Introduction
The JavaScript SDK lets you load Aspect Models in JavaScript and TypeScript applications. It reads Aspect Models written in RDF/Turtle (SAMM 2.0.0, 2.1.0 and 2.2.0) and returns them as typed TypeScript objects. You can traverse these objects, or process them with a visitor, to access the model’s information, such as properties, characteristics, entities, units, descriptions and constraints.
This lets you build generic frontends that adapt to the underlying Aspect Model automatically. For example, when a new property is added to the model, the UI can show the corresponding value together with the property’s name, description and unit without any code changes.
Getting Started
Install from GitHub release repository
npm install https://github.com/eclipse-esmf/esmf-sdk-js-aspect-model-loader/releases/download/v2.3.3/esmf-sdk-js-2.3.3.tgz
The package is named @esmf/sdk-js (formerly @esmf/aspect-model-loader).
The package is published as an ES module only and requires Node.js 24 or newer. CommonJS consumers can load it via require() on Node.js 22.12 or newer.
|
Usage
import {AspectModelLoader, Aspect} from '@esmf/sdk-js';
This package contains two methods for loading Turtle (.ttl) files (string value of the .ttl files). Each method is available as a Promise-based variant and as an RxJS Observable variant.
Load an aspect model which is self-contained (includes no imports to other ttl file):
const aspect: Aspect = await new AspectModelLoader().loadSelfContainedAspect(ttl);
// or as Observable
new AspectModelLoader().loadSelfContainedModel(ttl).subscribe((aspect: Aspect) => {
...
});
or if the model contains imports to additional ttl files:
const aspect: Aspect = await new AspectModelLoader().loadAspect('<aspect-model-urn>', ttl1, ttl2, ttl3);
// or as Observable
new AspectModelLoader().load('<aspect-model-urn>', ttl1, ttl2, ttl3).subscribe((aspect: Aspect) => {
...
});
Errors are reported as typed error classes (for example UnsupportedVersionError, AspectNotFoundError or MultipleAspectsFoundError), all derived from AspectModelError.
If you are using external .ttl files you may need to parse the contents of these files to strings, to be passed to the methods params.
Error handling
All errors thrown or emitted by the loaders derive from AspectModelError:
| Error | Cause |
|---|---|
|
The model uses a SAMM version that is not supported. |
|
No aspect with the requested URN was found. |
|
A self-contained model contains more than one aspect. |
|
An entity instance could not be resolved. |
|
An entity that must be abstract is not abstract. |
|
The Turtle input could not be parsed. |
import {AspectModelError, AspectNotFoundError} from '@esmf/sdk-js';
try {
await loader.loadAspect(urn, ttl);
} catch (error) {
if (error instanceof AspectNotFoundError) {
// handle missing aspect
} else if (error instanceof AspectModelError) {
// handle any other loader error
}
}
Helpful functions
After loading, the loader exposes helper functions to find model elements.
Find a model element by its URN (returns the element or undefined):
const element = loader.findByUrn('urn:samm:org.example:1.0.0#myProperty');
Find model elements by name (returns all matching elements):
const elements = loader.findByName('myProperty');
Filter all loaded model elements with a predicate:
import {DefaultProperty} from '@esmf/sdk-js';
const properties = loader.filterElements(element => element instanceof DefaultProperty);
Visitor
To process a loaded model, extend DefaultAspectModelVisitor and override the methods for the element types you need:
import {DefaultAspectModelVisitor, DefaultProperty} from '@esmf/sdk-js';
class PropertyCounter extends DefaultAspectModelVisitor<void, unknown> {
count = 0;
visitProperty(property: DefaultProperty, context: unknown): void {
this.count++;
return super.visitProperty(property, context);
}
}
const counter = new PropertyCounter();
counter.visit(aspect, {});
Development
Requirements: Node.js 24 or newer and pnpm.
pnpm install
pnpm run build # build the library into dist/
pnpm test # run the tests
pnpm run all # build, format, lint, type check, tests with coverage and package checks
See the contribution guideline and the changelog for details.