reliable-node-utils 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,643 @@
+/**
+ * Options for {@link retry}.
+ * @public
+ */
+interface RetryOptions {
+    /** Maximum number of attempts (including the first). Default: 3. */
+    maxAttempts?: number;
+    /** Base delay in ms for exponential backoff. Default: 1000. */
+    baseDelayMs?: number;
+    /** Maximum delay in ms. Default: 30000. */
+    maxDelayMs?: number;
+    /** If true, add random jitter to delays. Default: true. */
+    jitter?: boolean;
+    /** Called before each retry with attempt index (1-based) and error. */
+    onRetry?: (attempt: number, error: unknown) => void | Promise<void>;
+    /** When aborted, retry stops and rejects with AbortError. */
+    signal?: AbortSignal;
+}
+/**
+ * Retry an async function with exponential backoff and optional jitter.
+ * Supports AbortSignal; calls onRetry before each retry.
+ *
+ * @param fn - Async function to run (no arguments). Return value is passed through.
+ * @param options - maxAttempts, baseDelayMs, maxDelayMs, jitter, onRetry, signal
+ * @returns Promise resolving to the return value of `fn`
+ * @throws {TypeError} When options are invalid
+ * @throws {AbortError} When `signal` is aborted
+ * @throws {RetryExhaustedError} When all attempts fail (last error as cause)
+ *
+ * @example
+ * ```ts
+ * import { retry } from 'reliable-node-utils';
+ *
+ * const data = await retry(() => fetchJSON('/api/data'), {
+ *   maxAttempts: 5,
+ *   baseDelayMs: 500,
+ *   onRetry: (attempt, err) => console.warn(`Attempt ${attempt} failed`, err),
+ *   signal: controller.signal,
+ * });
+ * ```
+ *
+ * @example
+ * ```js
+ * const { retry } = require('reliable-node-utils');
+ * const result = await retry(async () => callExternalApi(), { maxAttempts: 3 });
+ * ```
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * Options for {@link withTimeout}.
+ * @public
+ */
+interface WithTimeoutOptions {
+    /** AbortSignal to respect; when aborted, the timeout is cancelled and AbortError is thrown. */
+    signal?: AbortSignal;
+}
+/**
+ * Run a promise or async function with a time limit.
+ * If the time limit is exceeded, the returned promise rejects with TimeoutError.
+ * Supports AbortSignal: aborting clears the timer and rejects with AbortError.
+ *
+ * @param promiseOrFn - A Promise or a function returning a Promise
+ * @param ms - Time limit in milliseconds
+ * @param options - Optional { signal }
+ * @returns Promise resolving to the same value as the input promise
+ * @throws {TypeError} When `ms` is negative or non-finite
+ * @throws {TimeoutError} When the operation exceeds `ms`
+ * @throws {AbortError} When `signal` is aborted
+ *
+ * @example
+ * ```ts
+ * import { withTimeout } from 'reliable-node-utils';
+ *
+ * const data = await withTimeout(fetch('/api/data').then(r => r.json()), 5000);
+ * // or
+ * const data = await withTimeout(() => fetch('/api/data').then(r => r.json()), 5000, {
+ *   signal: controller.signal,
+ * });
+ * ```
+ *
+ * @example
+ * ```js
+ * const { withTimeout } = require('reliable-node-utils');
+ * const result = await withTimeout(longRunningTask(), 3000);
+ * ```
+ */
+declare function withTimeout<T>(promiseOrFn: Promise<T> | (() => Promise<T>), ms: number, options?: WithTimeoutOptions): Promise<T>;
+
+/**
+ * Concurrency limiter: run at most `concurrency` promises at a time.
+ * Queues additional calls and runs them when a slot frees up.
+ *
+ * @param concurrency - Maximum number of concurrent executions (>= 1)
+ * @returns A function that accepts an async function and its arguments, returning a Promise
+ *
+ * @example
+ * ```ts
+ * import { pLimit } from 'reliable-node-utils';
+ *
+ * const limit = pLimit(2);
+ * const out = await Promise.all([
+ *   limit(() => fetch('/a')),
+ *   limit(() => fetch('/b')),
+ *   limit(() => fetch('/c')), // waits until one of the first two finishes
+ * ]);
+ * ```
+ *
+ * @example
+ * ```js
+ * const { pLimit } = require('reliable-node-utils');
+ * const limit = pLimit(5);
+ * const results = await Promise.all(urls.map(url => limit(() => fetch(url))));
+ * ```
+ */
+declare function pLimit(concurrency: number): <T, A extends unknown[]>(fn: (...args: A) => Promise<T>, ...args: A) => Promise<T>;
+
+/**
+ * Options for {@link memoize}.
+ * @public
+ */
+interface MemoizeOptions<F extends (...args: unknown[]) => unknown> {
+    /** TTL in milliseconds; entries expire after this long. Omit for no expiry. */
+    ttlMs?: number;
+    /** Maximum number of entries to keep (LRU eviction). Omit for unbounded. */
+    maxSize?: number;
+    /** Custom key function. Default: `(...args) => JSON.stringify(args)`. */
+    keyFn?: (...args: Parameters<F>) => string;
+}
+/**
+ * Memoize a function with optional TTL and size limit.
+ * Cache key is computed via keyFn (default: JSON.stringify of arguments).
+ * When maxSize is set, least-recently-used entries are evicted.
+ *
+ * @param fn - Function to memoize (any arity)
+ * @param options - ttlMs, maxSize, keyFn
+ * @returns Memoized function with the same signature
+ *
+ * @example
+ * ```ts
+ * import { memoize } from 'reliable-node-utils';
+ *
+ * const getData = memoize(async (id: string) => fetch(`/api/${id}`).then(r => r.json()), {
+ *   ttlMs: 60_000,
+ *   maxSize: 100,
+ *   keyFn: (id) => id,
+ * });
+ * ```
+ *
+ * @example
+ * ```js
+ * const { memoize } = require('reliable-node-utils');
+ * const heavy = memoize(function (x, y) { return x + y; }, { maxSize: 50 });
+ * ```
+ */
+declare function memoize<F extends (...args: unknown[]) => unknown>(fn: F, options?: MemoizeOptions<F>): F;
+
+/**
+ * Deep merge two values. Source `b` overrides `a`.
+ * - Plain objects are merged recursively; arrays and other values are replaced by `b`.
+ * - Primitives, dates, class instances: always use `b` when present (not merged).
+ * - `__proto__`, `prototype`, and `constructor` keys are ignored for safety.
+ *
+ * @param a - Base object
+ * @param b - Overrides (takes precedence)
+ * @returns New object; inputs are not mutated
+ *
+ * @example
+ * ```ts
+ * import { deepMerge } from 'reliable-node-utils';
+ *
+ * const merged = deepMerge({ a: 1, nested: { x: 1 } }, { nested: { y: 2 } });
+ * // { a: 1, nested: { x: 1, y: 2 } }
+ * ```
+ *
+ * @example
+ * ```js
+ * const { deepMerge } = require('reliable-node-utils');
+ * const config = deepMerge(defaults, userConfig);
+ * ```
+ */
+declare function deepMerge<T extends object, U extends object>(a: T, b: U): T & U;
+
+/**
+ * Runtime type guards. Use with TypeScript for correct narrowing.
+ * @module guards
+ */
+/**
+ * Type predicate: narrows out `null` and `undefined`.
+ *
+ * @param value - Any value
+ * @returns `true` if value is not `null` and not `undefined`
+ *
+ * @example
+ * ```ts
+ * const arr: (string | undefined)[] = ['a', undefined, 'b'];
+ * const defined: string[] = arr.filter(isDefined);
+ * ```
+ *
+ * @example
+ * ```js
+ * const { isDefined } = require('reliable-node-utils');
+ * if (isDefined(maybe)) console.log(maybe.toUpperCase());
+ * ```
+ */
+declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+ * Type predicate: narrows to a non-empty string (length > 0).
+ * Rejects `null`, `undefined`, non-strings, and `""`.
+ *
+ * @param value - Any value
+ * @returns `true` if value is a string with at least one character
+ *
+ * @example
+ * ```ts
+ * function greet(name: unknown) {
+ *   if (isNonEmptyString(name)) return `Hello, ${name}`;
+ *   return 'Hello, stranger';
+ * }
+ * ```
+ *
+ * @example
+ * ```js
+ * const { isNonEmptyString } = require('reliable-node-utils');
+ * if (isNonEmptyString(input)) validate(input);
+ * ```
+ */
+declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Type predicate: narrows to a plain object (object created by `{}` or `Object.create(null)`).
+ * Rejects `null`, arrays, and class instances (e.g. Date, RegExp).
+ *
+ * @param value - Any value
+ * @returns `true` if value is a plain object (record-like)
+ *
+ * @example
+ * ```ts
+ * function mergeConfig(config: unknown) {
+ *   if (!isPlainObject(config)) throw new Error('Config must be an object');
+ *   return deepMerge(defaults, config);
+ * }
+ * ```
+ *
+ * @example
+ * ```js
+ * const { isPlainObject } = require('reliable-node-utils');
+ * if (isPlainObject(obj)) Object.keys(obj).forEach(k => process(k, obj[k]));
+ * ```
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+
+/**
+ * Replace `{key}` placeholders in a template string with quoted values.
+ *
+ * @param template - Input template containing placeholders like `{name}`
+ * @param replacements - Key/value mapping for placeholders
+ * @returns Formatted string with replacements wrapped in double quotes
+ *
+ * @example
+ * ```ts
+ * const out = replaceTemplateValues("Hello {name}", { name: "Sam" });
+ * // Hello "Sam"
+ * ```
+ */
+declare function replaceTemplateValues(template: string, replacements: Record<string, unknown>): string;
+/**
+ * Split a string using a delimiter.
+ */
+declare function splitString(input: string, delimiter: string): string[];
+/**
+ * Parse a strict boolean string (`true`/`false`, case-insensitive).
+ *
+ * @throws {Error} If input is empty or not a valid boolean string
+ */
+declare function parseBooleanString(input: string | undefined | null): boolean;
+/**
+ * True when value is null/undefined/empty-after-trim.
+ */
+declare function isNullOrEmptyString(value: string | null | undefined): boolean;
+/**
+ * Convert snake_case (or mixed case) string into PascalCase.
+ *
+ * @example
+ * ```ts
+ * snakeToPascalCase("user_name"); // UserName
+ * ```
+ */
+declare function snakeToPascalCase(input: string): string;
+/**
+ * Backward-compatible alias; output is PascalCase.
+ */
+declare const convertToCamelCase: typeof snakeToPascalCase;
+/**
+ * Backward-compatible alias for legacy naming.
+ */
+declare const formatStringValue: typeof replaceTemplateValues;
+
+/**
+ * Generate random alphanumeric string.
+ */
+declare function generateRandomAlphanumericString(length: number, options?: {
+    uppercase?: boolean;
+    rng?: () => number;
+}): string;
+/**
+ * Generate random N-digit integer (base-10).
+ *
+ * @throws {Error} If length is invalid
+ */
+declare function generateRandomNDigitNumber(length: number, options?: {
+    rng?: () => number;
+}): number;
+/**
+ * Generate random alphabetic string (letters only).
+ */
+declare function generateRandomAlphabeticString(length: number, options?: {
+    rng?: () => number;
+}): string;
+/**
+ * Backward-compatible alias for legacy naming.
+ */
+declare const getAlphaNumericString: typeof generateRandomAlphanumericString;
+/**
+ * Backward-compatible alias for legacy naming.
+ */
+declare const generateRandomNumber: typeof generateRandomNDigitNumber;
+/**
+ * Backward-compatible alias for legacy naming.
+ */
+declare const generateRandomString: typeof generateRandomAlphabeticString;
+
+/**
+ * Parse JSON text and recursively update matching keys.
+ *
+ * @param jsonText - JSON string input
+ * @param updates - key/value map applied across nested objects and object arrays
+ * @returns Pretty-printed updated JSON text
+ */
+declare function updateJsonValues(jsonText: string, updates: Record<string, string>): string;
+/**
+ * Backward-compatible alias for legacy naming.
+ */
+declare const updateJsonData: typeof updateJsonValues;
+
+type RelativeDateToken = "Today" | "Yesterday" | "Year";
+/**
+ * Get a formatted date for Today/Yesterday/Year(-1 year).
+ *
+ * @param token - Relative token
+ * @param format - Pattern (default `yyyy-MM-dd`)
+ * @param now - Optional injection point for tests
+ */
+declare function getRelativeDate(token: RelativeDateToken | string, format?: string, now?: Date): string;
+/**
+ * Backward-compatible alias for legacy naming.
+ */
+declare const getDate: typeof getRelativeDate;
+
+/**
+ * Rename a key in a string map and strip wrapping quotes from its value.
+ *
+ * @returns true if key existed and was renamed, else false.
+ */
+declare function renameMapKey(data: Map<string, string>, oldKey: string, newKey: string): boolean;
+/**
+ * Backward-compatible alias for legacy naming.
+ */
+declare const updateKey: typeof renameMapKey;
+
+interface UniqueValueStore {
+    has(value: string): boolean | Promise<boolean>;
+    add(value: string): void | Promise<void>;
+}
+declare class InMemoryUniqueValueStore implements UniqueValueStore {
+    private readonly values;
+    has(value: string): boolean;
+    add(value: string): void;
+}
+declare function getScopedInMemoryStore(scope: string): InMemoryUniqueValueStore;
+declare function clearScopedInMemoryStores(): void;
+
+interface NameProvider {
+    firstName(options?: {
+        rng?: () => number;
+    }): string;
+    lastName(options?: {
+        rng?: () => number;
+    }): string;
+}
+interface FakerLike {
+    person: {
+        firstName: () => string;
+        lastName: () => string;
+    };
+}
+/**
+ * Name provider backed by the in-repo curated dataset.
+ */
+declare class StaticDatasetNameProvider implements NameProvider {
+    firstName(options?: {
+        rng?: () => number;
+    }): string;
+    lastName(options?: {
+        rng?: () => number;
+    }): string;
+}
+/**
+ * Name provider backed by `@faker-js/faker`.
+ *
+ * Useful for large-scale synthetic name generation without maintaining
+ * in-repo name lists.
+ */
+declare class FakerNameProvider implements NameProvider {
+    private readonly faker;
+    constructor(options?: {
+        faker?: FakerLike;
+    });
+    firstName(): string;
+    lastName(): string;
+}
+declare const DEFAULT_NAME_PROVIDER: StaticDatasetNameProvider;
+
+interface NameGenerationOptions {
+    /** Inject deterministic random source for tests. Default: Math.random. */
+    rng?: () => number;
+    /** Override name source (dataset/faker/custom). */
+    provider?: NameProvider;
+}
+interface UniqueNameOptions extends NameGenerationOptions {
+    /** Scope for in-memory uniqueness when no custom store is provided. */
+    scope?: string;
+    /** Custom persistence layer for cross-process uniqueness. */
+    store?: UniqueValueStore;
+    /** Maximum attempts to find an unused value. Default: 1000. */
+    maxAttempts?: number;
+    /** Normalize value before checking uniqueness. Default: lowercase trim. */
+    normalize?: (value: string) => string;
+}
+/**
+ * Generate a realistic first name from a curated common-name list.
+ *
+ * @example
+ * ```ts
+ * const first = generateFirstName();
+ * ```
+ */
+declare function generateFirstName(options?: NameGenerationOptions): string;
+/**
+ * Generate a realistic last name from a curated common-name list.
+ *
+ * @example
+ * ```ts
+ * const last = generateLastName();
+ * ```
+ */
+declare function generateLastName(options?: NameGenerationOptions): string;
+/**
+ * Generate a realistic full name.
+ *
+ * @example
+ * ```ts
+ * const fullName = generateFullName();
+ * ```
+ */
+declare function generateFullName(options?: NameGenerationOptions): string;
+/**
+ * Generate a unique first name within a scope/store.
+ */
+declare function generateUniqueFirstName(options?: UniqueNameOptions): Promise<string>;
+/**
+ * Generate a unique last name within a scope/store.
+ */
+declare function generateUniqueLastName(options?: UniqueNameOptions): Promise<string>;
+/**
+ * Generate a unique full name within a scope/store.
+ */
+declare function generateUniqueFullName(options?: UniqueNameOptions): Promise<string>;
+
+type SupportedCountryCode = "US" | "CA";
+interface PostalCodeLookupRequest {
+    country: SupportedCountryCode;
+    postalCode: string;
+    signal?: AbortSignal;
+}
+interface AddressInput {
+    country: SupportedCountryCode;
+    postalCode: string;
+    city?: string;
+    stateProvince?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    signal?: AbortSignal;
+}
+interface ValidatedPostalCodeAddress {
+    country: SupportedCountryCode;
+    postalCode: string;
+    city: string;
+    stateProvince: string;
+    source: string;
+    uspsVerified: boolean;
+}
+interface VerifiedAddress {
+    country: SupportedCountryCode;
+    postalCode: string;
+    city: string;
+    stateProvince: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    source: string;
+    uspsVerified: boolean;
+}
+interface AddressProvider {
+    readonly name: string;
+    supportsCountry(country: SupportedCountryCode): boolean;
+    lookupPostalCode(request: PostalCodeLookupRequest): Promise<ValidatedPostalCodeAddress>;
+    verifyAddress(request: AddressInput): Promise<VerifiedAddress>;
+}
+
+interface GetValidAddressByPostalCodeOptions {
+    country: SupportedCountryCode;
+    postalCode: string;
+    providers: AddressProvider[];
+    signal?: AbortSignal;
+    /**
+     * When true, US lookups must use the USPS provider.
+     * Default: true
+     */
+    requireUspsForUS?: boolean;
+}
+interface VerifyAddressOptions {
+    address: AddressInput;
+    providers: AddressProvider[];
+    /**
+     * When true, US verification must use the USPS provider.
+     * Default: true
+     */
+    requireUspsForUS?: boolean;
+}
+/**
+ * Resolve a valid city/state-province for a postal code.
+ * For US, this can be configured to strictly require USPS.
+ */
+declare function getValidAddressByPostalCode(options: GetValidAddressByPostalCodeOptions): Promise<ValidatedPostalCodeAddress>;
+/**
+ * Verify and normalize an address with the best provider for its country.
+ * For US, this can be configured to strictly require USPS.
+ */
+declare function verifyAddress(options: VerifyAddressOptions): Promise<VerifiedAddress>;
+
+/**
+ * Custom error base for utilities. Enables `instanceof` checks and preserves cause.
+ * @internal
+ */
+declare class UtilsError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an operation is aborted via AbortSignal.
+ * @public
+ */
+declare class AbortError extends UtilsError {
+    readonly name = "AbortError";
+}
+/**
+ * Thrown when an operation exceeds its time limit (e.g. withTimeout).
+ * @public
+ */
+declare class TimeoutError extends UtilsError {
+    readonly name = "TimeoutError";
+}
+/**
+ * Thrown when retry exhausts all attempts without success.
+ * @public
+ */
+declare class RetryExhaustedError extends UtilsError {
+    readonly attempt: number;
+    readonly lastError: unknown;
+    readonly name = "RetryExhaustedError";
+    constructor(message: string, attempt: number, lastError: unknown, options?: {
+        cause?: unknown;
+    });
+}
+
+declare class AddressProviderError extends UtilsError {
+    readonly name = "AddressProviderError";
+}
+declare class AddressVerificationError extends UtilsError {
+    readonly name = "AddressVerificationError";
+}
+declare class ProviderNotFoundError extends UtilsError {
+    readonly name = "ProviderNotFoundError";
+}
+
+interface UspsAddressProviderOptions {
+    userId: string;
+    endpoint?: string;
+}
+declare class UspsAddressProvider implements AddressProvider {
+    readonly name = "USPS";
+    private readonly endpoint;
+    private readonly userId;
+    constructor(options: UspsAddressProviderOptions);
+    supportsCountry(country: SupportedCountryCode): boolean;
+    lookupPostalCode(request: PostalCodeLookupRequest): Promise<ValidatedPostalCodeAddress>;
+    verifyAddress(request: AddressInput): Promise<VerifiedAddress>;
+    private callApi;
+}
+
+interface ZippopotamAddressProviderOptions {
+    endpoint?: string;
+}
+declare class ZippopotamAddressProvider implements AddressProvider {
+    readonly name = "Zippopotam";
+    private readonly endpoint;
+    constructor(options?: ZippopotamAddressProviderOptions);
+    supportsCountry(country: SupportedCountryCode): boolean;
+    lookupPostalCode(request: PostalCodeLookupRequest): Promise<ValidatedPostalCodeAddress>;
+    verifyAddress(request: AddressInput): Promise<VerifiedAddress>;
+}
+
+interface CanadaPostAddressProviderOptions {
+    key: string;
+    findEndpoint?: string;
+    retrieveEndpoint?: string;
+}
+declare class CanadaPostAddressProvider implements AddressProvider {
+    readonly name = "CanadaPost";
+    private readonly key;
+    private readonly findEndpoint;
+    private readonly retrieveEndpoint;
+    constructor(options: CanadaPostAddressProviderOptions);
+    supportsCountry(country: SupportedCountryCode): boolean;
+    lookupPostalCode(request: PostalCodeLookupRequest): Promise<ValidatedPostalCodeAddress>;
+    verifyAddress(request: AddressInput): Promise<VerifiedAddress>;
+    private findAndRetrieve;
+    private callFind;
+    private callRetrieve;
+}
+
+export { AbortError, type AddressInput, type AddressProvider, AddressProviderError, AddressVerificationError, CanadaPostAddressProvider, type CanadaPostAddressProviderOptions, DEFAULT_NAME_PROVIDER, FakerNameProvider, type GetValidAddressByPostalCodeOptions, InMemoryUniqueValueStore, type MemoizeOptions, type NameGenerationOptions, type NameProvider, type PostalCodeLookupRequest, ProviderNotFoundError, type RelativeDateToken, RetryExhaustedError, type RetryOptions, StaticDatasetNameProvider, type SupportedCountryCode, TimeoutError, type UniqueNameOptions, type UniqueValueStore, UspsAddressProvider, type UspsAddressProviderOptions, type ValidatedPostalCodeAddress, type VerifiedAddress, type VerifyAddressOptions, type WithTimeoutOptions, ZippopotamAddressProvider, type ZippopotamAddressProviderOptions, clearScopedInMemoryStores, convertToCamelCase, deepMerge, formatStringValue, generateFirstName, generateFullName, generateLastName, generateRandomAlphabeticString, generateRandomAlphanumericString, generateRandomNDigitNumber, generateRandomNumber, generateRandomString, generateUniqueFirstName, generateUniqueFullName, generateUniqueLastName, getAlphaNumericString, getDate, getRelativeDate, getScopedInMemoryStore, getValidAddressByPostalCode, isDefined, isNonEmptyString, isNullOrEmptyString, isPlainObject, memoize, pLimit, parseBooleanString, renameMapKey, replaceTemplateValues, retry, snakeToPascalCase, splitString, updateJsonData, updateJsonValues, updateKey, verifyAddress, withTimeout };