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

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,11 +64,11 @@ True if the document was valid.
 
 ***
 
-### toNodeObject()
+### toNodeObject() {#tonodeobject}
 
 > `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
 
@@ -82,17 +82,45 @@ Expand an object to a JSON-LD node object.
 
 `T`
 
-The object to expand.
+The object to convert.
 
 #### Returns
 
 `T` & [`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)
 
-The expanded JSON-LD node object.
+The JSON-LD node object.
 
 ***
 
-### expand()
+### 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 JSON-LD node object to convert.
+
+#### Returns
+
+`T`
+
+The structured object.
+
+***
+
+### expand() {#expand}
 
 > `static` **expand**(`document`): `Promise`\<[`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)[]\>
 
@@ -114,7 +142,7 @@ The expanded JSON-LD document.
 
 ***
 
-### isType()
+### isType() {#istype}
 
 > `static` **isType**(`documentOrExpanded`, `type`): `Promise`\<`boolean`\>
 
@@ -142,7 +170,7 @@ True if the document is of the specified type.
 
 ***
 
-### getType()
+### getType() {#gettype}
 
 > `static` **getType**(`documentOrExpanded`): `Promise`\<`string`[]\>
 
@@ -164,9 +192,9 @@ The type(s) extracted from the document.
 
 ***
 
-### getId()
+### getId() {#getid}
 
-> `static` **getId**(`documentOrExpanded`): `Promise`\<`string` \| `undefined`\>
+> `static` **getId**(`documentOrExpanded`, `additionalIdProperties?`): `Promise`\<`string` \| `undefined`\>
 
 Get the id from the document.
 
@@ -178,6 +206,12 @@ Get the id from the document.
 
 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`\>
@@ -186,7 +220,7 @@ The id extracted from the document.
 
 ***
 
-### getPropertyValue()
+### getPropertyValue() {#getpropertyvalue}
 
 > `static` **getPropertyValue**(`documentOrExpanded`, `propertyFullName`, `language?`): `Promise`\<[`IJsonLdNodePrimitive`](../type-aliases/IJsonLdNodePrimitive.md)[] \| `undefined`\>
 
@@ -220,7 +254,7 @@ Matching property values for the input property.
 
 ***
 
-### getPropertyValues()
+### getPropertyValues() {#getpropertyvalues}
 
 > `static` **getPropertyValues**(`documentOrExpanded`, `propertyFullNames`, `language?`): `Promise`\<([`IJsonLdNodePrimitive`](../type-aliases/IJsonLdNodePrimitive.md)[] \| `undefined`)[]\>
 
@@ -251,3 +285,87 @@ Optional filter values by their language property.
 `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.

package/docs/reference/classes/JsonLdProcessor.md

@@ -14,11 +14,11 @@ JSON-LD Processor.
 
 ## Methods
 
-### setDocumentLoader()
+### setDocumentLoader() {#setdocumentloader}
 
 > `static` **setDocumentLoader**(`documentLoader`): `void`
 
-The document loader to use.
+Set the document loader used for retrieving JSON-LD documents.
 
 #### Parameters
 
@@ -34,31 +34,21 @@ The document loader to use.
 
 ***
 
-### getDocumentLoader()
+### getDocumentLoader() {#getdocumentloader}
 
 > `static` **getDocumentLoader**(): (`url`) => `Promise`\<`RemoteDocument`\>
 
-The document loader to use for retrieving JSON-LD documents.
+Get the document loader used for retrieving JSON-LD documents.
 
 #### Returns
 
-The document loader.
-
-> (`url`): `Promise`\<`RemoteDocument`\>
-
-##### Parameters
+The active document loader function.
 
-###### url
-
-`string`
-
-##### Returns
-
-`Promise`\<`RemoteDocument`\>
+(`url`) => `Promise`\<`RemoteDocument`\>
 
 ***
 
-### setCacheLimit()
+### setCacheLimit() {#setcachelimit}
 
 > `static` **setCacheLimit**(`cacheLimitMs`): `void`
 
@@ -78,7 +68,7 @@ The cache limit in milliseconds.
 
 ***
 
-### getCacheLimit()
+### getCacheLimit() {#getcachelimit}
 
 > `static` **getCacheLimit**(): `number`
 
@@ -88,15 +78,16 @@ Get the cache limit for documents.
 
 `number`
 
-The document loader.
+The cache limit in milliseconds.
 
 ***
 
-### setRedirects()
+### setRedirects() {#setredirects}
 
 > `static` **setRedirects**(`redirects`): `void`
 
-Set the global redirects for JSON-LD, use addRedirect for default handling.
+Replace the global redirect list (use [JsonLdProcessor.addRedirect](#addredirect) to append without replacing).
+Redirects run before any HTTP GET or `Link` discovery; use them for stable overrides, tests, or hosts that do not expose a suitable `Link` header.
 
 #### Parameters
 
@@ -112,7 +103,7 @@ The redirects to use.
 
 ***
 
-### getRedirects()
+### getRedirects() {#getredirects}
 
 > `static` **getRedirects**(): `object`[]
 
@@ -126,7 +117,35 @@ The registered redirects.
 
 ***
 
-### compact()
+### addRedirect() {#addredirect}
+
+> `static` **addRedirect**(`from`, `to`): `void`
+
+Append a redirect rule (ignored if the same `RegExp.source` is already registered).
+Optional when the vocabulary URL supports HTTP `Link` discovery (`rel` includes `alternate`, `type` is `application/ld+json`) via the default document loader.
+Standards packages often expose `registerRedirects()` helpers that call this method; those are optional for the same reason.
+
+#### Parameters
+
+##### from
+
+`RegExp`
+
+The URL to redirect from.
+
+##### to
+
+`string`
+
+The URL to redirect to.
+
+#### Returns
+
+`void`
+
+***
+
+### compact() {#compact}
 
 > `static` **compact**\<`T`\>(`document`, `context?`, `options?`): `Promise`\<`T`\>
 
@@ -170,7 +189,7 @@ The compacted JSON-LD document.
 
 ***
 
-### expand()
+### expand() {#expand}
 
 > `static` **expand**\<`T`\>(`compacted`): `Promise`\<[`IJsonLdNodeObject`](../interfaces/IJsonLdNodeObject.md)[]\>
 
@@ -198,7 +217,7 @@ The expanded JSON-LD document.
 
 ***
 
-### canonize()
+### canonize() {#canonize}
 
 > `static` **canonize**\<`T`\>(`document`, `options?`): `Promise`\<`string`\>
 
@@ -236,33 +255,7 @@ The canonized document.
 
 ***
 
-### addRedirect()
-
-> `static` **addRedirect**(`from`, `to`): `void`
-
-Add a redirect to use during document resolution.
-
-#### Parameters
-
-##### from
-
-`RegExp`
-
-The URL to redirect from.
-
-##### to
-
-`string`
-
-The URL to redirect to.
-
-#### Returns
-
-`void`
-
-***
-
-### combineContexts()
+### combineContexts() {#combinecontexts}
 
 > `static` **combineContexts**(`context1`, `context2`): [`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) \| `undefined`
 
@@ -272,15 +265,15 @@ Combine contexts.
 
 ##### context1
 
-The first JSON-LD context to combine.
+[`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) \| `undefined`
 
-[`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) | `undefined`
+The first JSON-LD context to combine.
 
 ##### context2
 
-The second JSON-LD context to combine.
+[`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) \| `undefined`
 
-[`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) | `undefined`
+The second JSON-LD context to combine.
 
 #### Returns
 
@@ -290,7 +283,7 @@ The combined context.
 
 ***
 
-### gatherContexts()
+### gatherContexts() {#gathercontexts}
 
 > `static` **gatherContexts**\<`T`\>(`element`, `initial?`): [`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) \| `undefined`
 
@@ -324,7 +317,7 @@ The combined contexts.
 
 ***
 
-### removeContexts()
+### removeContexts() {#removecontexts}
 
 > `static` **removeContexts**(`context`, `match?`): [`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) \| `undefined`
 
@@ -334,9 +327,9 @@ Remove all the contexts that match the pattern.
 
 ##### context
 
-The context to remove the entries from.
+[`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) \| `undefined`
 
-[`IJsonLdContextDefinitionRoot`](../type-aliases/IJsonLdContextDefinitionRoot.md) | `undefined`
+The context to remove the entries from.
 
 ##### match?
 
@@ -352,7 +345,7 @@ The updated contexts.
 
 ***
 
-### documentCacheAdd()
+### documentCacheAdd() {#documentcacheadd}
 
 > `static` **documentCacheAdd**(`url`, `ldContext`): `Promise`\<`void`\>
 
@@ -376,11 +369,11 @@ The context to add.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the entry has been stored in the cache.
 
 ***
 
-### documentCacheRemove()
+### documentCacheRemove() {#documentcacheremove}
 
 > `static` **documentCacheRemove**(`url`): `Promise`\<`void`\>
 
@@ -398,4 +391,4 @@ The url the ld context is for.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the entry has been removed from the cache.