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

package/dist/types/utils/jsonLdHelper.d.ts

@@ -2,6 +2,7 @@ import { type IValidationFailure } from "@twin.org/core";
 import { type ValidationMode } from "@twin.org/data-core";
 import type { IJsonLdDocument } from "../models/IJsonLdDocument.js";
 import type { IJsonLdNodeObject } from "../models/IJsonLdNodeObject.js";
+import type { IJsonLdNodePrimitive } from "../models/IJsonLdNodePrimitive.js";
 /**
  * Class to help with JSON LD.
  */
@@ -20,28 +21,77 @@ export declare class JsonLdHelper {
         failOnMissingType?: boolean;
     }): Promise<boolean>;
     /**
-     * Expand an object to a JSON-LD node object.
-     * @param object The object to expand.
-     * @returns The expanded JSON-LD node object.
+     * Convert an object to a JSON-LD node object.
+     * @param object The object to convert.
+     * @returns The JSON-LD node object.
      */
-    static toNodeObject(object: unknown): IJsonLdNodeObject;
+    static toNodeObject<T = unknown>(object: T): T & IJsonLdNodeObject;
+    /**
+     * Convert the JSON-LD node object to a structured object.
+     * @param nodeObject The JSON-LD node object to convert.
+     * @returns The structured object.
+     */
+    static toStructuredObject<T = unknown>(nodeObject: IJsonLdNodeObject): T;
+    /**
+     * Expand the JSON-LD document.
+     * @param document The JSON-LD document to expand.
+     * @returns The expanded JSON-LD document.
+     */
+    static expand(document: IJsonLdDocument): Promise<IJsonLdNodeObject[]>;
     /**
      * Expand the JSON-LD document and check if it is of a specific type.
-     * @param document The JSON-LD document to check.
+     * @param documentOrExpanded The JSON-LD document to check or already expanded document.
      * @param type The type to check for.
      * @returns True if the document is of the specified type.
      */
-    static isType(document: IJsonLdDocument, type: string[]): Promise<boolean>;
+    static isType(documentOrExpanded: IJsonLdDocument | IJsonLdNodeObject[], type: string[]): Promise<boolean>;
     /**
      * Get the types from the document.
-     * @param document The JSON-LD document to check.
+     * @param documentOrExpanded The JSON-LD document to check or already expanded document.
      * @returns The type(s) extracted from the document.
      */
-    static getType(document: IJsonLdDocument): Promise<string[]>;
+    static getType(documentOrExpanded: IJsonLdDocument | IJsonLdNodeObject[]): Promise<string[]>;
     /**
      * Get the id from the document.
-     * @param document The JSON-LD document to get the id from.
+     * @param documentOrExpanded The JSON-LD document to get the id from or already expanded document.
+     * @param additionalIdProperties Optional additional properties to check for the id, in addition to "@id" and "id".
      * @returns The id extracted from the document.
      */
-    static getId(document: IJsonLdDocument): Promise<string | undefined>;
+    static getId(documentOrExpanded: IJsonLdDocument | IJsonLdNodeObject[], additionalIdProperties?: string[]): Promise<string | undefined>;
+    /**
+     * Get property values by a single full expanded property name.
+     * @param documentOrExpanded The JSON-LD document to get the property from or already expanded document.
+     * @param propertyFullName The full expanded property name.
+     * @param language Optional filter values by their language property.
+     * @returns Matching property values for the input property.
+     */
+    static getPropertyValue(documentOrExpanded: IJsonLdDocument | IJsonLdNodeObject[], propertyFullName: string, language?: string): Promise<IJsonLdNodePrimitive[] | undefined>;
+    /**
+     * Get property values by their full expanded property names.
+     * @param documentOrExpanded The JSON-LD document to get the property from or already expanded document.
+     * @param propertyFullNames The full expanded property names.
+     * @param language Optional filter values by their language property.
+     * @returns Matching property values for each input property, in the same index order.
+     */
+    static getPropertyValues(documentOrExpanded: IJsonLdDocument | IJsonLdNodeObject[], propertyFullNames: string[], language?: string): Promise<(IJsonLdNodePrimitive[] | undefined)[]>;
+    /**
+     * 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".
+     * @param nodeObject The JSON-LD node object to prefix properties on.
+     * @param prefix The prefix to add to the properties.
+     * @param properties Optional list of properties to prefix. If not provided, all properties except for JSON-LD properties.
+     * @returns A new JSON-LD node object with the properties prefixed.
+     */
+    static prefixProperties<T extends IJsonLdNodeObject>(nodeObject: T, prefix: string, properties?: string[]): IJsonLdNodeObject;
+    /**
+     * 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".
+     * @param nodeObject The JSON-LD node object to strip prefixed properties from.
+     * @param prefix The prefix to remove from the properties.
+     * @param properties Optional list of unprefixed properties to strip. If not provided, all matching prefixed properties.
+     * @returns A new JSON-LD node object with the prefix stripped from matching properties.
+     */
+    static stripPrefixProperties<T extends IJsonLdNodeObject>(nodeObject: T, prefix: string, properties?: string[]): IJsonLdNodeObject;
 }

package/dist/types/utils/jsonLdProcessor.d.ts

@@ -7,13 +7,13 @@ import type { IJsonLdNodeObject } from "../models/IJsonLdNodeObject.js";
  */
 export declare class JsonLdProcessor {
     /**
-     * The document loader to use.
+     * Set the document loader used for retrieving JSON-LD documents.
      * @param documentLoader The document loader to use.
      */
     static setDocumentLoader(documentLoader: (url: Url) => Promise<RemoteDocument>): void;
     /**
-     * The document loader to use for retrieving JSON-LD documents.
-     * @returns The document loader.
+     * Get the document loader used for retrieving JSON-LD documents.
+     * @returns The active document loader function.
      */
     static getDocumentLoader(): (url: Url) => Promise<RemoteDocument>;
     /**
@@ -23,11 +23,12 @@ export declare class JsonLdProcessor {
     static setCacheLimit(cacheLimitMs: number): void;
     /**
      * Get the cache limit for documents.
-     * @returns The document loader.
+     * @returns The cache limit in milliseconds.
      */
     static getCacheLimit(): number;
     /**
-     * Set the global redirects for JSON-LD, use addRedirect for default handling.
+     * Replace the global redirect list (use {@link JsonLdProcessor.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.
      * @param redirects The redirects to use.
      */
     static setRedirects(redirects: {
@@ -42,6 +43,14 @@ export declare class JsonLdProcessor {
         from: RegExp;
         to: string;
     }[];
+    /**
+     * 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.
+     * @param from The URL to redirect from.
+     * @param to The URL to redirect to.
+     */
+    static addRedirect(from: RegExp, to: string): void;
     /**
      * Compact a document according to a particular context.
      * @param document The JSON-LD document to compact.
@@ -69,12 +78,6 @@ export declare class JsonLdProcessor {
     static canonize<T extends IJsonLdNodeObject>(document: T, options?: {
         algorithm?: "URDNA2015" | "URGNA2012" | undefined;
     }): Promise<string>;
-    /**
-     * Add a redirect to use during document resolution.
-     * @param from The URL to redirect from.
-     * @param to The URL to redirect to.
-     */
-    static addRedirect(from: RegExp, to: string): void;
     /**
      * Combine contexts.
      * @param context1 The first JSON-LD context to combine.
@@ -100,13 +103,13 @@ export declare class JsonLdProcessor {
      * Add a context directly to the document loader cache.
      * @param url The url the ld context is for.
      * @param ldContext The context to add.
-     * @returns Nothing.
+     * @returns A promise that resolves when the entry has been stored in the cache.
      */
     static documentCacheAdd(url: string, ldContext: unknown): Promise<void>;
     /**
      * Remove a context from the document loader cache.
      * @param url The url the ld context is for.
-     * @returns Nothing.
+     * @returns A promise that resolves when the entry has been removed from the cache.
      */
     static documentCacheRemove(url: string): Promise<void>;
 }