@twin.org/data-core 0.0.1-next.3

package/dist/esm/index.mjs

@@ -0,0 +1,249 @@
+import { Factory, Urn, Is, StringHelper } from '@twin.org/core';
+import { FetchHelper, HttpMethod } from '@twin.org/web';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Factory for creating handlers for data types.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const DataTypeHandlerFactory = Factory.createFactory("data-type");
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Factory for creating handlers for identifiers.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const IdentifierHandlerFactory = Factory.createFactory("namespace", false, (names, uri) => {
+    Urn.guard("IdentifierHandlerFactory", "uri", uri);
+    const urn = Urn.fromValidString(uri);
+    const urnParts = urn.parts();
+    for (let i = urnParts.length - 1; i >= 0; i--) {
+        const wholeNamespace = urnParts.slice(i).join(":");
+        if (names.includes(wholeNamespace)) {
+            return wholeNamespace;
+        }
+    }
+});
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Validation modes for validating data types.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const ValidationMode = {
+    /**
+     * Use the validation method of the data type.
+     */
+    Validate: "validate",
+    /**
+     * Use the JSON Schema methods of the data type.
+     */
+    JsonSchema: "json-schema",
+    /**
+     * Use either validation mode.
+     */
+    Either: "either"
+};
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * A helper for JSON schemas.
+ */
+class JsonSchemaHelper {
+    /**
+     * The schema version.
+     */
+    static SCHEMA_VERSION = "https://json-schema.org/draft/2020-12/schema";
+    /**
+     * The class name.
+     * @internal
+     */
+    static _CLASS_NAME = "JsonSchemaHelper";
+    /**
+     * Validates data against the schema.
+     * @param schema The schema to validate the data with.
+     * @param data The data to be validated.
+     * @param additionalTypes Additional types to add for reference, not already in DataTypeHandlerFactory.
+     * @returns Result containing errors if there are any.
+     */
+    static async validate(schema, data, additionalTypes) {
+        const ajv = new Ajv({
+            allowUnionTypes: true,
+            loadSchema: async (uri) => {
+                const subTypeHandler = DataTypeHandlerFactory.getIfExists(uri);
+                if (Is.function(subTypeHandler?.jsonSchema)) {
+                    const subSchema = await subTypeHandler.jsonSchema();
+                    if (Is.object(subSchema)) {
+                        return subSchema;
+                    }
+                }
+                try {
+                    // We don't have the type in our local data types, so we try to fetch it from the web
+                    return FetchHelper.fetchJson(JsonSchemaHelper._CLASS_NAME, uri, HttpMethod.GET, undefined, {
+                        // Cache for an hour
+                        cacheTtlMs: 3600000
+                    });
+                }
+                catch {
+                    // Failed to load remotely so return an empty object
+                    // so the schema validation doesn't completely fail
+                    return {};
+                }
+            }
+        });
+        addFormats(ajv);
+        // Add the additional types provided by the user
+        if (Is.objectValue(additionalTypes)) {
+            for (const key in additionalTypes) {
+                ajv.addSchema(additionalTypes[key], key);
+            }
+        }
+        const compiled = await ajv.compileAsync(schema);
+        const result = await compiled(data);
+        const output = {
+            result
+        };
+        if (!output.result) {
+            output.error = compiled.errors;
+        }
+        return output;
+    }
+    /**
+     * Get the property type from a schema.
+     * @param schema The schema to extract the types from.
+     * @param propertyName The name of the property to get the type for.
+     * @returns The types of the property.
+     */
+    static getPropertyType(schema, propertyName) {
+        if (schema.type === "object" && Is.objectValue(schema.properties)) {
+            const propertySchema = schema.properties[propertyName];
+            if (Is.object(propertySchema)) {
+                if (Is.stringValue(propertySchema.$ref)) {
+                    return propertySchema.$ref;
+                }
+                return propertySchema.type;
+            }
+        }
+    }
+    /**
+     * Convert an entity schema to JSON schema e.g https://example.com/schemas/.
+     * @param entitySchema The entity schema to convert.
+     * @param baseDomain The base domain for local schemas e.g. https://example.com/
+     * @returns The JSON schema for the entity.
+     */
+    static entitySchemaToJsonSchema(entitySchema, baseDomain) {
+        let domain = StringHelper.trimTrailingSlashes(baseDomain ?? "");
+        if (domain.length > 0) {
+            domain += "/";
+        }
+        const properties = {};
+        const required = [];
+        if (Is.arrayValue(entitySchema?.properties)) {
+            for (const propertySchema of entitySchema.properties) {
+                const jsonPropertySchema = {
+                    type: propertySchema.type,
+                    description: propertySchema.description,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    examples: propertySchema.examples
+                };
+                if (Is.stringValue(propertySchema.itemType) && propertySchema.type === "array") {
+                    if (propertySchema.itemType === "object") {
+                        jsonPropertySchema.items = {
+                            $ref: propertySchema.itemTypeRef?.startsWith("http")
+                                ? propertySchema.itemTypeRef
+                                : `${domain}${propertySchema.itemTypeRef}`
+                        };
+                    }
+                    else {
+                        jsonPropertySchema.items = {
+                            type: propertySchema.itemType
+                        };
+                    }
+                }
+                else if (propertySchema.type === "object") {
+                    delete jsonPropertySchema.type;
+                    jsonPropertySchema.$ref = propertySchema.itemTypeRef?.startsWith("http")
+                        ? propertySchema.itemTypeRef
+                        : `${domain}${propertySchema.itemTypeRef}`;
+                }
+                properties[propertySchema.property] = jsonPropertySchema;
+                if (!propertySchema.optional) {
+                    required.push(propertySchema.property);
+                }
+            }
+        }
+        return {
+            $schema: JsonSchemaHelper.SCHEMA_VERSION,
+            $id: `${domain}${entitySchema?.type}`,
+            title: entitySchema?.type,
+            type: entitySchema ? "object" : "null",
+            description: entitySchema?.options?.description,
+            required,
+            properties,
+            additionalProperties: false
+        };
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class to help with data types.
+ */
+class DataTypeHelper {
+    /**
+     * Validate a data type.
+     * @param propertyName The name of the property being validated to use in error messages.
+     * @param dataType The data type to validate.
+     * @param data The data to validate.
+     * @param validationFailures The list of validation failures to add to.
+     * @param validationMode The validation mode to use, defaults to either.
+     * @returns True if the data was valid.
+     */
+    static async validate(propertyName, dataType, data, validationFailures, validationMode) {
+        if (Is.stringValue(dataType)) {
+            const handler = DataTypeHandlerFactory.getIfExists(dataType);
+            if (handler) {
+                validationMode = validationMode ?? ValidationMode.Either;
+                // If we have a validate function use that as it is more specific
+                // and will produce better error messages
+                if ((validationMode === ValidationMode.Validate ||
+                    validationMode === ValidationMode.Either) &&
+                    Is.function(handler.validate)) {
+                    return handler.validate(propertyName, data, validationFailures);
+                }
+                else if ((validationMode === ValidationMode.JsonSchema ||
+                    validationMode === ValidationMode.Either) &&
+                    Is.function(handler.jsonSchema)) {
+                    // Otherwise use the JSON schema if there is one
+                    const schema = await handler.jsonSchema();
+                    if (Is.object(schema)) {
+                        const validationResult = await JsonSchemaHelper.validate(schema, data);
+                        if (Is.arrayValue(validationResult.error)) {
+                            validationFailures.push({
+                                property: propertyName,
+                                reason: "validation.schema.failedValidation",
+                                properties: {
+                                    value: data,
+                                    schemaErrors: validationResult.error,
+                                    message: validationResult.error.map(e => e.message).join(", ")
+                                }
+                            });
+                        }
+                        return validationResult.result;
+                    }
+                }
+            }
+        }
+        // Return true by default if no other mechanism for validation is available
+        return true;
+    }
+}
+
+export { DataTypeHandlerFactory, DataTypeHelper, IdentifierHandlerFactory, JsonSchemaHelper, ValidationMode };

package/dist/types/factories/dataTypeHandlerFactory.d.ts

@@ -0,0 +1,6 @@
+import { Factory } from "@twin.org/core";
+import type { IDataTypeHandler } from "../models/IDataTypeHandler";
+/**
+ * Factory for creating handlers for data types.
+ */
+export declare const DataTypeHandlerFactory: Factory<IDataTypeHandler>;

package/dist/types/factories/identifierHandlerFactory.d.ts

@@ -0,0 +1,6 @@
+import { Factory } from "@twin.org/core";
+import type { IIdentifierHandler } from "../models/IIdentifierHandler";
+/**
+ * Factory for creating handlers for identifiers.
+ */
+export declare const IdentifierHandlerFactory: Factory<IIdentifierHandler>;

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./factories/dataTypeHandlerFactory";
+export * from "./factories/identifierHandlerFactory";
+export * from "./models/IDataTypeHandler";
+export * from "./models/IIdentifierHandler";
+export * from "./models/ISchemaValidationError";
+export * from "./models/ISchemaValidationResult";
+export * from "./models/validationMode";
+export * from "./utils/dataTypeHelper";
+export * from "./utils/jsonSchemaHelper";

package/dist/types/models/IDataTypeHandler.d.ts

@@ -0,0 +1,29 @@
+import type { IValidationFailure } from "@twin.org/core";
+import type { JSONSchema7 } from "json-schema";
+/**
+ * Interface describing a type which can handle a specific data type.
+ */
+export interface IDataTypeHandler {
+    /**
+     * The type for the item.
+     */
+    type: string;
+    /**
+     * The default value for the item.
+     */
+    defaultValue?: unknown;
+    /**
+     * Get the JSON schema for the data type.
+     * @returns The JSON schema for the data type.
+     */
+    jsonSchema?(): Promise<JSONSchema7 | undefined>;
+    /**
+     * A method for validating the data type.
+     * @param propertyName The name of the property being validated.
+     * @param value The value to validate.
+     * @param failures List of failures to add to.
+     * @param container The object which contains this one.
+     * @returns True if the item is valid.
+     */
+    validate?(propertyName: string, value: unknown, failures: IValidationFailure[], container?: unknown): Promise<boolean>;
+}

package/dist/types/models/IIdentifierHandler.d.ts

@@ -0,0 +1,18 @@
+import type { IValidationFailure } from "@twin.org/core";
+/**
+ * Interface describing a type which can handle a specific urn namespace.
+ */
+export interface IIdentifierHandler {
+    /**
+     * The namespace for the identifier.
+     */
+    namespace: string;
+    /**
+     * A method for validating the identifier.
+     * @param propertyName The name of the property being validated.
+     * @param value The value to validate.
+     * @param failures List of failures to add to.
+     * @returns True if the item is valid.
+     */
+    validate(propertyName: string, value: unknown, failures: IValidationFailure[]): boolean;
+}

package/dist/types/models/ISchemaValidationError.d.ts

@@ -0,0 +1,5 @@
+import type { ErrorObject } from "ajv";
+/**
+ * Schema validation error.
+ */
+export type ISchemaValidationError = ErrorObject[];

package/dist/types/models/ISchemaValidationResult.d.ts

@@ -0,0 +1,14 @@
+import type { ISchemaValidationError } from "./ISchemaValidationError";
+/**
+ * Validation result.
+ */
+export interface ISchemaValidationResult {
+    /**
+     * The result.
+     */
+    result: boolean;
+    /**
+     * The error.
+     */
+    error?: ISchemaValidationError;
+}

package/dist/types/models/validationMode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validation modes for validating data types.
+ */
+export declare const ValidationMode: {
+    /**
+     * Use the validation method of the data type.
+     */
+    readonly Validate: "validate";
+    /**
+     * Use the JSON Schema methods of the data type.
+     */
+    readonly JsonSchema: "json-schema";
+    /**
+     * Use either validation mode.
+     */
+    readonly Either: "either";
+};
+/**
+ * Validation modes for validating data types.
+ */
+export type ValidationMode = (typeof ValidationMode)[keyof typeof ValidationMode];

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

@@ -0,0 +1,17 @@
+import { type IValidationFailure } from "@twin.org/core";
+import { ValidationMode } from "../models/validationMode";
+/**
+ * Class to help with data types.
+ */
+export declare class DataTypeHelper {
+    /**
+     * Validate a data type.
+     * @param propertyName The name of the property being validated to use in error messages.
+     * @param dataType The data type to validate.
+     * @param data The data to validate.
+     * @param validationFailures The list of validation failures to add to.
+     * @param validationMode The validation mode to use, defaults to either.
+     * @returns True if the data was valid.
+     */
+    static validate(propertyName: string, dataType: string | undefined, data: unknown, validationFailures: IValidationFailure[], validationMode?: ValidationMode): Promise<boolean>;
+}

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

@@ -0,0 +1,36 @@
+import type { IEntitySchema } from "@twin.org/entity";
+import type { JSONSchema7 } from "json-schema";
+import type { ISchemaValidationResult } from "../models/ISchemaValidationResult";
+/**
+ * A helper for JSON schemas.
+ */
+export declare class JsonSchemaHelper {
+    /**
+     * The schema version.
+     */
+    static readonly SCHEMA_VERSION = "https://json-schema.org/draft/2020-12/schema";
+    /**
+     * Validates data against the schema.
+     * @param schema The schema to validate the data with.
+     * @param data The data to be validated.
+     * @param additionalTypes Additional types to add for reference, not already in DataTypeHandlerFactory.
+     * @returns Result containing errors if there are any.
+     */
+    static validate<T = unknown>(schema: JSONSchema7, data: T, additionalTypes?: {
+        [id: string]: JSONSchema7;
+    }): Promise<ISchemaValidationResult>;
+    /**
+     * Get the property type from a schema.
+     * @param schema The schema to extract the types from.
+     * @param propertyName The name of the property to get the type for.
+     * @returns The types of the property.
+     */
+    static getPropertyType(schema: JSONSchema7, propertyName: string): string | undefined;
+    /**
+     * Convert an entity schema to JSON schema e.g https://example.com/schemas/.
+     * @param entitySchema The entity schema to convert.
+     * @param baseDomain The base domain for local schemas e.g. https://example.com/
+     * @returns The JSON schema for the entity.
+     */
+    static entitySchemaToJsonSchema(entitySchema: IEntitySchema | undefined, baseDomain?: string): JSONSchema7;
+}

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/data-core - Changelog
+
+## v0.0.1-next.3
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/data-core - Examples

package/docs/reference/classes/DataTypeHelper.md

@@ -0,0 +1,49 @@
+# Class: DataTypeHelper
+
+Class to help with data types.
+
+## Constructors
+
+### new DataTypeHelper()
+
+> **new DataTypeHelper**(): [`DataTypeHelper`](DataTypeHelper.md)
+
+#### Returns
+
+[`DataTypeHelper`](DataTypeHelper.md)
+
+## Methods
+
+### validate()
+
+> `static` **validate**(`propertyName`, `dataType`, `data`, `validationFailures`, `validationMode`?): `Promise`\<`boolean`\>
+
+Validate a data type.
+
+#### Parameters
+
+• **propertyName**: `string`
+
+The name of the property being validated to use in error messages.
+
+• **dataType**: `undefined` \| `string`
+
+The data type to validate.
+
+• **data**: `unknown`
+
+The data to validate.
+
+• **validationFailures**: `IValidationFailure`[]
+
+The list of validation failures to add to.
+
+• **validationMode?**: [`ValidationMode`](../type-aliases/ValidationMode.md)
+
+The validation mode to use, defaults to either.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the data was valid.

package/docs/reference/classes/JsonSchemaHelper.md

@@ -0,0 +1,101 @@
+# Class: JsonSchemaHelper
+
+A helper for JSON schemas.
+
+## Constructors
+
+### new JsonSchemaHelper()
+
+> **new JsonSchemaHelper**(): [`JsonSchemaHelper`](JsonSchemaHelper.md)
+
+#### Returns
+
+[`JsonSchemaHelper`](JsonSchemaHelper.md)
+
+## Properties
+
+### SCHEMA\_VERSION
+
+> `readonly` `static` **SCHEMA\_VERSION**: `"https://json-schema.org/draft/2020-12/schema"` = `"https://json-schema.org/draft/2020-12/schema"`
+
+The schema version.
+
+## Methods
+
+### validate()
+
+> `static` **validate**\<`T`\>(`schema`, `data`, `additionalTypes`?): `Promise`\<[`ISchemaValidationResult`](../interfaces/ISchemaValidationResult.md)\>
+
+Validates data against the schema.
+
+#### Type Parameters
+
+• **T** = `unknown`
+
+#### Parameters
+
+• **schema**: `JSONSchema7`
+
+The schema to validate the data with.
+
+• **data**: `T`
+
+The data to be validated.
+
+• **additionalTypes?**
+
+Additional types to add for reference, not already in DataTypeHandlerFactory.
+
+#### Returns
+
+`Promise`\<[`ISchemaValidationResult`](../interfaces/ISchemaValidationResult.md)\>
+
+Result containing errors if there are any.
+
+***
+
+### getPropertyType()
+
+> `static` **getPropertyType**(`schema`, `propertyName`): `undefined` \| `string`
+
+Get the property type from a schema.
+
+#### Parameters
+
+• **schema**: `JSONSchema7`
+
+The schema to extract the types from.
+
+• **propertyName**: `string`
+
+The name of the property to get the type for.
+
+#### Returns
+
+`undefined` \| `string`
+
+The types of the property.
+
+***
+
+### entitySchemaToJsonSchema()
+
+> `static` **entitySchemaToJsonSchema**(`entitySchema`, `baseDomain`?): `JSONSchema7`
+
+Convert an entity schema to JSON schema e.g https://example.com/schemas/.
+
+#### Parameters
+
+• **entitySchema**: `undefined` \| `IEntitySchema`\<`unknown`\>
+
+The entity schema to convert.
+
+• **baseDomain?**: `string`
+
+The base domain for local schemas e.g. https://example.com/
+
+#### Returns
+
+`JSONSchema7`
+
+The JSON schema for the entity.

package/docs/reference/index.md

@@ -0,0 +1,23 @@
+# @twin.org/data-core
+
+## Classes
+
+- [DataTypeHelper](classes/DataTypeHelper.md)
+- [JsonSchemaHelper](classes/JsonSchemaHelper.md)
+
+## Interfaces
+
+- [IDataTypeHandler](interfaces/IDataTypeHandler.md)
+- [IIdentifierHandler](interfaces/IIdentifierHandler.md)
+- [ISchemaValidationResult](interfaces/ISchemaValidationResult.md)
+
+## Type Aliases
+
+- [ISchemaValidationError](type-aliases/ISchemaValidationError.md)
+- [ValidationMode](type-aliases/ValidationMode.md)
+
+## Variables
+
+- [DataTypeHandlerFactory](variables/DataTypeHandlerFactory.md)
+- [IdentifierHandlerFactory](variables/IdentifierHandlerFactory.md)
+- [ValidationMode](variables/ValidationMode.md)

package/docs/reference/interfaces/IDataTypeHandler.md

@@ -0,0 +1,65 @@
+# Interface: IDataTypeHandler
+
+Interface describing a type which can handle a specific data type.
+
+## Properties
+
+### type
+
+> **type**: `string`
+
+The type for the item.
+
+***
+
+### defaultValue?
+
+> `optional` **defaultValue**: `unknown`
+
+The default value for the item.
+
+## Methods
+
+### jsonSchema()?
+
+> `optional` **jsonSchema**(): `Promise`\<`undefined` \| `JSONSchema7`\>
+
+Get the JSON schema for the data type.
+
+#### Returns
+
+`Promise`\<`undefined` \| `JSONSchema7`\>
+
+The JSON schema for the data type.
+
+***
+
+### validate()?
+
+> `optional` **validate**(`propertyName`, `value`, `failures`, `container`?): `Promise`\<`boolean`\>
+
+A method for validating the data type.
+
+#### Parameters
+
+• **propertyName**: `string`
+
+The name of the property being validated.
+
+• **value**: `unknown`
+
+The value to validate.
+
+• **failures**: `IValidationFailure`[]
+
+List of failures to add to.
+
+• **container?**: `unknown`
+
+The object which contains this one.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the item is valid.