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

package/dist/tools/NumberHelper.js

@@ -0,0 +1,49 @@
+/** Predicates never coerce strings, booleans or null into numbers. */
+export class NumberHelper {
+    static isFinite(value) {
+        return typeof value === "number" && Number.isFinite(value);
+    }
+    static isInteger(value) {
+        return typeof value === "number" && Number.isInteger(value);
+    }
+    static isSafeInteger(value) {
+        return typeof value === "number" && Number.isSafeInteger(value);
+    }
+    static isPositive(value) {
+        return this.isFinite(value) && value > 0;
+    }
+    static isNegative(value) {
+        return this.isFinite(value) && value < 0;
+    }
+    static isNonNegative(value) {
+        return this.isFinite(value) && value >= 0;
+    }
+    static isPositiveInteger(value) {
+        return this.isInteger(value) && value > 0;
+    }
+    static isNonNegativeInteger(value) {
+        return this.isInteger(value) && value >= 0;
+    }
+    static isInRange(value, min, max, inclusive = true) {
+        return (this.isFinite(value) &&
+            this.isFinite(min) &&
+            this.isFinite(max) &&
+            min <= max &&
+            (inclusive ? value >= min && value <= max : value > min && value < max));
+    }
+    static isValid(value, options = {}) {
+        if (!this.isFinite(value))
+            return false;
+        if (options.integer && !this.isInteger(value))
+            return false;
+        if (options.safeInteger && !this.isSafeInteger(value))
+            return false;
+        if (options.min !== undefined &&
+            (!this.isFinite(options.min) || value < options.min))
+            return false;
+        if (options.max !== undefined &&
+            (!this.isFinite(options.max) || value > options.max))
+            return false;
+        return true;
+    }
+}

package/dist/tools/ObjectHelper.d.ts

@@ -0,0 +1,28 @@
+export declare class ObjectHelper {
+    static toEntries<T extends object>(object: T): Array<{
+        key: string;
+        value: T[keyof T];
+    }>;
+    static toEntries<T extends object, K>(object: T, options: {
+        mapKey: (key: string, value: T[keyof T]) => K;
+    }): Array<{
+        key: K;
+        value: T[keyof T];
+    }>;
+    static isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;
+    /** Shallow clone of arrays/plain records; nested references are retained. */
+    static clone<T extends object>(value: T): T;
+    /** Native structured-clone semantics, not a class-instance/prototype clone. */
+    static deepClone<T>(value: T): T;
+    static equals(left: unknown, right: unknown): boolean;
+    /** JSON representation comparison only; may throw for cycles/BigInt. Prefer equals(). */
+    static compareAsString(left: unknown, right: unknown): boolean;
+    private static enumerableKeys;
+    static countProps(value: unknown): number;
+    /** Only actual objects with no own enumerable keys are empty. Collections use size. */
+    static isObjectEmpty(value: unknown): boolean;
+    /** Nullish leaves and empty containers; cycles are visited once. */
+    static isAllKeysEmpty(value: unknown): boolean;
+    static pick<T extends object, K extends keyof T>(object: T, keys: readonly K[]): Pick<T, K>;
+    static omit<T extends object, K extends keyof T>(object: T, keys: readonly K[]): Omit<T, K>;
+}

package/dist/tools/ObjectHelper.js

@@ -0,0 +1,90 @@
+import { isDeepStrictEqual } from "node:util";
+export class ObjectHelper {
+    static toEntries(object, options) {
+        return Object.entries(object).map(([key, value]) => ({
+            key: options ? options.mapKey(key, value) : key,
+            value: value,
+        }));
+    }
+    static isPlainObject(value) {
+        if (value === null || typeof value !== "object")
+            return false;
+        const prototype = Object.getPrototypeOf(value);
+        return prototype === Object.prototype || prototype === null;
+    }
+    /** Shallow clone of arrays/plain records; nested references are retained. */
+    static clone(value) {
+        if (Array.isArray(value))
+            return Object.defineProperties(new Array(value.length), Object.getOwnPropertyDescriptors(value));
+        if (!this.isPlainObject(value))
+            throw new TypeError("Shallow clone requires an array or a plain object");
+        return Object.defineProperties(Object.create(Object.getPrototypeOf(value)), Object.getOwnPropertyDescriptors(value));
+    }
+    /** Native structured-clone semantics, not a class-instance/prototype clone. */
+    static deepClone(value) {
+        return structuredClone(value);
+    }
+    static equals(left, right) {
+        return isDeepStrictEqual(left, right);
+    }
+    /** JSON representation comparison only; may throw for cycles/BigInt. Prefer equals(). */
+    static compareAsString(left, right) {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    static enumerableKeys(object) {
+        return Reflect.ownKeys(object).filter((key) => Object.prototype.propertyIsEnumerable.call(object, key));
+    }
+    static countProps(value) {
+        return value !== null && typeof value === "object"
+            ? this.enumerableKeys(value).length
+            : 0;
+    }
+    /** Only actual objects with no own enumerable keys are empty. Collections use size. */
+    static isObjectEmpty(value) {
+        if (value instanceof Map || value instanceof Set)
+            return value.size === 0;
+        if (!this.isPlainObject(value) && !Array.isArray(value))
+            return false;
+        return this.countProps(value) === 0;
+    }
+    /** Nullish leaves and empty containers; cycles are visited once. */
+    static isAllKeysEmpty(value) {
+        const visited = new WeakSet();
+        const pending = [value];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === null || current === undefined)
+                continue;
+            if (current instanceof Map || current instanceof Set) {
+                if (current.size !== 0)
+                    return false;
+                continue;
+            }
+            if (!this.isPlainObject(current) && !Array.isArray(current))
+                return false;
+            if (visited.has(current))
+                continue;
+            visited.add(current);
+            for (const key of this.enumerableKeys(current)) {
+                const descriptor = Object.getOwnPropertyDescriptor(current, key);
+                // Do not invoke arbitrary getters while checking emptiness.
+                if (!("value" in descriptor))
+                    return false;
+                pending.push(descriptor.value);
+            }
+        }
+        return true;
+    }
+    static pick(object, keys) {
+        const entries = keys
+            .filter((key) => Object.hasOwn(object, key))
+            .map((key) => [key, object[key]]);
+        return Object.fromEntries(entries);
+    }
+    static omit(object, keys) {
+        const excluded = new Set(keys.map((key) => (typeof key === "number" ? String(key) : key)));
+        return Object.fromEntries(this.enumerableKeys(object)
+            .filter((key) => !excluded.has(key))
+            .map((key) => [key, object[key]]));
+    }
+}

package/dist/tools/PromiseHelper.d.ts

@@ -0,0 +1,3 @@
+export declare class PromiseHelper {
+    static isPromiseLike<T = unknown>(value: unknown): value is PromiseLike<T>;
+}

package/dist/tools/PromiseHelper.js

@@ -0,0 +1,7 @@
+export class PromiseHelper {
+    static isPromiseLike(value) {
+        return (((typeof value === "object" && value !== null) ||
+            typeof value === "function") &&
+            typeof value.then === "function");
+    }
+}

package/dist/tools/StringHelper.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Utility class for common text operations such as pluralization, truncation, and more.
+ */
+export interface StringValidationOptions {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    /** Trim before checking length and pattern, without modifying the input. */
+    trim?: boolean;
+    allowEmpty?: boolean;
+    allowNull?: boolean;
+    allowUndefined?: boolean;
+}
+export declare class StringHelper {
+    static isNotEmpty(value: unknown): value is string;
+    /** Length follows JavaScript string.length (UTF-16 code units). */
+    static hasLength(value: unknown, min?: number, max?: number): value is string;
+    /** Global/sticky patterns start at zero without changing the caller's lastIndex. */
+    static matches(value: unknown, pattern: RegExp): value is string;
+    static isValid(value: unknown, options?: StringValidationOptions): boolean;
+    /**
+     * Returns the correct plural form from an array of word forms based on the given number.
+     *
+     * For languages like Russian, array should have 3 forms:
+     *   - titles[0]: singular (1)
+     *   - titles[1]: few (2,3,4)
+     *   - titles[2]: many (0,5-20)
+     *
+     * For languages like English, array should have 2 forms:
+     *   - titles[0]: singular (1)
+     *   - titles[1]: plural (everything else)
+     *
+     * @param {number} num - The number to base the pluralization on.
+     * @param {string[]} titles - Array of word forms (2 or 3 elements).
+     * @returns {string} The correct plural form according to the number.
+     * @throws {Error} Throws if titles array length is not 2 or 3.
+     *
+     * @example
+     * StringHelper.pluralize(1, ['apple', 'apples']); // 'apple'
+     * StringHelper.pluralize(2, ['apple', 'apples']); // 'apples'
+     * StringHelper.pluralize(1, ['яблоко', 'яблока', 'яблок']); // 'яблоко'
+     * StringHelper.pluralize(5, ['яблоко', 'яблока', 'яблок']); // 'яблок'
+     */
+    static pluralize(num: number, titles: string[]): string;
+    /**
+     * Truncates a string to a specified maximum length, adding ellipsis if truncated.
+     *
+     * @param text - The input string to truncate.
+     * @param maxLength - Maximum number of source characters kept before the ellipsis.
+     * @param ellipsis - Optional ellipsis string to append (default: '...').
+     * @returns Truncated string with ellipsis if needed. Its final length can be `maxLength + ellipsis.length`.
+     */
+    static truncate(text: string, maxLength: number, ellipsis?: string): string;
+    /**
+     * Capitalizes the first character of the given string.
+     *
+     * @param text - The input string.
+     * @returns The string with the first character capitalized.
+     */
+    static capitalize(text: string): string;
+    /**
+     * Converts the first character of the given string to lowercase.
+     *
+     * @param text - The input string.
+     * @returns The string with the first character in lowercase.
+     */
+    static decapitalize(text: string): string;
+    /**
+     * Checks if a string is empty or consists only of whitespace characters.
+     *
+     * @param text - The input string.
+     * @returns True if string is empty or whitespace only, false otherwise.
+     */
+    static isEmptyOrWhitespace(text: unknown): boolean;
+}

package/dist/tools/StringHelper.js

@@ -0,0 +1,127 @@
+export class StringHelper {
+    static isNotEmpty(value) {
+        return typeof value === "string" && value.trim().length > 0;
+    }
+    /** Length follows JavaScript string.length (UTF-16 code units). */
+    static hasLength(value, min = 0, max) {
+        return (typeof value === "string" &&
+            Number.isSafeInteger(min) &&
+            min >= 0 &&
+            value.length >= min &&
+            (max === undefined ||
+                (Number.isSafeInteger(max) && max >= min && value.length <= max)));
+    }
+    /** Global/sticky patterns start at zero without changing the caller's lastIndex. */
+    static matches(value, pattern) {
+        if (typeof value !== "string" || !(pattern instanceof RegExp))
+            return false;
+        return (pattern.global || pattern.sticky
+            ? new RegExp(pattern.source, pattern.flags)
+            : pattern).test(value);
+    }
+    static isValid(value, options = {}) {
+        if (value === null)
+            return options.allowNull === true;
+        if (value === undefined)
+            return options.allowUndefined === true;
+        if (typeof value !== "string")
+            return false;
+        const candidate = options.trim ? value.trim() : value;
+        if (!options.allowEmpty && !this.isNotEmpty(candidate))
+            return false;
+        if (!this.hasLength(candidate, options.minLength ?? 0, options.maxLength))
+            return false;
+        return (options.pattern === undefined || this.matches(candidate, options.pattern));
+    }
+    /**
+     * Returns the correct plural form from an array of word forms based on the given number.
+     *
+     * For languages like Russian, array should have 3 forms:
+     *   - titles[0]: singular (1)
+     *   - titles[1]: few (2,3,4)
+     *   - titles[2]: many (0,5-20)
+     *
+     * For languages like English, array should have 2 forms:
+     *   - titles[0]: singular (1)
+     *   - titles[1]: plural (everything else)
+     *
+     * @param {number} num - The number to base the pluralization on.
+     * @param {string[]} titles - Array of word forms (2 or 3 elements).
+     * @returns {string} The correct plural form according to the number.
+     * @throws {Error} Throws if titles array length is not 2 or 3.
+     *
+     * @example
+     * StringHelper.pluralize(1, ['apple', 'apples']); // 'apple'
+     * StringHelper.pluralize(2, ['apple', 'apples']); // 'apples'
+     * StringHelper.pluralize(1, ['яблоко', 'яблока', 'яблок']); // 'яблоко'
+     * StringHelper.pluralize(5, ['яблоко', 'яблока', 'яблок']); // 'яблок'
+     */
+    static pluralize(num, titles) {
+        if (titles.length !== 2 && titles.length !== 3) {
+            throw new Error("Titles array must have 2 or 3 elements");
+        }
+        const number = Math.abs(num);
+        if (!Number.isFinite(number))
+            return titles[titles.length - 1];
+        if (titles.length === 2) {
+            // English-like pluralization (singular/plural)
+            return number === 1 ? titles[0] : titles[1];
+        }
+        else {
+            if (!Number.isInteger(number))
+                return titles[1];
+            // Russian-like pluralization with 3 forms
+            const cases = [2, 0, 1, 1, 1, 2];
+            if (number % 100 > 4 && number % 100 < 20) {
+                return titles[2];
+            }
+            return titles[cases[number % 10 < 5 ? number % 10 : 5]];
+        }
+    }
+    /**
+     * Truncates a string to a specified maximum length, adding ellipsis if truncated.
+     *
+     * @param text - The input string to truncate.
+     * @param maxLength - Maximum number of source characters kept before the ellipsis.
+     * @param ellipsis - Optional ellipsis string to append (default: '...').
+     * @returns Truncated string with ellipsis if needed. Its final length can be `maxLength + ellipsis.length`.
+     */
+    static truncate(text, maxLength, ellipsis = "...") {
+        if (text.length <= maxLength)
+            return text;
+        return text.slice(0, maxLength) + ellipsis;
+    }
+    /**
+     * Capitalizes the first character of the given string.
+     *
+     * @param text - The input string.
+     * @returns The string with the first character capitalized.
+     */
+    static capitalize(text) {
+        if (!text)
+            return "";
+        return text.charAt(0).toUpperCase() + text.slice(1);
+    }
+    /**
+     * Converts the first character of the given string to lowercase.
+     *
+     * @param text - The input string.
+     * @returns The string with the first character in lowercase.
+     */
+    static decapitalize(text) {
+        if (!text)
+            return "";
+        return text.charAt(0).toLowerCase() + text.slice(1);
+    }
+    /**
+     * Checks if a string is empty or consists only of whitespace characters.
+     *
+     * @param text - The input string.
+     * @returns True if string is empty or whitespace only, false otherwise.
+     */
+    static isEmptyOrWhitespace(text) {
+        return (text === null ||
+            text === undefined ||
+            (typeof text === "string" && text.trim().length === 0));
+    }
+}

package/dist/tools/UidHelper.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Cryptographically random IDs. Randomness does not guarantee collision-free IDs.
+ */
+export declare class UidHelper {
+    private static readonly ALPHANUMERIC;
+    private static readonly URL_SAFE;
+    private static readonly HEX;
+    private static counter;
+    private static readonly MAX_RANDOM_BYTES;
+    private static readonly RANDOM_NUMBER_SPACE;
+    private static fillRandomBytes;
+    /**
+     * Generates unique string
+     * @param length - string length (16 by default)
+     * @param alphabet - symbols alphabet
+     * @returns unique string
+     */
+    static generateUniqueString(length?: number, alphabet?: string): string;
+    /**
+     * Generates a random integer in the inclusive range. Values can repeat.
+     * @param min - min value (0 by default)
+     * @param max - max value (Number.MAX_SAFE_INTEGER by default)
+     * @returns unique number
+     */
+    static generateUniqueNumber(min?: number, max?: number): number;
+    /**
+     * Generates UUID v4
+     * @returns UUID string. Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+     */
+    static generateUuid(): string;
+    /**
+     * Generates url-safe ID (like NanoID)
+     * @param length - length (21 by default)
+     * @returns URL-safe id
+     */
+    static generateNanoId(length?: number): string;
+    /**
+     * Generates id by current timestamp
+     * @param prefix - prefix
+     * @param includeRandom - includes random part (for unique safety)
+     * @returns ID with timestamp
+     */
+    static generateTimestampId(prefix?: string, includeRandom?: boolean): string;
+    /**
+     * Generates a random hexadecimal ID, not a hash of data.
+     * @param length - length (32 by default)
+     * @returns hash-like string
+     */
+    static generateHashId(length?: number): string;
+    /**
+     * Checks that a value is a valid UUID v4 (same version as generateUuid).
+     * @param uuid - uuid string
+     * @returns boolean - is uuid valid or not
+     */
+    static isValidUuid(uuid: unknown): boolean;
+}

package/dist/tools/UidHelper.js

@@ -0,0 +1,132 @@
+import { randomFillSync, randomUUID } from "node:crypto";
+/**
+ * Cryptographically random IDs. Randomness does not guarantee collision-free IDs.
+ */
+export class UidHelper {
+    static ALPHANUMERIC = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    static URL_SAFE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+    static HEX = "0123456789abcdef";
+    static counter = 0;
+    static MAX_RANDOM_BYTES = 65_536;
+    static RANDOM_NUMBER_SPACE = 2 ** 53;
+    static fillRandomBytes(bytes) {
+        randomFillSync(bytes);
+    }
+    /**
+     * Generates unique string
+     * @param length - string length (16 by default)
+     * @param alphabet - symbols alphabet
+     * @returns unique string
+     */
+    static generateUniqueString(length = 16, alphabet = UidHelper.ALPHANUMERIC) {
+        if (!Number.isSafeInteger(length) || length < 0) {
+            throw new RangeError("Length must be a non-negative safe integer");
+        }
+        const symbols = Array.from(alphabet);
+        if (symbols.length === 0 ||
+            symbols.length > 256 ||
+            new Set(symbols).size !== symbols.length) {
+            throw new RangeError("Alphabet must contain between 1 and 256 distinct symbols");
+        }
+        if (length === 0)
+            return "";
+        const chars = [];
+        const acceptanceLimit = 256 - (256 % symbols.length);
+        while (chars.length < length) {
+            const remaining = length - chars.length;
+            const batchSize = Math.min(this.MAX_RANDOM_BYTES, Math.ceil((remaining * 256) / acceptanceLimit));
+            const randomValues = new Uint8Array(batchSize);
+            this.fillRandomBytes(randomValues);
+            for (const randomValue of randomValues) {
+                if (randomValue >= acceptanceLimit)
+                    continue;
+                chars.push(symbols[randomValue % symbols.length]);
+                if (chars.length === length)
+                    break;
+            }
+        }
+        return chars.join("");
+    }
+    /**
+     * Generates a random integer in the inclusive range. Values can repeat.
+     * @param min - min value (0 by default)
+     * @param max - max value (Number.MAX_SAFE_INTEGER by default)
+     * @returns unique number
+     */
+    static generateUniqueNumber(min = 0, max = Number.MAX_SAFE_INTEGER) {
+        if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max)) {
+            throw new RangeError("Min and max must be safe integers");
+        }
+        if (max < min)
+            throw new RangeError("Max must be greater than or equal to min");
+        if (min === max)
+            return min;
+        const rangeSize = max - min + 1;
+        if (!Number.isSafeInteger(rangeSize) &&
+            rangeSize !== this.RANDOM_NUMBER_SPACE) {
+            throw new RangeError("Requested range is too large");
+        }
+        const acceptanceLimit = Math.floor(this.RANDOM_NUMBER_SPACE / rangeSize) * rangeSize;
+        const bytes = new Uint8Array(7);
+        let randomNumber;
+        do {
+            this.fillRandomBytes(bytes);
+            randomNumber = bytes[0] & 0x1f;
+            for (let index = 1; index < bytes.length; index += 1) {
+                randomNumber = randomNumber * 256 + bytes[index];
+            }
+        } while (randomNumber >= acceptanceLimit);
+        return min + (randomNumber % rangeSize);
+    }
+    /**
+     * Generates UUID v4
+     * @returns UUID string. Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+     */
+    static generateUuid() {
+        return randomUUID();
+    }
+    /**
+     * Generates url-safe ID (like NanoID)
+     * @param length - length (21 by default)
+     * @returns URL-safe id
+     */
+    static generateNanoId(length = 21) {
+        return UidHelper.generateUniqueString(length, UidHelper.URL_SAFE);
+    }
+    /**
+     * Generates id by current timestamp
+     * @param prefix - prefix
+     * @param includeRandom - includes random part (for unique safety)
+     * @returns ID with timestamp
+     */
+    static generateTimestampId(prefix = "", includeRandom = true) {
+        const timestamp = Date.now().toString(36);
+        UidHelper.counter =
+            UidHelper.counter >= Number.MAX_SAFE_INTEGER ? 1 : UidHelper.counter + 1;
+        const counter = UidHelper.counter.toString(36);
+        let id = prefix ? `${prefix}_${timestamp}` : timestamp;
+        id += `_${counter}`;
+        if (includeRandom) {
+            const random = UidHelper.generateUniqueString(6, UidHelper.ALPHANUMERIC);
+            id += `_${random}`;
+        }
+        return id;
+    }
+    /**
+     * Generates a random hexadecimal ID, not a hash of data.
+     * @param length - length (32 by default)
+     * @returns hash-like string
+     */
+    static generateHashId(length = 32) {
+        return UidHelper.generateUniqueString(length, UidHelper.HEX);
+    }
+    /**
+     * Checks that a value is a valid UUID v4 (same version as generateUuid).
+     * @param uuid - uuid string
+     * @returns boolean - is uuid valid or not
+     */
+    static isValidUuid(uuid) {
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+        return typeof uuid === "string" && uuidRegex.test(uuid);
+    }
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./EnumHelper.js";
+export * from "./UidHelper.js";
+export * from "./StringHelper.js";
+export * from "./PromiseHelper.js";
+export * from "./ErrorHelper.js";
+export * from "./ObjectHelper.js";
+export * from "./DateHelper.js";
+export * from "./NumberHelper.js";
+export * from "./DurationHelper.js";

package/dist/tools/index.js

@@ -0,0 +1,9 @@
+export * from "./EnumHelper.js";
+export * from "./UidHelper.js";
+export * from "./StringHelper.js";
+export * from "./PromiseHelper.js";
+export * from "./ErrorHelper.js";
+export * from "./ObjectHelper.js";
+export * from "./DateHelper.js";
+export * from "./NumberHelper.js";
+export * from "./DurationHelper.js";

package/dist/validation/Engine.d.ts

@@ -0,0 +1,6 @@
+import type { AnyRule, ValidationOptions, ValidatorOptions } from "./Types.js";
+import { ValidationResult } from "./Result.js";
+type Shape = Readonly<Record<string, readonly AnyRule[]>>;
+export declare function validateSync<T>(input: unknown, shape: Shape, config: ValidatorOptions, options: ValidationOptions): ValidationResult<T>;
+export declare function validateAsync<T>(input: unknown, shape: Shape, config: ValidatorOptions, options: ValidationOptions): Promise<ValidationResult<T>>;
+export {};