@develia/commons 0.4.16 → 0.4.18

package/src/functions.ts

@@ -0,0 +1,496 @@
+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. */
+    leading?: boolean;
+    /** Execute once more at the end of the throttle window using the latest arguments. Defaults to true. */
+    trailing?: boolean;
+}
+
+/**
+ * A delayed function returned by {@link debounce} or {@link throttle}.
+ *
+ * @example
+ * ```ts
+ * const saveLater = debounce(save, 250);
+ * saveLater();
+ *
+ * if (saveLater.pending()) {
+ *     saveLater.flush();
+ * }
+ * ```
+ */
+export type DeferredFunction<F extends AnyFunction> = ((
+    this: ThisParameterType<F>,
+    ...args: Parameters<F>
+) => ReturnType<F> | undefined) & {
+    /** Cancel the scheduled call and forget the latest arguments. */
+    cancel(): void;
+    /** Execute the scheduled trailing call immediately, when one exists. */
+    flush(): ReturnType<F> | undefined;
+    /** Return true while a trailing call is scheduled. */
+    pending(): boolean;
+};
+
+/**
+ * A memoized function with helpers for inspecting and invalidating its cache.
+ *
+ * @example
+ * ```ts
+ * const getUser = memoize((id: string) => fetchUser(id));
+ *
+ * getUser("42");
+ * getUser.has("42"); // true
+ * getUser.delete("42");
+ * ```
+ */
+export type MemoizedFunction<F extends AnyFunction, K> = ((
+    this: ThisParameterType<F>,
+    ...args: Parameters<F>
+) => ReturnType<F>) & {
+    /** The backing cache used by the memoized function. */
+    readonly cache: Map<K, ReturnType<F>>;
+    /** Remove every cached value. */
+    clear(): void;
+    /** Remove the cached value for the key resolved from the provided arguments. */
+    delete(...args: Parameters<F>): boolean;
+    /** Return true when a cached value exists for the key resolved from the provided arguments. */
+    has(...args: Parameters<F>): boolean;
+};
+
+type Unary<T, R> = (arg: T) => R;
+
+/**
+ * Return the received value unchanged.
+ * Useful as a default mapper, placeholder callback, or neutral transform in a pipeline.
+ *
+ * @example
+ * ```ts
+ * identity(5); // 5
+ *
+ * const value = {name: "commons"};
+ * identity(value) === value; // true
+ * ```
+ */
+export function identity<T>(value: T): T {
+    return value;
+}
+
+/**
+ * Create a function that always returns the same value.
+ *
+ * @example
+ * ```ts
+ * const getAnswer = constant(42);
+ *
+ * getAnswer(); // 42
+ * getAnswer(); // 42
+ * ```
+ */
+export function constant<T>(value: T): () => T {
+    return () => value;
+}
+
+/**
+ * Do nothing and return undefined.
+ * Useful as a safe default callback.
+ *
+ * @example
+ * ```ts
+ * const onComplete = options.onComplete ?? noop;
+ * onComplete();
+ * ```
+ */
+export function noop(): void {
+    // Intentionally empty.
+}
+
+/**
+ * Create a function that can be executed only once.
+ * Later calls return the result from the first execution without calling the original function again.
+ *
+ * @example
+ * ```ts
+ * const initialize = once(() => ({connected: true}));
+ *
+ * const first = initialize();
+ * const second = initialize();
+ * first === second; // true
+ * ```
+ */
+export function once<F extends AnyFunction>(fn: F): F {
+    let called = false;
+    let result: ReturnType<F>;
+
+    return function (this: ThisParameterType<F>, ...args: Parameters<F>): ReturnType<F> {
+        if (!called) {
+            called = true;
+            result = fn.apply(this, args);
+        }
+        return result;
+    } as F;
+}
+
+/**
+ * Cache the result of a function and reuse it for calls with the same resolved key.
+ * By default, the first argument is used as the cache key.
+ *
+ * @example
+ * ```ts
+ * const double = memoize((value: number) => value * 2);
+ *
+ * double(4); // 8, computed
+ * double(4); // 8, read from cache
+ * double.has(4); // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * const sum = memoize(
+ *     (left: number, right: number) => left + right,
+ *     (left, right) => `${left}:${right}`,
+ * );
+ *
+ * sum(2, 3); // 5
+ * sum.delete(2, 3); // true
+ * sum.clear();
+ * ```
+ */
+export function memoize<F extends AnyFunction, K = Parameters<F>[0]>(
+    fn: F,
+    resolver?: (...args: Parameters<F>) => K,
+    cache: Map<K, ReturnType<F>> = new Map<K, ReturnType<F>>()
+): MemoizedFunction<F, K> {
+    const resolveKey = (...args: Parameters<F>): K => {
+        if (resolver) return resolver(...args);
+        return args[0] as K;
+    };
+
+    const memoized = function (this: ThisParameterType<F>, ...args: Parameters<F>): ReturnType<F> {
+        const key = resolveKey(...args);
+        if (cache.has(key)) {
+            return cache.get(key)!;
+        }
+
+        const value = fn.apply(this, args);
+        cache.set(key, value);
+        return value;
+    } as MemoizedFunction<F, K>;
+
+    Object.defineProperty(memoized, "cache", {
+        value: cache,
+        enumerable: false,
+    });
+
+    memoized.clear = () => cache.clear();
+    memoized.delete = (...args: Parameters<F>) => cache.delete(resolveKey(...args));
+    memoized.has = (...args: Parameters<F>) => cache.has(resolveKey(...args));
+
+    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.
+ *
+ * @example
+ * ```ts
+ * const onScroll = throttle(() => {
+ *     console.log(window.scrollY);
+ * }, 100);
+ *
+ * window.addEventListener("scroll", onScroll);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const refresh = throttle(loadData, 500, {leading: false});
+ *
+ * refresh(); // scheduled instead of executed immediately
+ * refresh.flush(); // execute the scheduled call now
+ * ```
+ */
+export function throttle<F extends AnyFunction>(
+    fn: F,
+    wait: number,
+    options: ThrottleOptions = {}
+): DeferredFunction<F> {
+    const delay = normalizeDelay(wait);
+    const leading = options.leading ?? true;
+    const trailing = options.trailing ?? true;
+
+    let timer: TimerHandle | undefined;
+    let lastArgs: Parameters<F> | undefined;
+    let lastThis: ThisParameterType<F> | undefined;
+    let lastInvokeTime = 0;
+    let hasInvoked = false;
+    let result: ReturnType<F> | undefined;
+
+    const invoke = (time: number): ReturnType<F> => {
+        const args = lastArgs!;
+        const context = lastThis!;
+        lastArgs = undefined;
+        lastThis = undefined;
+        hasInvoked = true;
+        lastInvokeTime = time;
+        result = fn.apply(context, args);
+        return result as ReturnType<F>;
+    };
+
+    const expire = (): void => {
+        timer = undefined;
+        if (trailing && lastArgs) {
+            invoke(Date.now());
+        } else {
+            lastArgs = undefined;
+            lastThis = undefined;
+        }
+    };
+
+    const throttled = function (this: ThisParameterType<F>, ...args: Parameters<F>): ReturnType<F> | undefined {
+        const now = Date.now();
+        lastArgs = args;
+        lastThis = this;
+
+        if (!hasInvoked) {
+            if (leading) {
+                return invoke(now);
+            }
+            hasInvoked = true;
+            lastInvokeTime = now;
+        }
+
+        const remaining = delay - (now - lastInvokeTime);
+        if (remaining <= 0 || remaining > delay) {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            return invoke(now);
+        }
+
+        if (timer === undefined && trailing) {
+            timer = setTimeout(expire, remaining);
+        }
+
+        return result;
+    } as DeferredFunction<F>;
+
+    throttled.cancel = (): void => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        timer = undefined;
+        lastArgs = undefined;
+        lastThis = undefined;
+        lastInvokeTime = 0;
+        hasInvoked = false;
+    };
+
+    throttled.flush = (): ReturnType<F> | undefined => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+            if (lastArgs && trailing) {
+                return invoke(Date.now());
+            }
+        }
+        return result;
+    };
+
+    throttled.pending = (): boolean => timer !== undefined;
+
+    return throttled;
+}
+
+/**
+ * Create a function with one or more arguments already provided.
+ * Later arguments are appended after the preset arguments.
+ *
+ * @example
+ * ```ts
+ * const sum = (a: number, b: number, c: number) => a + b + c;
+ * const addFive = partial(sum, 2, 3);
+ *
+ * addFive(4); // 9
+ * ```
+ */
+export function partial<F extends AnyFunction>(
+    fn: F,
+    ...presetArgs: unknown[]
+): (...laterArgs: unknown[]) => ReturnType<F> {
+    return function (this: ThisParameterType<F>, ...laterArgs: unknown[]): ReturnType<F> {
+        return fn.apply(this, [...presetArgs, ...laterArgs] as Parameters<F>);
+    };
+}
+
+/**
+ * Compose unary functions from left to right.
+ * The first function receives the original arguments, and each next function receives the previous result.
+ *
+ * @example
+ * ```ts
+ * const transform = pipe(
+ *     (value: number) => value + 1,
+ *     (value: number) => value * 2,
+ * );
+ *
+ * transform(2); // 6
+ * ```
+ */
+export function pipe<A, B>(ab: Unary<A, B>): Unary<A, B>;
+export function pipe<A, B, C>(ab: Unary<A, B>, bc: Unary<B, C>): Unary<A, C>;
+export function pipe<A, B, C, D>(ab: Unary<A, B>, bc: Unary<B, C>, cd: Unary<C, D>): Unary<A, D>;
+export function pipe<A, B, C, D, E>(ab: Unary<A, B>, bc: Unary<B, C>, cd: Unary<C, D>, de: Unary<D, E>): Unary<A, E>;
+export function pipe(...fns: AnyFunction[]): AnyFunction {
+    return createFlow(fns);
+}
+
+/**
+ * Compose unary functions from right to left.
+ * The rightmost function receives the original arguments, and each function to its left receives the previous result.
+ *
+ * @example
+ * ```ts
+ * const transform = compose(
+ *     (value: number) => value + 1,
+ *     (value: number) => value * 2,
+ * );
+ *
+ * transform(2); // 5
+ * ```
+ */
+export function compose<A, B>(ab: Unary<A, B>): Unary<A, B>;
+export function compose<A, B, C>(bc: Unary<B, C>, ab: Unary<A, B>): Unary<A, C>;
+export function compose<A, B, C, D>(cd: Unary<C, D>, bc: Unary<B, C>, ab: Unary<A, B>): Unary<A, D>;
+export function compose<A, B, C, D, E>(de: Unary<D, E>, cd: Unary<C, D>, bc: Unary<B, C>, ab: Unary<A, B>): Unary<A, E>;
+export function compose(...fns: AnyFunction[]): AnyFunction {
+    return createFlow(fns.slice().reverse());
+}
+
+function createFlow(fns: AnyFunction[]): AnyFunction {
+    if (fns.length === 0) return identity;
+
+    return function (this: any, ...args: any[]): unknown {
+        let result = fns[0].apply(this, args);
+        for (let i = 1; i < fns.length; i++) {
+            result = fns[i].call(this, result);
+        }
+        return result;
+    };
+}
+
+function normalizeDelay(wait: number): number {
+    return Number.isFinite(wait) ? Math.max(0, wait) : 0;
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export {default as TypeCode} from './type-code.js';
 
 // ─── Utilities ───────────────────────────────────────
 export * from './utilities.js';
+export * from './functions.js';
 export * from './string.js';
 export * from './math.js';
 export {default as CancellablePromise} from "./cancellable-promise.js";

package/src/key-value-pair.ts

@@ -1,25 +1,25 @@
-/**
- * Represents a pair of key and value.
- *
- * @template TKey The type of the key.
- * @template TValue The type of the value.
- */
-export default class KeyValuePair<TKey, TValue> {
-    get value(): TValue {
-        return this._value;
-    }
-
-    get key(): TKey {
-        return this._key;
-    }
-
-    private readonly _key: TKey;
-    private readonly _value: TValue;
-
-    constructor(key: TKey, value: TValue) {
-        this._key = key;
-        this._value = value;
-    }
-
-
+/**
+ * Represents a pair of key and value.
+ *
+ * @template TKey The type of the key.
+ * @template TValue The type of the value.
+ */
+export default class KeyValuePair<TKey, TValue> {
+    get value(): TValue {
+        return this._value;
+    }
+
+    get key(): TKey {
+        return this._key;
+    }
+
+    private readonly _key: TKey;
+    private readonly _value: TValue;
+
+    constructor(key: TKey, value: TValue) {
+        this._key = key;
+        this._value = value;
+    }
+
+
 }

package/src/lazy.ts

@@ -1,33 +1,33 @@
-import type {Nullable, Supplier} from "./types.js";
-
-
-/**
- * Represents a lazy value that is created only when it is accessed for the first time.
- * @template T The type of the lazy value.
- */
-export default class Lazy<T> {
-    private _valueCreated = false;
-    private _value: Nullable<T> = null;
-    private readonly _factoryMethod: Supplier<T>;
-
-    constructor(getter: Supplier<T>) {
-        this._factoryMethod = getter;
-    }
-
-    get valueCreated(): boolean {
-        return this._valueCreated;
-    }
-
-    public get value(): T {
-        if (!this._valueCreated) {
-            this._value = this._factoryMethod();
-            this._valueCreated = true;
-        }
-        return this._value as T;
-    }
-
-    reset(): void {
-        this._valueCreated = false;
-        this._value = null;
-    }
+import type {Nullable, Supplier} from "./types.js";
+
+
+/**
+ * Represents a lazy value that is created only when it is accessed for the first time.
+ * @template T The type of the lazy value.
+ */
+export default class Lazy<T> {
+    private _valueCreated = false;
+    private _value: Nullable<T> = null;
+    private readonly _factoryMethod: Supplier<T>;
+
+    constructor(getter: Supplier<T>) {
+        this._factoryMethod = getter;
+    }
+
+    get valueCreated(): boolean {
+        return this._valueCreated;
+    }
+
+    public get value(): T {
+        if (!this._valueCreated) {
+            this._value = this._factoryMethod();
+            this._valueCreated = true;
+        }
+        return this._value as T;
+    }
+
+    reset(): void {
+        this._valueCreated = false;
+        this._value = null;
+    }
 }

package/src/math.ts

@@ -1,30 +1,33 @@
-/**
- * Linearly interpolates a number between two ranges.
- *
- * @param {number} n - The number to interpolate.
- * @param {number} inMin - The minimum value of the input range.
- * @param {number} inMax - The maximum value of the input range.
- * @param {number} outMin - The minimum value of the output range.
- * @param {number} outMax - The maximum value of the output range.
- *
- * @return {number} - The interpolated value.
- */
-export function lerp(n: number, inMin: number, inMax: number, outMin: number, outMax: number): number {
-    return outMin + (outMax - outMin) * ((n - inMin) / (inMax - inMin))
-}
-
-/**
- * Clamps a number between a minimum and maximum value.
- *
- * @param {number} n - The value to be clamped.
- * @param {number} min - The minimum value.
- * @param {number} max - The maximum value.
- * @return {number} The clamped value.
- */
-export function clamp(n: number, min: number, max: number): number {
-    if (n <= min)
-        return min;
-    if (n >= max)
-        return max;
-    return n
-}
+/**
+ * Linearly interpolates a number between two ranges.
+ *
+ * @param {number} n - The number to interpolate.
+ * @param {number} inMin - The minimum value of the input range.
+ * @param {number} inMax - The maximum value of the input range.
+ * @param {number} outMin - The minimum value of the output range.
+ * @param {number} outMax - The maximum value of the output range.
+ *
+ * @return {number} - The interpolated value.
+ */
+export function lerp(n: number, inMin: number, inMax: number, outMin: number, outMax: number): number {
+    if (inMax === inMin) {
+        throw new Error("Input range cannot be zero");
+    }
+    return outMin + (outMax - outMin) * ((n - inMin) / (inMax - inMin))
+}
+
+/**
+ * Clamps a number between a minimum and maximum value.
+ *
+ * @param {number} n - The value to be clamped.
+ * @param {number} min - The minimum value.
+ * @param {number} max - The maximum value.
+ * @return {number} The clamped value.
+ */
+export function clamp(n: number, min: number, max: number): number {
+    if (n <= min)
+        return min;
+    if (n >= max)
+        return max;
+    return n
+}

package/src/order.ts

@@ -1,6 +1,6 @@
-enum Order {
-    Ascending = "asc",
-    Descending = "desc"
-}
-
+enum Order {
+    Ascending = "asc",
+    Descending = "desc"
+}
+
 export default Order;