@vielzeug/toolkit 1.0.14 → 1.1.2

package/dist/index.d.ts

@@ -260,6 +260,35 @@ export declare function average<T>(array: T[], callback?: (item: T) => number |
  */
 export declare function boil<T>(array: readonly T[], callback: (a: T, b: T) => T): T | undefined;
 
+/**
+ * Creates a generic key-value cache with automatic garbage collection and observer support.
+ *
+ * @example
+ * ```ts
+ * const myCache = cache<string>();
+ * myCache.set(['user', 1], 'John Doe');
+ * const value = myCache.get(['user', 1]); // 'John Doe'
+ * myCache.scheduleGc(['user', 1], 5000); // Auto-delete after 5s
+ * ```
+ *
+ * @template T - The type of values stored in the cache.
+ *
+ * @returns A cache instance with get, set, delete, clear, and GC methods.
+ */
+export declare function cache<T>(): {
+    clear: () => void;
+    delete: (key: readonly unknown[]) => boolean;
+    get: (key: readonly unknown[]) => T | undefined;
+    getMeta: (key: readonly unknown[]) => Record<string, unknown> | undefined;
+    getMetaByHash: (keyHash: string) => Record<string, unknown> | undefined;
+    hash: (key: readonly unknown[]) => string;
+    listMetaHashes: () => string[];
+    scheduleGc: (key: readonly unknown[], delayMs: number) => void;
+    set: (key: readonly unknown[], value: T) => void;
+    setMeta: (key: readonly unknown[], meta: Record<string, unknown>) => void;
+    size: () => number;
+};
+
 /** biome-ignore-all lint/suspicious/noExplicitAny: - */
 export declare type Callback<T = any, R = any> = (value: T, index: number, array: T[]) => R;
 
@@ -519,6 +548,29 @@ declare type DeepMerge<T, U> = T extends Obj ? U extends Obj ? {
     [K in keyof T | keyof U]: K extends keyof T ? K extends keyof U ? DeepMerge<T[K], U[K]> : T[K] : K extends keyof U ? U[K] : never;
 } : U : U;
 
+/**
+ * Creates a deferred promise with resolve and reject methods exposed.
+ * Useful for creating promises that are resolved/rejected externally.
+ *
+ * @example
+ * ```ts
+ * const deferred = defer<string>();
+ *
+ * setTimeout(() => {
+ *   deferred.resolve('Done!');
+ * }, 1000);
+ *
+ * const result = await deferred.promise; // 'Done!'
+ * ```
+ *
+ * @returns Object with promise and resolve/reject methods
+ */
+export declare function defer<T = void>(): {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+};
+
 /**
  * Delays the execution of a function by a specified amount of time.
  *
@@ -1898,6 +1950,27 @@ export declare function pipe<T extends FnDynamic[]>(...fns: T): PipeReturn<T>;
 
 declare type PipeReturn<T extends FnDynamic[]> = (...args: FirstParameters<T>) => LastReturnType<T> extends Promise<any> ? Promise<Awaited<LastReturnType<T>>> : LastReturnType<T>;
 
+/**
+ * Creates a promise pool that limits the number of concurrent promises.
+ * Useful for rate limiting API calls or controlling resource usage.
+ *
+ * @example
+ * ```ts
+ * const requestPool = pool(3);
+ *
+ * const results = await Promise.all([
+ *   requestPool(() => fetch('/api/1')),
+ *   requestPool(() => fetch('/api/2')),
+ *   requestPool(() => fetch('/api/3')),
+ *   requestPool(() => fetch('/api/4')), // Will wait for one of the above to finish
+ * ]);
+ * ```
+ *
+ * @param limit - Maximum number of concurrent promises
+ * @returns Function that accepts a promise-returning function and executes it when a slot is available
+ */
+export declare function pool(limit: number): <T>(fn: () => Promise<T>) => Promise<T>;
+
 export declare type Predicate<T> = (value: T, index: number, array: readonly T[]) => boolean;
 
 /**
@@ -1976,6 +2049,74 @@ declare type ProxyOptions<T> = {
  */
 export declare function prune<T>(value: T): T | undefined;
 
+/**
+ * Creates a promise queue that processes promises sequentially with optional concurrency limit.
+ *
+ * @example
+ * ```ts
+ * const requestQueue = queue({ concurrency: 2 });
+ *
+ * requestQueue.add(() => fetch('/api/1'));
+ * requestQueue.add(() => fetch('/api/2'));
+ * requestQueue.add(() => fetch('/api/3'));
+ *
+ * await requestQueue.onIdle(); // Wait for all tasks to complete
+ * ```
+ *
+ * @param options - Queue configuration
+ * @param options.concurrency - Maximum number of concurrent promises (default: 1)
+ * @returns Queue instance with add, onIdle, and clear methods
+ */
+export declare function queue(options?: {
+    concurrency?: number;
+}): {
+    /**
+     * Adds a promise-returning function to the queue
+     */
+    add: <T>(fn: () => Promise<T>) => Promise<T>;
+    /**
+     * Clears all pending tasks from the queue
+     */
+    clear: () => void;
+    /**
+     * Returns a promise that resolves when the queue becomes idle
+     */
+    onIdle: () => Promise<void>;
+    /**
+     * Returns the number of currently active promises
+     */
+    readonly pending: number;
+    /**
+     * Returns the current size of the queue
+     */
+    readonly size: number;
+};
+
+/**
+ * Race multiple promises but with a guaranteed minimum delay.
+ * Useful for showing loading states for at least a minimum duration.
+ *
+ * @example
+ * ```ts
+ * // Show loading spinner for at least 500ms
+ * const result = await race(
+ *   fetchData(),
+ *   500
+ * );
+ *
+ * // With multiple promises
+ * const result = await race(
+ *   [fetch('/api/1'), fetch('/api/2')],
+ *   1000
+ * );
+ * ```
+ *
+ * @param promises - Single promise or array of promises to race
+ * @param minDelay - Minimum delay in milliseconds before resolving
+ * @returns Promise that resolves with the first result after the minimum delay
+ */
+export declare function race<T>(promises: Promise<T> | Promise<T>[], minDelay: number): Promise<T>;
+
 /**
  * Generates a random integer between two values, inclusive.
  *
@@ -2621,6 +2762,40 @@ export declare function uuid(): string;
  */
 export declare function values<T extends Obj, K extends keyof T>(item: T): T[K][];
 
+/**
+ * Waits for a condition to become true by polling.
+ * Useful for waiting for DOM elements, API states, or other conditions.
+ *
+ * @example
+ * ```ts
+ * // Wait for an element to appear
+ * await waitFor(() => document.querySelector('#myElement') !== null);
+ *
+ * // Wait for API to be ready
+ * await waitFor(
+ *   async () => {
+ *     const res = await fetch('/api/health');
+ *     return res.ok;
+ *   },
+ *   { timeout: 30000, interval: 1000 }
+ * );
+ * ```
+ *
+ * @param condition - Function that returns true when condition is met
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait in ms (default: 5000)
+ * @param options.interval - Polling interval in ms (default: 100)
+ * @param options.signal - AbortSignal to cancel waiting
+ * @returns Promise that resolves when condition becomes true
+ * @throws {Error} If timeout is reached
+ * @throws {DOMException} If aborted via signal
+ */
+export declare function waitFor(condition: () => boolean | Promise<boolean>, options?: {
+    timeout?: number;
+    interval?: number;
+    signal?: AbortSignal;
+}): Promise<void>;
+
 /**
  * Creates a function that runs the provided callback in a web worker with specified dependencies.
  *