@ix-xs/node-comfort 1.1.3 → 1.2.0

package/types/src/FS.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Reads an environment variable from process.env.
+ * @param {string} value - The environment variable name.
+ * @param {string} [envFilePath] - Reserved for future use.
+ * @returns {string|undefined} The environment value, or undefined if not set.
+ */
+export function getEnv(value: string, envFilePath?: string): string | undefined;
+/**
+ * Resolves a path even when it does not already exist.
+ * @param {string} [path=process.cwd()] - The path to resolve.
+ * @returns {string} The resolved path.
+ */
+export function createPath(path?: string): string;
+/**
+ * Returns folders found inside a path.
+ * @param {string} [path=process.cwd()] - The base path to inspect.
+ * @param {boolean} [recursive=true] - Whether to scan recursively.
+ * @returns {string[]|undefined} Matching folders, or undefined if the path cannot be resolved.
+ */
+export function getFoldersIn(path?: string, recursive?: boolean): string[] | undefined;
+/**
+ * Returns the resolved folder path.
+ * @param {string} [path=process.cwd()] - The folder path to resolve.
+ * @returns {string|undefined} The resolved folder path, or undefined if not found.
+ */
+export function getFolder(path?: string): string | undefined;
+/**
+ * Returns files found inside a path.
+ * @param {string} [path=process.cwd()] - The base path to inspect.
+ * @param {boolean} [recursive=true] - Whether to scan recursively.
+ * @returns {string[]|undefined} Matching files, or undefined if the path cannot be resolved.
+ */
+export function getFilesIn(path?: string, recursive?: boolean): string[] | undefined;
+/**
+ * Returns the resolved file path.
+ * @param {string} path - The file path to resolve.
+ * @returns {string|undefined} The resolved file path, or undefined if not found.
+ */
+export function getFile(path: string): string | undefined;
+/**
+ * Creates a folder.
+ * @param {string} path - The folder path to create.
+ * @param {boolean} [force=false] - Whether to recreate the folder if it already exists.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if no path was provided.
+ */
+export function createFolder(path: string, force?: boolean): boolean | undefined;
+/**
+ * Creates a file.
+ * @param {string} path - The file path to create.
+ * @param {boolean} [force=false] - Whether to recreate the file if it already exists.
+ * @param {string|object|null|undefined} [data] - File content to write.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if no path was provided.
+ */
+export function createFile(path: string, force?: boolean, data?: string | object | null | undefined): boolean | undefined;
+/**
+ * Deletes folders found inside a path.
+ * @param {string} [path=process.cwd()] - The base path to inspect.
+ * @param {(folder: string) => boolean} [filter=() => true] - Filter applied to each folder path.
+ * @returns {number|undefined} Number of deleted folders, or undefined if the path cannot be resolved.
+ */
+export function deleteFoldersIn(path?: string, filter?: (folder: string) => boolean): number | undefined;
+/**
+ * Deletes a folder.
+ * @param {string} path - The folder path to delete.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if the path is invalid.
+ */
+export function deleteFolder(path: string): boolean | undefined;
+/**
+ * Deletes files found inside a path.
+ * @param {string} [path=process.cwd()] - The base path to inspect.
+ * @param {boolean} [recursive=false] - Whether to scan recursively.
+ * @param {(file: string) => boolean} [filter=() => true] - Filter applied to each file path.
+ * @returns {number|undefined} Number of deleted files, or undefined if the path cannot be resolved.
+ */
+export function deleteFilesIn(path?: string, recursive?: boolean, filter?: (file: string) => boolean): number | undefined;
+/**
+ * Deletes a file.
+ * @param {string} path - The file path to delete.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if the path is invalid.
+ */
+export function deleteFile(path: string): boolean | undefined;
+/**
+ * Copies folders from a source path into a destination folder.
+ * @param {Object} options - Copy options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
+ * @param {boolean} [options.withFiles=false] - Whether to copy files as well.
+ * @param {boolean} [options.force=false] - Whether to overwrite existing folders.
+ * @param {(folder: string) => boolean} [options.filter=() => true] - Filter applied to each folder.
+ * @returns {number|undefined} Number of copied folders, or undefined if invalid input.
+ */
+export function copyFoldersIn(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    withFiles?: boolean | undefined;
+    force?: boolean | undefined;
+    filter?: ((folder: string) => boolean) | undefined;
+}): number | undefined;
+/**
+ * Copies a folder to a destination path.
+ * @param {Object} options - Copy options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=false] - Whether to copy subfolders.
+ * @param {boolean} [options.withFiles=false] - Whether to copy files.
+ * @param {boolean} [options.force=false] - Whether to overwrite the destination.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ */
+export function copyFolder(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    withFiles?: boolean | undefined;
+    force?: boolean | undefined;
+}): boolean | undefined;
+/**
+ * Copies files from a source path into a destination folder.
+ * @param {Object} options - Copy options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
+ * @param {boolean} [options.force=false] - Whether to overwrite existing files.
+ * @param {(file: string) => boolean} [options.filter=() => true] - Filter applied to each file.
+ * @returns {number|undefined} Number of copied files, or undefined if invalid input.
+ */
+export function copyFilesIn(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    force?: boolean | undefined;
+    filter?: ((file: string) => boolean) | undefined;
+}): number | undefined;
+/**
+ * Copies a file to a destination path.
+ * @param {Object} options - Copy options.
+ * @param {string} options.path - Source file path.
+ * @param {string} options.dest - Destination path.
+ * @param {boolean} [options.force=false] - Whether to overwrite the destination file.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ */
+export function copyFile(options: {
+    path: string;
+    dest: string;
+    force?: boolean | undefined;
+}): boolean | undefined;
+/**
+ * Moves folders from a source path into a destination folder.
+ * @param {Object} options - Move options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
+ * @param {boolean} [options.withFiles=false] - Whether to move files as well.
+ * @param {boolean} [options.force=false] - Whether to overwrite existing folders.
+ * @param {(folder: string) => boolean} [options.filter=() => true] - Filter applied to each folder.
+ * @returns {number|undefined} Number of copied folders, or undefined if invalid input.
+ */
+export function moveFoldersIn(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    withFiles?: boolean | undefined;
+    force?: boolean | undefined;
+    filter?: ((folder: string) => boolean) | undefined;
+}): number | undefined;
+/**
+ * Moves a folder to a destination path.
+ * @param {Object} options - Move options.
+ * @param {string} options.path - Source folder path.
+ * @param {string} options.dest - Destination path.
+ * @param {boolean} [options.recursive=false] - Whether to move subfolders.
+ * @param {boolean} [options.withFiles=false] - Whether to move files.
+ * @param {boolean} [options.force=false] - Whether to overwrite the destination.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ */
+export function moveFolder(options: {
+    path: string;
+    dest: string;
+    recursive?: boolean | undefined;
+    withFiles?: boolean | undefined;
+    force?: boolean | undefined;
+}): boolean | undefined;
+/**
+ * Moves files from a source path into a destination folder.
+ * @param {Object} options - Move options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
+ * @param {boolean} [options.force=false] - Whether to overwrite existing files.
+ * @param {(file: string) => boolean} [options.filter=() => true] - Filter applied to each file.
+ * @returns {number|undefined} Number of copied files, or undefined if invalid input.
+ */
+export function moveFilesIn(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    force?: boolean | undefined;
+    filter?: ((file: string) => boolean) | undefined;
+}): number | undefined;
+/**
+ * Moves a file to a destination path.
+ * @param {Object} options - Move options.
+ * @param {string} options.path - Source file path.
+ * @param {string} options.dest - Destination path.
+ * @param {boolean} [options.force=false] - Whether to overwrite the destination file.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ */
+export function moveFile(options: {
+    path: string;
+    dest: string;
+    force?: boolean | undefined;
+}): boolean | undefined;
+/**
+ * Reads a file as UTF-8 text.
+ * @param {string} path - The file path to read.
+ * @returns {string|undefined} File content, or undefined if the file cannot be read.
+ */
+export function readFile(path: string): string | undefined;
+/**
+ * Reads and parses a JSON file.
+ * @template T
+ * @param {string} path - The JSON file path.
+ * @param {T} [fallback] - Value returned when the file is missing or invalid.
+ * @returns {T|any|undefined} The parsed value, or the fallback.
+ */
+export function readJSON<T>(path: string, fallback?: T): T | any | undefined;
+/**
+ * Serializes a value to JSON and writes it to a file (creating folders as needed).
+ * @param {string} path - The destination file path.
+ * @param {*} data - The value to serialize.
+ * @param {{ spaces?: number, force?: boolean }} [options] - Formatting options (`spaces` default 2).
+ * @returns {boolean} True on success, false on failure.
+ */
+export function writeJSON(path: string, data: any, options?: {
+    spaces?: number;
+    force?: boolean;
+}): boolean;
+/**
+ * Appends text to a file, creating it (and its folders) if necessary.
+ * @param {string} path - The file path.
+ * @param {string} data - The text to append.
+ * @returns {boolean} True on success, false on failure.
+ */
+export function appendFile(path: string, data: string): boolean;
+/**
+ * Checks whether a path (file or folder) exists.
+ * @param {string} path - The path to check.
+ * @returns {boolean} True if the path exists.
+ */
+export function exists(path: string): boolean;
+/**
+ * Returns filesystem stats for a path, or undefined if it does not exist.
+ * @param {string} path - The path to stat.
+ * @returns {import("node:fs").Stats|undefined} The stats object, or undefined.
+ */
+export function stat(path: string): any | undefined;
+/**
+ * Returns the size of a file in bytes.
+ * @param {string} path - The file path.
+ * @returns {number|undefined} Size in bytes, or undefined if not found.
+ */
+export function fileSize(path: string): number | undefined;
+/**
+ * Computes a hash digest of a file's contents.
+ * @param {string} path - The file path.
+ * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - Hash options.
+ * @returns {string|undefined} The digest, or undefined if the file cannot be read.
+ */
+export function hashFile(path: string, options?: {
+    algorithm?: string;
+    encoding?: "hex" | "base64" | "base64url";
+}): string | undefined;
+/**
+ * Empties a folder's contents while keeping the folder itself.
+ * @param {string} path - The folder to empty.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if not found.
+ */
+export function emptyFolder(path: string): boolean | undefined;
+/**
+ * Watches a path and exposes event listeners.
+ * @param {Object} [options] - Watch options.
+ * @param {string} [options.path=process.cwd()] - Path to watch.
+ * @param {boolean} [options.recursive=false] - Whether to watch recursively.
+ * @param {(event: "rename"|"change", file: string) => boolean} [options.filter] - Filter applied before dispatch.
+ * @returns {{
+ *   on: <E extends "change"|"rename"|"all">(event: E, callback: E extends "all" ? (event: "change"|"rename", file: string) => void|Promise<void> : (file: string) => void|Promise<void>) => any,
+ *   stop: () => void,
+ *   pause: () => any,
+ *   resume: () => any,
+ * }|undefined} Watch controller, or undefined if the path cannot be resolved.
+ */
+export function watch(options?: {
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    filter?: ((event: "rename" | "change", file: string) => boolean) | undefined;
+}): {
+    on: <E extends "change" | "rename" | "all">(event: E, callback: E extends "all" ? (event: "change" | "rename", file: string) => void | Promise<void> : (file: string) => void | Promise<void>) => any;
+    stop: () => void;
+    pause: () => any;
+    resume: () => any;
+} | undefined;
+//# sourceMappingURL=FS.d.ts.map

package/types/src/FS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FS.d.ts","sourceRoot":"","sources":["../../src/FS.js"],"names":[],"mappings":"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"}

package/types/src/Func.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Creates a debounced version of a function that delays invocation until
+ * `wait` ms have elapsed since the last call.
+ *
+ * The returned function exposes `.cancel()` and `.flush()`.
+ *
+ * @example
+ * const onResize = nodeComfort.func.debounce(() => render(), 200);
+ * window.on("resize", onResize);
+ * onResize.cancel(); // drop any pending call
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - Function to debounce.
+ * @param {number} wait - Delay in milliseconds.
+ * @param {{ leading?: boolean }} [options] - Set `leading` to fire on the first call.
+ * @returns {F & { cancel: () => void, flush: () => void }} The debounced function.
+ */
+export function debounce<F extends (...args: any[]) => any>(fn: F, wait: number, options?: {
+    leading?: boolean;
+}): F & {
+    cancel: () => void;
+    flush: () => void;
+};
+/**
+ * Creates a throttled version of a function that runs at most once per
+ * `wait` ms.
+ *
+ * @example
+ * const onScroll = nodeComfort.func.throttle(() => update(), 100);
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - Function to throttle.
+ * @param {number} wait - Minimum interval in milliseconds.
+ * @param {{ trailing?: boolean }} [options] - Set `trailing` (default true) to run a final call.
+ * @returns {F & { cancel: () => void }} The throttled function.
+ */
+export function throttle<F extends (...args: any[]) => any>(fn: F, wait: number, options?: {
+    trailing?: boolean;
+}): F & {
+    cancel: () => void;
+};
+/**
+ * Wraps a function so it can only ever run once; subsequent calls return
+ * the first result.
+ *
+ * @example
+ * const init = nodeComfort.func.once(() => expensiveSetup());
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - Function to wrap.
+ * @returns {F} The single-call function.
+ */
+export function once<F extends (...args: any[]) => any>(fn: F): F;
+/**
+ * Memoizes a function, caching results by argument key.
+ *
+ * By default the cache key is a JSON serialization of the arguments; pass a
+ * `resolver` for custom keys.
+ *
+ * @example
+ * const fib = nodeComfort.func.memoize((n) => (n < 2 ? n : fib(n - 1) + fib(n - 2)));
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - Function to memoize.
+ * @param {(...args: any[]) => any} [resolver] - Cache-key resolver.
+ * @returns {F & { cache: Map<any, any> }} The memoized function.
+ */
+export function memoize<F extends (...args: any[]) => any>(fn: F, resolver?: (...args: any[]) => any): F & {
+    cache: Map<any, any>;
+};
+/**
+ * Retries an async function until it succeeds or the attempt budget runs out.
+ *
+ * Supports fixed or exponential backoff and a `shouldRetry` guard.
+ *
+ * @example
+ * const data = await nodeComfort.func.retry(() => fetch(url), {
+ *   attempts: 5,
+ *   delay: 200,
+ *   backoff: 2, // 200, 400, 800, ...
+ * });
+ *
+ * @template T
+ * @param {() => T|Promise<T>} fn - Function to run.
+ * @param {{
+ *   attempts?: number,
+ *   delay?: number,
+ *   backoff?: number,
+ *   maxDelay?: number,
+ *   shouldRetry?: (error: unknown, attempt: number) => boolean,
+ *   onRetry?: (error: unknown, attempt: number) => void
+ * }} [options] - Retry options.
+ * @returns {Promise<T>} The resolved value.
+ * @throws Re-throws the last error if all attempts fail.
+ */
+export function retry<T>(fn: () => T | Promise<T>, options?: {
+    attempts?: number;
+    delay?: number;
+    backoff?: number;
+    maxDelay?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    onRetry?: (error: unknown, attempt: number) => void;
+}): Promise<T>;
+/**
+ * Runs a promise (or async function) with a timeout, rejecting if it takes
+ * too long.
+ *
+ * @example
+ * await nodeComfort.func.timeout(fetch(url), 5000, "fetch too slow");
+ *
+ * @template T
+ * @param {Promise<T>|(() => Promise<T>)} promise - Promise or async function.
+ * @param {number} ms - Timeout in milliseconds.
+ * @param {string} [message="Operation timed out"] - Error message on timeout.
+ * @returns {Promise<T>} The resolved value.
+ * @throws {Error} If the timeout elapses first.
+ */
+export function timeout<T>(promise: Promise<T> | (() => Promise<T>), ms: number, message?: string): Promise<T>;
+/**
+ * Composes functions left-to-right: `pipe(f, g)(x)` is `g(f(x))`.
+ *
+ * The first function may take multiple arguments; the rest take one.
+ *
+ * @example
+ * const process = nodeComfort.func.pipe(
+ *   (s) => s.trim(),
+ *   (s) => s.toUpperCase(),
+ * );
+ * process("  hi  "); // "HI"
+ *
+ * @param {...((arg: any) => any)} fns - Functions to compose.
+ * @returns {(...args: any[]) => any} The composed function.
+ */
+export function pipe(...fns: ((arg: any) => any)[]): (...args: any[]) => any;
+/**
+ * Composes functions right-to-left: `compose(f, g)(x)` is `f(g(x))`.
+ *
+ * @example
+ * const process = nodeComfort.func.compose(
+ *   (s) => s.toUpperCase(),
+ *   (s) => s.trim(),
+ * );
+ * process("  hi  "); // "HI"
+ *
+ * @param {...((arg: any) => any)} fns - Functions to compose.
+ * @returns {(...args: any[]) => any} The composed function.
+ */
+export function compose(...fns: ((arg: any) => any)[]): (...args: any[]) => any;
+/**
+ * Curries a function so it can be called with arguments one (or a few) at a time.
+ *
+ * @example
+ * const add = nodeComfort.func.curry((a, b, c) => a + b + c);
+ * add(1)(2)(3);   // 6
+ * add(1, 2)(3);   // 6
+ *
+ * @param {(...args: any[]) => any} fn - Function to curry.
+ * @param {number} [arity=fn.length] - Number of arguments to wait for.
+ * @returns {(...args: any[]) => any} The curried function.
+ */
+export function curry(fn: (...args: any[]) => any, arity?: number): (...args: any[]) => any;
+/**
+ * Returns a function that negates the result of `predicate`.
+ *
+ * @example
+ * const isOdd = nodeComfort.func.negate((n) => n % 2 === 0);
+ *
+ * @param {(...args: any[]) => boolean} predicate - Predicate to negate.
+ * @returns {(...args: any[]) => boolean} The negated predicate.
+ */
+export function negate(predicate: (...args: any[]) => boolean): (...args: any[]) => boolean;
+/**
+ * Wraps a function so that it is only actually invoked from the `n`-th call on.
+ *
+ * @example
+ * const save = nodeComfort.func.after(2, () => persist());
+ * save(); save(); // persists on the 2nd call
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {number} n - Number of calls before `fn` fires.
+ * @param {F} fn - Function to wrap.
+ * @returns {F} The wrapped function.
+ */
+export function after<F extends (...args: any[]) => any>(n: number, fn: F): F;
+/**
+ * Turns a Node-style callback function (`(err, result) => ...`) into one that
+ * returns a Promise.
+ *
+ * @example
+ * const readFile = nodeComfort.func.promisify(fs.readFile);
+ * const data = await readFile("a.txt", "utf8");
+ *
+ * @param {(...args: any[]) => void} fn - Callback-style function.
+ * @returns {(...args: any[]) => Promise<any>} A promise-returning function.
+ */
+export function promisify(fn: (...args: any[]) => void): (...args: any[]) => Promise<any>;
+/**
+ * Wraps an async function so it resolves to a `[error, result]` tuple instead
+ * of throwing • Go-style error handling.
+ *
+ * @example
+ * const [err, user] = await nodeComfort.func.attempt(() => getUser(id))();
+ * if (err) return handle(err);
+ *
+ * @template T
+ * @param {(...args: any[]) => Promise<T>|T} fn - Function to wrap.
+ * @returns {(...args: any[]) => Promise<[unknown, T|undefined]>} The safe function.
+ */
+export function attempt<T>(fn: (...args: any[]) => Promise<T> | T): (...args: any[]) => Promise<[unknown, T | undefined]>;
+//# sourceMappingURL=Func.d.ts.map

package/types/src/Func.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Func.d.ts","sourceRoot":"","sources":["../../src/Func.js"],"names":[],"mappings":"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"}

package/types/src/Id.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Generates a random UUID v4.
+ *
+ * @example
+ * nodeComfort.id.uuid(); // "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
+ *
+ * @returns {string} A UUID v4 string.
+ */
+export function uuid(): string;
+/**
+ * Generates a URL-safe, collision-resistant ID (nanoid-compatible alphabet).
+ *
+ * Uses secure randomness with unbiased rejection sampling.
+ *
+ * @example
+ * nodeComfort.id.nano();    // "V1StGXR8_Z5jdHi6B-myT"
+ * nodeComfort.id.nano(10);  // "IRFa-VaY2b"
+ *
+ * @param {number} [size=21] - Desired length.
+ * @param {string} [alphabet] - Custom alphabet.
+ * @returns {string} The generated ID.
+ */
+export function nano(size?: number, alphabet?: string): string;
+/**
+ * Generates a ULID • a lexicographically-sortable, timestamp-prefixed ID.
+ *
+ * ULIDs sort by creation time and are a great primary-key alternative to UUIDs.
+ *
+ * @example
+ * nodeComfort.id.ulid(); // "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+ *
+ * @param {number} [time=Date.now()] - Timestamp in ms to encode.
+ * @returns {string} A 26-character ULID.
+ */
+export function ulid(time?: number): string;
+/**
+ * Generates a cryptographically-secure random token.
+ *
+ * @example
+ * nodeComfort.id.token();               // 32-byte hex string
+ * nodeComfort.id.token(16, "base64url"); // 16 bytes, URL-safe base64
+ *
+ * @param {number} [bytes=32] - Number of random bytes.
+ * @param {"hex"|"base64"|"base64url"|"base58"} [encoding="hex"] - Output encoding.
+ * @returns {string} The token.
+ */
+export function token(bytes?: number, encoding?: "hex" | "base64" | "base64url" | "base58"): string;
+/**
+ * Generates a short, human-friendly random code (uppercase + digits by default).
+ *
+ * Ambiguous characters (`0/O`, `1/I`) are excluded, making it suitable for
+ * coupons, OTP-like codes and invite links.
+ *
+ * @example
+ * nodeComfort.id.code();            // "K7QF9X"
+ * nodeComfort.id.code(4, "1234");   // "3142"
+ *
+ * @param {number} [length=6] - Number of characters.
+ * @param {string} [alphabet="ABCDEFGHJKLMNPQRSTUVWXYZ23456789"] - Characters to pick from.
+ * @returns {string} The random code.
+ */
+export function code(length?: number, alphabet?: string): string;
+/**
+ * Hashes a value with a chosen algorithm.
+ *
+ * @example
+ * nodeComfort.id.hash("hello");                  // sha256 hex
+ * nodeComfort.id.hash("hello", { algorithm: "md5" });
+ *
+ * @param {string|Buffer} value - Data to hash.
+ * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - Hash options.
+ * @returns {string} The digest.
+ */
+export function hash(value: string | Buffer, options?: {
+    algorithm?: string;
+    encoding?: "hex" | "base64" | "base64url";
+}): string;
+/**
+ * Computes an HMAC signature for a value using a secret key.
+ *
+ * @example
+ * nodeComfort.id.hmac("payload", "secret"); // sha256 HMAC hex
+ *
+ * @param {string|Buffer} value - Data to sign.
+ * @param {string|Buffer} secret - Secret key.
+ * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - HMAC options.
+ * @returns {string} The signature.
+ */
+export function hmac(value: string | Buffer, secret: string | Buffer, options?: {
+    algorithm?: string;
+    encoding?: "hex" | "base64" | "base64url";
+}): string;
+/**
+ * Compares two strings/buffers in constant time to prevent timing attacks.
+ *
+ * Use this when comparing secrets, tokens, or signatures.
+ *
+ * @example
+ * if (nodeComfort.id.safeEqual(provided, expected)) { ... }
+ *
+ * @param {string|Buffer} a - First value.
+ * @param {string|Buffer} b - Second value.
+ * @returns {boolean} True if equal.
+ */
+export function safeEqual(a: string | Buffer, b: string | Buffer): boolean;
+/**
+ * Returns a monotonically-increasing counter ID prefixed with an optional label.
+ *
+ * Useful for readable, unique keys within a single process run.
+ *
+ * @example
+ * nodeComfort.id.seq("user"); // "user-1"
+ * nodeComfort.id.seq("user"); // "user-2"
+ *
+ * @param {string} [prefix=""] - Optional prefix.
+ * @returns {string} The sequential ID.
+ */
+export function seq(prefix?: string): string;
+//# sourceMappingURL=Id.d.ts.map

package/types/src/Id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Id.d.ts","sourceRoot":"","sources":["../../src/Id.js"],"names":[],"mappings":"AAyDE;;;;;;;GAOG;AACH,wBAFa,MAAM,CAIlB;AAED;;;;;;;;;;;;GAYG;AACH,4BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;;;;GAUG;AACH,4BAHW,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;;;;GAUG;AACH,8BAJW,MAAM,aACN,KAAK,GAAC,QAAQ,GAAC,WAAW,GAAC,QAAQ,GACjC,MAAM,CAMlB;AAED;;;;;;;;;;;;;GAaG;AACH,8BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;;;;;GAUG;AACH,4BAJW,MAAM,GAAC,MAAM,YACb;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,GAAC,QAAQ,GAAC,WAAW,CAAA;CAAE,GAC3D,MAAM,CAMlB;AAED;;;;;;;;;;GAUG;AACH,4BALW,MAAM,GAAC,MAAM,UACb,MAAM,GAAC,MAAM,YACb;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,GAAC,QAAQ,GAAC,WAAW,CAAA;CAAE,GAC3D,MAAM,CAMlB;AAED;;;;;;;;;;;GAWG;AACH,6BAJW,MAAM,GAAC,MAAM,KACb,MAAM,GAAC,MAAM,GACX,OAAO,CAOnB;AAED;;;;;;;;;;;GAWG;AACH,6BAHW,MAAM,GACJ,MAAM,CAKlB"}