@twin.org/core 0.0.1-next.1

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

@@ -0,0 +1,90 @@
+/**
+ * Class to help with string.
+ */
+export declare class StringHelper {
+    /**
+     * Trim trailing slashes from a string.
+     * @param value The value to trim.
+     * @returns The trimmed value.
+     */
+    static trimTrailingSlashes(value: string | undefined): string;
+    /**
+     * Trim leading slashes from a string.
+     * @param value The value to trim.
+     * @returns The trimmed value.
+     */
+    static trimLeadingSlashes(value: string | undefined): string;
+    /**
+     * Convert the input string to kebab case.
+     * @param input The input to convert.
+     * @param stripInterfacePrefix Strip interface prefixes.
+     * @returns The kebab case version of the input.
+     */
+    static kebabCase(input: string, stripInterfacePrefix?: boolean): string;
+    /**
+     * Convert the input string to snake case.
+     * @param input The input to convert.
+     * @param stripInterfacePrefix Strip interface prefixes.
+     * @returns The snake case version of the input.
+     */
+    static snakeCase(input: string, stripInterfacePrefix?: boolean): string;
+    /**
+     * Title case all the words.
+     * @param input The input to convert.
+     * @param stripInterfacePrefix Strip interface prefixes.
+     * @returns The title case version of the input.
+     */
+    static titleCase(input: string, stripInterfacePrefix?: boolean): string;
+    /**
+     * Pascal case all the words.
+     * @param input The input to convert.
+     * @param stripInterfacePrefix Strip interface prefixes.
+     * @returns The pascal case version of the input.
+     */
+    static pascalCase(input: string, stripInterfacePrefix?: boolean): string;
+    /**
+     * Camel case all the words.
+     * @param input The input to convert.
+     * @param stripInterfacePrefix Strip interface prefixes.
+     * @returns The camel case version of the input.
+     */
+    static camelCase(input: string, stripInterfacePrefix?: boolean): string;
+    /**
+     * Convert the words to a path.
+     * @param input The input to convert.
+     * @param stripInterfacePrefix Strip interface prefixes.
+     * @returns The path version of the input.
+     */
+    static wordPath(input: string, stripInterfacePrefix?: boolean): string;
+    /**
+     * Strip interface prefix if there is one.
+     * @param input The input to strip.
+     * @returns The input with any interface prefix stripped.
+     */
+    static stripPrefix(input: string): string;
+    /**
+     * Split a string into words.
+     * @param input The input to split.
+     * @returns The string split into words.
+     */
+    static words(input: string): string[];
+    /**
+     * Check if a Node.js Buffer or Uint8Array is UTF-8.
+     * Url https://tools.ietf.org/html/rfc3629
+     * Source https://github.com/hcodes/isutf8
+     * UTF8-char = UTF8-1 / UTF8-2 / UTF8-3 / UTF8-4.
+     * UTF8-1    = %x00-7F.
+     * UTF8-2    = %xC2-DF UTF8-tail.
+     * UTF8-3    = %xE0 %xA0-BF UTF8-tail.
+     * -           %xE1-EC 2( UTF8-tail ).
+     * -           %xED %x80-9F UTF8-tail.
+     * -           %xEE-EF 2( UTF8-tail ).
+     * UTF8-4    = %xF0 %x90-BF 2( UTF8-tail ).
+     * -           %xF1-F3 3( UTF8-tail ).
+     * -           %xF4 %x80-8F 2( UTF8-tail ).
+     * UTF8-tail = %x80-BF.
+     * @param data The data to check.
+     * @returns True if the data is utf8.
+     */
+    static isUtf8(data: Uint8Array): boolean;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,46 @@
+export * from "./encoding/base32";
+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/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 "./models/compressionType";
+export * from "./models/IComponent";
+export * from "./models/IError";
+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 "./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/validation";

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

@@ -0,0 +1,29 @@
+/**
+ * Interface describing a component which can be bootstrapped, started and stopped.
+ */
+export interface IComponent {
+    /**
+     * The name of the component.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Bootstrap the component by creating and initializing any resources it needs.
+     * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @returns True if the bootstrapping process was successful.
+     */
+    bootstrap?(nodeLoggingConnectorType?: 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 nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @returns Nothing.
+     */
+    start?(nodeIdentity: string, nodeLoggingConnectorType?: 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 nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @returns Nothing.
+     */
+    stop?(nodeIdentity: string, nodeLoggingConnectorType?: string): Promise<void>;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Model to describe serialized error.
+ */
+export interface IError {
+    /**
+     * The name for the error.
+     */
+    name: string;
+    /**
+     * The message for the error.
+     */
+    message: string;
+    /**
+     * The source of the error.
+     */
+    source?: string;
+    /**
+     * Any additional information for the error.
+     */
+    properties?: {
+        [id: string]: unknown;
+    };
+    /**
+     * The stack trace for the error.
+     */
+    stack?: string;
+    /**
+     * The inner error if there was one.
+     */
+    inner?: IError;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Interface describing a key/value pair.
+ */
+export interface IKeyValue<T> {
+    /**
+     * The key for the item.
+     */
+    key: string;
+    /**
+     * The value for the item.
+     */
+    value: T;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Interface describing a label/value pair.
+ */
+export interface ILabelledValue<T> {
+    /**
+     * The label for the item.
+     */
+    label: string;
+    /**
+     * The value for the item.
+     */
+    value: T;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Model for a local.
+ */
+export interface ILocale {
+    /**
+     * The label.
+     */
+    label: string;
+    /**
+     * The code.
+     */
+    code: string;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Type for the JSON locale dictionary files.
+ */
+export interface ILocaleDictionary {
+    [key: string]: string | ILocaleDictionary;
+}

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

@@ -0,0 +1,10 @@
+import type { ILocale } from "./ILocale";
+/**
+ * Model for a locales index.
+ */
+export interface ILocalesIndex {
+    /**
+     * The list of locales.
+     */
+    locales: ILocale[];
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Interface describing a patch operation to add a property.
+ */
+export interface IPatchOperation {
+    /**
+     * The operation that was performed on the item.
+     */
+    op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+    /**
+     * The path to the object that was changed.
+     */
+    path: string;
+    /**
+     * The path the value was copied or moved from.
+     */
+    from?: string;
+    /**
+     * The value to add.
+     */
+    value?: unknown;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Model to describe the parts of a url.
+ */
+export interface IUrlParts {
+    /**
+     * The schema for the url.
+     */
+    schema: string;
+    /**
+     * The host for the url.
+     */
+    host: string;
+    /**
+     * The port for the url.
+     */
+    port?: number;
+    /**
+     * The path for the url.
+     */
+    path: string;
+    /**
+     * The params for the url.
+     */
+    params?: string;
+    /**
+     * The hash for the url.
+     */
+    hash?: string;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Interface describing the reason a validation failed.
+ */
+export interface IValidationFailure {
+    /**
+     * The property that failed validation.
+     */
+    property: string;
+    /**
+     * 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.
+     */
+    properties?: {
+        [id: string]: unknown;
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Compression types.
+ */
+export declare const CompressionType: {
+    /**
+     * Gzip.
+     */
+    readonly Gzip: "gzip";
+    /**
+     * deflate.
+     */
+    readonly Deflate: "deflate";
+};
+/**
+ * Compression types.
+ */
+export type CompressionType = (typeof CompressionType)[keyof typeof CompressionType];

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

@@ -0,0 +1,41 @@
+/**
+ * A class to represent a bit string.
+ */
+export declare class BitString {
+    /**
+     * Create a new instance of BitString.
+     * @param numberBits The length of the bit string.
+     */
+    constructor(numberBits: number);
+    /**
+     * Create a new instance of BitString from a bit array.
+     * @param bits The bits to create the bit string from.
+     * @param numberBits The number of bits in the bit string.
+     * @returns The new instance of BitString.
+     */
+    static fromBits(bits: Uint8Array, numberBits: number): BitString;
+    /**
+     * Get the bit at the given index.
+     * @param index The index to get the bit for.
+     * @returns True if the bit at the index is set.
+     * @throws GeneralError if the index is out of range.
+     */
+    getBit(index: number): boolean;
+    /**
+     * Set the bit at the given index.
+     * @param index The index to set the bit for.
+     * @param value The value to set the bit to.
+     * @throws GeneralError if the index is out of range.
+     */
+    setBit(index: number, value: boolean): void;
+    /**
+     * Get the bits of the bit string.
+     * @returns The bits stored in a Uint8Array.
+     */
+    getBits(): Uint8Array;
+    /**
+     * Get the length of the bit string.
+     * @returns The length of the bit string.
+     */
+    getLength(): number;
+}

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

@@ -0,0 +1,56 @@
+import type { IUrlParts } from "../models/IUrlParts";
+import type { IValidationFailure } from "../models/IValidationFailure";
+/**
+ * Class to help with urls.
+ */
+export declare class Url {
+    /**
+     * Create a new instance of Url.
+     * @param url The url string.
+     */
+    constructor(url: string);
+    /**
+     * Try and parse a string into the url parts.
+     * @param url The url to parse.
+     * @returns The formatted url or undefined if the value is not a url.
+     */
+    static tryParseExact(url: unknown): Url | undefined;
+    /**
+     * Parse a string into the url parts.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The url to parse.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static guard(source: string, property: string, value: unknown): asserts value is string;
+    /**
+     * Validate a string as a 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.
+     * @returns The formatted url.
+     */
+    static validate(property: string, value: unknown, failures: IValidationFailure[]): value is Url;
+    /**
+     * Construct a url from a URL.
+     * @param url The url to construct from.
+     * @returns The formatted url.
+     */
+    static fromURLToParts(url: URL): IUrlParts;
+    /**
+     * Construct a url from valid parts.
+     * @param urlParts The url to create the parts from.
+     * @returns The formatted url.
+     */
+    static fromParts(urlParts: IUrlParts): Url;
+    /**
+     * Get the parts of the url.
+     * @returns The parts of the url.
+     */
+    parts(): IUrlParts;
+    /**
+     * Convert the parts in to a full string.
+     * @returns The formatted url.
+     */
+    toString(): string;
+}

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

@@ -0,0 +1,93 @@
+import type { IValidationFailure } from "../models/IValidationFailure";
+/**
+ * Class to help with urns.
+ */
+export declare class Urn {
+    /**
+     * Create a new instance of Urn.
+     * @param namespaceIdentifier The identifier for the namespace.
+     * @param namespaceSpecific The specific part of the namespace.
+     */
+    constructor(namespaceIdentifier: string, namespaceSpecific: string | string[]);
+    /**
+     * Generate a random identifier with 32 byte id.
+     * @param namespace The prefix for the urn.
+     * @returns A new Id in URN format.
+     */
+    static generateRandom(namespace: string): Urn;
+    /**
+     * Does the provided urn match the namespace.
+     * @param urn The urn to check.
+     * @param namespace The namespace to match.
+     * @returns True if the namespace matches.
+     */
+    static hasNamespace(urn: string, namespace: string): boolean;
+    /**
+     * Try and parse a string into the urn parts.
+     * @param urn The urn to parse.
+     * @returns The formatted urn or undefined if the value is not a urn.
+     */
+    static tryParseExact(urn: unknown): Urn | undefined;
+    /**
+     * Construct a urn from a string that has already been validated.
+     * @param urn The urn to parse.
+     * @returns The formatted urn.
+     */
+    static fromValidString(urn: string): Urn;
+    /**
+     * Add a urn: prefix if there isn't one already.
+     * @param urn The urn string to add a prefix to.
+     * @returns The urn with a prefix.
+     */
+    static addPrefix(urn: unknown): string | undefined;
+    /**
+     * Parse a string into the urn parts.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The urn to parse.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static guard(source: string, property: string, value: unknown): asserts value is string;
+    /**
+     * Validate a string as a 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.
+     * @returns The formatted urn.
+     */
+    static validate(property: string, value: unknown, failures: IValidationFailure[]): value is string;
+    /**
+     * Get the parts.
+     * @param startIndex The index to start from, defaults to 0.
+     * @returns The parts.
+     */
+    parts(startIndex?: number): string[];
+    /**
+     * Get the namespace identifier.
+     * @returns The namespace identifier.
+     */
+    namespaceIdentifier(): string;
+    /**
+     * Get the namespace method, the first component after the identifier.
+     * @returns The namespace method.
+     */
+    namespaceMethod(): string;
+    /**
+     * Get the namespace specific parts.
+     * @param startIndex The index to start from, defaults to 0.
+     * @returns The namespace specific parts.
+     */
+    namespaceSpecificParts(startIndex?: number): string[];
+    /**
+     * Get the namespace specific.
+     * @param startIndex The index to start from, defaults to 0.
+     * @returns The namespace specific.
+     */
+    namespaceSpecific(startIndex?: number): string;
+    /**
+     * Convert the parts in to a full string.
+     * @param omitPrefix Omit the urn: prefix from the string.
+     * @returns The formatted urn.
+     */
+    toString(omitPrefix?: boolean): string;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Cache the results from asynchronous requests.
+ */
+export declare class AsyncCache {
+    /**
+     * Execute an async request and cache the result.
+     * @param key The key for the entry in the cache.
+     * @param ttlMs The TTL of the entry in the cache.
+     * @param requestMethod The method to call if not cached.
+     * @returns The response.
+     */
+    static exec<T = unknown>(key: string, ttlMs: number | undefined, requestMethod: () => Promise<T>): Promise<T> | undefined;
+    /**
+     * Get an entry from the cache.
+     * @param key The key to get from the cache.
+     * @returns The item from the cache if it exists.
+     */
+    static get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Remove an entry from the cache.
+     * @param key The key to remove from the cache.
+     */
+    static remove(key: string): void;
+    /**
+     * Clear the cache.
+     * @param prefix Optional prefix to clear only entries with that prefix.
+     */
+    static clearCache(prefix?: string): void;
+    /**
+     * Perform a cleanup of the expired entries in the cache.
+     */
+    static cleanupExpired(): void;
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Coerce an object from one type to another.
+ */
+export declare class Coerce {
+    /**
+     * Coerce the value to a string.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static string(value: unknown): string | undefined;
+    /**
+     * Coerce the value to a number.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static number(value: unknown): number | undefined;
+    /**
+     * Coerce the value to a bigint.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static bigint(value: unknown): bigint | undefined;
+    /**
+     * Coerce the value to a boolean.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static boolean(value: unknown): boolean | undefined;
+    /**
+     * Coerce the value to a date.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static date(value: unknown): Date | undefined;
+    /**
+     * Coerce the value to a date/time.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static dateTime(value: unknown): Date | undefined;
+    /**
+     * Coerce the value to a time.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static time(value: unknown): Date | undefined;
+    /**
+     * Coerce the value to an object.
+     * @param value The value to coerce.
+     * @throws TypeError If the value can not be coerced.
+     * @returns The value if it can be coerced.
+     */
+    static object<T = unknown>(value: unknown): T | undefined;
+}

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

@@ -0,0 +1,20 @@
+import { CompressionType } from "../models/compressionType";
+/**
+ * A class to handle compression.
+ */
+export declare class Compression {
+    /**
+     * Compress bytes using GZIP.
+     * @param bytes The bytes to compress.
+     * @param type The type of compression to use.
+     * @returns The compressed bytes.
+     */
+    static compress(bytes: Uint8Array, type: CompressionType): Promise<Uint8Array>;
+    /**
+     * Decompress a gzipped compressed byte array.
+     * @param compressedBytes The compressed bytes.
+     * @param type The type of compression to use.
+     * @returns The decompressed bytes.
+     */
+    static decompress(compressedBytes: Uint8Array, type: CompressionType): Promise<Uint8Array>;
+}