@twin.org/core 0.0.2-next.8 → 0.0.2

package/dist/types/index.d.ts

@@ -1,53 +1,57 @@
-export * from "./encoding/base32";
-export * from "./encoding/base58";
-export * from "./encoding/base64";
-export * from "./encoding/base64Url";
-export * from "./errors/alreadyExistsError";
-export * from "./errors/baseError";
-export * from "./errors/conflictError";
-export * from "./errors/generalError";
-export * from "./errors/guardError";
-export * from "./errors/notFoundError";
-export * from "./errors/notImplementedError";
-export * from "./errors/notSupportedError";
-export * from "./errors/unauthorizedError";
-export * from "./errors/unprocessableError";
-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";
-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";
-export * from "./models/II18nShared";
-export * from "./models/IKeyValue";
-export * from "./models/ILabelledValue";
-export * from "./models/ILocale";
-export * from "./models/ILocaleDictionary";
-export * from "./models/ILocalesIndex";
-export * from "./models/IPatchOperation";
-export * from "./models/IUrlParts";
-export * from "./models/IValidationFailure";
-export * from "./models/objectOrArray";
-export * from "./types/bitString";
-export * from "./types/url";
-export * from "./types/urn";
-export * from "./utils/asyncCache";
-export * from "./utils/coerce";
-export * from "./utils/compression";
-export * from "./utils/converter";
-export * from "./utils/guards";
-export * from "./utils/i18n";
-export * from "./utils/is";
-export * from "./utils/sharedStore";
-export * from "./utils/validation";
+export * from "./encoding/base32.js";
+export * from "./encoding/base58.js";
+export * from "./encoding/base64.js";
+export * from "./encoding/base64Url.js";
+export * from "./errors/alreadyExistsError.js";
+export * from "./errors/baseError.js";
+export * from "./errors/conflictError.js";
+export * from "./errors/generalError.js";
+export * from "./errors/guardError.js";
+export * from "./errors/notFoundError.js";
+export * from "./errors/notImplementedError.js";
+export * from "./errors/notSupportedError.js";
+export * from "./errors/unauthorizedError.js";
+export * from "./errors/unprocessableError.js";
+export * from "./errors/validationError.js";
+export * from "./factories/componentFactory.js";
+export * from "./factories/factory.js";
+export * from "./helpers/arrayHelper.js";
+export * from "./helpers/envHelper.js";
+export * from "./helpers/errorHelper.js";
+export * from "./helpers/filenameHelper.js";
+export * from "./helpers/hexHelper.js";
+export * from "./helpers/jsonHelper.js";
+export * from "./helpers/numberHelper.js";
+export * from "./helpers/objectHelper.js";
+export * from "./helpers/randomHelper.js";
+export * from "./helpers/stringHelper.js";
+export * from "./helpers/uint8ArrayHelper.js";
+export * from "./models/coerceType.js";
+export * from "./models/compressionType.js";
+export * from "./models/healthStatus.js";
+export * from "./models/IComponent.js";
+export * from "./models/IError.js";
+export * from "./models/IHealth.js";
+export * from "./models/II18nShared.js";
+export * from "./models/IKeyValue.js";
+export * from "./models/ILabelledValue.js";
+export * from "./models/ILocale.js";
+export * from "./models/ILocaleDictionary.js";
+export * from "./models/ILocalesIndex.js";
+export * from "./models/IPatchOperation.js";
+export * from "./models/IUrlParts.js";
+export * from "./models/IValidationFailure.js";
+export * from "./types/bitString.js";
+export * from "./types/objectOrArray.js";
+export * from "./types/singleOccurrenceArray.js";
+export * from "./types/url.js";
+export * from "./types/urn.js";
+export * from "./utils/asyncCache.js";
+export * from "./utils/coerce.js";
+export * from "./utils/compression.js";
+export * from "./utils/converter.js";
+export * from "./utils/guards.js";
+export * from "./utils/i18n.js";
+export * from "./utils/is.js";
+export * from "./utils/sharedStore.js";
+export * from "./utils/validation.js";

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

@@ -1,29 +1,40 @@
+import type { IHealth } from "./IHealth.js";
 /**
  * Interface describing a component which can be bootstrapped, started and stopped.
  */
 export interface IComponent {
     /**
-     * The name of the component.
+     * Returns the class name of the component.
+     * @returns The class name of the component.
      */
-    readonly CLASS_NAME: string;
+    className(): string;
     /**
      * Bootstrap the component by creating and initializing any resources it needs.
      * @param nodeLoggingComponentType The node logging component type.
      * @returns True if the bootstrapping process was successful.
      */
-    bootstrap?(nodeLoggingComponentType: string | undefined): Promise<boolean>;
+    bootstrap?(nodeLoggingComponentType?: string): Promise<boolean>;
+    /**
+     * Teardown the component by releasing any resources it holds.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns True if the teardown process was successful.
+     */
+    teardown?(nodeLoggingComponentType?: string): Promise<boolean>;
     /**
      * The component needs to be started when the node is initialized.
-     * @param nodeIdentity The identity of the node starting the component.
      * @param nodeLoggingComponentType The node logging component type.
      * @returns Nothing.
      */
-    start?(nodeIdentity: string, nodeLoggingComponentType: string | undefined): Promise<void>;
+    start?(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * The component needs to be stopped when the node is closed.
-     * @param nodeIdentity The identity of the node stopping the component.
      * @param nodeLoggingComponentType The node logging component type.
      * @returns Nothing.
      */
-    stop?(nodeIdentity: string, nodeLoggingComponentType: string | undefined): Promise<void>;
+    stop?(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Returns the health status of the component.
+     * @returns The health status of the component, can return multiple entries for elements within the component.
+     */
+    health?(): Promise<IHealth[]>;
 }

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

@@ -7,7 +7,7 @@ export interface IError {
      */
     name: string;
     /**
-     * The message for the error.
+     * The message for the error as an i18n key.
      */
     message: string;
     /**

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

@@ -0,0 +1,32 @@
+import type { HealthStatus } from "./healthStatus.js";
+/**
+ * Provides health information for a component.
+ */
+export interface IHealth {
+    /**
+     * The source of the health information.
+     */
+    source: string;
+    /**
+     * The description of the component as an i18n key.
+     */
+    description?: string;
+    /**
+     * The overall status of the component, the entries can also report their own health.
+     */
+    status: HealthStatus;
+    /**
+     * The message for the status if there are further details to provide as an i18n key.
+     */
+    message?: string;
+    /**
+     * Data to substitute in the i18n key for the message.
+     */
+    data?: {
+        [id: string]: unknown;
+    };
+    /**
+     * The grouped child components, if any.
+     */
+    grouped?: IHealth[];
+}

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

@@ -1,4 +1,4 @@
-import type { ILocale } from "./ILocale";
+import type { ILocale } from "./ILocale.js";
 /**
  * Model for a locales index.
  */

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

@@ -10,10 +10,6 @@ export interface IValidationFailure {
      * The reason the validation failed as an i18 resource error.
      */
     reason: string;
-    /**
-     * The optional human readable name for the field as an i18 resource.
-     */
-    fieldName?: string;
     /**
      * Additional properties for the validation failure.
      */

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

@@ -0,0 +1,21 @@
+/**
+ * The health status of the component.
+ */
+export declare const HealthStatus: {
+    /**
+     * OK.
+     */
+    readonly Ok: "ok";
+    /**
+     * Warning.
+     */
+    readonly Warning: "warning";
+    /**
+     * Error.
+     */
+    readonly Error: "error";
+};
+/**
+ * The health status of the component.
+ */
+export type HealthStatus = (typeof HealthStatus)[keyof typeof HealthStatus];

package/dist/types/types/bitString.d.ts

@@ -2,6 +2,10 @@
  * A class to represent a bit string.
  */
 export declare class BitString {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
     /**
      * Create a new instance of BitString.
      * @param numberBits The length of the bit string.

package/dist/types/types/singleOccurrenceArray.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Helper with bounded recursion depth to keep type instantiation tractable.
+ */
+export type SingleOccurrenceArrayDepthHelper<T, U, Depth extends 0[]> = Depth["length"] extends 16 ? [U, ...T[]] : [U, ...T[]] | [T, ...SingleOccurrenceArrayDepthHelper<T, U, [0, ...Depth]>];
+/**
+ * Utility type to create a non-empty array with values of type T and exactly one value of type U.
+ */
+export type SingleOccurrenceArray<T = unknown, U = never> = SingleOccurrenceArrayDepthHelper<T, U, [
+]>;

package/dist/types/types/url.d.ts

@@ -1,9 +1,13 @@
-import type { IUrlParts } from "../models/IUrlParts";
-import type { IValidationFailure } from "../models/IValidationFailure";
+import type { IUrlParts } from "../models/IUrlParts.js";
+import type { IValidationFailure } from "../models/IValidationFailure.js";
 /**
  * Class to help with urls.
  */
 export declare class Url {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
     /**
      * Create a new instance of Url.
      * @param url The url string.
@@ -28,9 +32,10 @@ export declare class Url {
      * @param property Throw an exception if the url property is invalid.
      * @param value The url to parse.
      * @param failures The list of failures to add to.
+     * @param fieldNameResource The optional human readable name for the field as an i18 resource.
      * @returns The formatted url.
      */
-    static validate(property: string, value: unknown, failures: IValidationFailure[]): value is Url;
+    static validate(property: string, value: unknown, failures: IValidationFailure[], fieldNameResource?: string): value is Url;
     /**
      * Construct a url from a URL.
      * @param url The url to construct from.

package/dist/types/types/urn.d.ts

@@ -1,8 +1,12 @@
-import type { IValidationFailure } from "../models/IValidationFailure";
+import type { IValidationFailure } from "../models/IValidationFailure.js";
 /**
  * Class to help with urns.
  */
 export declare class Urn {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
     /**
      * Create a new instance of Urn.
      * @param namespaceIdentifier The identifier for the namespace.
@@ -53,9 +57,10 @@ export declare class Urn {
      * @param property Throw an exception if the urn property is invalid.
      * @param value The urn to parse.
      * @param failures The list of failures to add to.
+     * @param fieldNameResource The optional human readable name for the field as an i18 resource.
      * @returns The formatted urn.
      */
-    static validate(property: string, value: unknown, failures: IValidationFailure[]): value is string;
+    static validate(property: string, value: unknown, failures: IValidationFailure[], fieldNameResource?: string): value is string;
     /**
      * Get the parts.
      * @param startIndex The index to start from, defaults to 0.

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

@@ -39,4 +39,11 @@ export declare class AsyncCache {
      * Perform a cleanup of the expired entries in the cache.
      */
     static cleanupExpired(): void;
+    /**
+     * Resolve a waiter by re-running its request method safely.
+     * @param requestMethod The method to execute.
+     * @param resolve The resolver for the waiter.
+     * @param reject The rejector for the waiter.
+     */
+    private static resolveWaiter;
 }

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

@@ -1,4 +1,4 @@
-import { CoerceType } from "../models/coerceType";
+import { CoerceType } from "../models/coerceType.js";
 /**
  * Coerce an object from one type to another.
  */

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

@@ -1,8 +1,12 @@
-import { CompressionType } from "../models/compressionType";
+import { CompressionType } from "../models/compressionType.js";
 /**
  * A class to handle compression.
  */
 export declare class Compression {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
     /**
      * Compress bytes using GZIP.
      * @param bytes The bytes to compress.

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

@@ -1,4 +1,4 @@
-import type { ObjectOrArray } from "../models/objectOrArray";
+import type { ObjectOrArray } from "../types/objectOrArray.js";
 /**
  * Class to handle guard operations for parameters.
  */
@@ -210,10 +210,9 @@ export declare class Guards {
      * @param source The source of the error.
      * @param property The name of the property.
      * @param value The value to test.
-     * @returns True if the value is a function.
      * @throws GuardError If the value does not match the assertion.
      */
-    static function(source: string, property: string, value: unknown): boolean;
+    static function<T extends (...args: any[]) => any = (...args: any[]) => any>(source: string, property: string, value: unknown): asserts value is T;
     /**
      * Is the property a string formatted as an email address.
      * @param source The source of the error.
@@ -222,4 +221,13 @@ export declare class Guards {
      * @throws GuardError If the value does not match the assertion.
      */
     static email(source: string, property: string, value: unknown): asserts value is string;
+    /**
+     * Is the property a string containing uuidV7.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @param format The format of the uuidV7, either standard or compact.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static uuidV7(source: string, property: string, value: unknown, format?: "standard" | "compact"): asserts value is string;
 }

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

@@ -1,4 +1,4 @@
-import type { ILocaleDictionary } from "../models/ILocaleDictionary";
+import type { ILocaleDictionary } from "../models/ILocaleDictionary.js";
 /**
  * Class to perform internationalization.
  */
@@ -78,4 +78,19 @@ export declare class I18n {
      * @returns True if the key exists.
      */
     static hasMessage(key: string): boolean;
+    /**
+     * Flatten the translation property paths for faster lookup.
+     * @param translation The translation to merge.
+     * @param propertyPath The current root path.
+     * @param mergedKeys The merged keys dictionary to populate.
+     */
+    static flattenTranslationKeys(translation: ILocaleDictionary, propertyPath: string, mergedKeys: {
+        [key: string]: string;
+    }): void;
+    /**
+     * Get a list of the property names from the message.
+     * @param message The message to extract the property names from.
+     * @returns The list of property names.
+     */
+    static getPropertyNames(message: string): string[];
 }

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

@@ -195,7 +195,7 @@ export declare class Is {
      * @param value The value to test.
      * @returns True if the value is a function.
      */
-    static function(value: unknown): value is (...args: unknown[]) => unknown;
+    static function<T extends (...args: any[]) => any = (...args: any[]) => any>(value: unknown): value is T;
     /**
      * Is the value a string formatted as an email address.
      * @param value The value to test.
@@ -220,4 +220,11 @@ export declare class Is {
      * @returns True if the object is a class, false otherwise.
      */
     static class<T = unknown>(obj: unknown): obj is new (...args: any[]) => T;
+    /**
+     * Is the value a uuidV7 string.
+     * @param value The value to test.
+     * @param format The format of the UUIDv7 string.
+     * @returns True if the value is a uuidV7 string.
+     */
+    static uuidV7(value: unknown, format?: "standard" | "compact"): value is string;
 }

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

@@ -1,4 +1,4 @@
-import type { IValidationFailure } from "../models/IValidationFailure";
+import type { IValidationFailure } from "../models/IValidationFailure.js";
 /**
  * Class to handle validation operations.
  */