@twin.org/core 0.0.1-next.5 → 0.0.1-next.50

package/dist/types/encoding/base58.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Class to help with base58 Encoding/Decoding.
+ */
+export declare class Base58 {
+    /**
+     * Convert the base 58 string to a byte array.
+     * @param base58 The base58 string to convert.
+     * @returns The byte array.
+     * @throws If the input string contains a character not in the Base58 alphabet.
+     */
+    static decode(base58: string): Uint8Array;
+    /**
+     * Convert a byte array to base 58.
+     * @param bytes The byte array to encode.
+     * @returns The data as base58 string.
+     */
+    static encode(bytes: Uint8Array): string;
+}

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

@@ -10,6 +10,21 @@ export declare class Factory<T> {
      * @returns The factory instance.
      */
     static createFactory<U>(typeName: string, autoInstance?: boolean, matcher?: (names: string[], name: string) => string | undefined): Factory<U>;
+    /**
+     * Get all the factories.
+     * @returns All the factories.
+     */
+    static getFactories(): {
+        [typeName: string]: Factory<unknown>;
+    };
+    /**
+     * Reset all the factories, which removes any created instances, but not the registrations.
+     */
+    static resetFactories(): void;
+    /**
+     * Clear all the factories, which removes anything registered with the factories.
+     */
+    static clearFactories(): void;
     /**
      * Register a new generator.
      * @param name The name of the generator.
@@ -38,9 +53,13 @@ export declare class Factory<T> {
      */
     getIfExists<U extends T>(name: string): U | undefined;
     /**
-     * Reset all the instances.
+     * Remove all the instances and leave the generators intact.
      */
     reset(): void;
+    /**
+     * Remove all the instances and the generators.
+     */
+    clear(): void;
     /**
      * Get all the instances as a map.
      * @returns The instances as a map.

package/dist/types/helpers/envHelper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Environment variable helper.
+ */
+export declare 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<T = {
+        [id: string]: string;
+    }>(envVars: {
+        [id: string]: string | undefined;
+    }, prefix?: string): T;
+}

package/dist/types/helpers/jsonHelper.d.ts

@@ -24,6 +24,36 @@ export declare class JsonHelper {
      * @param object The object to patch.
      * @param patches The second object.
      * @returns The updated object.
+     * @throws GeneralError if the patch fails.
      */
     static patch<T = unknown>(object: T, patches: IPatchOperation[]): T;
+    /**
+     * Stringify the JSON with support for extended data types date/bigint/uint8array.
+     * @param object The object to stringify.
+     * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
+     * @returns The stringified object.
+     */
+    static stringifyEx(object: any, space?: string | number): string;
+    /**
+     * Parse the JSON string with support for extended data types date/bigint/uint8array.
+     * @param json The object to pause.
+     * @returns The object.
+     */
+    static parseEx(json: string): any;
+    /**
+     * Replacer function to handle extended data types.
+     * @param this The object.
+     * @param key The key.
+     * @param value The value.
+     * @returns The value.
+     */
+    static stringifyExReplacer(this: any, key: string, value: unknown): unknown;
+    /**
+     * Reviver function to handle extended data types.
+     * @param this The object.
+     * @param key The key.
+     * @param value The value.
+     * @returns The value.
+     */
+    static parseExReviver(this: any, key: string, value: unknown): unknown;
 }

package/dist/types/helpers/objectHelper.d.ts

@@ -49,6 +49,7 @@ export declare class ObjectHelper {
      * @param obj The object to set the property from.
      * @param property The property to set.
      * @param value The value to set.
+     * @throws GeneralError if the property target is not an object.
      */
     static propertySet(obj: unknown, property: string, value: unknown): void;
     /**
@@ -57,6 +58,14 @@ export declare class ObjectHelper {
      * @param property The property to set
      */
     static propertyDelete(obj: unknown, property: string): void;
+    /**
+     * Extract a property from the object, providing alternative names.
+     * @param obj The object to extract from.
+     * @param propertyNames The possible names for the property.
+     * @param removeProperties Remove the properties from the object, defaults to true.
+     * @returns The property if available.
+     */
+    static extractProperty<T>(obj: unknown, propertyNames: string | string[], removeProperties?: boolean): T | undefined;
     /**
      * Pick a subset of properties from an object.
      * @param obj The object to pick the properties from.
@@ -71,4 +80,28 @@ export declare class ObjectHelper {
      * @returns The partial object.
      */
     static omit<T>(obj: T | undefined, keys?: (keyof T)[]): Partial<T>;
+    /**
+     * Converter the non JSON primitives to extended types.
+     * @param obj The object to convert.
+     * @returns The object with extended properties.
+     */
+    static toExtended(obj: any): any;
+    /**
+     * Converter the extended types to non JSON primitives.
+     * @param obj The object to convert.
+     * @returns The object with regular properties.
+     */
+    static fromExtended(obj: any): any;
+    /**
+     * Remove empty properties from an object.
+     * @param obj The object to remove the empty properties from.
+     * @param options The options for the removal.
+     * @param options.removeUndefined Remove undefined properties, defaults to true.
+     * @param options.removeNull Remove null properties, defaults to false.
+     * @returns The object with empty properties removed.
+     */
+    static removeEmptyProperties<T = unknown>(obj: T, options?: {
+        removeUndefined?: boolean;
+        removeNull?: boolean;
+    }): T;
 }

package/dist/types/helpers/uint8ArrayHelper.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Class to help with uint8 arrays.
+ */
+export declare class Uint8ArrayHelper {
+    /**
+     * Concatenate multiple arrays.
+     * @param arrays The array to concatenate.
+     * @returns The combined array.
+     */
+    static concat(arrays: Uint8Array[]): Uint8Array;
+}

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./encoding/base32";
+export * from "./encoding/base58";
 export * from "./encoding/base64";
 export * from "./encoding/base64Url";
 export * from "./errors/alreadyExistsError";
@@ -15,6 +16,7 @@ export * from "./errors/validationError";
 export * from "./factories/componentFactory";
 export * from "./factories/factory";
 export * from "./helpers/arrayHelper";
+export * from "./helpers/envHelper";
 export * from "./helpers/errorHelper";
 export * from "./helpers/filenameHelper";
 export * from "./helpers/hexHelper";
@@ -22,6 +24,8 @@ export * from "./helpers/jsonHelper";
 export * from "./helpers/objectHelper";
 export * from "./helpers/randomHelper";
 export * from "./helpers/stringHelper";
+export * from "./helpers/uint8ArrayHelper";
+export * from "./models/coerceType";
 export * from "./models/compressionType";
 export * from "./models/IComponent";
 export * from "./models/IError";

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

@@ -9,21 +9,30 @@ export interface IComponent {
     /**
      * Bootstrap the component by creating and initializing any resources it needs.
      * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @param componentState A persistent state which can be modified by the method.
      * @returns True if the bootstrapping process was successful.
      */
-    bootstrap?(nodeLoggingConnectorType?: string): Promise<boolean>;
+    bootstrap?(nodeLoggingConnectorType: string | undefined, componentState?: {
+        [id: string]: unknown;
+    }): Promise<boolean>;
     /**
      * The component needs to be started when the node is initialized.
      * @param nodeIdentity The identity of the node starting the component.
      * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @param componentState A persistent state which can be modified by the method.
      * @returns Nothing.
      */
-    start?(nodeIdentity: string, nodeLoggingConnectorType?: string): Promise<void>;
+    start?(nodeIdentity: string, nodeLoggingConnectorType: string | undefined, componentState?: {
+        [id: string]: unknown;
+    }): Promise<void>;
     /**
      * The component needs to be stopped when the node is closed.
      * @param nodeIdentity The identity of the node stopping the component.
      * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @param componentState A persistent state which can be modified by the method.
      * @returns Nothing.
      */
-    stop?(nodeIdentity: string, nodeLoggingConnectorType?: string): Promise<void>;
+    stop?(nodeIdentity: string, nodeLoggingConnectorType: string | undefined, componentState?: {
+        [id: string]: unknown;
+    }): Promise<void>;
 }

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

@@ -0,0 +1,49 @@
+/**
+ * The types the extracted data can be coerced to.
+ */
+export declare const CoerceType: {
+    /**
+     * String.
+     */
+    readonly String: "string";
+    /**
+     * Number.
+     */
+    readonly Number: "number";
+    /**
+     * Integer.
+     */
+    readonly Integer: "integer";
+    /**
+     * Boolean.
+     */
+    readonly Boolean: "boolean";
+    /**
+     * Big Integer.
+     */
+    readonly BigInt: "bigint";
+    /**
+     * Date.
+     */
+    readonly Date: "date";
+    /**
+     * Date Time.
+     */
+    readonly DateTime: "datetime";
+    /**
+     * Time.
+     */
+    readonly Time: "time";
+    /**
+     * Object.
+     */
+    readonly Object: "object";
+    /**
+     * Uint8Array.
+     */
+    readonly Uint8Array: "uint8array";
+};
+/**
+ * The types the extracted data can be coerced to.
+ */
+export type CoerceType = (typeof CoerceType)[keyof typeof CoerceType];

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

@@ -7,7 +7,7 @@ export declare const CompressionType: {
      */
     readonly Gzip: "gzip";
     /**
-     * deflate.
+     * Deflate.
      */
     readonly Deflate: "deflate";
 };

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

@@ -16,6 +16,14 @@ export declare class AsyncCache {
      * @returns The item from the cache if it exists.
      */
     static get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Set an entry into the cache.
+     * @param key The key to set in the cache.
+     * @param value The value to set in the cache.
+     * @param ttlMs The TTL of the entry in the cache in ms, defaults to 1s.
+     * @returns Nothing.
+     */
+    static set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
     /**
      * Remove an entry from the cache.
      * @param key The key to remove from the cache.

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

@@ -1,3 +1,4 @@
+import { CoerceType } from "../models/coerceType";
 /**
  * Coerce an object from one type to another.
  */
@@ -16,6 +17,13 @@ export declare class Coerce {
      * @returns The value if it can be coerced.
      */
     static number(value: unknown): number | undefined;
+    /**
+     * Coerce the value to an integer.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static integer(value: unknown): number | undefined;
     /**
      * Coerce the value to a bigint.
      * @param value The value to coerce.
@@ -58,4 +66,18 @@ export declare class Coerce {
      * @returns The value if it can be coerced.
      */
     static object<T = unknown>(value: unknown): T | undefined;
+    /**
+     * Coerce the value to a Uint8Array.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static uint8Array(value: unknown): Uint8Array | undefined;
+    /**
+     * Coerces a value based on the coercion type.
+     * @param value The value to coerce.
+     * @param type The coercion type to perform.
+     * @returns The coerced value.
+     */
+    static byType(value: unknown, type?: CoerceType): unknown;
 }

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

@@ -82,4 +82,16 @@ export declare class Converter {
      * @returns The bytes.
      */
     static base64UrlToBytes(base64Url: string): Uint8Array;
+    /**
+     * Convert bytes to base58 string.
+     * @param bytes The bytes to convert.
+     * @returns A base58 string of the bytes.
+     */
+    static bytesToBase58(bytes: Uint8Array): string;
+    /**
+     * Convert a base58 string to bytes.
+     * @param base58 The base58 string.
+     * @returns The bytes.
+     */
+    static base58ToBytes(base58: string): Uint8Array;
 }

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

@@ -26,6 +26,14 @@ export declare class Guards {
      * @throws GuardError If the value does not match the assertion.
      */
     static stringValue(source: string, property: string, value: unknown): asserts value is string;
+    /**
+     * Is the property a JSON value.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static json(source: string, property: string, value: unknown): asserts value is string;
     /**
      * Is the property a base64 string.
      * @param source The source of the error.
@@ -42,6 +50,14 @@ export declare class Guards {
      * @throws GuardError If the value does not match the assertion.
      */
     static stringBase64Url(source: string, property: string, value: unknown): asserts value is string;
+    /**
+     * Is the property a base58 string.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static stringBase58(source: string, property: string, value: unknown): asserts value is string;
     /**
      * Is the property a string with a hex value.
      * @param source The source of the error.

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

@@ -56,6 +56,12 @@ export declare class Is {
      * @returns True if the value is a base64 string.
      */
     static stringBase64Url(value: unknown): value is string;
+    /**
+     * Is the value a base58 string.
+     * @param value The value to test.
+     * @returns True if the value is a base58 string.
+     */
+    static stringBase58(value: unknown): value is string;
     /**
      * Is the value a hex string.
      * @param value The value to test.
@@ -202,4 +208,10 @@ export declare class Is {
      * @returns True if the value is a promise.
      */
     static promise<T = unknown>(value: unknown): value is Promise<T>;
+    /**
+     * Is the value a regexp.
+     * @param value The value to test.
+     * @returns True if the value is a regexp.
+     */
+    static regexp(value: unknown): value is RegExp;
 }

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

@@ -30,9 +30,11 @@ export declare class Validation {
      * @param options Additional options for the validation.
      * @param options.minLength The minimum length of the string.
      * @param options.maxLength The maximum length of the string.
+     * @param options.format Specific format to check.
      * @returns True if the value is a valid string.
      */
     static string(property: string, value: unknown, failures: IValidationFailure[], fieldNameResource?: string, options?: {
+        format?: "base64" | "base58" | "hex" | RegExp;
         minLength?: number;
         maxLength?: number;
     }): value is string;

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # @twin.org/core - Changelog
 
-## 0.0.1-next.5
+## [0.0.1-next.50](https://github.com/twinfoundation/framework/compare/core-v0.0.1-next.49...core-v0.0.1-next.50) (2025-03-26)
+
+
+### Features
+
+* add set method for async caches ([ba34b55](https://github.com/twinfoundation/framework/commit/ba34b55e651ad56ab8fc59e139e4af631c19cda0))
+
+## 0.0.1-next.49
 
 - Initial Release

package/docs/reference/classes/AlreadyExistsError.md

@@ -16,19 +16,27 @@ Create a new instance of AlreadyExistsError.
 
 #### Parameters
 
-• **source**: `string`
+##### source
+
+`string`
 
 The source of the error.
 
-• **message**: `string`
+##### message
+
+`string`
 
 The message as a code.
 
-• **existingId?**: `string`
+##### existingId?
+
+`string`
 
 The id for the item.
 
-• **inner?**: `unknown`
+##### inner?
+
+`unknown`
 
 The inner error if we have wrapped another error.
 
@@ -58,7 +66,7 @@ The source of the error.
 
 #### Inherited from
 
-[`BaseError`](BaseError.md).[`source`](BaseError.md#source)
+[`BaseError`](BaseError.md).[`source`](BaseError.md#source-1)
 
 ***
 
@@ -70,11 +78,11 @@ Any additional information for the error.
 
 #### Index Signature
 
- \[`id`: `string`\]: `unknown`
+\[`id`: `string`\]: `unknown`
 
 #### Inherited from
 
-[`BaseError`](BaseError.md).[`properties`](BaseError.md#properties)
+[`BaseError`](BaseError.md).[`properties`](BaseError.md#properties-1)
 
 ***
 
@@ -86,7 +94,7 @@ The inner error if there was one.
 
 #### Inherited from
 
-[`BaseError`](BaseError.md).[`inner`](BaseError.md#inner)
+[`BaseError`](BaseError.md).[`inner`](BaseError.md#inner-1)
 
 ## Methods
 
@@ -98,7 +106,9 @@ Construct an error from an existing one.
 
 #### Parameters
 
-• **err**: `unknown`
+##### err
+
+`unknown`
 
 The existing error.
 
@@ -122,7 +132,9 @@ Flatten an error tree.
 
 #### Parameters
 
-• **err**: `unknown`
+##### err
+
+`unknown`
 
 The starting error.
 
@@ -146,10 +158,12 @@ Expand an error tree.
 
 #### Parameters
 
-• **errors**: `undefined` \| [`IError`](../interfaces/IError.md)[]
+##### errors
 
 The list of errors to expand.
 
+`undefined` | [`IError`](../interfaces/IError.md)[]
+
 #### Returns
 
 `undefined` \| [`IError`](../interfaces/IError.md)
@@ -170,14 +184,18 @@ Test to see if the error has the specified error name.
 
 #### Parameters
 
-• **error**: `unknown`
+##### error
+
+`unknown`
 
 The error to test.
 
-• **name**: `string` \| `RegExp`
+##### name
 
 The name to check for.
 
+`string` | `RegExp`
+
 #### Returns
 
 `error is BaseError`
@@ -198,14 +216,18 @@ Test to see if the error has the specified error message.
 
 #### Parameters
 
-• **error**: `unknown`
+##### error
+
+`unknown`
 
 The error to test.
 
-• **message**: `string` \| `RegExp`
+##### message
 
 The message to check for.
 
+`string` | `RegExp`
+
 #### Returns
 
 `error is BaseError`
@@ -226,14 +248,18 @@ Test to see if the error has the specified error code.
 
 #### Parameters
 
-• **error**: `unknown`
+##### error
+
+`unknown`
 
 The error to test.
 
-• **code**: `string` \| `RegExp`
+##### code
 
 The code to check for.
 
+`string` | `RegExp`
+
 #### Returns
 
 `boolean`
@@ -254,14 +280,18 @@ Test to see if any of the errors or children have the given error name.
 
 #### Parameters
 
-• **error**: `unknown`
+##### error
+
+`unknown`
 
 The error to test.
 
-• **name**: `string` \| `RegExp`
+##### name
 
 The name to check for.
 
+`string` | `RegExp`
+
 #### Returns
 
 `error is BaseError`
@@ -282,14 +312,18 @@ Test to see if any of the errors or children have the given error message.
 
 #### Parameters
 
-• **error**: `unknown`
+##### error
+
+`unknown`
 
 The error to test.
 
-• **message**: `string` \| `RegExp`
+##### message
 
 The message to check for.
 
+`string` | `RegExp`
+
 #### Returns
 
 `error is BaseError`
@@ -310,11 +344,15 @@ Test to see if any of the errors or children are from a specific class.
 
 #### Parameters
 
-• **error**: `unknown`
+##### error
+
+`unknown`
 
 The error to test.
 
-• **cls**: `string`
+##### cls
+
+`string`
 
 The class to check for.
 
@@ -338,14 +376,18 @@ Test to see if any of the errors or children have the given error code.
 
 #### Parameters
 
-• **error**: `unknown`
+##### error
+
+`unknown`
 
 The error to test.
 
-• **code**: `string` \| `RegExp`
+##### code
 
 The code to check for.
 
+`string` | `RegExp`
+
 #### Returns
 
 `error is BaseError`