@azure-net/node-kit 0.0.0-stage → 0.1.0

package/dist/delivery/http/ResponseBuilder.d.ts

@@ -0,0 +1,44 @@
+declare const responseStatuses: readonly [200, 201, 202, 203, 206, 207, 208, 226, 300, 301, 302, 303, 305, 306, 307, 308, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511];
+/** Standard final HTTP statuses that permit a response body. */
+export type ResponseStatus = (typeof responseStatuses)[number];
+export interface ResponseOptions<TMeta = null, TErrors = null, TStatus extends ResponseStatus = ResponseStatus> {
+    status?: TStatus;
+    message?: string;
+    meta?: TMeta;
+    errors?: TErrors;
+    code?: string | null;
+}
+export type ResponsePresetOptions<TMeta = null, TErrors = null> = Omit<ResponseOptions<TMeta, TErrors>, "status">;
+export interface ResponseEnvelope<TData, TMeta = null, TErrors = null, TStatus extends ResponseStatus = ResponseStatus> {
+    readonly success: boolean;
+    readonly status: TStatus;
+    readonly message: string;
+    readonly data: TData | null;
+    readonly meta: TMeta | null;
+    readonly errors: TErrors | null;
+    readonly code: string | null;
+}
+export declare class ResponseBuilder<TData = null, TMeta = null, TErrors = null, TStatus extends ResponseStatus = ResponseStatus> implements ResponseEnvelope<TData, TMeta, TErrors, TStatus> {
+    readonly success: boolean;
+    readonly status: TStatus;
+    readonly message: string;
+    readonly data: TData | null;
+    readonly meta: TMeta | null;
+    readonly errors: TErrors | null;
+    readonly code: string | null;
+    constructor(data?: TData, options?: ResponseOptions<TMeta, TErrors, TStatus>);
+    static Ok<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 200>;
+    static Created<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 201>;
+    static Accepted<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 202>;
+    static BadRequest<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 400>;
+    static Unauthorized<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 401>;
+    static Forbidden<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 403>;
+    static NotFound<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 404>;
+    static Conflict<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 409>;
+    static UnprocessableEntity<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 422>;
+    static TooManyRequests<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 429>;
+    static InternalServerError<TData = null, TMeta = null, TErrors = null>(data?: TData, options?: ResponsePresetOptions<TMeta, TErrors>): ResponseBuilder<TData, TMeta, TErrors, 500>;
+    toJSON(): ResponseEnvelope<TData, TMeta, TErrors, TStatus>;
+    toResponse(headers?: ConstructorParameters<typeof Headers>[0]): Response;
+}
+export {};

package/dist/delivery/http/ResponseBuilder.js

@@ -0,0 +1,135 @@
+const responseStatuses = [
+    200, 201, 202, 203, 206, 207, 208, 226, 300, 301, 302, 303, 305, 306, 307,
+    308, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413,
+    414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451,
+    500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511,
+];
+const allowedStatuses = new Set(responseStatuses);
+export class ResponseBuilder {
+    success;
+    status;
+    message;
+    data;
+    meta;
+    errors;
+    code;
+    constructor(data, options = {}) {
+        const status = options.status ?? 200;
+        if (!allowedStatuses.has(status)) {
+            throw new RangeError("Response status must be a standard final HTTP status permitting a body (not 204, 205 or 304).");
+        }
+        if (status < 400 && (options.code != null || options.errors != null)) {
+            throw new TypeError("Response code and errors are only allowed for error statuses.");
+        }
+        this.status = status;
+        this.success = status < 400;
+        this.message = options.message ?? (this.success ? "OK" : "Error");
+        this.data = data ?? null;
+        this.meta = options.meta ?? null;
+        this.errors = options.errors ?? null;
+        this.code = options.code ?? null;
+        Object.freeze(this);
+    }
+    static Ok(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "OK",
+            code: null,
+            ...options,
+            status: 200,
+        });
+    }
+    static Created(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Created",
+            code: null,
+            ...options,
+            status: 201,
+        });
+    }
+    static Accepted(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Accepted",
+            code: null,
+            ...options,
+            status: 202,
+        });
+    }
+    static BadRequest(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Bad Request",
+            code: "BAD_REQUEST",
+            ...options,
+            status: 400,
+        });
+    }
+    static Unauthorized(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Unauthorized",
+            code: "UNAUTHORIZED",
+            ...options,
+            status: 401,
+        });
+    }
+    static Forbidden(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Forbidden",
+            code: "FORBIDDEN",
+            ...options,
+            status: 403,
+        });
+    }
+    static NotFound(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Not Found",
+            code: "NOT_FOUND",
+            ...options,
+            status: 404,
+        });
+    }
+    static Conflict(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Conflict",
+            code: "CONFLICT",
+            ...options,
+            status: 409,
+        });
+    }
+    static UnprocessableEntity(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Unprocessable Entity",
+            code: "UNPROCESSABLE_ENTITY",
+            ...options,
+            status: 422,
+        });
+    }
+    static TooManyRequests(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Too Many Requests",
+            code: "TOO_MANY_REQUESTS",
+            ...options,
+            status: 429,
+        });
+    }
+    static InternalServerError(data, options = {}) {
+        return new ResponseBuilder(data, {
+            message: "Internal Server Error",
+            code: "INTERNAL_SERVER_ERROR",
+            ...options,
+            status: 500,
+        });
+    }
+    toJSON() {
+        return {
+            success: this.success,
+            status: this.status,
+            message: this.message,
+            data: this.data,
+            meta: this.meta,
+            errors: this.errors,
+            code: this.code,
+        };
+    }
+    toResponse(headers) {
+        return Response.json(this.toJSON(), { status: this.status, headers });
+    }
+}

package/dist/delivery/http/index.d.ts

@@ -0,0 +1 @@
+export * from "./ResponseBuilder.js";

package/dist/delivery/http/index.js

@@ -0,0 +1 @@
+export * from "./ResponseBuilder.js";

package/dist/delivery/index.d.ts

@@ -0,0 +1 @@
+export * from "./http/index.js";

package/dist/delivery/index.js

@@ -0,0 +1 @@
+export * from "./http/index.js";

package/dist/domain/Ensure.d.ts

@@ -0,0 +1,2 @@
+/** Enforces an invariant; error factories run only when the condition fails. */
+export declare function Ensure(condition: boolean, error: string | (() => Error)): asserts condition;

package/dist/domain/Ensure.js

@@ -0,0 +1,7 @@
+import { EnsureError } from "./EnsureError.js";
+/** Enforces an invariant; error factories run only when the condition fails. */
+export function Ensure(condition, error) {
+    if (condition)
+        return;
+    throw typeof error === "string" ? new EnsureError(error) : error();
+}

package/dist/domain/EnsureError.d.ts

@@ -0,0 +1,4 @@
+/** A domain invariant violation, independent of transport and localization. */
+export declare class EnsureError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/domain/EnsureError.js

@@ -0,0 +1,7 @@
+/** A domain invariant violation, independent of transport and localization. */
+export class EnsureError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "EnsureError";
+    }
+}

package/dist/domain/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Ensure.js";
+export * from "./EnsureError.js";

package/dist/domain/index.js

@@ -0,0 +1,2 @@
+export * from "./Ensure.js";
+export * from "./EnsureError.js";

package/dist/infrastructure/background/BackgroundTask.d.ts

@@ -0,0 +1,12 @@
+export interface BackgroundTaskOptions {
+    onError: (error: unknown) => void | PromiseLike<void>;
+}
+/** Tracks in-process I/O tasks, not durable jobs or CPU worker threads. */
+export declare class BackgroundTask {
+    #private;
+    constructor(options: BackgroundTaskOptions);
+    get pendingCount(): number;
+    run(task: () => unknown | PromiseLike<unknown>): void;
+    /** Includes tasks added while draining. Stop accepting requests before shutdown. */
+    drain(): Promise<void>;
+}

package/dist/infrastructure/background/BackgroundTask.js

@@ -0,0 +1,41 @@
+/** Tracks in-process I/O tasks, not durable jobs or CPU worker threads. */
+export class BackgroundTask {
+    #pending = new Set();
+    #onError;
+    constructor(options) {
+        if (typeof options?.onError !== "function") {
+            throw new TypeError("BackgroundTask requires an onError handler.");
+        }
+        this.#onError = options.onError;
+    }
+    get pendingCount() {
+        return this.#pending.size;
+    }
+    run(task) {
+        if (typeof task !== "function") {
+            throw new TypeError("BackgroundTask.run requires a task function.");
+        }
+        const pending = Promise.resolve()
+            .then(task)
+            .then(() => undefined)
+            .catch(async (error) => {
+            try {
+                await this.#onError(error);
+            }
+            catch (handlerError) {
+                // A failing error handler must not cause an unhandled rejection.
+                console.error("BackgroundTask error handler failed", handlerError, "Task error:", error);
+            }
+        })
+            .finally(() => {
+            this.#pending.delete(pending);
+        });
+        this.#pending.add(pending);
+    }
+    /** Includes tasks added while draining. Stop accepting requests before shutdown. */
+    async drain() {
+        while (this.#pending.size > 0) {
+            await Promise.all(this.#pending);
+        }
+    }
+}

package/dist/infrastructure/background/index.d.ts

@@ -0,0 +1 @@
+export * from "./BackgroundTask.js";

package/dist/infrastructure/background/index.js

@@ -0,0 +1 @@
+export * from "./BackgroundTask.js";

package/dist/infrastructure/environment/Env.d.ts

@@ -0,0 +1,19 @@
+export type EnvValues = Readonly<Record<string, string | undefined>>;
+export interface EnvGetOptions {
+    fallback?: string;
+    allowEmpty?: boolean;
+}
+export interface EnvParseContext {
+    value: string;
+    invalid: (message: string) => never;
+}
+export interface EnvParseOptions<T> extends EnvGetOptions {
+    parse: (context: EnvParseContext) => T;
+}
+/** Reads the supplied object on each get; never reads process.env implicitly. */
+export declare class Env {
+    private readonly values;
+    constructor(values: EnvValues);
+    get<T>(name: string, options: EnvParseOptions<T>): T;
+    get(name: string, options?: EnvGetOptions): string;
+}

package/dist/infrastructure/environment/Env.js

@@ -0,0 +1,33 @@
+import { StringHelper } from "../../tools/StringHelper.js";
+/** Reads the supplied object on each get; never reads process.env implicitly. */
+export class Env {
+    values;
+    constructor(values) {
+        this.values = values;
+        if (values === null ||
+            typeof values !== "object" ||
+            Array.isArray(values)) {
+            throw new TypeError("Env requires an object of string values");
+        }
+    }
+    get(name, options = {}) {
+        if (!StringHelper.isNotEmpty(name)) {
+            throw new TypeError("Environment variable name must be a nonblank string");
+        }
+        const invalid = (message) => {
+            throw new Error(`Environment variable ${JSON.stringify(name)} ${message}`);
+        };
+        const original = Object.hasOwn(this.values, name)
+            ? this.values[name]
+            : undefined;
+        const value = original === undefined ? options.fallback : original;
+        if (value === undefined)
+            return invalid("must be configured.");
+        if (typeof value !== "string")
+            return invalid("must be a string.");
+        if (!options.allowEmpty && !StringHelper.isNotEmpty(value)) {
+            return invalid("must not be empty or whitespace-only.");
+        }
+        return options.parse ? options.parse({ value, invalid }) : value;
+    }
+}

package/dist/infrastructure/environment/index.d.ts

@@ -0,0 +1 @@
+export * from "./Env.js";

package/dist/infrastructure/environment/index.js

@@ -0,0 +1 @@
+export * from "./Env.js";

package/dist/infrastructure/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./environment/index.js";
+export * from "./background/index.js";

package/dist/infrastructure/index.js

@@ -0,0 +1,2 @@
+export * from "./environment/index.js";
+export * from "./background/index.js";

package/dist/tools/DateHelper.d.ts

@@ -0,0 +1,13 @@
+/** Date, millisecond timestamp or strict ISO string. Zone-less strings use UTC. */
+export type DateInput = Date | string | number;
+export declare class DateHelper {
+    private static timestamp;
+    static compare(left: unknown, right: unknown): -1 | 0 | 1 | null;
+    static isBefore(date: unknown, comparison: unknown): boolean;
+    static isAfter(date: unknown, comparison: unknown): boolean;
+    static isSame(date: unknown, comparison: unknown): boolean;
+    /** Bounds can be supplied in either order. */
+    static isBetween(date: unknown, start: unknown, end: unknown, inclusive?: boolean): boolean;
+    static isPast(date: unknown, now?: DateInput): boolean;
+    static isFuture(date: unknown, now?: DateInput): boolean;
+}

package/dist/tools/DateHelper.js

@@ -0,0 +1,77 @@
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+export class DateHelper {
+    static timestamp(input) {
+        if (input instanceof Date) {
+            const value = input.getTime();
+            return Number.isFinite(value) ? value : null;
+        }
+        if (typeof input === "number") {
+            return Number.isFinite(input) &&
+                Number.isInteger(input) &&
+                Math.abs(input) <= 8.64e15
+                ? input
+                : null;
+        }
+        if (typeof input !== "string")
+            return null;
+        const match = ISO_DATE.exec(input.trim());
+        if (!match)
+            return null;
+        const [, y, m, d, h = "0", min = "0", s = "0", fraction = "", zone = "Z"] = match;
+        const year = Number(y), month = Number(m), day = Number(d);
+        const hours = Number(h), minutes = Number(min), seconds = Number(s);
+        const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+        const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+        if (month < 1 ||
+            month > 12 ||
+            day < 1 ||
+            day > days[month - 1] ||
+            hours > 23 ||
+            minutes > 59 ||
+            seconds > 59)
+            return null;
+        let offset = 0;
+        if (zone !== "Z") {
+            const offsetHours = Number(zone.slice(1, 3)), offsetMinutes = Number(zone.slice(4, 6));
+            if (offsetHours > 23 || offsetMinutes > 59)
+                return null;
+            offset =
+                (offsetHours * 60 + offsetMinutes) *
+                    60_000 *
+                    (zone[0] === "+" ? 1 : -1);
+        }
+        const date = new Date(0);
+        date.setUTCFullYear(year, month - 1, day);
+        date.setUTCHours(hours, minutes, seconds, Number(fraction.slice(0, 3).padEnd(3, "0")));
+        return date.getTime() - offset;
+    }
+    static compare(left, right) {
+        const a = this.timestamp(left), b = this.timestamp(right);
+        return a === null || b === null ? null : a === b ? 0 : a < b ? -1 : 1;
+    }
+    static isBefore(date, comparison) {
+        return this.compare(date, comparison) === -1;
+    }
+    static isAfter(date, comparison) {
+        return this.compare(date, comparison) === 1;
+    }
+    static isSame(date, comparison) {
+        return this.compare(date, comparison) === 0;
+    }
+    /** Bounds can be supplied in either order. */
+    static isBetween(date, start, end, inclusive = true) {
+        const value = this.timestamp(date), a = this.timestamp(start), b = this.timestamp(end);
+        if (value === null || a === null || b === null)
+            return false;
+        const min = Math.min(a, b), max = Math.max(a, b);
+        return inclusive
+            ? value >= min && value <= max
+            : value > min && value < max;
+    }
+    static isPast(date, now = Date.now()) {
+        return this.isBefore(date, now);
+    }
+    static isFuture(date, now = Date.now()) {
+        return this.isAfter(date, now);
+    }
+}

package/dist/tools/DurationHelper.d.ts

@@ -0,0 +1,6 @@
+/** Non-negative, timer-safe durations with exact millisecond precision. */
+export declare class DurationHelper {
+    /** Unit-less strings represent seconds. Invalid input returns null, including numbers. */
+    static toMilliseconds(value: unknown): number | null;
+    static toSeconds(value: unknown): number | null;
+}

package/dist/tools/DurationHelper.js

@@ -0,0 +1,31 @@
+const DURATION = /^(\d+)(?:\.(\d+))?(ms|s|m|h)?$/;
+const MILLISECONDS = { ms: 1n, s: 1000n, m: 60000n, h: 3600000n };
+const MAX_MILLISECONDS = 2147483647n;
+/** Non-negative, timer-safe durations with exact millisecond precision. */
+export class DurationHelper {
+    /** Unit-less strings represent seconds. Invalid input returns null, including numbers. */
+    static toMilliseconds(value) {
+        if (typeof value !== "string")
+            return null;
+        const match = DURATION.exec(value);
+        if (!match)
+            return null;
+        const whole = match[1].replace(/^0+/, "") || "0";
+        const fraction = (match[2] ?? "").replace(/0+$/, "");
+        // Reject impossible values before BigInt conversion. The largest unit has
+        // at most seven factors of 2 or 5, so longer nonzero fractions cannot yield integer ms.
+        if (whole.length > 10 || fraction.length > 7)
+            return null;
+        const unit = (match[3] ?? "s");
+        const denominator = 10n ** BigInt(fraction.length);
+        const numerator = BigInt(whole + fraction) * MILLISECONDS[unit];
+        if (numerator % denominator !== 0n)
+            return null;
+        const milliseconds = numerator / denominator;
+        return milliseconds <= MAX_MILLISECONDS ? Number(milliseconds) : null;
+    }
+    static toSeconds(value) {
+        const milliseconds = this.toMilliseconds(value);
+        return milliseconds === null ? null : milliseconds / 1000;
+    }
+}

package/dist/tools/EnumHelper.d.ts

@@ -0,0 +1,26 @@
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+type LastOf<U> = UnionToIntersection<U extends unknown ? () => U : never> extends () => infer R ? R : never;
+type UnionToTuple<U, Last = LastOf<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, Last>>, Last];
+type EnumLength<E> = UnionToTuple<Extract<keyof E, string>> extends infer T extends unknown[] ? T["length"] : never;
+type TupleOf<N extends number, T, R extends T[] = []> = R["length"] extends N ? R : TupleOf<N, T, [...R, T]>;
+type ObjectEntry<T extends object, K = Extract<keyof T, string>> = {
+    key: K;
+    value: T[keyof T];
+};
+export type EnumLike = Record<string, string | number>;
+export type EnumValue<E extends EnumLike> = E[Extract<keyof E, string>];
+export declare class EnumHelper {
+    private static getEntries;
+    /** Checks enum values, not names or numeric reverse mappings. No coercion. */
+    static isInEnum<const E extends EnumLike>(enumeration: E, value: unknown): value is EnumValue<E>;
+    static getValue<const E extends EnumLike>(enumeration: E, value: unknown): EnumValue<E> | null;
+    static associateByIndex<const E extends Record<string, string | number>>(enumeration: E, ...values: TupleOf<EnumLength<E>, string>): Record<E[Extract<keyof E, string>], string>;
+    static associateByKey<const T extends Record<string, string | number>, const A extends {
+        [K in keyof T]: unknown;
+    }>(enumeration: T, associations: A): Record<T[keyof T], A[keyof T]>;
+    static toEntries<const T extends object>(object: T): ObjectEntry<T>[];
+    static toEntries<const T extends object, K>(object: T, options: {
+        mapKey: (key: Extract<keyof T, string>, value: T[keyof T]) => K;
+    }): ObjectEntry<T, K>[];
+}
+export {};

package/dist/tools/EnumHelper.js

@@ -0,0 +1,40 @@
+export class EnumHelper {
+    static getEntries(enumeration) {
+        return Object.entries(enumeration).filter(([key, value]) => !(String(Number(key)) === key &&
+            typeof value === "string" &&
+            Object.hasOwn(enumeration, value) &&
+            enumeration[value] === Number(key)));
+    }
+    /** Checks enum values, not names or numeric reverse mappings. No coercion. */
+    static isInEnum(enumeration, value) {
+        return ((typeof value === "string" || typeof value === "number") &&
+            this.getEntries(enumeration).some(([, item]) => item === value));
+    }
+    static getValue(enumeration, value) {
+        return this.isInEnum(enumeration, value) ? value : null;
+    }
+    static associateByIndex(enumeration, ...values) {
+        const entries = this.getEntries(enumeration);
+        const associations = values;
+        if (entries.length !== associations.length) {
+            throw new RangeError("Enum values count mismatch");
+        }
+        return Object.fromEntries(entries.map(([, value], index) => [value, associations[index]]));
+    }
+    static associateByKey(enumeration, associations) {
+        return Object.fromEntries(this.getEntries(enumeration).map(([key, value]) => [
+            value,
+            associations[key],
+        ]));
+    }
+    static toEntries(object, options) {
+        return this.getEntries(object).map(([key, value]) => {
+            const typedKey = key;
+            const typedValue = value;
+            return {
+                key: options?.mapKey ? options.mapKey(typedKey, typedValue) : typedKey,
+                value: typedValue,
+            };
+        });
+    }
+}

package/dist/tools/ErrorHelper.d.ts

@@ -0,0 +1,3 @@
+export declare class ErrorHelper {
+    static toError(value: unknown, fallbackMessage?: string): Error;
+}

package/dist/tools/ErrorHelper.js

@@ -0,0 +1,31 @@
+export class ErrorHelper {
+    static toError(value, fallbackMessage = "Unknown error") {
+        if (value instanceof Error)
+            return value;
+        let message = fallbackMessage;
+        let name;
+        if (typeof value === "string" && value.length > 0) {
+            message = value;
+        }
+        else if (typeof value === "object" && value !== null) {
+            const errorLike = value;
+            if (typeof errorLike.message === "string" && errorLike.message.length > 0)
+                message = errorLike.message;
+            if (typeof errorLike.name === "string" && errorLike.name.length > 0)
+                name = errorLike.name;
+        }
+        else if (value !== null && value !== undefined) {
+            message = String(value);
+        }
+        const error = new Error(message);
+        if (name)
+            error.name = name;
+        Object.defineProperty(error, "cause", {
+            value,
+            configurable: true,
+            enumerable: false,
+            writable: true,
+        });
+        return error;
+    }
+}

package/dist/tools/NumberHelper.d.ts

@@ -0,0 +1,19 @@
+export interface NumberValidationOptions {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    safeInteger?: boolean;
+}
+/** Predicates never coerce strings, booleans or null into numbers. */
+export declare class NumberHelper {
+    static isFinite(value: unknown): value is number;
+    static isInteger(value: unknown): value is number;
+    static isSafeInteger(value: unknown): value is number;
+    static isPositive(value: unknown): value is number;
+    static isNegative(value: unknown): value is number;
+    static isNonNegative(value: unknown): value is number;
+    static isPositiveInteger(value: unknown): value is number;
+    static isNonNegativeInteger(value: unknown): value is number;
+    static isInRange(value: unknown, min: number, max: number, inclusive?: boolean): value is number;
+    static isValid(value: unknown, options?: NumberValidationOptions): value is number;
+}