@twin.org/data-json-ld 0.0.3-next.8 → 0.9.0-next.1

package/docs/examples.md

@@ -1 +1,214 @@
-# @twin.org/data-json-ld - Examples
+# Data Json Ld Examples
+
+These examples walk through context management, document processing, validation, and property access patterns for JSON-LD documents.
+
+## JsonLdProcessor
+
+```typescript
+import { JsonLdProcessor } from '@twin.org/data-json-ld';
+
+JsonLdProcessor.setCacheLimit(900000);
+console.log('Cache limit:', JsonLdProcessor.getCacheLimit());
+
+JsonLdProcessor.setRedirects([
+  {
+    from: /^https:\/\/raw\.githubusercontent\.com\//,
+    to: 'https://cdn.example.org/github-content'
+  }
+]);
+
+JsonLdProcessor.addRedirect(/^https:\/\/schema\.org\//, 'https://schema.org/');
+console.log('Has redirects:', JsonLdProcessor.getRedirects().length > 0);
+
+const loader = JsonLdProcessor.getDocumentLoader();
+console.log('Loader type:', typeof loader);
+```
+
+```typescript
+import { JsonLdProcessor, type IJsonLdNodeObject } from '@twin.org/data-json-ld';
+
+const compactedDoc = {
+  '@context': {
+    ex: 'https://example.org/vocab/',
+    name: 'ex:name'
+  },
+  '@id': 'urn:example:person:1',
+  name: 'Ada'
+};
+
+const expanded = await JsonLdProcessor.expand(compactedDoc);
+const compactedAgain = await JsonLdProcessor.compact(expanded[0], compactedDoc['@context']);
+
+console.log('Compacted id:', compactedAgain['@id']);
+
+const canonical = await JsonLdProcessor.canonize(expanded[0] as IJsonLdNodeObject);
+console.log('Canonical includes id:', canonical.includes('urn:example:person:1'));
+```
+
+```typescript
+import { JsonLdProcessor, type IJsonLdNodeObject } from '@twin.org/data-json-ld';
+
+const contextA = 'https://example.org/context/base';
+const contextB = {
+  ex: 'https://example.org/vocab/',
+  name: 'ex:name'
+};
+
+const combined = JsonLdProcessor.combineContexts(contextA, contextB);
+
+const documentWithNestedContexts: IJsonLdNodeObject = {
+  '@context': contextA,
+  '@graph': [
+    {
+      '@context': contextB,
+      '@id': 'urn:example:item:1',
+      '@type': 'ex:Person',
+      'ex:name': 'Ada'
+    }
+  ]
+};
+
+const gathered = JsonLdProcessor.gatherContexts(documentWithNestedContexts);
+const filtered = JsonLdProcessor.removeContexts(gathered, [contextB]);
+
+console.log('Combined is array:', Array.isArray(combined));
+console.log('Filtered context equals contextA:', filtered === contextA);
+```
+
+```typescript
+import { JsonLdProcessor } from '@twin.org/data-json-ld';
+
+await JsonLdProcessor.documentCacheAdd('https://example.org/context', {
+  '@context': {
+    ex: 'https://example.org/vocab/'
+  }
+});
+
+await JsonLdProcessor.documentCacheRemove('https://example.org/context');
+```
+
+### Remote `@context` URLs: redirects and HTTP `Link` discovery
+
+When a remote `@context` URL is a string, the default document loader resolves it in this order:
+
+1. **Registered redirects** — `setRedirects` / `addRedirect` run first. If a pattern matches, the request uses the replacement URL only (no `HEAD` or discovery against the original namespace URL).
+2. **GET with `Accept: application/ld+json`**. If the response is an **HTTP error** (for example **404**), the load fails and discovery does not run. If the response is **OK** but the body is **not valid JSON** (for example HTML), retry **GET** with **`Accept: application/json`**.
+3. **HTTP `Link` discovery** — only if **both** `GET`s in step 2 failed with a **JSON decode** error: `HEAD` on the current URL (or `GET` if the server returns **405** / **501** for `HEAD`), then inspect `Link` for `rel="alternate"` and `type="application/ld+json"`, resolve the target URL, and **fetch that context document once** (at most **one** discovery hop per load chain).
+
+Use **manual redirects** for stable overrides, offline tests, or hosts that do not expose a suitable `Link` header. Rely on **discovery** when the namespace URL serves HTML but advertises a JSON-LD context via `Link`.
+
+```typescript
+import { JsonLdProcessor } from '@twin.org/data-json-ld';
+
+// Optional: force a namespace URL to a known context document (runs before discovery).
+JsonLdProcessor.addRedirect(
+  /^https:\/\/example\.org\/vocab\/?$/,
+  'https://example.org/context/doc.jsonld'
+);
+```
+
+### Standards packages and `registerRedirects()`
+
+Vocabulary packages (for example `@twin.org/standards-schema-org`) often expose `SchemaOrgDataTypes.registerRedirects()`, which forwards to `JsonLdProcessor.addRedirect` for a known namespace URL. That call is **optional** in many deployments: the default loader can reach the same JSON-LD context via **HTTP `Link` discovery** when the namespace URL returns HTML and advertises `rel="alternate"` with `type="application/ld+json"`. Prefer **explicit redirects** when you want predictable URLs without an extra `HEAD`/`GET` for discovery, **fully offline** or hermetic tests, or when the host does not send a usable `Link` header.
+
+## JsonLdHelper
+
+```typescript
+import { type IValidationFailure } from '@twin.org/core';
+import { ValidationMode } from '@twin.org/data-core';
+import { JsonLdHelper, type IJsonLdNodeObject } from '@twin.org/data-json-ld';
+
+const compactedDocument = {
+  '@context': {
+    ex: 'https://example.org/vocab/',
+    id: '@id',
+    type: '@type',
+    name: 'ex:name'
+  },
+  id: 'urn:example:person:1',
+  type: 'ex:Person',
+  name: 'Ada'
+};
+
+const failures: IValidationFailure[] = [];
+await JsonLdHelper.validate(compactedDocument, failures, {
+  validationMode: ValidationMode.Either,
+  failOnMissingType: false
+});
+
+const expanded = await JsonLdHelper.expand(compactedDocument);
+const hasPersonType = await JsonLdHelper.isType(expanded, ['https://example.org/vocab/Person']);
+const types = await JsonLdHelper.getType(expanded);
+const id = await JsonLdHelper.getId(expanded);
+
+console.log('Failure count:', failures.length);
+console.log('Has person type:', hasPersonType);
+console.log('Type list includes person:', types.includes('https://example.org/vocab/Person'));
+console.log('Document id:', id);
+
+const nodeObject = JsonLdHelper.toNodeObject(compactedDocument);
+const structuredObject = JsonLdHelper.toStructuredObject<{ name: string }>(
+  nodeObject as IJsonLdNodeObject
+);
+
+console.log('Structured name:', structuredObject.name);
+```
+
+```typescript
+import { JsonLdHelper } from '@twin.org/data-json-ld';
+
+const expandedDocument = [
+  {
+    '@id': 'urn:example:article:1',
+    'https://schema.org/name': [
+      { '@value': 'Hello', '@language': 'en' },
+      { '@value': 'Hallo', '@language': 'de' }
+    ],
+    'https://schema.org/wordCount': [{ '@value': 240 }]
+  }
+];
+
+const title = await JsonLdHelper.getPropertyValue(
+  expandedDocument,
+  'https://schema.org/name',
+  'en'
+);
+const [nameValues, wordCountValues] = await JsonLdHelper.getPropertyValues(expandedDocument, [
+  'https://schema.org/name',
+  'https://schema.org/wordCount'
+]);
+
+console.log('English title:', title?.[0]);
+console.log('Name value count:', nameValues?.length);
+console.log('Word count value:', wordCountValues?.[0]);
+```
+
+```typescript
+import { JsonLdHelper } from '@twin.org/data-json-ld';
+
+const node = {
+  '@id': 'urn:example:item:1',
+  name: 'Ada',
+  role: 'Engineer'
+};
+
+const prefixed = JsonLdHelper.prefixProperties(node, 'ex', ['name', 'role']);
+const stripped = JsonLdHelper.stripPrefixProperties(prefixed, 'ex');
+
+console.log('Prefixed name:', prefixed['ex:name']);
+console.log('Stripped name:', stripped.name);
+```
+
+## JsonLdDataTypes
+
+```typescript
+import { DataTypeHelper } from '@twin.org/data-core';
+import { JsonLdContexts, JsonLdDataTypes, JsonLdTypes } from '@twin.org/data-json-ld';
+
+JsonLdDataTypes.registerTypes();
+
+const schema = await DataTypeHelper.getSchemaForType(
+  `${JsonLdContexts.Namespace}${JsonLdTypes.Document}`
+);
+console.log('Registered schema type:', schema?.type);
+```

package/docs/reference/classes/JsonLdDataTypes.md

@@ -14,7 +14,7 @@ Handle all the data types for JSON-LD.
 
 ## Methods
 
-### registerTypes()
+### registerTypes() {#registertypes}
 
 > `static` **registerTypes**(): `void`
 

package/docs/reference/classes/JsonLdHelper.md

@@ -14,7 +14,7 @@ Class to help with JSON LD.
 
 ## Methods
 
-### validate()
+### validate() {#validate}
 
 > `static` **validate**\<`T`\>(`document`, `validationFailures`, `options?`): `Promise`\<`boolean`\>
 
@@ -64,33 +64,67 @@ True if the document was valid.
 
 ***
 
-### toNodeObject()
+### toNodeObject() {#tonodeobject}
 
-> `static` **toNodeObject**(`object`): [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
+> `static` **toNodeObject**\<`T`\>(`object`): `T` & [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
 
-Expand an object to a JSON-LD node object.
+Convert an object to a JSON-LD node object.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
 
 #### Parameters
 
 ##### object
 
-`unknown`
+`T`
 
-The object to expand.
+The object to convert.
 
 #### Returns
 
+`T` & [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
+
+The JSON-LD node object.
+
+***
+
+### toStructuredObject() {#tostructuredobject}
+
+> `static` **toStructuredObject**\<`T`\>(`nodeObject`): `T`
+
+Convert the JSON-LD node object to a structured object.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+#### Parameters
+
+##### nodeObject
+
 [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
 
-The expanded JSON-LD node object.
+The JSON-LD node object to convert.
+
+#### Returns
+
+`T`
+
+The structured object.
 
 ***
 
-### isType()
+### expand() {#expand}
 
-> `static` **isType**(`document`, `type`): `Promise`\<`boolean`\>
+> `static` **expand**(`document`): `Promise`\<[`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)[]\>
 
-Expand the JSON-LD document and check if it is of a specific type.
+Expand the JSON-LD document.
 
 #### Parameters
 
@@ -98,7 +132,29 @@ Expand the JSON-LD document and check if it is of a specific type.
 
 [`IJsonLdDocument`](../type-aliases/IJsonLdDocument.md)
 
-The JSON-LD document to check.
+The JSON-LD document to expand.
+
+#### Returns
+
+`Promise`\<[`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)[]\>
+
+The expanded JSON-LD document.
+
+***
+
+### isType() {#istype}
+
+> `static` **isType**(`documentOrExpanded`, `type`): `Promise`\<`boolean`\>
+
+Expand the JSON-LD document and check if it is of a specific type.
+
+#### Parameters
+
+##### documentOrExpanded
+
+[`IJsonLdDocument`](../type-aliases/IJsonLdDocument.md)
+
+The JSON-LD document to check or already expanded document.
 
 ##### type
 
@@ -114,19 +170,19 @@ True if the document is of the specified type.
 
 ***
 
-### getType()
+### getType() {#gettype}
 
-> `static` **getType**(`document`): `Promise`\<`string`[]\>
+> `static` **getType**(`documentOrExpanded`): `Promise`\<`string`[]\>
 
 Get the types from the document.
 
 #### Parameters
 
-##### document
+##### documentOrExpanded
 
 [`IJsonLdDocument`](../type-aliases/IJsonLdDocument.md)
 
-The JSON-LD document to check.
+The JSON-LD document to check or already expanded document.
 
 #### Returns
 
@@ -136,22 +192,180 @@ The type(s) extracted from the document.
 
 ***
 
-### getId()
+### getId() {#getid}
 
-> `static` **getId**(`document`): `Promise`\<`string` \| `undefined`\>
+> `static` **getId**(`documentOrExpanded`, `additionalIdProperties?`): `Promise`\<`string` \| `undefined`\>
 
 Get the id from the document.
 
 #### Parameters
 
-##### document
+##### documentOrExpanded
 
 [`IJsonLdDocument`](../type-aliases/IJsonLdDocument.md)
 
-The JSON-LD document to get the id from.
+The JSON-LD document to get the id from or already expanded document.
+
+##### additionalIdProperties?
+
+`string`[]
+
+Optional additional properties to check for the id, in addition to "@id" and "id".
 
 #### Returns
 
 `Promise`\<`string` \| `undefined`\>
 
 The id extracted from the document.
+
+***
+
+### getPropertyValue() {#getpropertyvalue}
+
+> `static` **getPropertyValue**(`documentOrExpanded`, `propertyFullName`, `language?`): `Promise`\<[`IJsonLdNodePrimitive`](../type-aliases/IJsonLdNodePrimitive.md)[] \| `undefined`\>
+
+Get property values by a single full expanded property name.
+
+#### Parameters
+
+##### documentOrExpanded
+
+[`IJsonLdDocument`](../type-aliases/IJsonLdDocument.md)
+
+The JSON-LD document to get the property from or already expanded document.
+
+##### propertyFullName
+
+`string`
+
+The full expanded property name.
+
+##### language?
+
+`string`
+
+Optional filter values by their language property.
+
+#### Returns
+
+`Promise`\<[`IJsonLdNodePrimitive`](../type-aliases/IJsonLdNodePrimitive.md)[] \| `undefined`\>
+
+Matching property values for the input property.
+
+***
+
+### getPropertyValues() {#getpropertyvalues}
+
+> `static` **getPropertyValues**(`documentOrExpanded`, `propertyFullNames`, `language?`): `Promise`\<([`IJsonLdNodePrimitive`](../type-aliases/IJsonLdNodePrimitive.md)[] \| `undefined`)[]\>
+
+Get property values by their full expanded property names.
+
+#### Parameters
+
+##### documentOrExpanded
+
+[`IJsonLdDocument`](../type-aliases/IJsonLdDocument.md)
+
+The JSON-LD document to get the property from or already expanded document.
+
+##### propertyFullNames
+
+`string`[]
+
+The full expanded property names.
+
+##### language?
+
+`string`
+
+Optional filter values by their language property.
+
+#### Returns
+
+`Promise`\<([`IJsonLdNodePrimitive`](../type-aliases/IJsonLdNodePrimitive.md)[] \| `undefined`)[]\>
+
+Matching property values for each input property, in the same index order.
+
+***
+
+### prefixProperties() {#prefixproperties}
+
+> `static` **prefixProperties**\<`T`\>(`nodeObject`, `prefix`, `properties?`): [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
+
+Prefix all properties in the document with the provided prefix, except for JSON-LD properties.
+This is useful for ensuring that all properties are fully qualified with a namespace.
+For example, if the prefix is "ex" and the document has a property "name", it will be transformed to "ex:name".
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
+
+#### Parameters
+
+##### nodeObject
+
+`T`
+
+The JSON-LD node object to prefix properties on.
+
+##### prefix
+
+`string`
+
+The prefix to add to the properties.
+
+##### properties?
+
+`string`[]
+
+Optional list of properties to prefix. If not provided, all properties except for JSON-LD properties.
+
+#### Returns
+
+[`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
+
+A new JSON-LD node object with the properties prefixed.
+
+***
+
+### stripPrefixProperties() {#stripprefixproperties}
+
+> `static` **stripPrefixProperties**\<`T`\>(`nodeObject`, `prefix`, `properties?`): [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
+
+Strip a prefix from properties in the document, except for JSON-LD properties.
+This is useful for converting fully qualified namespaced properties back to local names.
+For example, if the prefix is "ex" and the document has a property "ex:name", it will be transformed to "name".
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
+
+#### Parameters
+
+##### nodeObject
+
+`T`
+
+The JSON-LD node object to strip prefixed properties from.
+
+##### prefix
+
+`string`
+
+The prefix to remove from the properties.
+
+##### properties?
+
+`string`[]
+
+Optional list of unprefixed properties to strip. If not provided, all matching prefixed properties.
+
+#### Returns
+
+[`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
+
+A new JSON-LD node object with the prefix stripped from matching properties.