@develia/commons 0.4.22 → 0.4.24

package/src/collections/cache-dictionary.ts

@@ -46,9 +46,7 @@ export default class CacheDictionary<T> {
         if (duration === null) {
             delete this.expiration[key];
         } else {
-            const expiration = new Date();
-            expiration.setSeconds(expiration.getSeconds() + duration);
-            this.expiration[key] = expiration;
+            this.expiration[key] = this.calculateExpiration(duration);
         }
     }
 
@@ -109,8 +107,6 @@ export default class CacheDictionary<T> {
             return undefined;
         }
 
-        const expiration = new Date();
-        expiration.setSeconds(expiration.getSeconds() + duration);
-        return expiration;
+        return new Date(Date.now() + duration * 1000);
     }
 }

package/src/debouncer.ts

@@ -0,0 +1,135 @@
+import {delay} from "./utilities.js";
+import {noop} from "./functions.js";
+
+/**
+ * Cancellable task. It must honour `signal`: pass it to fetch/SDKs and check
+ * `signal.aborted` before producing irreversible side effects.
+ */
+export type DebouncedTask = (signal: AbortSignal) => Promise<void>;
+
+/** Options accepted by {@link Debouncer}. */
+export interface DebouncerOptions {
+    /** Default wait, in milliseconds, before a task is executed. */
+    delayMs: number;
+    /** Called every time a task is scheduled, after any previous task has been cancelled. */
+    onSchedule?: () => void;
+    /** Called when the wait elapses and the task is about to run. */
+    onStart?: () => void;
+    /** Called when a task completes without throwing and without being cancelled. */
+    onSuccess?: () => void;
+    /** Called when a live task is cancelled, either by {@link Debouncer.cancel} or by being replaced. */
+    onCancel?: () => void;
+    /** Receives task errors. Cancellations never reach this callback. Defaults to `console.error`. */
+    onError?: (error: unknown) => void;
+    /** Called every time the debouncer goes from busy to idle. */
+    onIdle?: () => void;
+}
+
+/**
+ * Keeps at most one live task.
+ * Scheduling a new task cancels the previous one, whether it was still
+ * waiting or already running.
+ *
+ * @example
+ * ```ts
+ * const debouncer = new Debouncer({delayMs: 1500});
+ *
+ * debouncer.schedule(async (signal) => {
+ *     const reply = await callAI(messages, {signal});
+ *     if (signal.aborted) return;
+ *     await sendReply(reply);
+ * });
+ * ```
+ */
+export default class Debouncer {
+    #controller: AbortController | undefined;
+    readonly #delayMs: number;
+    readonly #onSchedule: () => void;
+    readonly #onStart: () => void;
+    readonly #onSuccess: () => void;
+    readonly #onCancel: () => void;
+    readonly #onError: (error: unknown) => void;
+    readonly #onIdle: () => void;
+
+    constructor(options: DebouncerOptions) {
+        assertValidDelay(options.delayMs);
+        this.#delayMs = options.delayMs;
+        this.#onSchedule = options.onSchedule ?? noop;
+        this.#onStart = options.onStart ?? noop;
+        this.#onSuccess = options.onSuccess ?? noop;
+        this.#onCancel = options.onCancel ?? noop;
+        this.#onError = options.onError ?? console.error;
+        this.#onIdle = options.onIdle ?? noop;
+    }
+
+    /** Whether a task is waiting or running. */
+    get isPending(): boolean {
+        return this.#controller !== undefined;
+    }
+
+    /**
+     * Schedule `task`, cancelling any previous task.
+     *
+     * @param task - The task to run once the delay elapses.
+     * @param delayMs - Wait for this task only. Defaults to the configured `delayMs`.
+     */
+    schedule(task: DebouncedTask, delayMs: number = this.#delayMs): void {
+        assertValidDelay(delayMs);
+        if (this.#controller !== undefined) {
+            this.#controller.abort();
+            this.#onCancel();
+        }
+
+        const controller = new AbortController();
+        this.#controller = controller;
+        this.#onSchedule();
+        void this.#run(task, delayMs, controller);
+    }
+
+    /** Cancel the current task, if any. */
+    cancel(): void {
+        if (this.#controller === undefined) {
+            return;
+        }
+        this.#controller.abort();
+        this.#onCancel();
+        this.#becomeIdle();
+    }
+
+    async #run(task: DebouncedTask, delayMs: number, controller: AbortController): Promise<void> {
+        const signal = controller.signal;
+        try {
+            await delay(delayMs, signal);
+            this.#onStart();
+            await task(signal);
+            if (!signal.aborted) {
+                this.#onSuccess();
+            }
+        } catch (error) {
+            if (!signal.aborted) {
+                this.#onError(error);
+            }
+        } finally {
+            // A replaced or cancelled task must not touch the current state.
+            if (this.#controller === controller) {
+                this.#becomeIdle();
+            }
+        }
+    }
+
+    #becomeIdle(): void {
+        this.#controller = undefined;
+        this.#onIdle();
+    }
+}
+
+/**
+ * Throw a `RangeError` unless `delayMs` is a finite number >= 0.
+ *
+ * @internal Shared with `KeyedDebouncer`; not part of the public API.
+ */
+export function assertValidDelay(delayMs: number): void {
+    if (!Number.isFinite(delayMs) || delayMs < 0) {
+        throw new RangeError(`delayMs must be a number >= 0 (received: ${delayMs})`);
+    }
+}

package/src/functions.ts

@@ -1,14 +1,6 @@
 type AnyFunction = (this: any, ...args: any[]) => any;
 type TimerHandle = ReturnType<typeof setTimeout>;
 
-/** Options that control when a debounced function is executed. */
-export interface DebounceOptions {
-    /** Execute on the first call in a debounce window. Defaults to false. */
-    leading?: boolean;
-    /** Execute after the debounce window using the latest arguments. Defaults to true. */
-    trailing?: boolean;
-}
-
 /** Options that control when a throttled function is executed. */
 export interface ThrottleOptions {
     /** Execute immediately on the first call in a throttle window. Defaults to true. */
@@ -18,15 +10,15 @@ export interface ThrottleOptions {
 }
 
 /**
- * A delayed function returned by {@link debounce} or {@link throttle}.
+ * A delayed function returned by {@link throttle}.
  *
  * @example
  * ```ts
- * const saveLater = debounce(save, 250);
- * saveLater();
+ * const refresh = throttle(loadData, 250);
+ * refresh();
  *
- * if (saveLater.pending()) {
- *     saveLater.flush();
+ * if (refresh.pending()) {
+ *     refresh.flush();
  * }
  * ```
  */
@@ -199,107 +191,6 @@ export function memoize<F extends AnyFunction, K = Parameters<F>[0]>(
     return memoized;
 }
 
-/**
- * Delay a function until no calls have been made for the configured wait time.
- * The latest arguments and this-context are used for the trailing execution.
- *
- * @example
- * ```ts
- * const search = debounce((query: string) => {
- *     console.log(query);
- * }, 300);
- *
- * search("com");
- * search("commons"); // only this value is printed after 300 ms
- * ```
- *
- * @example
- * ```ts
- * const track = debounce(sendAnalytics, 1000, {leading: true, trailing: false});
- *
- * track("open"); // executed immediately
- * track.cancel(); // cancel the pending debounce window
- * ```
- */
-export function debounce<F extends AnyFunction>(
-    fn: F,
-    wait: number,
-    options: DebounceOptions = {}
-): DeferredFunction<F> {
-    const delay = normalizeDelay(wait);
-    const leading = options.leading ?? false;
-    const trailing = options.trailing ?? true;
-
-    let timer: TimerHandle | undefined;
-    let lastArgs: Parameters<F> | undefined;
-    let lastThis: ThisParameterType<F> | undefined;
-    let result: ReturnType<F> | undefined;
-
-    const invoke = (): ReturnType<F> => {
-        const args = lastArgs!;
-        const context = lastThis!;
-        lastArgs = undefined;
-        lastThis = undefined;
-        result = fn.apply(context, args);
-        return result as ReturnType<F>;
-    };
-
-    const expire = (): void => {
-        timer = undefined;
-        if (trailing && lastArgs) {
-            invoke();
-        } else {
-            lastArgs = undefined;
-            lastThis = undefined;
-        }
-    };
-
-    const start = (): void => {
-        timer = setTimeout(expire, delay);
-    };
-
-    const debounced = function (this: ThisParameterType<F>, ...args: Parameters<F>): ReturnType<F> | undefined {
-        const invokeLeading = leading && timer === undefined;
-        lastArgs = args;
-        lastThis = this;
-
-        if (timer !== undefined) {
-            clearTimeout(timer);
-        }
-        start();
-
-        if (invokeLeading) {
-            return invoke();
-        }
-
-        return result;
-    } as DeferredFunction<F>;
-
-    debounced.cancel = (): void => {
-        if (timer !== undefined) {
-            clearTimeout(timer);
-        }
-        timer = undefined;
-        lastArgs = undefined;
-        lastThis = undefined;
-    };
-
-    debounced.flush = (): ReturnType<F> | undefined => {
-        if (timer !== undefined) {
-            clearTimeout(timer);
-            timer = undefined;
-            if (lastArgs && trailing) {
-                return invoke();
-            }
-        }
-        return result;
-    };
-
-    debounced.pending = (): boolean => timer !== undefined;
-
-    return debounced;
-}
-
 /**
  * Limit how often a function can run during a time window.
  * Calls made while the function is throttled can optionally be replayed once at the end with the latest arguments.

package/src/index.ts

@@ -21,7 +21,13 @@ export {default as Order} from './order.js';
 export {default as Timer} from './timer.js';
 export {default as TimeSpan} from './timespan.js';
 export {default as Stopwatch} from './stopwatch.js';
+export type {Result} from './result.js';
+export {TimeTrigger, CountTrigger} from './triggers.js';
 export {default as AsyncPoolExecutor} from './async-pool-executor.js';
+export {default as Debouncer} from './debouncer.js';
+export type {DebouncedTask, DebouncerOptions} from './debouncer.js';
+export {default as KeyedDebouncer} from './keyed-debouncer.js';
+export type {KeyedDebouncerOptions} from './keyed-debouncer.js';
 
 // ─── Patterns ────────────────────────────────────────
 export {default as Lazy} from './lazy.js';

package/src/keyed-debouncer.ts

@@ -0,0 +1,121 @@
+import Debouncer, {assertValidDelay, type DebouncedTask} from "./debouncer.js";
+import {noop} from "./functions.js";
+
+/** Options accepted by {@link KeyedDebouncer}. Every callback receives the affected key. */
+export interface KeyedDebouncerOptions<K> {
+    /** Default wait, in milliseconds, before a task is executed. */
+    delayMs: number;
+    /** Called every time a task is scheduled for `key`, after any previous task of that key has been cancelled. */
+    onSchedule?: (key: K) => void;
+    /** Called when the wait elapses and the task of `key` is about to run. */
+    onStart?: (key: K) => void;
+    /** Called when the task of `key` completes without throwing and without being cancelled. */
+    onSuccess?: (key: K) => void;
+    /** Called when a live task of `key` is cancelled, either explicitly or by being replaced. */
+    onCancel?: (key: K) => void;
+    /** Receives task errors. Cancellations never reach this callback. Defaults to `console.error`. */
+    onError?: (error: unknown, key: K) => void;
+    /** Called when `key` has no more pending work, after it has been removed from the debouncer. */
+    onIdle?: (key: K) => void;
+}
+
+/**
+ * An independent {@link Debouncer} per key.
+ * Debouncers only exist for keys with pending work: each one is created when
+ * its first task is scheduled and removed as soon as it becomes idle.
+ *
+ * @example
+ * ```ts
+ * const debouncer = new KeyedDebouncer<string>({delayMs: 1500});
+ *
+ * debouncer.schedule(chatId, async (signal) => {
+ *     const pending = await store.getPending(chatId);
+ *     const reply = await callAI(pending, {signal});
+ *     if (signal.aborted) return;
+ *     await sendReply(chatId, reply);
+ * });
+ * ```
+ */
+export default class KeyedDebouncer<K = string> {
+    readonly #debouncers = new Map<K, Debouncer>();
+    readonly #delayMs: number;
+    readonly #onSchedule: (key: K) => void;
+    readonly #onStart: (key: K) => void;
+    readonly #onSuccess: (key: K) => void;
+    readonly #onCancel: (key: K) => void;
+    readonly #onError: (error: unknown, key: K) => void;
+    readonly #onIdle: (key: K) => void;
+
+    constructor(options: KeyedDebouncerOptions<K>) {
+        assertValidDelay(options.delayMs);
+        this.#delayMs = options.delayMs;
+        this.#onSchedule = options.onSchedule ?? noop;
+        this.#onStart = options.onStart ?? noop;
+        this.#onSuccess = options.onSuccess ?? noop;
+        this.#onCancel = options.onCancel ?? noop;
+        this.#onError = options.onError ?? console.error;
+        this.#onIdle = options.onIdle ?? noop;
+    }
+
+    /** Number of keys with a task waiting or running. */
+    get size(): number {
+        return this.#debouncers.size;
+    }
+
+    /**
+     * Schedule `task` for `key`, cancelling any previous task of that key.
+     *
+     * @param key - The key whose task is replaced.
+     * @param task - The task to run once the delay elapses.
+     * @param delayMs - Wait for this task only. Defaults to the configured `delayMs`.
+     */
+    schedule(key: K, task: DebouncedTask, delayMs?: number): void {
+        const existing = this.#debouncers.get(key);
+        if (existing !== undefined) {
+            existing.schedule(task, delayMs);
+            return;
+        }
+
+        // Validate first so an invalid delay never registers the key.
+        assertValidDelay(delayMs ?? this.#delayMs);
+        const debouncer = this.#create(key);
+        this.#debouncers.set(key, debouncer);
+        debouncer.schedule(task, delayMs);
+    }
+
+    /** Cancel the task of `key`, if any. */
+    cancel(key: K): void {
+        this.#debouncers.get(key)?.cancel();
+    }
+
+    /** Cancel every task. Useful when shutting the process down. */
+    cancelAll(): void {
+        // Copy first: cancelling removes the debouncer from the map.
+        for (const debouncer of [...this.#debouncers.values()]) {
+            debouncer.cancel();
+        }
+    }
+
+    /** Whether a task is waiting or running for `key`. */
+    isPending(key: K): boolean {
+        return this.#debouncers.has(key);
+    }
+
+    #create(key: K): Debouncer {
+        const debouncer: Debouncer = new Debouncer({
+            delayMs: this.#delayMs,
+            onSchedule: () => this.#onSchedule(key),
+            onStart: () => this.#onStart(key),
+            onSuccess: () => this.#onSuccess(key),
+            onCancel: () => this.#onCancel(key),
+            onError: (error) => this.#onError(error, key),
+            onIdle: () => {
+                if (this.#debouncers.get(key) === debouncer) {
+                    this.#debouncers.delete(key);
+                    this.#onIdle(key);
+                }
+            },
+        });
+        return debouncer;
+    }
+}

package/src/result.ts

@@ -0,0 +1,6 @@
+/**
+ * Represents success and failure outputs narrowed by `success`.
+ */
+export type Result<TSuccessOutput, TFailureOutput = undefined> =
+    | {readonly success: true; readonly output: TSuccessOutput}
+    | {readonly success: false; readonly output?: TFailureOutput};

package/src/triggers.ts

@@ -0,0 +1,126 @@
+import type {Result} from './result.js';
+import TimeSpan from './timespan.js';
+import type {Nullable, Supplier} from './types.js';
+
+/**
+ * Runs a callback at most once during a configured time interval.
+ */
+export class TimeTrigger<T> {
+    private callback: Supplier<T | Promise<T>>;
+    private interval: TimeSpan;
+    private lastRunTime: Nullable<number>;
+
+    public constructor(callback: Supplier<T | Promise<T>>, interval: TimeSpan) {
+        this.callback = callback;
+        this.interval = interval;
+        this.lastRunTime = null;
+    }
+
+    /**
+     * Executes the callback when the configured interval has elapsed.
+     */
+    public async check(): Promise<Result<T>> {
+        const currentTime = performance.now();
+
+        if (this.lastRunTime === null
+            || currentTime - this.lastRunTime >= this.interval.milliseconds
+        ) {
+            return {success: true, output: await this.trigger()};
+        }
+
+        return {success: false};
+    }
+
+    /**
+     * Executes the callback regardless of the configured interval.
+     */
+    public async trigger(): Promise<T> {
+        this.lastRunTime = performance.now();
+        return this.callback();
+    }
+
+    /**
+     * Replaces the callback executed by this trigger.
+     */
+    public setCallback(callback: Supplier<T | Promise<T>>): void {
+        this.callback = callback;
+    }
+
+    /**
+     * Gets the configured time interval.
+     */
+    public getInterval(): TimeSpan {
+        return this.interval;
+    }
+
+    /**
+     * Replaces the configured time interval.
+     */
+    public setInterval(interval: TimeSpan): void {
+        this.interval = interval;
+    }
+
+
+}
+
+/**
+ * Runs a callback after a configured number of checks.
+ */
+export class CountTrigger<T> {
+    private callback: Supplier<T | Promise<T>>;
+    private interval: number = 1;
+    private checkCount: number = 0;
+
+    public constructor(callback: Supplier<T | Promise<T>>, interval: number) {
+        this.callback = callback;
+        this.setInterval(interval);
+    }
+
+    /**
+     * Executes the callback when the configured number of checks is reached.
+     */
+    public async check(): Promise<Result<T>> {
+        this.checkCount++;
+
+        if (this.checkCount >= this.interval) {
+            return {success: true, output: await this.trigger()};
+        }
+
+        return {success: false};
+    }
+
+    /**
+     * Executes the callback regardless of the configured check count.
+     */
+    public async trigger(): Promise<T> {
+        this.checkCount = 0;
+        return this.callback();
+    }
+
+    /**
+     * Replaces the callback executed by this trigger.
+     */
+    public setCallback(callback: Supplier<T | Promise<T>>): void {
+        this.callback = callback;
+    }
+
+    /**
+     * Gets the configured check interval.
+     */
+    public getInterval(): number {
+        return this.interval;
+    }
+
+    /**
+     * Replaces the configured check interval.
+     *
+     * @throws {RangeError} When the interval is less than one.
+     */
+    public setInterval(interval: number): void {
+        if (interval < 1) {
+            throw new RangeError('Interval must be greater than zero.');
+        }
+
+        this.interval = interval;
+    }
+}

package/src/utilities.ts

@@ -357,11 +357,37 @@ export function shallowEqual(a: any, b: any): boolean {
 /**
  * Pauses the execution of an asynchronous function for a specified duration.
  *
- * @param {number} ms - The delay duration in milliseconds.
- * @return {Promise<void>} A promise that resolves after the specified delay.
+ * When `signal` is provided, the returned promise rejects with `signal.reason`
+ * as soon as the signal is aborted (or immediately if it is already aborted),
+ * and the pending timer is cleared.
+ *
+ * @param ms - The delay duration in milliseconds.
+ * @param signal - Optional signal that cancels the wait.
+ * @return A promise that resolves after the specified delay.
  */
-export async function delay(ms: number): Promise<void> {
-    await new Promise(resolve => setTimeout(resolve, ms));
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        if (signal === undefined) {
+            setTimeout(resolve, ms);
+            return;
+        }
+
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+
+        const onAbort = (): void => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+
+        signal.addEventListener("abort", onAbort, {once: true});
+    });
 }
 
 /**

package/dist/cjs/package.json

@@ -1,3 +0,0 @@
-{
-  "type": "commonjs"
-}