@twin.org/core 0.0.2-next.9 → 0.0.3-next.2

package/dist/es/factories/factory.js

@@ -0,0 +1,256 @@
+import { GeneralError } from "../errors/generalError.js";
+import { Guards } from "../utils/guards.js";
+import { Is } from "../utils/is.js";
+import { SharedStore } from "../utils/sharedStore.js";
+/**
+ * Factory for creating implementation of generic types.
+ */
+export class Factory {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "Factory";
+    /**
+     * Type name for the instances.
+     * @internal
+     */
+    _typeName;
+    /**
+     * Store the generators.
+     * @internal
+     */
+    _generators;
+    /**
+     * Store the created instances.
+     * @internal
+     */
+    _instances;
+    /**
+     * Counter for the ordering.
+     * @internal
+     */
+    _orderCounter;
+    /**
+     * Automatically created an instance when registered.
+     * @internal
+     */
+    _autoInstance;
+    /**
+     * Match the name of the instance.
+     * @internal
+     */
+    _matcher;
+    /**
+     * Create a new instance of Factory, private use createFactory.
+     * @param typeName The type name for the instances.
+     * @param autoInstance Automatically create an instance when registered.
+     * @param matcher Match the name of the instance.
+     * @internal
+     */
+    constructor(typeName, autoInstance = false, matcher) {
+        this._typeName = typeName;
+        this._generators = {};
+        this._instances = {};
+        this._orderCounter = 0;
+        this._autoInstance = autoInstance;
+        this._matcher = matcher ?? this.defaultMatcher.bind(this);
+    }
+    /**
+     * Create a new factory, which is shared throughout all library instances.
+     * @param typeName The type name for the instances.
+     * @param autoInstance Automatically create an instance when registered.
+     * @param matcher Match the name of the instance.
+     * @returns The factory instance.
+     */
+    static createFactory(typeName, autoInstance = false, matcher) {
+        const factories = Factory.getFactories();
+        if (Is.undefined(factories[typeName])) {
+            factories[typeName] = new Factory(typeName, autoInstance, matcher);
+        }
+        return factories[typeName];
+    }
+    /**
+     * Get all the factories.
+     * @returns All the factories.
+     */
+    static getFactories() {
+        let factories = SharedStore.get("factories");
+        if (Is.undefined(factories)) {
+            factories = {};
+            SharedStore.set("factories", factories);
+        }
+        return factories;
+    }
+    /**
+     * Reset all the factories, which removes any created instances, but not the registrations.
+     */
+    static resetFactories() {
+        const factories = Factory.getFactories();
+        for (const typeName in factories) {
+            factories[typeName].reset();
+        }
+    }
+    /**
+     * Clear all the factories, which removes anything registered with the factories.
+     */
+    static clearFactories() {
+        const factories = Factory.getFactories();
+        for (const typeName in factories) {
+            factories[typeName].clear();
+        }
+    }
+    /**
+     * Register a new generator.
+     * @param name The name of the generator.
+     * @param generator The function to create an instance.
+     */
+    register(name, generator) {
+        Guards.stringValue(Factory.CLASS_NAME, "name", name);
+        Guards.function(Factory.CLASS_NAME, "generator", generator);
+        this._generators[name] = {
+            generator,
+            order: this._orderCounter++
+        };
+        // Remove any existing instance
+        this.removeInstance(name);
+        if (this._autoInstance) {
+            this._instances[name] = generator();
+        }
+    }
+    /**
+     * Unregister a generator.
+     * @param name The name of the generator to unregister.
+     * @throws GuardError if the parameters are invalid.
+     * @throws GeneralError if no generator exists.
+     */
+    unregister(name) {
+        Guards.stringValue(Factory.CLASS_NAME, "name", name);
+        if (!this._generators[name]) {
+            throw new GeneralError(Factory.CLASS_NAME, "noUnregister", {
+                typeName: this._typeName,
+                name
+            });
+        }
+        delete this._generators[name];
+        // Remove any existing instance
+        this.removeInstance(name);
+    }
+    /**
+     * Get a generator instance.
+     * @param name The name of the instance to generate.
+     * @returns An instance of the item.
+     * @throws GuardError if the parameters are invalid.
+     * @throws GeneralError if no item exists to get.
+     */
+    get(name) {
+        Guards.stringValue(Factory.CLASS_NAME, "name", name);
+        const instance = this.getIfExists(name);
+        if (!instance) {
+            throw new GeneralError(Factory.CLASS_NAME, "noGet", {
+                typeName: this._typeName,
+                name
+            });
+        }
+        return instance;
+    }
+    /**
+     * Get a generator instance with no exceptions.
+     * @param name The name of the instance to generate.
+     * @returns An instance of the item or undefined if it does not exist.
+     */
+    getIfExists(name) {
+        if (Is.empty(name)) {
+            return;
+        }
+        Guards.stringValue(Factory.CLASS_NAME, "name", name);
+        const matchName = this._matcher(Object.keys(this._generators), name);
+        if (Is.stringValue(matchName) && this._generators[matchName]) {
+            if (!this._instances[matchName]) {
+                this._instances[matchName] = this._generators[matchName].generator();
+            }
+            if (this._instances[matchName]) {
+                return this._instances[matchName];
+            }
+        }
+    }
+    /**
+     * Remove all the instances and leave the generators intact.
+     */
+    reset() {
+        for (const name in this._generators) {
+            this.removeInstance(name);
+        }
+        this._instances = {};
+    }
+    /**
+     * Remove all the instances and the generators.
+     */
+    clear() {
+        this._instances = {};
+        this._generators = {};
+        this._orderCounter = 0;
+    }
+    /**
+     * Get all the instances as a map.
+     * @returns The instances as a map.
+     */
+    instancesMap() {
+        return this._instances;
+    }
+    /**
+     * Get all the instances as a list in the order they were registered.
+     * @returns The instances as a list in the order they were registered.
+     */
+    instancesList() {
+        const orderedInstances = [];
+        for (const instanceName in this._instances) {
+            orderedInstances.push({
+                instance: this._instances[instanceName],
+                order: this._generators[instanceName].order
+            });
+        }
+        return orderedInstances.sort((a, b) => a.order - b.order).map(o => o.instance);
+    }
+    /**
+     * Get all the generator names in the order they were registered.
+     * @returns The ordered generator names.
+     */
+    names() {
+        const orderedNames = [];
+        for (const generator in this._generators) {
+            orderedNames.push({
+                name: generator,
+                order: this._generators[generator].order
+            });
+        }
+        return orderedNames.sort((a, b) => a.order - b.order).map(o => o.name);
+    }
+    /**
+     * Does the factory contain the name.
+     * @param name The name of the instance to find.
+     * @returns True if the factory has a matching name.
+     */
+    hasName(name) {
+        Guards.stringValue(Factory.CLASS_NAME, "name", name);
+        return Is.stringValue(this._matcher(Object.keys(this._generators), name));
+    }
+    /**
+     * Remove any instances of the given name.
+     * @param name The name of the instances to remove.
+     * @internal
+     */
+    removeInstance(name) {
+        delete this._instances[name];
+    }
+    /**
+     * Match the requested name to the generator name.
+     * @param names The list of names for all the generators.
+     * @param name The name to match.
+     * @returns The matched name or undefined if no match.
+     * @internal
+     */
+    defaultMatcher(names, name) {
+        return this._generators[name] ? name : undefined;
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/es/factories/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/factories/factory.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { nameof } from \"@twin.org/nameof\";\nimport { GeneralError } from \"../errors/generalError.js\";\nimport { Guards } from \"../utils/guards.js\";\nimport { Is } from \"../utils/is.js\";\nimport { SharedStore } from \"../utils/sharedStore.js\";\n\n/**\n * Factory for creating implementation of generic types.\n */\nexport class Factory<T> {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<Factory<unknown>>();\n\n\t/**\n\t * Type name for the instances.\n\t * @internal\n\t */\n\tprivate readonly _typeName: string;\n\n\t/**\n\t * Store the generators.\n\t * @internal\n\t */\n\tprivate _generators: {\n\t\t[name: string]: {\n\t\t\tgenerator: () => T;\n\t\t\torder: number;\n\t\t};\n\t};\n\n\t/**\n\t * Store the created instances.\n\t * @internal\n\t */\n\tprivate _instances: { [name: string]: T };\n\n\t/**\n\t * Counter for the ordering.\n\t * @internal\n\t */\n\tprivate _orderCounter: number;\n\n\t/**\n\t * Automatically created an instance when registered.\n\t * @internal\n\t */\n\tprivate readonly _autoInstance: boolean;\n\n\t/**\n\t * Match the name of the instance.\n\t * @internal\n\t */\n\tprivate readonly _matcher: (names: string[], name: string) => string | undefined;\n\n\t/**\n\t * Create a new instance of Factory, private use createFactory.\n\t * @param typeName The type name for the instances.\n\t * @param autoInstance Automatically create an instance when registered.\n\t * @param matcher Match the name of the instance.\n\t * @internal\n\t */\n\tprivate constructor(\n\t\ttypeName: string,\n\t\tautoInstance: boolean = false,\n\t\tmatcher?: (names: string[], name: string) => string | undefined\n\t) {\n\t\tthis._typeName = typeName;\n\t\tthis._generators = {};\n\t\tthis._instances = {};\n\t\tthis._orderCounter = 0;\n\t\tthis._autoInstance = autoInstance;\n\t\tthis._matcher = matcher ?? this.defaultMatcher.bind(this);\n\t}\n\n\t/**\n\t * Create a new factory, which is shared throughout all library instances.\n\t * @param typeName The type name for the instances.\n\t * @param autoInstance Automatically create an instance when registered.\n\t * @param matcher Match the name of the instance.\n\t * @returns The factory instance.\n\t */\n\tpublic static createFactory<U>(\n\t\ttypeName: string,\n\t\tautoInstance: boolean = false,\n\t\tmatcher?: (names: string[], name: string) => string | undefined\n\t): Factory<U> {\n\t\tconst factories = Factory.getFactories();\n\n\t\tif (Is.undefined(factories[typeName])) {\n\t\t\tfactories[typeName] = new Factory<U>(typeName, autoInstance, matcher);\n\t\t}\n\t\treturn factories[typeName] as Factory<U>;\n\t}\n\n\t/**\n\t * Get all the factories.\n\t * @returns All the factories.\n\t */\n\tpublic static getFactories(): { [typeName: string]: Factory<unknown> } {\n\t\tlet factories = SharedStore.get<{\n\t\t\t[typeName: string]: Factory<unknown>;\n\t\t}>(\"factories\");\n\n\t\tif (Is.undefined(factories)) {\n\t\t\tfactories = {};\n\t\t\tSharedStore.set(\"factories\", factories);\n\t\t}\n\n\t\treturn factories;\n\t}\n\n\t/**\n\t * Reset all the factories, which removes any created instances, but not the registrations.\n\t */\n\tpublic static resetFactories(): void {\n\t\tconst factories = Factory.getFactories();\n\n\t\tfor (const typeName in factories) {\n\t\t\tfactories[typeName].reset();\n\t\t}\n\t}\n\n\t/**\n\t * Clear all the factories, which removes anything registered with the factories.\n\t */\n\tpublic static clearFactories(): void {\n\t\tconst factories = Factory.getFactories();\n\n\t\tfor (const typeName in factories) {\n\t\t\tfactories[typeName].clear();\n\t\t}\n\t}\n\n\t/**\n\t * Register a new generator.\n\t * @param name The name of the generator.\n\t * @param generator The function to create an instance.\n\t */\n\tpublic register<U extends T>(name: string, generator: () => U): void {\n\t\tGuards.stringValue(Factory.CLASS_NAME, nameof(name), name);\n\t\tGuards.function(Factory.CLASS_NAME, nameof(generator), generator);\n\t\tthis._generators[name] = {\n\t\t\tgenerator,\n\t\t\torder: this._orderCounter++\n\t\t};\n\t\t// Remove any existing instance\n\t\tthis.removeInstance(name);\n\t\tif (this._autoInstance) {\n\t\t\tthis._instances[name] = generator();\n\t\t}\n\t}\n\n\t/**\n\t * Unregister a generator.\n\t * @param name The name of the generator to unregister.\n\t * @throws GuardError if the parameters are invalid.\n\t * @throws GeneralError if no generator exists.\n\t */\n\tpublic unregister(name: string): void {\n\t\tGuards.stringValue(Factory.CLASS_NAME, nameof(name), name);\n\t\tif (!this._generators[name]) {\n\t\t\tthrow new GeneralError(Factory.CLASS_NAME, \"noUnregister\", {\n\t\t\t\ttypeName: this._typeName,\n\t\t\t\tname\n\t\t\t});\n\t\t}\n\t\tdelete this._generators[name];\n\t\t// Remove any existing instance\n\t\tthis.removeInstance(name);\n\t}\n\n\t/**\n\t * Get a generator instance.\n\t * @param name The name of the instance to generate.\n\t * @returns An instance of the item.\n\t * @throws GuardError if the parameters are invalid.\n\t * @throws GeneralError if no item exists to get.\n\t */\n\tpublic get<U extends T>(name: string): U {\n\t\tGuards.stringValue(Factory.CLASS_NAME, nameof(name), name);\n\t\tconst instance = this.getIfExists(name);\n\t\tif (!instance) {\n\t\t\tthrow new GeneralError(Factory.CLASS_NAME, \"noGet\", {\n\t\t\t\ttypeName: this._typeName,\n\t\t\t\tname\n\t\t\t});\n\t\t}\n\t\treturn instance as U;\n\t}\n\n\t/**\n\t * Get a generator instance with no exceptions.\n\t * @param name The name of the instance to generate.\n\t * @returns An instance of the item or undefined if it does not exist.\n\t */\n\tpublic getIfExists<U extends T>(name?: string): U | undefined {\n\t\tif (Is.empty(name)) {\n\t\t\treturn;\n\t\t}\n\t\tGuards.stringValue(Factory.CLASS_NAME, nameof(name), name);\n\n\t\tconst matchName = this._matcher(Object.keys(this._generators), name);\n\n\t\tif (Is.stringValue(matchName) && this._generators[matchName]) {\n\t\t\tif (!this._instances[matchName]) {\n\t\t\t\tthis._instances[matchName] = this._generators[matchName].generator();\n\t\t\t}\n\t\t\tif (this._instances[matchName]) {\n\t\t\t\treturn this._instances[matchName] as U;\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Remove all the instances and leave the generators intact.\n\t */\n\tpublic reset(): void {\n\t\tfor (const name in this._generators) {\n\t\t\tthis.removeInstance(name);\n\t\t}\n\t\tthis._instances = {};\n\t}\n\n\t/**\n\t * Remove all the instances and the generators.\n\t */\n\tpublic clear(): void {\n\t\tthis._instances = {};\n\t\tthis._generators = {};\n\t\tthis._orderCounter = 0;\n\t}\n\n\t/**\n\t * Get all the instances as a map.\n\t * @returns The instances as a map.\n\t */\n\tpublic instancesMap(): { [name: string]: T } {\n\t\treturn this._instances;\n\t}\n\n\t/**\n\t * Get all the instances as a list in the order they were registered.\n\t * @returns The instances as a list in the order they were registered.\n\t */\n\tpublic instancesList(): T[] {\n\t\tconst orderedInstances: { instance: T; order: number }[] = [];\n\t\tfor (const instanceName in this._instances) {\n\t\t\torderedInstances.push({\n\t\t\t\tinstance: this._instances[instanceName],\n\t\t\t\torder: this._generators[instanceName].order\n\t\t\t});\n\t\t}\n\t\treturn orderedInstances.sort((a, b) => a.order - b.order).map(o => o.instance);\n\t}\n\n\t/**\n\t * Get all the generator names in the order they were registered.\n\t * @returns The ordered generator names.\n\t */\n\tpublic names(): string[] {\n\t\tconst orderedNames: { name: string; order: number }[] = [];\n\t\tfor (const generator in this._generators) {\n\t\t\torderedNames.push({\n\t\t\t\tname: generator,\n\t\t\t\torder: this._generators[generator].order\n\t\t\t});\n\t\t}\n\t\treturn orderedNames.sort((a, b) => a.order - b.order).map(o => o.name);\n\t}\n\n\t/**\n\t * Does the factory contain the name.\n\t * @param name The name of the instance to find.\n\t * @returns True if the factory has a matching name.\n\t */\n\tpublic hasName(name: string): boolean {\n\t\tGuards.stringValue(Factory.CLASS_NAME, nameof(name), name);\n\t\treturn Is.stringValue(this._matcher(Object.keys(this._generators), name));\n\t}\n\n\t/**\n\t * Remove any instances of the given name.\n\t * @param name The name of the instances to remove.\n\t * @internal\n\t */\n\tprivate removeInstance(name: string): void {\n\t\tdelete this._instances[name];\n\t}\n\n\t/**\n\t * Match the requested name to the generator name.\n\t * @param names The list of names for all the generators.\n\t * @param name The name to match.\n\t * @returns The matched name or undefined if no match.\n\t * @internal\n\t */\n\tprivate defaultMatcher(names: string[], name: string): string | undefined {\n\t\treturn this._generators[name] ? name : undefined;\n\t}\n}\n"]}

package/dist/es/helpers/arrayHelper.js

@@ -0,0 +1,44 @@
+import { Is } from "../utils/is.js";
+/**
+ * Class to help with arrays.
+ */
+export class ArrayHelper {
+    /**
+     * Do the two arrays match.
+     * @param arr1 The first array.
+     * @param arr2 The second array.
+     * @returns True if both arrays are empty of have the same values.
+     */
+    static matches(arr1, arr2) {
+        if (Is.empty(arr1) && Is.empty(arr2)) {
+            return true;
+        }
+        if (!((Is.array(arr1) && Is.array(arr2)) || (Is.typedArray(arr1) && Is.typedArray(arr2)))) {
+            return false;
+        }
+        if (arr1.length !== arr2.length) {
+            return false;
+        }
+        for (let i = 0; i < arr1.length; i++) {
+            if (arr1[i] !== arr2[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Convert an object or array to an array.
+     * @param value The object or array to convert.
+     * @returns The array.
+     */
+    static fromObjectOrArray(value) {
+        if (Is.empty(value)) {
+            return undefined;
+        }
+        if (Is.array(value)) {
+            return value;
+        }
+        return [value];
+    }
+}
+//# sourceMappingURL=arrayHelper.js.map

package/dist/es/helpers/arrayHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayHelper.js","sourceRoot":"","sources":["../../../src/helpers/arrayHelper.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAEpC;;GAEG;AACH,MAAM,OAAO,WAAW;IACvB;;;;;OAKG;IACI,MAAM,CAAC,OAAO,CAAC,IAAa,EAAE,IAAa;QACjD,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC;QACb,CAAC;QACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3F,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YACjC,OAAO,KAAK,CAAC;QACd,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzB,OAAO,KAAK,CAAC;YACd,CAAC;QACF,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;IAeD;;;;OAIG;IACI,MAAM,CAAC,iBAAiB,CAC9B,KAAmC;QAEnC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,IAAI,EAAE,CAAC,KAAK,CAAI,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACd,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { ObjectOrArray } from \"../models/objectOrArray.js\";\nimport { Is } from \"../utils/is.js\";\n\n/**\n * Class to help with arrays.\n */\nexport class ArrayHelper {\n\t/**\n\t * Do the two arrays match.\n\t * @param arr1 The first array.\n\t * @param arr2 The second array.\n\t * @returns True if both arrays are empty of have the same values.\n\t */\n\tpublic static matches(arr1: unknown, arr2: unknown): boolean {\n\t\tif (Is.empty(arr1) && Is.empty(arr2)) {\n\t\t\treturn true;\n\t\t}\n\t\tif (!((Is.array(arr1) && Is.array(arr2)) || (Is.typedArray(arr1) && Is.typedArray(arr2)))) {\n\t\t\treturn false;\n\t\t}\n\t\tif (arr1.length !== arr2.length) {\n\t\t\treturn false;\n\t\t}\n\t\tfor (let i = 0; i < arr1.length; i++) {\n\t\t\tif (arr1[i] !== arr2[i]) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\treturn true;\n\t}\n\n\t/**\n\t * Convert an object or array to an array.\n\t * @param value The object or array to convert.\n\t * @returns The array.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/no-unused-vars\n\tpublic static fromObjectOrArray<T = unknown>(value: undefined): undefined;\n\t/**\n\t * Convert an object or array to an array.\n\t * @param value The object or array to convert.\n\t * @returns The array.\n\t */\n\tpublic static fromObjectOrArray<T = unknown>(value: ObjectOrArray<T>): T[];\n\t/**\n\t * Convert an object or array to an array.\n\t * @param value The object or array to convert.\n\t * @returns The array.\n\t */\n\tpublic static fromObjectOrArray<T = unknown>(\n\t\tvalue: ObjectOrArray<T> | undefined\n\t): T[] | undefined {\n\t\tif (Is.empty(value)) {\n\t\t\treturn undefined;\n\t\t}\n\t\tif (Is.array<T>(value)) {\n\t\t\treturn value;\n\t\t}\n\t\treturn [value];\n\t}\n}\n"]}

package/dist/es/helpers/envHelper.js

@@ -0,0 +1,39 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { ObjectHelper } from "./objectHelper.js";
+import { StringHelper } from "./stringHelper.js";
+import { Is } from "../utils/is.js";
+/**
+ * Environment variable helper.
+ */
+export class EnvHelper {
+    /**
+     * Get the environment variable as an object with camel cased names.
+     * @param envVars The environment variables.
+     * @param prefix The prefix of the environment variables, if not provided gets all.
+     * @returns The object with camel cased names.
+     */
+    static envToJson(envVars, prefix) {
+        const result = {};
+        if (!Is.empty(envVars)) {
+            if (Is.empty(prefix)) {
+                for (const envVar in envVars) {
+                    if (Is.stringValue(envVars[envVar])) {
+                        const camelCaseName = StringHelper.camelCase(envVar.toLowerCase());
+                        ObjectHelper.propertySet(result, camelCaseName, envVars[envVar]);
+                    }
+                }
+            }
+            else {
+                for (const envVar in envVars) {
+                    if (envVar.startsWith(prefix) && Is.stringValue(envVars[envVar])) {
+                        const camelCaseName = StringHelper.camelCase(envVar.replace(prefix, "").toLowerCase());
+                        ObjectHelper.propertySet(result, camelCaseName, envVars[envVar]);
+                    }
+                }
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=envHelper.js.map

package/dist/es/helpers/envHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envHelper.js","sourceRoot":"","sources":["../../../src/helpers/envHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAEpC;;GAEG;AACH,MAAM,OAAO,SAAS;IACrB;;;;;OAKG;IACI,MAAM,CAAC,SAAS,CACtB,OAA6C,EAC7C,MAAe;QAEf,MAAM,MAAM,GAA6B,EAAE,CAAC;QAE5C,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBACtB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC9B,IAAI,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;wBACrC,MAAM,aAAa,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;wBACnE,YAAY,CAAC,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;oBAClE,CAAC;gBACF,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC9B,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;wBAClE,MAAM,aAAa,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;wBACvF,YAAY,CAAC,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;oBAClE,CAAC;gBACF,CAAC;YACF,CAAC;QACF,CAAC;QAED,OAAO,MAAW,CAAC;IACpB,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { ObjectHelper } from \"./objectHelper.js\";\nimport { StringHelper } from \"./stringHelper.js\";\nimport { Is } from \"../utils/is.js\";\n\n/**\n * Environment variable helper.\n */\nexport class EnvHelper {\n\t/**\n\t * Get the environment variable as an object with camel cased names.\n\t * @param envVars The environment variables.\n\t * @param prefix The prefix of the environment variables, if not provided gets all.\n\t * @returns The object with camel cased names.\n\t */\n\tpublic static envToJson<T = { [id: string]: string }>(\n\t\tenvVars: { [id: string]: string | undefined },\n\t\tprefix?: string\n\t): T {\n\t\tconst result: { [id: string]: string } = {};\n\n\t\tif (!Is.empty(envVars)) {\n\t\t\tif (Is.empty(prefix)) {\n\t\t\t\tfor (const envVar in envVars) {\n\t\t\t\t\tif (Is.stringValue(envVars[envVar])) {\n\t\t\t\t\t\tconst camelCaseName = StringHelper.camelCase(envVar.toLowerCase());\n\t\t\t\t\t\tObjectHelper.propertySet(result, camelCaseName, envVars[envVar]);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tfor (const envVar in envVars) {\n\t\t\t\t\tif (envVar.startsWith(prefix) && Is.stringValue(envVars[envVar])) {\n\t\t\t\t\t\tconst camelCaseName = StringHelper.camelCase(envVar.replace(prefix, \"\").toLowerCase());\n\t\t\t\t\t\tObjectHelper.propertySet(result, camelCaseName, envVars[envVar]);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn result as T;\n\t}\n}\n"]}

package/dist/es/helpers/errorHelper.js

@@ -0,0 +1,100 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { StringHelper } from "./stringHelper.js";
+import { BaseError } from "../errors/baseError.js";
+import { I18n } from "../utils/i18n.js";
+import { Is } from "../utils/is.js";
+/**
+ * Error helper functions.
+ */
+export class ErrorHelper {
+    /**
+     * Format Errors and returns just their messages.
+     * @param error The error to format.
+     * @param includeDetails Whether to include error details, defaults to false.
+     * @returns The error formatted including any causes errors.
+     */
+    static formatErrors(error, includeDetails) {
+        const localizedErrors = ErrorHelper.localizeErrors(error);
+        if (includeDetails ?? false) {
+            const output = [];
+            for (const err of localizedErrors) {
+                let detailedError = err.message;
+                if (Is.stringValue(err.stack)) {
+                    detailedError += `\n${err.stack}`;
+                }
+                output.push(detailedError);
+            }
+            return output;
+        }
+        return localizedErrors.map(e => e.message);
+    }
+    /**
+     * Localize the content of an error and any causes.
+     * @param error The error to format.
+     * @returns The localized version of the errors flattened.
+     */
+    static localizeErrors(error) {
+        const formattedErrors = [];
+        if (Is.notEmpty(error)) {
+            const errors = BaseError.flatten(error);
+            for (const err of errors) {
+                const errorNameKey = `errorNames.${StringHelper.camelCase(err.name)}`;
+                const errorMessageKey = `error.${err.message}`;
+                // If there is no error message then it is probably
+                // from a 3rd party lib, so don't format it just display
+                const hasErrorName = I18n.hasMessage(errorNameKey);
+                const hasErrorMessage = I18n.hasMessage(errorMessageKey);
+                const localizedError = {
+                    name: I18n.formatMessage(hasErrorName ? errorNameKey : "errorNames.error"),
+                    message: hasErrorMessage
+                        ? I18n.formatMessage(errorMessageKey, err.properties)
+                        : err.message
+                };
+                if (Is.stringValue(err.source)) {
+                    localizedError.source = err.source;
+                }
+                if (Is.stringValue(err.stack)) {
+                    // Remove the first line from the stack traces as they
+                    // just have the error type and message duplicated
+                    const lines = err.stack.split("\n");
+                    lines.shift();
+                    localizedError.stack = lines.join("\n");
+                }
+                const additional = ErrorHelper.formatValidationErrors(err);
+                if (Is.stringValue(additional)) {
+                    localizedError.additional = additional;
+                }
+                formattedErrors.push(localizedError);
+            }
+        }
+        return formattedErrors;
+    }
+    /**
+     * Localize the content of an error and any causes.
+     * @param error The error to format.
+     * @returns The localized version of the errors flattened.
+     */
+    static formatValidationErrors(error) {
+        if (Is.object(error.properties) &&
+            Object.keys(error.properties).length > 0 &&
+            Is.object(error.properties) &&
+            Is.arrayValue(error.properties.validationFailures)) {
+            const validationErrors = [];
+            for (const validationFailure of error.properties.validationFailures) {
+                const errorI18n = `error.${validationFailure.reason}`;
+                const errorMessage = I18n.hasMessage(errorI18n)
+                    ? I18n.formatMessage(errorI18n, validationFailure.properties)
+                    : errorI18n;
+                let v = `${validationFailure.property}: ${errorMessage}`;
+                if (Is.object(validationFailure.properties) &&
+                    Is.notEmpty(validationFailure.properties.value)) {
+                    v += ` = ${JSON.stringify(validationFailure.properties.value)}`;
+                }
+                validationErrors.push(v);
+            }
+            return validationErrors.join("\n");
+        }
+    }
+}
+//# sourceMappingURL=errorHelper.js.map

package/dist/es/helpers/errorHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHelper.js","sourceRoot":"","sources":["../../../src/helpers/errorHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { StringHelper } from \"./stringHelper.js\";\nimport { BaseError } from \"../errors/baseError.js\";\nimport type { IError } from \"../models/IError.js\";\nimport type { IValidationFailure } from \"../models/IValidationFailure.js\";\nimport { I18n } from \"../utils/i18n.js\";\nimport { Is } from \"../utils/is.js\";\n\n/**\n * Error helper functions.\n */\nexport class ErrorHelper {\n\t/**\n\t * Format Errors and returns just their messages.\n\t * @param error The error to format.\n\t * @param includeDetails Whether to include error details, defaults to false.\n\t * @returns The error formatted including any causes errors.\n\t */\n\tpublic static formatErrors(error: unknown, includeDetails?: boolean): string[] {\n\t\tconst localizedErrors = ErrorHelper.localizeErrors(error);\n\t\tif (includeDetails ?? false) {\n\t\t\tconst output: string[] = [];\n\t\t\tfor (const err of localizedErrors) {\n\t\t\t\tlet detailedError = err.message;\n\t\t\t\tif (Is.stringValue(err.stack)) {\n\t\t\t\t\tdetailedError += `\\n${err.stack}`;\n\t\t\t\t}\n\t\t\t\toutput.push(detailedError);\n\t\t\t}\n\t\t\treturn output;\n\t\t}\n\t\treturn localizedErrors.map(e => e.message);\n\t}\n\n\t/**\n\t * Localize the content of an error and any causes.\n\t * @param error The error to format.\n\t * @returns The localized version of the errors flattened.\n\t */\n\tpublic static localizeErrors(error: unknown): IError[] {\n\t\tconst formattedErrors: IError[] = [];\n\n\t\tif (Is.notEmpty(error)) {\n\t\t\tconst errors = BaseError.flatten(error);\n\n\t\t\tfor (const err of errors) {\n\t\t\t\tconst errorNameKey = `errorNames.${StringHelper.camelCase(err.name)}`;\n\t\t\t\tconst errorMessageKey = `error.${err.message}`;\n\n\t\t\t\t// If there is no error message then it is probably\n\t\t\t\t// from a 3rd party lib, so don't format it just display\n\t\t\t\tconst hasErrorName = I18n.hasMessage(errorNameKey);\n\t\t\t\tconst hasErrorMessage = I18n.hasMessage(errorMessageKey);\n\n\t\t\t\tconst localizedError: IError & { additional?: string } = {\n\t\t\t\t\tname: I18n.formatMessage(hasErrorName ? errorNameKey : \"errorNames.error\"),\n\t\t\t\t\tmessage: hasErrorMessage\n\t\t\t\t\t\t? I18n.formatMessage(errorMessageKey, err.properties)\n\t\t\t\t\t\t: err.message\n\t\t\t\t};\n\n\t\t\t\tif (Is.stringValue(err.source)) {\n\t\t\t\t\tlocalizedError.source = err.source;\n\t\t\t\t}\n\t\t\t\tif (Is.stringValue(err.stack)) {\n\t\t\t\t\t// Remove the first line from the stack traces as they\n\t\t\t\t\t// just have the error type and message duplicated\n\t\t\t\t\tconst lines = err.stack.split(\"\\n\");\n\t\t\t\t\tlines.shift();\n\t\t\t\t\tlocalizedError.stack = lines.join(\"\\n\");\n\t\t\t\t}\n\n\t\t\t\tconst additional = ErrorHelper.formatValidationErrors(err);\n\t\t\t\tif (Is.stringValue(additional)) {\n\t\t\t\t\tlocalizedError.additional = additional;\n\t\t\t\t}\n\n\t\t\t\tformattedErrors.push(localizedError);\n\t\t\t}\n\t\t}\n\n\t\treturn formattedErrors;\n\t}\n\n\t/**\n\t * Localize the content of an error and any causes.\n\t * @param error The error to format.\n\t * @returns The localized version of the errors flattened.\n\t */\n\tpublic static formatValidationErrors(error: IError): string | undefined {\n\t\tif (\n\t\t\tIs.object(error.properties) &&\n\t\t\tObject.keys(error.properties).length > 0 &&\n\t\t\tIs.object<{ validationFailures: IValidationFailure[] }>(error.properties) &&\n\t\t\tIs.arrayValue(error.properties.validationFailures)\n\t\t) {\n\t\t\tconst validationErrors = [];\n\t\t\tfor (const validationFailure of error.properties.validationFailures) {\n\t\t\t\tconst errorI18n = `error.${validationFailure.reason}`;\n\t\t\t\tconst errorMessage = I18n.hasMessage(errorI18n)\n\t\t\t\t\t? I18n.formatMessage(errorI18n, validationFailure.properties)\n\t\t\t\t\t: errorI18n;\n\n\t\t\t\tlet v = `${validationFailure.property}: ${errorMessage}`;\n\t\t\t\tif (\n\t\t\t\t\tIs.object<{ value: unknown }>(validationFailure.properties) &&\n\t\t\t\t\tIs.notEmpty(validationFailure.properties.value)\n\t\t\t\t) {\n\t\t\t\t\tv += ` = ${JSON.stringify(validationFailure.properties.value)}`;\n\t\t\t\t}\n\t\t\t\tvalidationErrors.push(v);\n\t\t\t}\n\t\t\treturn validationErrors.join(\"\\n\");\n\t\t}\n\t}\n}\n"]}

package/dist/es/helpers/filenameHelper.js

@@ -0,0 +1,32 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Coerce } from "../utils/coerce.js";
+import { Is } from "../utils/is.js";
+/**
+ * Class to help with filenames.
+ */
+export class FilenameHelper {
+    /**
+     * Replaces any unsafe characters in the filename.
+     * @param filename The filename to make safe.
+     * @returns The safe filename.
+     */
+    static safeFilename(filename) {
+        let safe = Coerce.string(filename);
+        if (Is.empty(safe)) {
+            return "";
+        }
+        // Common non filename characters
+        safe = safe.replace(/["*/:<>?\\|]/g, "_");
+        // Windows non filename characters
+        safe = safe.replace(/^(con|prn|aux|nul|com\d|lpt\d)$/i, "_");
+        // Control characters
+        safe = safe.replace(/[\u0000-\u001F\u0080-\u009F]/g, "_");
+        // Relative paths
+        safe = safe.replace(/^\.+/, "_");
+        // Trailing periods
+        safe = safe.replace(/\.+$/, "");
+        return safe;
+    }
+}
+//# sourceMappingURL=filenameHelper.js.map

package/dist/es/helpers/filenameHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filenameHelper.js","sourceRoot":"","sources":["../../../src/helpers/filenameHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAEpC;;GAEG;AACH,MAAM,OAAO,cAAc;IAC1B;;;;OAIG;IACI,MAAM,CAAC,YAAY,CAAC,QAAiB;QAC3C,IAAI,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEnC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,OAAO,EAAE,CAAC;QACX,CAAC;QAED,iCAAiC;QACjC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;QAC1C,kCAAkC;QAClC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,kCAAkC,EAAE,GAAG,CAAC,CAAC;QAC7D,qBAAqB;QACrB,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,+BAA+B,EAAE,GAAG,CAAC,CAAC;QAC1D,iBAAiB;QACjB,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjC,mBAAmB;QACnB,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAEhC,OAAO,IAAI,CAAC;IACb,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Coerce } from \"../utils/coerce.js\";\nimport { Is } from \"../utils/is.js\";\n\n/**\n * Class to help with filenames.\n */\nexport class FilenameHelper {\n\t/**\n\t * Replaces any unsafe characters in the filename.\n\t * @param filename The filename to make safe.\n\t * @returns The safe filename.\n\t */\n\tpublic static safeFilename(filename: unknown): string {\n\t\tlet safe = Coerce.string(filename);\n\n\t\tif (Is.empty(safe)) {\n\t\t\treturn \"\";\n\t\t}\n\n\t\t// Common non filename characters\n\t\tsafe = safe.replace(/[\"*/:<>?\\\\|]/g, \"_\");\n\t\t// Windows non filename characters\n\t\tsafe = safe.replace(/^(con|prn|aux|nul|com\\d|lpt\\d)$/i, \"_\");\n\t\t// Control characters\n\t\tsafe = safe.replace(/[\\u0000-\\u001F\\u0080-\\u009F]/g, \"_\");\n\t\t// Relative paths\n\t\tsafe = safe.replace(/^\\.+/, \"_\");\n\t\t// Trailing periods\n\t\tsafe = safe.replace(/\\.+$/, \"\");\n\n\t\treturn safe;\n\t}\n}\n"]}

package/dist/es/helpers/hexHelper.js

@@ -0,0 +1,45 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Helper methods for hex conversions.
+ */
+export class HexHelper {
+    /**
+     * Strip the 0x prefix if it exists.
+     * @param hex The hex value to strip.
+     * @returns The stripped hex without the prefix.
+     */
+    static stripPrefix(hex) {
+        return hex.replace(/^0x/, "");
+    }
+    /**
+     * Add the 0x prefix if it does not exist.
+     * @param hex The hex value to add the prefix to.
+     * @returns The hex with the prefix.
+     */
+    static addPrefix(hex) {
+        return HexHelper.hasPrefix(hex) ? hex : `0x${hex}`;
+    }
+    /**
+     * Does the hex string have the prefix.
+     * @param hex The hex value to check for the prefix.
+     * @returns True if the hex string has the prefix.
+     */
+    static hasPrefix(hex) {
+        return hex.startsWith("0x");
+    }
+    /**
+     * Is the data hex format.
+     * @param value The value to test.
+     * @param allowPrefix Allow the hex to have the 0x prefix.
+     * @returns True if the string is hex.
+     */
+    static isHex(value, allowPrefix = false) {
+        const localHex = allowPrefix ? HexHelper.stripPrefix(value) : value;
+        if (localHex.length % 2 === 1) {
+            return false;
+        }
+        return /^[\da-f]+$/g.test(localHex);
+    }
+}
+//# sourceMappingURL=hexHelper.js.map

package/dist/es/helpers/hexHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hexHelper.js","sourceRoot":"","sources":["../../../src/helpers/hexHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,MAAM,OAAO,SAAS;IACrB;;;;OAIG;IACI,MAAM,CAAC,WAAW,CAAC,GAAW;QACpC,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,SAAS,CAAC,GAAW;QAClC,OAAO,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,SAAS,CAAC,GAAW;QAClC,OAAO,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,KAAa,EAAE,cAAuB,KAAK;QAC9D,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAEpE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAC;QACd,CAAC;QACD,OAAO,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Helper methods for hex conversions.\n */\nexport class HexHelper {\n\t/**\n\t * Strip the 0x prefix if it exists.\n\t * @param hex The hex value to strip.\n\t * @returns The stripped hex without the prefix.\n\t */\n\tpublic static stripPrefix(hex: string): string {\n\t\treturn hex.replace(/^0x/, \"\");\n\t}\n\n\t/**\n\t * Add the 0x prefix if it does not exist.\n\t * @param hex The hex value to add the prefix to.\n\t * @returns The hex with the prefix.\n\t */\n\tpublic static addPrefix(hex: string): string {\n\t\treturn HexHelper.hasPrefix(hex) ? hex : `0x${hex}`;\n\t}\n\n\t/**\n\t * Does the hex string have the prefix.\n\t * @param hex The hex value to check for the prefix.\n\t * @returns True if the hex string has the prefix.\n\t */\n\tpublic static hasPrefix(hex: string): boolean {\n\t\treturn hex.startsWith(\"0x\");\n\t}\n\n\t/**\n\t * Is the data hex format.\n\t * @param value The value to test.\n\t * @param allowPrefix Allow the hex to have the 0x prefix.\n\t * @returns True if the string is hex.\n\t */\n\tpublic static isHex(value: string, allowPrefix: boolean = false): boolean {\n\t\tconst localHex = allowPrefix ? HexHelper.stripPrefix(value) : value;\n\n\t\tif (localHex.length % 2 === 1) {\n\t\t\treturn false;\n\t\t}\n\t\treturn /^[\\da-f]+$/g.test(localHex);\n\t}\n}\n"]}