ldkit 2.2.0 → 2.3.0

package/esm/library/decoder.js

@@ -1,6 +1,6 @@
-import { fromRdf } from "./rdf.js";
 import { ldkit } from "../namespaces/ldkit.js";
 import { rdf } from "../namespaces/rdf.js";
+import { translateFromRdf } from "./translator.js";
 export const decode = (graph, schema, options) => {
     return Decoder.decode(graph, schema, options);
 };
@@ -185,7 +185,7 @@ class Decoder {
             return term.value;
         }
         else if (term.termType === "Literal") {
-            return fromRdf(term);
+            return translateFromRdf(term);
         }
         else {
             throw new Error(`Unsupported term type to resolve: ${term.termType}`);

package/esm/library/encoder.js

@@ -1,7 +1,8 @@
-import { DataFactory, toRdf } from "./rdf.js";
+import { DataFactory } from "./rdf.js";
 import { xsd } from "../namespaces/xsd.js";
 import { rdf } from "../namespaces/rdf.js";
 import { ldkit } from "../namespaces/ldkit.js";
+import { translateToRdf } from "./translator.js";
 export const encode = (node, schema, options, includeType = true, variableInitCounter = 0) => {
     return Encoder.encode(node, schema, options, includeType, variableInitCounter);
 };
@@ -9,9 +10,7 @@ export const encodeValue = (value, datatype, df) => {
     if (datatype === ldkit.IRI) {
         return df.namedNode(value);
     }
-    return toRdf(value, {
-        datatype: df.namedNode(datatype),
-    });
+    return translateToRdf(value, datatype);
 };
 class Encoder {
     constructor(options, includeType, variableInitCounter) {

package/esm/library/translator.js

@@ -0,0 +1,62 @@
+import { DataFactory, fromRdf, toRdf } from "./rdf.js";
+const df = new DataFactory();
+const rdfToNativeHandlers = new Map();
+const nativeToRdfHandlers = new Map();
+/**
+ * Registers a data type handler for translating between RDF literals and JavaScript values.
+ *
+ * In order to register a custom data type handler, the custom data type TypeScript mapping needs
+ * to be added to the {@link CustomDataTypes} interface using module augmentation.
+ *
+ * Two handlers are required:
+ * 1) A function to translate from RDF literal value (string) to JavaScript value.
+ * 2) A function to translate from JavaScript value to RDF literal value (string).
+ *
+ * @example
+ * ```typescript
+ * import { registerDataHandler } from "ldkit";
+ *
+ * const customNumberDataType = "http://example.org/number";
+ *
+ * declare module "ldkit" {
+ *   interface CustomDataTypes {
+ *     [customNumberDataType]: number;
+ *   }
+ * }
+ *
+ * registerDataHandler(
+ *   customNumberDataType,
+ *   (literalValue: string) => parseInt(literalValue),
+ *   (nativeValue: number) => nativeValue.toString(),
+ * );
+ * ```
+ *
+ * @param dataType - The data type to register.
+ * @param translateFromRDF - Function to translate from RDF literal to JavaScript value.
+ * @param translateToRDF - Function to translate from JavaScript value to RDF literal.
+ */
+export function registerDataHandler(dataType, translateFromRDF, translateToRDF) {
+    rdfToNativeHandlers.set(dataType, translateFromRDF);
+    nativeToRdfHandlers.set(dataType, translateToRDF);
+}
+export function translateFromRdf(literal) {
+    const dataType = literal.datatype.value;
+    const customHandler = rdfToNativeHandlers.get(dataType);
+    if (customHandler) {
+        return customHandler(literal.value);
+    }
+    else {
+        return fromRdf(literal);
+    }
+}
+export function translateToRdf(value, dataType) {
+    const customHandler = nativeToRdfHandlers.get(dataType);
+    if (customHandler) {
+        return df.literal(customHandler(value), df.namedNode(dataType));
+    }
+    else {
+        return toRdf(value, {
+            datatype: df.namedNode(dataType),
+        });
+    }
+}

package/esm/mod.js

@@ -1,4 +1,5 @@
 export { setGlobalOptions } from "./library/options.js";
+export { registerDataHandler } from "./library/translator.js";
 export * from "./library/lens/mod.js";
 export * from "./library/namespace.js";
 export * from "./library/engine/mod.js";

package/package.json

@@ -3,7 +3,7 @@
   "main": "./script/mod.js",
   "types": "./types/mod.d.ts",
   "name": "ldkit",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "LDkit, a Linked Data query toolkit for TypeScript developers",
   "homepage": "https://ldkit.io",
   "author": "Karel Klima <karelklima@gmail.com> (https://karelklima.com)",

package/script/library/decoder.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decode = void 0;
-const rdf_js_1 = require("./rdf.js");
 const ldkit_js_1 = require("../namespaces/ldkit.js");
-const rdf_js_2 = require("../namespaces/rdf.js");
+const rdf_js_1 = require("../namespaces/rdf.js");
+const translator_js_1 = require("./translator.js");
 const decode = (graph, schema, options) => {
     return Decoder.decode(graph, schema, options);
 };
@@ -56,8 +56,8 @@ class Decoder {
     decode() {
         const output = [];
         for (const [iri, properties] of this.graph) {
-            if (properties.has(rdf_js_2.rdf.type)) {
-                const types = properties.get(rdf_js_2.rdf.type);
+            if (properties.has(rdf_js_1.rdf.type)) {
+                const types = properties.get(rdf_js_1.rdf.type);
                 for (const type of types) {
                     if (type.termType === "NamedNode" && type.value === ldkit_js_1.ldkit.Resource) {
                         output.push(this.decodeNode(iri, this.schema));
@@ -96,7 +96,7 @@ class Decoder {
     }
     decodeNodeProperty(nodeIri, node, propertyKey, property) {
         const allTerms = node.get(property["@id"]);
-        const terms = property["@id"] !== rdf_js_2.rdf.type
+        const terms = property["@id"] !== rdf_js_1.rdf.type
             ? allTerms
             : allTerms?.filter((term) => term.value !== ldkit_js_1.ldkit.Resource);
         if (!terms) {
@@ -189,7 +189,7 @@ class Decoder {
             return term.value;
         }
         else if (term.termType === "Literal") {
-            return (0, rdf_js_1.fromRdf)(term);
+            return (0, translator_js_1.translateFromRdf)(term);
         }
         else {
             throw new Error(`Unsupported term type to resolve: ${term.termType}`);

package/script/library/encoder.js

@@ -5,6 +5,7 @@ const rdf_js_1 = require("./rdf.js");
 const xsd_js_1 = require("../namespaces/xsd.js");
 const rdf_js_2 = require("../namespaces/rdf.js");
 const ldkit_js_1 = require("../namespaces/ldkit.js");
+const translator_js_1 = require("./translator.js");
 const encode = (node, schema, options, includeType = true, variableInitCounter = 0) => {
     return Encoder.encode(node, schema, options, includeType, variableInitCounter);
 };
@@ -13,9 +14,7 @@ const encodeValue = (value, datatype, df) => {
     if (datatype === ldkit_js_1.ldkit.IRI) {
         return df.namedNode(value);
     }
-    return (0, rdf_js_1.toRdf)(value, {
-        datatype: df.namedNode(datatype),
-    });
+    return (0, translator_js_1.translateToRdf)(value, datatype);
 };
 exports.encodeValue = encodeValue;
 class Encoder {

package/script/library/translator.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateToRdf = exports.translateFromRdf = exports.registerDataHandler = void 0;
+const rdf_js_1 = require("./rdf.js");
+const df = new rdf_js_1.DataFactory();
+const rdfToNativeHandlers = new Map();
+const nativeToRdfHandlers = new Map();
+/**
+ * Registers a data type handler for translating between RDF literals and JavaScript values.
+ *
+ * In order to register a custom data type handler, the custom data type TypeScript mapping needs
+ * to be added to the {@link CustomDataTypes} interface using module augmentation.
+ *
+ * Two handlers are required:
+ * 1) A function to translate from RDF literal value (string) to JavaScript value.
+ * 2) A function to translate from JavaScript value to RDF literal value (string).
+ *
+ * @example
+ * ```typescript
+ * import { registerDataHandler } from "ldkit";
+ *
+ * const customNumberDataType = "http://example.org/number";
+ *
+ * declare module "ldkit" {
+ *   interface CustomDataTypes {
+ *     [customNumberDataType]: number;
+ *   }
+ * }
+ *
+ * registerDataHandler(
+ *   customNumberDataType,
+ *   (literalValue: string) => parseInt(literalValue),
+ *   (nativeValue: number) => nativeValue.toString(),
+ * );
+ * ```
+ *
+ * @param dataType - The data type to register.
+ * @param translateFromRDF - Function to translate from RDF literal to JavaScript value.
+ * @param translateToRDF - Function to translate from JavaScript value to RDF literal.
+ */
+function registerDataHandler(dataType, translateFromRDF, translateToRDF) {
+    rdfToNativeHandlers.set(dataType, translateFromRDF);
+    nativeToRdfHandlers.set(dataType, translateToRDF);
+}
+exports.registerDataHandler = registerDataHandler;
+function translateFromRdf(literal) {
+    const dataType = literal.datatype.value;
+    const customHandler = rdfToNativeHandlers.get(dataType);
+    if (customHandler) {
+        return customHandler(literal.value);
+    }
+    else {
+        return (0, rdf_js_1.fromRdf)(literal);
+    }
+}
+exports.translateFromRdf = translateFromRdf;
+function translateToRdf(value, dataType) {
+    const customHandler = nativeToRdfHandlers.get(dataType);
+    if (customHandler) {
+        return df.literal(customHandler(value), df.namedNode(dataType));
+    }
+    else {
+        return (0, rdf_js_1.toRdf)(value, {
+            datatype: df.namedNode(dataType),
+        });
+    }
+}
+exports.translateToRdf = translateToRdf;

package/script/mod.js

@@ -14,9 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setGlobalOptions = void 0;
+exports.registerDataHandler = exports.setGlobalOptions = void 0;
 var options_js_1 = require("./library/options.js");
 Object.defineProperty(exports, "setGlobalOptions", { enumerable: true, get: function () { return options_js_1.setGlobalOptions; } });
+var translator_js_1 = require("./library/translator.js");
+Object.defineProperty(exports, "registerDataHandler", { enumerable: true, get: function () { return translator_js_1.registerDataHandler; } });
 __exportStar(require("./library/lens/mod.js"), exports);
 __exportStar(require("./library/namespace.js"), exports);
 __exportStar(require("./library/engine/mod.js"), exports);

package/types/library/encoder.d.ts

@@ -3,5 +3,5 @@ import { DataFactory, type RDF } from "./rdf.js";
 import type { ExpandedSchema } from "./schema/mod.js";
 type DecodedNode = Record<string, unknown>;
 export declare const encode: (node: DecodedNode, schema: ExpandedSchema, options: Options, includeType?: boolean, variableInitCounter?: number) => RDF.Quad[];
-export declare const encodeValue: (value: unknown, datatype: string, df: DataFactory) => RDF.Literal | import("rdf-data-factory").NamedNode<string>;
+export declare const encodeValue: (value: unknown, datatype: string, df: DataFactory) => RDF.Literal | import("rdf-data-factory").Literal | import("rdf-data-factory").NamedNode<string>;
 export {};

package/types/library/schema/data_types.d.ts

@@ -2,8 +2,8 @@ import { xsd } from "../../namespaces/xsd.js";
 import { rdf } from "../../namespaces/rdf.js";
 import { ldkit } from "../../namespaces/ldkit.js";
 import { type IRI } from "../rdf.js";
-/** Map of supported RDF data types and their JavaScript native counterparts */
-export type SupportedDataTypes = {
+/** Map of default RDF data types and their JavaScript native counterparts */
+type DefaultDataTypes = {
     [xsd.dateTime]: Date;
     [xsd.date]: Date;
     [xsd.gDay]: Date;
@@ -42,5 +42,15 @@ export type SupportedDataTypes = {
     [xsd.duration]: string;
     [ldkit.IRI]: IRI;
 };
+/** Custom data types definition. Keys are type IRIs, values are JavaScript native types */
+export interface CustomDataTypes {
+}
+/**
+ * Map of supported RDF data types and their JavaScript native counterparts,
+ * combines default data types with custom data types.
+ * The keys are the IRIs of the data types, and the values are the corresponding JavaScript types.
+ */
+export type SupportedDataTypes = Omit<DefaultDataTypes, keyof CustomDataTypes> & CustomDataTypes;
 /** List of supported native JavaScript types */
 export type SupportedNativeTypes = SupportedDataTypes[keyof SupportedDataTypes];
+export {};

package/types/library/schema/mod.d.ts

@@ -1,4 +1,4 @@
-export type { SupportedDataTypes, SupportedNativeTypes } from "./data_types.js";
+export type { CustomDataTypes, SupportedDataTypes, SupportedNativeTypes, } from "./data_types.js";
 export type { Identity, SchemaInterface, SchemaSearchInterface, SchemaUpdateInterface, } from "./interface.js";
 export type { ExpandedProperty, ExpandedSchema, Property, Schema, } from "./schema.js";
 export type { SearchFilters, SearchSchema } from "./search.js";

package/types/library/translator.d.ts

@@ -0,0 +1,38 @@
+import { RDF } from "./rdf.js";
+import { SupportedDataTypes } from "./schema/mod.js";
+/**
+ * Registers a data type handler for translating between RDF literals and JavaScript values.
+ *
+ * In order to register a custom data type handler, the custom data type TypeScript mapping needs
+ * to be added to the {@link CustomDataTypes} interface using module augmentation.
+ *
+ * Two handlers are required:
+ * 1) A function to translate from RDF literal value (string) to JavaScript value.
+ * 2) A function to translate from JavaScript value to RDF literal value (string).
+ *
+ * @example
+ * ```typescript
+ * import { registerDataHandler } from "ldkit";
+ *
+ * const customNumberDataType = "http://example.org/number";
+ *
+ * declare module "ldkit" {
+ *   interface CustomDataTypes {
+ *     [customNumberDataType]: number;
+ *   }
+ * }
+ *
+ * registerDataHandler(
+ *   customNumberDataType,
+ *   (literalValue: string) => parseInt(literalValue),
+ *   (nativeValue: number) => nativeValue.toString(),
+ * );
+ * ```
+ *
+ * @param dataType - The data type to register.
+ * @param translateFromRDF - Function to translate from RDF literal to JavaScript value.
+ * @param translateToRDF - Function to translate from JavaScript value to RDF literal.
+ */
+export declare function registerDataHandler<T extends keyof SupportedDataTypes>(dataType: T, translateFromRDF: (literalValue: string) => SupportedDataTypes[T], translateToRDF: (nativeValue: SupportedDataTypes[T]) => string): void;
+export declare function translateFromRdf(literal: RDF.Literal): any;
+export declare function translateToRdf(value: unknown, dataType: keyof SupportedDataTypes | string): RDF.Literal | import("rdf-data-factory").Literal;

package/types/mod.d.ts

@@ -1,5 +1,6 @@
 export { type Options, setGlobalOptions } from "./library/options.js";
-export type { Identity, Property, Schema, SchemaInterface, SchemaSearchInterface, SchemaUpdateInterface, SupportedDataTypes, } from "./library/schema/mod.js";
+export type { CustomDataTypes, Identity, Property, Schema, SchemaInterface, SchemaSearchInterface, SchemaUpdateInterface, SupportedDataTypes, } from "./library/schema/mod.js";
+export { registerDataHandler } from "./library/translator.js";
 export * from "./library/lens/mod.js";
 export * from "./library/namespace.js";
 export * from "./library/engine/mod.js";