@pithos/core 2.0.0

package/dist/arkhe/async/parallel.js

@@ -0,0 +1,57 @@
+import { clamp } from "../number/clamp";
+/**
+ * Executes multiple async functions in parallel with concurrency control.
+ *
+ * @template T - The return type of the functions.
+ * @param functions - Array of async functions to execute.
+ * @param concurrency - Maximum number of concurrent executions. Defaults to `Infinity`.
+ * @defaultValue Infinity
+ * @returns Promise that resolves to array of results in original order.
+ * @throws Rejects if any function rejects (remaining operations are aborted).
+ * @since 1.1.0
+ *
+ * @note Results preserve input order. Fails fast like `Promise.all()`.
+ *
+ * @performance Early abort on first error prevents unnecessary work.
+ *
+ * @example
+ * ```typescript
+ * const results = await parallel([
+ *   () => fetchUser(1),
+ *   () => fetchUser(2),
+ *   () => fetchUser(3)
+ * ], 2);
+ * ```
+ */
+export async function parallel(functions, concurrency = Infinity) {
+    // Stryker disable next-line ConditionalExpression,BlockStatement: Performance optimization - worker loop produces identical results for Infinity
+    if (concurrency === Infinity) {
+        return Promise.all(functions.map((fn) => fn()));
+    }
+    // Stryker disable next-line ConditionalExpression,BlockStatement: Early return optimization - while loop produces identical empty result
+    if (functions.length === 0) {
+        // Stryker disable next-line ArrayDeclaration: Early return optimization - while loop handles empty array identically
+        return [];
+    }
+    // Stryker disable next-line ArrayDeclaration: pre-allocation optimization
+    const results = new Array(functions.length);
+    let index = 0;
+    let hasError = false;
+    const executeNext = async () => {
+        while (index < functions.length && !hasError) {
+            const currentIndex = index++;
+            try {
+                const result = await functions[currentIndex]();
+                results[currentIndex] = result;
+            }
+            catch (error) {
+                hasError = true;
+                throw error;
+            }
+        }
+    };
+    const workers = Array.from({ length: clamp(concurrency, 1, functions.length) }, () => executeNext());
+    await Promise.all(workers);
+    return results;
+}
+//# sourceMappingURL=parallel.js.map

package/dist/arkhe/async/parallel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.js","sourceRoot":"","sources":["../../../src/arkhe/async/parallel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,SAA+B,EAC/B,cAAsB,QAAQ;IAE9B,iJAAiJ;IACjJ,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,yIAAyI;IACzI,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,qHAAqH;QACrH,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,0EAA0E;IAC1E,MAAM,OAAO,GAAQ,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACjD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,WAAW,GAAG,KAAK,IAAmB,EAAE;QAC5C,OAAO,KAAK,GAAG,SAAS,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC7C,MAAM,YAAY,GAAG,KAAK,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC/C,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC;YACjC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,GAAG,IAAI,CAAC;gBAChB,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CACxB,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,EACnD,GAAG,EAAE,CAAC,WAAW,EAAE,CACpB,CAAC;IAEF,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/arkhe/async/queue-by-key.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Queues async functions by key to ensure sequential execution.
+ *
+ * @template T - The return type of the function.
+ * @param key - Unique key for the operation queue.
+ * @param fn - The async function to queue.
+ * @returns Promise that resolves to the function result.
+ * @throws Rejects if the queued function rejects.
+ * @since 1.1.0
+ *
+ * @note Functions with the same key execute sequentially. Different keys run in parallel.
+ *
+ * @performance Silently catches errors to prevent queue breakage; errors still propagate to caller.
+ *
+ * @see dedupeByKey — for deduplication instead of queuing.
+ *
+ * @example
+ * ```typescript
+ * // Sequential execution for same key
+ * queueByKey('user-123', () => updateUser('123'));
+ * queueByKey('user-123', () => updateUser('123'));
+ * // Second waits for first to complete
+ *
+ * // Parallel execution for different keys
+ * queueByKey('user-A', () => updateUser('A'));
+ * queueByKey('user-B', () => updateUser('B'));
+ * ```
+ */
+export declare function queueByKey<T>(key: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=queue-by-key.d.ts.map

package/dist/arkhe/async/queue-by-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-by-key.d.ts","sourceRoot":"","sources":["../../../src/arkhe/async/queue-by-key.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/arkhe/async/queue-by-key.js

@@ -0,0 +1,43 @@
+const queueMap = new Map();
+/**
+ * Queues async functions by key to ensure sequential execution.
+ *
+ * @template T - The return type of the function.
+ * @param key - Unique key for the operation queue.
+ * @param fn - The async function to queue.
+ * @returns Promise that resolves to the function result.
+ * @throws Rejects if the queued function rejects.
+ * @since 1.1.0
+ *
+ * @note Functions with the same key execute sequentially. Different keys run in parallel.
+ *
+ * @performance Silently catches errors to prevent queue breakage; errors still propagate to caller.
+ *
+ * @see dedupeByKey — for deduplication instead of queuing.
+ *
+ * @example
+ * ```typescript
+ * // Sequential execution for same key
+ * queueByKey('user-123', () => updateUser('123'));
+ * queueByKey('user-123', () => updateUser('123'));
+ * // Second waits for first to complete
+ *
+ * // Parallel execution for different keys
+ * queueByKey('user-A', () => updateUser('A'));
+ * queueByKey('user-B', () => updateUser('B'));
+ * ```
+ */
+export async function queueByKey(key, fn) {
+    const previous = queueMap.get(key) ?? Promise.resolve();
+    const current = previous.then(() => fn());
+    const silent = current.catch(() => { });
+    queueMap.set(key, silent);
+    // Stryker disable next-line BlockStatement: internal cleanup, memory optimization only
+    return current.finally(() => {
+        // Stryker disable next-line ConditionalExpression,BlockStatement,EqualityOperator: internal cleanup, memory optimization only
+        if (queueMap.get(key) === silent) {
+            queueMap.delete(key);
+        }
+    });
+}
+//# sourceMappingURL=queue-by-key.js.map

package/dist/arkhe/async/queue-by-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-by-key.js","sourceRoot":"","sources":["../../../src/arkhe/async/queue-by-key.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA4B,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAW,EACX,EAAoB;IAEpB,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAExD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAEvC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAE1B,uFAAuF;IACvF,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;QAC1B,8HAA8H;QAC9H,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM,EAAE,CAAC;YACjC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/arkhe/async/retry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Configuration options for retry behavior.
+ *
+ * @since 2.0.0
+ */
+export interface RetryOptions {
+    /** Number of retry attempts. Defaults to `3`. */
+    attempts?: number;
+    /** Initial delay between retries in milliseconds. Defaults to `1000`. */
+    delay?: number;
+    /** Backoff multiplier for delay. Defaults to `1` (no backoff). */
+    backoff?: number;
+    /** Maximum delay between retries in milliseconds. Defaults to `10000`. */
+    maxDelay?: number;
+    /** Random jitter factor (0-1) to add variation to delay. Defaults to `0`. */
+    jitter?: number;
+    /** Function to determine if error should trigger retry. Return `false` to abort. */
+    until?: (error: unknown) => boolean;
+}
+/**
+ * Retries an async function with configurable backoff and error filtering.
+ *
+ * @info Why wrapping native?: We prefer to wrap this to improve resilience against transient failures, adhering to **Fail Fast** principles by managing retries declaratively. See [Design Philosophy](/guide/contribution/design-principles/design-philosophy/)
+ *
+ *
+ * @template T - The return type of the function.
+ * @param fn - The async function to retry.
+ * @param options - Retry configuration options.
+ * @returns Promise that resolves to the function's return value.
+ * @throws The last error thrown by `fn` if all retries fail.
+ * @since 1.1.0
+ *
+ * @performance Exponential backoff with `maxDelay` cap prevents excessive wait times.
+ *              Jitter prevents thundering herd problem in distributed systems.
+ *
+ * @example
+ * ```typescript
+ * const result = await retry(() => fetchData(), { attempts: 3 });
+ *
+ * const result = await retry(() => apiCall(), {
+ *   attempts: 5,
+ *   delay: 1000,
+ *   backoff: 2,
+ *   jitter: 0.5,
+ *   until: (error) => error.code !== 'PERMANENT_ERROR'
+ * });
+ * ```
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/arkhe/async/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/arkhe/async/retry.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAgCZ"}

package/dist/arkhe/async/retry.js

@@ -0,0 +1,53 @@
+import { sleep } from "../util/sleep";
+/**
+ * Retries an async function with configurable backoff and error filtering.
+ *
+ * @info Why wrapping native?: We prefer to wrap this to improve resilience against transient failures, adhering to **Fail Fast** principles by managing retries declaratively. See [Design Philosophy](/guide/contribution/design-principles/design-philosophy/)
+ *
+ *
+ * @template T - The return type of the function.
+ * @param fn - The async function to retry.
+ * @param options - Retry configuration options.
+ * @returns Promise that resolves to the function's return value.
+ * @throws The last error thrown by `fn` if all retries fail.
+ * @since 1.1.0
+ *
+ * @performance Exponential backoff with `maxDelay` cap prevents excessive wait times.
+ *              Jitter prevents thundering herd problem in distributed systems.
+ *
+ * @example
+ * ```typescript
+ * const result = await retry(() => fetchData(), { attempts: 3 });
+ *
+ * const result = await retry(() => apiCall(), {
+ *   attempts: 5,
+ *   delay: 1000,
+ *   backoff: 2,
+ *   jitter: 0.5,
+ *   until: (error) => error.code !== 'PERMANENT_ERROR'
+ * });
+ * ```
+ */
+export async function retry(fn, options = {}) {
+    const { attempts = 3, delay = 1000, backoff = 1, maxDelay = 10000, jitter = 0, until = () => true, } = options;
+    let lastError;
+    let currentDelay = delay;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (!until(error)) {
+                throw error;
+            }
+            if (attempt < attempts - 1) {
+                const jitterAmount = currentDelay * jitter * Math.random();
+                await sleep(currentDelay + jitterAmount);
+                currentDelay = Math.min(currentDelay * backoff, maxDelay);
+            }
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=retry.js.map

package/dist/arkhe/async/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/arkhe/async/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAsB1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,EAAoB,EACpB,UAAwB,EAAE;IAE1B,MAAM,EACJ,QAAQ,GAAG,CAAC,EACZ,KAAK,GAAG,IAAI,EACZ,OAAO,GAAG,CAAC,EACX,QAAQ,GAAG,KAAK,EAChB,MAAM,GAAG,CAAC,EACV,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,GACnB,GAAG,OAAO,CAAC;IAEZ,IAAI,SAAkB,CAAC;IACvB,IAAI,YAAY,GAAG,KAAK,CAAC;IAEzB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,CAAC;YAElB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;gBAClB,MAAM,KAAK,CAAC;YACd,CAAC;YAED,IAAI,OAAO,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,YAAY,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC3D,MAAM,KAAK,CAAC,YAAY,GAAG,YAAY,CAAC,CAAC;gBACzC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,GAAG,OAAO,EAAE,QAAQ,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC"}

package/dist/arkhe/function/after.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Creates a function that invokes func after it's called n or more times.
+ *
+ * @template Args - The argument types of the function.
+ * @template Return - The return type of the function.
+ * @param func - The function to restrict.
+ * @param n - The number of calls before func is invoked.
+ * @returns The new restricted function. Returns `undefined` for the first `n-1` calls.
+ * @throws {RangeError} If n is negative or not an integer.
+ * @see before - Inverse operation: invokes func at most n-1 times.
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * let attempts = 0;
+ * const saveData = after(() => {
+ *   attempts++;
+ *   console.log(`Data saved! Attempt #${attempts}`);
+ * }, 3);
+ *
+ * saveData(); // Nothing happens
+ * saveData(); // Nothing happens
+ * saveData(); // "Data saved! Attempt #1"
+ * saveData(); // "Data saved! Attempt #2"
+ * saveData(); // "Data saved! Attempt #3"
+ *
+ * // Use case: Only start logging after initial setup calls
+ * const logger = after((message: string) => {
+ *   console.log(`[LOG] ${message}`);
+ * }, 2);
+ *
+ * logger('Initializing...'); // Nothing (setup call)
+ * logger('Loading config...'); // "[LOG] Loading config..."
+ * logger('Ready!'); // "[LOG] Ready!"
+ * ```
+ */
+export declare function after<Args extends unknown[], Return>(func: (...args: Args) => Return, n: number): (...args: Args) => Return | undefined;
+//# sourceMappingURL=after.d.ts.map

package/dist/arkhe/function/after.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"after.d.ts","sourceRoot":"","sources":["../../../src/arkhe/function/after.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,KAAK,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EAClD,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,EAC/B,CAAC,EAAE,MAAM,GACR,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GAAG,SAAS,CAYvC"}

package/dist/arkhe/function/after.js

@@ -0,0 +1,50 @@
+/**
+ * Creates a function that invokes func after it's called n or more times.
+ *
+ * @template Args - The argument types of the function.
+ * @template Return - The return type of the function.
+ * @param func - The function to restrict.
+ * @param n - The number of calls before func is invoked.
+ * @returns The new restricted function. Returns `undefined` for the first `n-1` calls.
+ * @throws {RangeError} If n is negative or not an integer.
+ * @see before - Inverse operation: invokes func at most n-1 times.
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * let attempts = 0;
+ * const saveData = after(() => {
+ *   attempts++;
+ *   console.log(`Data saved! Attempt #${attempts}`);
+ * }, 3);
+ *
+ * saveData(); // Nothing happens
+ * saveData(); // Nothing happens
+ * saveData(); // "Data saved! Attempt #1"
+ * saveData(); // "Data saved! Attempt #2"
+ * saveData(); // "Data saved! Attempt #3"
+ *
+ * // Use case: Only start logging after initial setup calls
+ * const logger = after((message: string) => {
+ *   console.log(`[LOG] ${message}`);
+ * }, 2);
+ *
+ * logger('Initializing...'); // Nothing (setup call)
+ * logger('Loading config...'); // "[LOG] Loading config..."
+ * logger('Ready!'); // "[LOG] Ready!"
+ * ```
+ */
+export function after(func, n) {
+    if (n < 0)
+        throw new RangeError("n must be non-negative");
+    if (!Number.isInteger(n))
+        throw new RangeError("n must be an integer");
+    let count = 0;
+    return (...args) => {
+        if (++count >= n) {
+            return func(...args);
+        }
+        return undefined;
+    };
+}
+//# sourceMappingURL=after.js.map

package/dist/arkhe/function/after.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"after.js","sourceRoot":"","sources":["../../../src/arkhe/function/after.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,KAAK,CACnB,IAA+B,EAC/B,CAAS;IAET,IAAI,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,wBAAwB,CAAC,CAAC;IAC1D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,sBAAsB,CAAC,CAAC;IAEvE,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,OAAO,CAAC,GAAG,IAAI,EAAE,EAAE;QACjB,IAAI,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC"}

package/dist/arkhe/function/before.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Creates a function that invokes func at most n-1 times.
+ * Subsequent calls return the result of the last invocation.
+ *
+ * @template Args - The argument types of the function.
+ * @template Return - The return type of the function.
+ * @param func - The function to restrict.
+ * @param n - The number of calls at which func is no longer invoked.
+ * @returns The new restricted function. Returns `undefined` until func is first invoked.
+ * @throws {RangeError} If n is negative or not an integer.
+ * @see after - Inverse operation: invokes func only after n calls.
+ * @since 2.0.0
+ *
+ * @note When n ≤ 1, func is never invoked and `undefined` is always returned.
+ *
+ * @example
+ * ```typescript
+ * let count = 0;
+ * const increment = before(() => ++count, 3);
+ *
+ * increment(); // => 1
+ * increment(); // => 2
+ * increment(); // => 2 (no longer invoked)
+ * increment(); // => 2
+ *
+ * // Use case: Initialize only once
+ * const initialize = before(() => {
+ *   console.log('Initializing...');
+ *   return { ready: true };
+ * }, 2);
+ *
+ * initialize(); // "Initializing..." => { ready: true }
+ * initialize(); // => { ready: true } (cached)
+ * ```
+ */
+export declare function before<Args extends unknown[], Return>(func: (...args: Args) => Return, n: number): (...args: Args) => Return | undefined;
+//# sourceMappingURL=before.d.ts.map

package/dist/arkhe/function/before.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"before.d.ts","sourceRoot":"","sources":["../../../src/arkhe/function/before.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,MAAM,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACjD,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,EAC/B,CAAC,EAAE,MAAM,GACR,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GAAG,SAAS,CAgBvC"}

package/dist/arkhe/function/before.js

@@ -0,0 +1,53 @@
+/**
+ * Creates a function that invokes func at most n-1 times.
+ * Subsequent calls return the result of the last invocation.
+ *
+ * @template Args - The argument types of the function.
+ * @template Return - The return type of the function.
+ * @param func - The function to restrict.
+ * @param n - The number of calls at which func is no longer invoked.
+ * @returns The new restricted function. Returns `undefined` until func is first invoked.
+ * @throws {RangeError} If n is negative or not an integer.
+ * @see after - Inverse operation: invokes func only after n calls.
+ * @since 2.0.0
+ *
+ * @note When n ≤ 1, func is never invoked and `undefined` is always returned.
+ *
+ * @example
+ * ```typescript
+ * let count = 0;
+ * const increment = before(() => ++count, 3);
+ *
+ * increment(); // => 1
+ * increment(); // => 2
+ * increment(); // => 2 (no longer invoked)
+ * increment(); // => 2
+ *
+ * // Use case: Initialize only once
+ * const initialize = before(() => {
+ *   console.log('Initializing...');
+ *   return { ready: true };
+ * }, 2);
+ *
+ * initialize(); // "Initializing..." => { ready: true }
+ * initialize(); // => { ready: true } (cached)
+ * ```
+ */
+export function before(func, n) {
+    // Stryker disable next-line EqualityOperator: n < 0 catches negative values
+    if (n < 0)
+        throw new RangeError("n must be non-negative");
+    // Stryker disable next-line all: validates integer constraint
+    if (!Number.isInteger(n))
+        throw new RangeError("n must be an integer");
+    let count = 0;
+    let lastResult;
+    return (...args) => {
+        // Stryker disable next-line EqualityOperator: < n ensures func invoked exactly n-1 times
+        if (++count < n) {
+            lastResult = func(...args);
+        }
+        return lastResult;
+    };
+}
+//# sourceMappingURL=before.js.map

package/dist/arkhe/function/before.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"before.js","sourceRoot":"","sources":["../../../src/arkhe/function/before.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,MAAM,CAClB,IAA+B,EAC/B,CAAS;IAET,4EAA4E;IAC5E,IAAI,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,wBAAwB,CAAC,CAAC;IAC1D,8DAA8D;IAC9D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,sBAAsB,CAAC,CAAC;IAEvE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,UAA8B,CAAC;IAEnC,OAAO,CAAC,GAAG,IAAI,EAAE,EAAE;QACjB,yFAAyF;QACzF,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC;YAChB,UAAU,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/arkhe/function/cast-comparator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Options for the comparator function.
+ *
+ * @template ComparedValue - The type of values being compared.
+ * @since 2.0.0
+ */
+export interface ComparatorOptions<ComparedValue> {
+    /** Custom comparison function. */
+    compare?: (a: ComparedValue, b: ComparedValue) => number;
+    /** If true, reverses the sort order. */
+    reverse?: boolean;
+}
+/**
+ * Creates a comparator function for Array.sort() with flexible mapping and comparison options.
+ *
+ * @template Item - The type of items being sorted.
+ * @template Key - The type of the property key.
+ * @template MappedValue - The type of the mapped value.
+ * @param mapping - A property key or mapping function to extract the comparison value.
+ * @param options - Comparison options.
+ * @returns A comparator function for Array.sort().
+ * @since 2.0.0
+ *
+ * @note Null/undefined values sort last. Dates compare by timestamp. Uses `localeCompare` for strings.
+ *
+ * @example
+ * ```typescript
+ * const users = [{ name: 'John', age: 25 }, { name: 'Jane', age: 30 }];
+ *
+ * users.sort(castComparator('age'));
+ * // Sorted by age ascending
+ *
+ * users.sort(castComparator((u) => u.name.length));
+ * // Sorted by name length
+ *
+ * users.sort(castComparator('age', { reverse: true }));
+ * // Sorted by age descending
+ * ```
+ */
+export declare function castComparator<Item, Key extends keyof Item>(key: Key, options?: ComparatorOptions<Item[Key]>): (a: Item, b: Item) => number;
+export declare function castComparator<Item, MappedValue>(mapper: (item: Item) => MappedValue, options?: ComparatorOptions<MappedValue>): (a: Item, b: Item) => number;
+//# sourceMappingURL=cast-comparator.d.ts.map

package/dist/arkhe/function/cast-comparator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cast-comparator.d.ts","sourceRoot":"","sources":["../../../src/arkhe/function/cast-comparator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,aAAa;IAC9C,kCAAkC;IAClC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,KAAK,MAAM,CAAC;IACzD,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,SAAS,MAAM,IAAI,EACzD,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GACrC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,KAAK,MAAM,CAAC;AAChC,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,EAC9C,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,WAAW,EACnC,OAAO,CAAC,EAAE,iBAAiB,CAAC,WAAW,CAAC,GACvC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,KAAK,MAAM,CAAC"}

package/dist/arkhe/function/cast-comparator.js

@@ -0,0 +1,41 @@
+/**
+ * Default comparison function handling common types.
+ *
+ * @internal
+ */
+const defaultCompare = (a, b) => {
+    if (Object.is(a, b))
+        return 0;
+    if (a === null || a === undefined)
+        return 1;
+    if (b === null || b === undefined)
+        return -1;
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() - b.getTime();
+    }
+    // Stryker disable next-line all: equivalent mutant, String(string) === string, so fallback produces identical result
+    if (typeof a === "string" && typeof b === "string") {
+        return a.localeCompare(b);
+    }
+    if (typeof a === "number" && typeof b === "number") {
+        return a - b;
+    }
+    return String(a).localeCompare(String(b));
+};
+export function castComparator(mapping, options = {}) {
+    const { compare, reverse = false } = options;
+    const multiplier = reverse ? -1 : 1;
+    if (typeof mapping === "function") {
+        const mapper = mapping;
+        const compareFn = compare ??
+            defaultCompare;
+        // Stryker disable next-line ArithmeticOperator: equivalent mutant, x*1=x/1 and x*(-1)=x/(-1)
+        return (a, b) => compareFn(mapper(a), mapper(b)) * multiplier;
+    }
+    const key = mapping;
+    const compareFn = compare ??
+        defaultCompare;
+    // Stryker disable next-line ArithmeticOperator: equivalent mutant, x*1=x/1 and x*(-1)=x/(-1)
+    return (a, b) => compareFn(a[key], b[key]) * multiplier;
+}
+//# sourceMappingURL=cast-comparator.js.map

package/dist/arkhe/function/cast-comparator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cast-comparator.js","sourceRoot":"","sources":["../../../src/arkhe/function/cast-comparator.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,MAAM,cAAc,GAAG,CAAQ,CAAQ,EAAE,CAAQ,EAAU,EAAE;IAC3D,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC;IAE7C,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;QAC3C,OAAO,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;IACnC,CAAC;IAED,qHAAqH;IACrH,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnD,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAED,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC,CAAC;AAsCF,MAAM,UAAU,cAAc,CAC5B,OAA4C,EAC5C,UAAyE,EAAE;IAE3E,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAC7C,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,OAAO,CAAC;QACvB,MAAM,SAAS,GACZ,OAAoE;YACrE,cAAc,CAAC;QACjB,6FAA6F;QAC7F,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC;IAChE,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC;IACpB,MAAM,SAAS,GACZ,OAAgE;QACjE,cAAc,CAAC;IACjB,6FAA6F;IAC7F,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC;AAC1D,CAAC"}

package/dist/arkhe/function/cast-mapping.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Creates a mapping function from a property key, function, or identity.
+ *
+ * @template Item - The type of items being mapped.
+ * @template Key - The type of the property key.
+ * @template Result - The type of the mapping result.
+ * @param input - Property key, mapping function, or nullish (identity).
+ * @returns A mapping function.
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const users = [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }];
+ *
+ * // Property key → accessor
+ * users.map(castMapping('name'));
+ * // => ['Alice', 'Bob']
+ *
+ * // Function → itself
+ * users.map(castMapping((u) => u.name.length));
+ * // => [5, 3]
+ *
+ * // Nullish → identity
+ * users.map(castMapping());
+ * // => [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }]
+ * ```
+ */
+export declare function castMapping<Item, Key extends keyof Item>(key: Key): (item: Item) => Item[Key];
+export declare function castMapping<Item, Result>(mapper: (item: Item) => Result): (item: Item) => Result;
+export declare function castMapping<Item>(input?: null): (item: Item) => Item;
+//# sourceMappingURL=cast-mapping.d.ts.map

package/dist/arkhe/function/cast-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cast-mapping.d.ts","sourceRoot":"","sources":["../../../src/arkhe/function/cast-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wBAAgB,WAAW,CAAC,IAAI,EAAE,GAAG,SAAS,MAAM,IAAI,EACtD,GAAG,EAAE,GAAG,GACP,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7B,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EACtC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,GAC7B,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;AAC1B,wBAAgB,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC"}

package/dist/arkhe/function/cast-mapping.js

@@ -0,0 +1,37 @@
+/**
+ * Creates a mapping function from a property key, function, or identity.
+ *
+ * @template Item - The type of items being mapped.
+ * @template Key - The type of the property key.
+ * @template Result - The type of the mapping result.
+ * @param input - Property key, mapping function, or nullish (identity).
+ * @returns A mapping function.
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const users = [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }];
+ *
+ * // Property key → accessor
+ * users.map(castMapping('name'));
+ * // => ['Alice', 'Bob']
+ *
+ * // Function → itself
+ * users.map(castMapping((u) => u.name.length));
+ * // => [5, 3]
+ *
+ * // Nullish → identity
+ * users.map(castMapping());
+ * // => [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }]
+ * ```
+ */
+export function castMapping(input) {
+    if (typeof input === "function") {
+        return input;
+    }
+    if (input != null) {
+        return (item) => item[input];
+    }
+    return (item) => item;
+}
+//# sourceMappingURL=cast-mapping.js.map

package/dist/arkhe/function/cast-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cast-mapping.js","sourceRoot":"","sources":["../../../src/arkhe/function/cast-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,MAAM,UAAU,WAAW,CACzB,KAA6C;IAE7C,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;AACxB,CAAC"}