@pawells/typescript-common 1.4.1 → 2.1.5

package/{build → dist}/enum/enum-values.js

@@ -22,4 +22,3 @@ export function EnumValues(enumObj) {
         .filter(key => Number.isNaN(Number(key))) // Filter out reverse mappings
         .map(key => enumObj[key]);
 }
-//# sourceMappingURL=enum-values.js.map

package/{build → dist}/enum/index.d.ts

@@ -1,4 +1,3 @@
-export * from './types.js';
 /**
  * Enum utility functions.
  *
@@ -8,6 +7,7 @@ export * from './types.js';
  *
  * @module enum
  */
+export * from './types.js';
 export * from './enum-keys.js';
 export * from './enum-values.js';
 export * from './enum-entries.js';

package/dist/enum/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/enum/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC"}

package/{build → dist}/enum/index.js

@@ -1,4 +1,3 @@
-export * from './types.js';
 /**
  * Enum utility functions.
  *
@@ -8,10 +7,10 @@ export * from './types.js';
  *
  * @module enum
  */
+export * from './types.js';
 export * from './enum-keys.js';
 export * from './enum-values.js';
 export * from './enum-entries.js';
 export * from './validate-enum-value.js';
 export * from './enum-key-by-value.js';
 export * from './enum-safe-value.js';
-//# sourceMappingURL=index.js.map

package/dist/enum/types.js

@@ -0,0 +1 @@
+export {};

package/{build → dist}/enum/validate-enum-value.d.ts

@@ -1,4 +1,4 @@
-import { TEnumType, TEnumValue } from './types.js';
+import type { TEnumType, TEnumValue } from './types.js';
 /**
  * Checks if a value is a valid member of the given enum.
  *

package/dist/enum/validate-enum-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-enum-value.d.ts","sourceRoot":"","sources":["../../src/enum/validate-enum-value.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAKnG"}

package/{build → dist}/enum/validate-enum-value.js

@@ -20,4 +20,3 @@ export function ValidateEnumValue(e, value) {
     const possibleValues = EnumValues(e);
     return possibleValues.includes(value);
 }
-//# sourceMappingURL=validate-enum-value.js.map

package/{build → dist}/function/compose.d.ts

@@ -1,9 +1,13 @@
+import type { TAnyFunction } from './types.js';
 /**
  * Composes functions **right-to-left** — the rightmost function is applied first.
  *
  * Overloads are provided for up to five functions with distinct types.
  * For same-type pipelines of any length, use the variadic form.
  *
+ * @param fns - One or more functions to compose
+ * @returns A function that applies the input through the composed pipeline
+ *
  * @example
  * ```typescript
  * const process = Compose(trim, toLowerCase, removeSpaces);
@@ -15,13 +19,16 @@ export declare function Compose<A, B, C>(f1: (b: B) => C, f2: (a: A) => B): (a:
 export declare function Compose<A, B, C, D>(f1: (c: C) => D, f2: (b: B) => C, f3: (a: A) => B): (a: A) => D;
 export declare function Compose<A, B, C, D, E>(f1: (d: D) => E, f2: (c: C) => D, f3: (b: B) => C, f4: (a: A) => B): (a: A) => E;
 export declare function Compose<A, B, C, D, E, F>(f1: (e: E) => F, f2: (d: D) => E, f3: (c: C) => D, f4: (b: B) => C, f5: (a: A) => B): (a: A) => F;
-export declare function Compose(...fns: Array<(arg: any) => any>): (arg: any) => any;
+export declare function Compose(...fns: TAnyFunction[]): TAnyFunction;
 /**
  * Pipes functions **left-to-right** — the leftmost function is applied first.
  *
  * Overloads are provided for up to five functions with distinct types.
  * For same-type pipelines of any length, use the variadic form.
  *
+ * @param fns - One or more functions to pipe
+ * @returns A function that applies the input through the piped pipeline
+ *
  * @example
  * ```typescript
  * const process = Pipe(trim, toLowerCase, removeSpaces);
@@ -33,5 +40,5 @@ export declare function Pipe<A, B, C>(f1: (a: A) => B, f2: (b: B) => C): (a: A)
 export declare function Pipe<A, B, C, D>(f1: (a: A) => B, f2: (b: B) => C, f3: (c: C) => D): (a: A) => D;
 export declare function Pipe<A, B, C, D, E>(f1: (a: A) => B, f2: (b: B) => C, f3: (c: C) => D, f4: (d: D) => E): (a: A) => E;
 export declare function Pipe<A, B, C, D, E, F>(f1: (a: A) => B, f2: (b: B) => C, f3: (c: C) => D, f4: (d: D) => E, f5: (e: E) => F): (a: A) => F;
-export declare function Pipe(...fns: Array<(arg: any) => any>): (arg: any) => any;
+export declare function Pipe(...fns: TAnyFunction[]): TAnyFunction;
 //# sourceMappingURL=compose.d.ts.map

package/dist/function/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/function/compose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AAC5D,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AAChF,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AACpG,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AACxH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AAC5I,wBAAgB,OAAO,CAAC,GAAG,GAAG,EAAE,YAAY,EAAE,GAAG,YAAY,CAAC;AAM9D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AACzD,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AAC7E,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AACjG,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AACrH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AACzI,wBAAgB,IAAI,CAAC,GAAG,GAAG,EAAE,YAAY,EAAE,GAAG,YAAY,CAAC"}

package/{build → dist}/function/compose.js

@@ -4,4 +4,3 @@ export function Compose(...fns) {
 export function Pipe(...fns) {
     return (arg) => fns.reduce((v, fn) => fn(v), arg);
 }
-//# sourceMappingURL=compose.js.map

package/{build → dist}/function/debounce.d.ts

@@ -1,3 +1,4 @@
+import type { TAnyFunction } from './types.js';
 /**
  * Creates a debounced version of `fn` that delays execution until after `ms`
  * milliseconds have elapsed since the last invocation.
@@ -5,6 +6,12 @@
  * The returned function also exposes a `.cancel()` method to discard any
  * pending invocation.
  *
+ * @remarks
+ * Debounce differs from throttle in that it **delays execution** until silence.
+ * Each call resets the timer; the function executes only after `ms` milliseconds
+ * of inactivity. Throttle, by contrast, limits calls to **at most once per `ms` milliseconds**
+ * regardless of how frequently calls are made.
+ *
  * @template T - The wrapped function type
  * @param fn - The function to debounce
  * @param ms - Delay in milliseconds
@@ -19,7 +26,7 @@
  * save.cancel();
  * ```
  */
-export declare function Debounce<T extends (...args: any[]) => any>(fn: T, ms: number): ((...args: Parameters<T>) => void) & {
+export declare function Debounce<T extends TAnyFunction>(fn: T, ms: number): ((...args: Parameters<T>) => void) & {
     cancel: () => void;
 };
 //# sourceMappingURL=debounce.d.ts.map

package/dist/function/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../src/function/debounce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,YAAY,EAC9C,EAAE,EAAE,CAAC,EACL,EAAE,EAAE,MAAM,GACR,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,CAiB7D"}

package/{build → dist}/function/debounce.js

@@ -5,6 +5,12 @@
  * The returned function also exposes a `.cancel()` method to discard any
  * pending invocation.
  *
+ * @remarks
+ * Debounce differs from throttle in that it **delays execution** until silence.
+ * Each call resets the timer; the function executes only after `ms` milliseconds
+ * of inactivity. Throttle, by contrast, limits calls to **at most once per `ms` milliseconds**
+ * regardless of how frequently calls are made.
+ *
  * @template T - The wrapped function type
  * @param fn - The function to debounce
  * @param ms - Delay in milliseconds
@@ -34,4 +40,3 @@ export function Debounce(fn, ms) {
     };
     return debounced;
 }
-//# sourceMappingURL=debounce.js.map

package/{build → dist}/function/index.js

@@ -13,4 +13,3 @@ export * from './memoize.js';
 export * from './once.js';
 export * from './compose.js';
 export * from './sleep.js';
-//# sourceMappingURL=index.js.map

package/dist/function/memoize.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Returns a memoized version of `fn` that caches results by serialising its
+ * arguments with `JSON.stringify` (or a custom `keyFn`).
+ *
+ * Only suitable for **pure functions** with serialisable arguments.
+ *
+ * Uses an LRU (Least Recently Used) eviction policy: when the cache reaches
+ * `maxCacheSize`, the entry that was accessed least recently is evicted.
+ *
+ * @template T - The function type to memoize
+ * @param fn - The function to memoize
+ * @param keyFn - Optional custom cache key function. If not provided, arguments are serialized with JSON.stringify
+ * @param maxCacheSize - Maximum number of cached results before LRU eviction (default: 1000)
+ * @returns A memoized function with the same signature as `fn`
+ *
+ * @warning Do not memoize functions with sensitive parameters (passwords, tokens, API keys).
+ * The cache stores return values keyed by serialized arguments, which could expose sensitive
+ * data if the cache is inspected or if the keyFn inadvertently includes sensitive data
+ * in the cache key. For functions handling sensitive data, consider:
+ * - Not memoizing at all
+ * - Using a custom keyFn that excludes sensitive parameters
+ * - Implementing manual cache invalidation after processing sensitive data
+ *
+ * @example
+ * ```typescript
+ * const expensiveCalc = Memoize((n: number) => n * n);
+ * expensiveCalc(4); // computed
+ * expensiveCalc(4); // cached → same value returned immediately
+ *
+ * // Custom key function:
+ * const getUser = Memoize(fetchUser, (id) => `user:${id}`);
+ *
+ * // With custom cache size:
+ * const cached = Memoize(fn, undefined, 500);
+ *
+ * const add = (a: number, b: number) => a + b;
+ * const cachedAdd = Memoize(add);
+ * console.log(cachedAdd(1, 2)); // Computes: 3
+ * console.log(cachedAdd(1, 2)); // Returns cached result: 3
+ * ```
+ */
+export declare function Memoize<T extends (...args: any[]) => any>(fn: T, keyFn?: (...args: Parameters<T>) => string, maxCacheSize?: number): T;
+//# sourceMappingURL=memoize.d.ts.map

package/dist/function/memoize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../src/function/memoize.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxD,EAAE,EAAE,CAAC,EACL,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,EAC1C,YAAY,SAAO,GACjB,CAAC,CAkBH"}

package/dist/function/memoize.js

@@ -0,0 +1,59 @@
+import { LRUCache } from '../lru-cache.js';
+/**
+ * Returns a memoized version of `fn` that caches results by serialising its
+ * arguments with `JSON.stringify` (or a custom `keyFn`).
+ *
+ * Only suitable for **pure functions** with serialisable arguments.
+ *
+ * Uses an LRU (Least Recently Used) eviction policy: when the cache reaches
+ * `maxCacheSize`, the entry that was accessed least recently is evicted.
+ *
+ * @template T - The function type to memoize
+ * @param fn - The function to memoize
+ * @param keyFn - Optional custom cache key function. If not provided, arguments are serialized with JSON.stringify
+ * @param maxCacheSize - Maximum number of cached results before LRU eviction (default: 1000)
+ * @returns A memoized function with the same signature as `fn`
+ *
+ * @warning Do not memoize functions with sensitive parameters (passwords, tokens, API keys).
+ * The cache stores return values keyed by serialized arguments, which could expose sensitive
+ * data if the cache is inspected or if the keyFn inadvertently includes sensitive data
+ * in the cache key. For functions handling sensitive data, consider:
+ * - Not memoizing at all
+ * - Using a custom keyFn that excludes sensitive parameters
+ * - Implementing manual cache invalidation after processing sensitive data
+ *
+ * @example
+ * ```typescript
+ * const expensiveCalc = Memoize((n: number) => n * n);
+ * expensiveCalc(4); // computed
+ * expensiveCalc(4); // cached → same value returned immediately
+ *
+ * // Custom key function:
+ * const getUser = Memoize(fetchUser, (id) => `user:${id}`);
+ *
+ * // With custom cache size:
+ * const cached = Memoize(fn, undefined, 500);
+ *
+ * const add = (a: number, b: number) => a + b;
+ * const cachedAdd = Memoize(add);
+ * console.log(cachedAdd(1, 2)); // Computes: 3
+ * console.log(cachedAdd(1, 2)); // Returns cached result: 3
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function Memoize(fn, keyFn, maxCacheSize = 1000) {
+    const cache = new LRUCache(maxCacheSize);
+    return function memoized(...args) {
+        const key = keyFn ? keyFn(...args) : JSON.stringify(args);
+        if (cache.has(key)) {
+            // PERFORMANCE NOTE: LRUCache.get() calls Map.delete() + Map.set() on every cache hit.
+            // For read-heavy workloads, tracking access timestamps would be faster than
+            // the delete/reinsert pattern. This is correct for LRU semantics but can be slow
+            // for hot cache entries accessed thousands of times per second.
+            return cache.get(key);
+        }
+        const result = fn(...args);
+        cache.set(key, result);
+        return result;
+    };
+}

package/{build → dist}/function/once.d.ts

@@ -5,6 +5,7 @@
  * @template T - The wrapped function type
  * @param fn - The function to restrict
  * @returns A wrapped function that executes `fn` at most once
+ * @throws When the wrapped function throws an error, the error is cached and re-thrown on all subsequent calls
  *
  * @example
  * ```typescript

package/{build → dist}/function/once.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../../src/function/once.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAsBhE"}
+{"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../../src/function/once.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAsBhE"}

package/{build → dist}/function/once.js

@@ -5,6 +5,7 @@
  * @template T - The wrapped function type
  * @param fn - The function to restrict
  * @returns A wrapped function that executes `fn` at most once
+ * @throws When the wrapped function throws an error, the error is cached and re-thrown on all subsequent calls
  *
  * @example
  * ```typescript
@@ -13,6 +14,7 @@
  * init(); // no-op — returns cached result
  * ```
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function Once(fn) {
     let called = false;
     let result;
@@ -36,4 +38,3 @@ export function Once(fn) {
         return result;
     };
 }
-//# sourceMappingURL=once.js.map

package/{build → dist}/function/sleep.js

@@ -19,4 +19,3 @@
 export async function Sleep(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
 }
-//# sourceMappingURL=sleep.js.map

package/dist/function/throttle.d.ts

@@ -0,0 +1,25 @@
+import type { TAnyFunction } from './types.js';
+/**
+ * Creates a throttled version of `fn` that invokes at most once per `ms`
+ * milliseconds, guaranteeing the final call in a burst is also executed.
+ *
+ * @remarks
+ * Throttle differs from debounce in that it **rate-limits execution** to at most
+ * once per `ms` milliseconds. The function executes immediately on the first call,
+ * and subsequent calls are batched; the final pending call always executes. Debounce,
+ * by contrast, **delays execution** until `ms` milliseconds of silence have elapsed
+ * and resets the timer on each call.
+ *
+ * @template T - The wrapped function type
+ * @param fn - The function to throttle
+ * @param ms - Minimum interval in milliseconds between invocations
+ * @returns A throttled function
+ *
+ * @example
+ * ```typescript
+ * const onScroll = Throttle(() => updatePosition(), 100);
+ * window.addEventListener('scroll', onScroll);
+ * ```
+ */
+export declare function Throttle<T extends TAnyFunction>(fn: T, ms: number): (...args: Parameters<T>) => void;
+//# sourceMappingURL=throttle.d.ts.map

package/dist/function/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../src/function/throttle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,YAAY,EAC9C,EAAE,EAAE,CAAC,EACL,EAAE,EAAE,MAAM,GACR,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAuBlC"}

package/{build → dist}/function/throttle.js

@@ -2,6 +2,13 @@
  * Creates a throttled version of `fn` that invokes at most once per `ms`
  * milliseconds, guaranteeing the final call in a burst is also executed.
  *
+ * @remarks
+ * Throttle differs from debounce in that it **rate-limits execution** to at most
+ * once per `ms` milliseconds. The function executes immediately on the first call,
+ * and subsequent calls are batched; the final pending call always executes. Debounce,
+ * by contrast, **delays execution** until `ms` milliseconds of silence have elapsed
+ * and resets the timer on each call.
+ *
  * @template T - The wrapped function type
  * @param fn - The function to throttle
  * @param ms - Minimum interval in milliseconds between invocations
@@ -36,4 +43,3 @@ export function Throttle(fn, ms) {
         }
     };
 }
-//# sourceMappingURL=throttle.js.map

package/dist/function/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Any function signature.
+ *
+ * A type alias for functions accepting any arguments and returning any type.
+ * Used throughout the function domain for function wrappers and utilities
+ * that operate on generic functions without type-specific constraints.
+ */
+export type TAnyFunction = (...args: any[]) => any;
+/**
+ * Any async function signature.
+ *
+ * A type alias for async functions accepting any arguments and returning
+ * a Promise of the specified generic type (default `void`).
+ *
+ * @template T - The resolved value type of the returned Promise (default `void`)
+ */
+export type TAsyncFunction<T = void> = (...args: any[]) => Promise<T>;
+//# sourceMappingURL=types.d.ts.map

package/dist/function/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/function/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;AAEnD;;;;;;;GAOG;AAEH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/function/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './lru-cache.js';
+export * from './array/index.js';
+export * from './asserts/index.js';
+export * from './boolean/index.js';
+export * from './enum/index.js';
+export * from './function/index.js';
+export * from './number/index.js';
+export * from './object/index.js';
+export * from './string/index.js';
+export * from './time/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from './lru-cache.js';
+export * from './array/index.js';
+export * from './asserts/index.js';
+export * from './boolean/index.js';
+export * from './enum/index.js';
+export * from './function/index.js';
+export * from './number/index.js';
+export * from './object/index.js';
+export * from './string/index.js';
+export * from './time/index.js';

package/{build → dist}/lru-cache.d.ts

@@ -8,6 +8,12 @@
  * @typeParam K - Key type
  * @typeParam V - Value type
  *
+ * @warning Do not cache sensitive objects (API keys, tokens, passwords, PII).
+ * Cache entries remain in memory until evicted or cleared. If cache is inspected
+ * (via debugger, memory dump, or compromised process), sensitive values will be exposed.
+ * For sensitive data, prefer ephemeral processing without caching, or implement
+ * automatic expiration and secure clearing (e.g., overwrite before eviction).
+ *
  * @example
  * ```typescript
  * const cache = new LRUCache<string, number>(2);
@@ -46,6 +52,12 @@ export declare class LRUCache<K, V> {
      * @param key - The key to look up
      * @returns The cached value, or `undefined` if not found
      *
+     * @remarks
+     * Each cache hit triggers an internal Map delete and re-insert operation to maintain
+     * LRU order. This is O(1) amortized, but introduces per-access overhead.
+     * For read-heavy workloads, consider a timestamp-based LRU approach to reduce
+     * per-access cost, though it adds space overhead for timestamp storage.
+     *
      * @example
      * ```typescript
      * const cache = new LRUCache<string, number>(2);
@@ -101,5 +113,12 @@ export declare class LRUCache<K, V> {
      * ```
      */
     clear(): void;
+    /**
+     * Removes a specific key from the cache.
+     *
+     * @param key - The key to delete
+     * @returns `true` if the key existed and was deleted, `false` otherwise
+     */
+    delete(key: K): boolean;
 }
 //# sourceMappingURL=lru-cache.d.ts.map

package/dist/lru-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-cache.d.ts","sourceRoot":"","sources":["../src/lru-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IAExC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC;;;;;;;;;;OAUG;gBACS,OAAO,EAAE,MAAM;IAO3B;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAajC;;;;;;;;;;;;;OAaG;IACI,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAI3B;;;;;;;;;;;;;;;;;OAiBG;IACI,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAgBlC;;;;;;;;;;OAUG;IACI,KAAK,IAAI,IAAI;IAIpB;;;;;OAKG;IACI,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;CAG9B"}

package/{build → dist}/lru-cache.js

@@ -8,6 +8,12 @@
  * @typeParam K - Key type
  * @typeParam V - Value type
  *
+ * @warning Do not cache sensitive objects (API keys, tokens, passwords, PII).
+ * Cache entries remain in memory until evicted or cleared. If cache is inspected
+ * (via debugger, memory dump, or compromised process), sensitive values will be exposed.
+ * For sensitive data, prefer ephemeral processing without caching, or implement
+ * automatic expiration and secure clearing (e.g., overwrite before eviction).
+ *
  * @example
  * ```typescript
  * const cache = new LRUCache<string, number>(2);
@@ -53,6 +59,12 @@ export class LRUCache {
      * @param key - The key to look up
      * @returns The cached value, or `undefined` if not found
      *
+     * @remarks
+     * Each cache hit triggers an internal Map delete and re-insert operation to maintain
+     * LRU order. This is O(1) amortized, but introduces per-access overhead.
+     * For read-heavy workloads, consider a timestamp-based LRU approach to reduce
+     * per-access cost, though it adds space overhead for timestamp storage.
+     *
      * @example
      * ```typescript
      * const cache = new LRUCache<string, number>(2);
@@ -66,7 +78,9 @@ export class LRUCache {
             return undefined;
         }
         const value = this._map.get(key);
-        // Move to end (mark as recently used)
+        // LRU maintenance: re-insert at map tail on every read hit.
+        // This is O(1) but involves Map.delete + Map.set per call.
+        // For read-heavy workloads, consider a timestamp-based LRU alternative.
         this._map.delete(key);
         this._map.set(key, value);
         return value;
@@ -135,5 +149,13 @@ export class LRUCache {
     clear() {
         this._map.clear();
     }
+    /**
+     * Removes a specific key from the cache.
+     *
+     * @param key - The key to delete
+     * @returns `true` if the key existed and was deleted, `false` otherwise
+     */
+    delete(key) {
+        return this._map.delete(key);
+    }
 }
-//# sourceMappingURL=lru-cache.js.map

package/{build → dist}/number/assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/number/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,SAAQ,WAAW;gBAC/B,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACpC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC;AAEnG;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,iBAAiB;IACjC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,iBAAsB,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAoDpI"}
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/number/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,SAAQ,WAAW;gBAC/B,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACpC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC;AAEnG;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,iBAAiB;IACjC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,iBAAsB,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAiDpI"}

package/{build → dist}/number/assert.js

@@ -1,4 +1,4 @@
-import { SetExceptionClass, SetExceptionMessage, ThrowException } from '../asserts/utils.js';
+import { SetExceptionClass, SetExceptionMessage, ThrowException, AssertValueType } from '../asserts/utils.js';
 import { SimpleError } from '../asserts/errors.js';
 /**
  * Error thrown when a value is not a valid number or fails basic numeric validation.
@@ -102,49 +102,44 @@ export class NumberRangeError extends NumberError {
  * ```
  */
 export function AssertNumber(value, args = {}, exception = {}) {
-    if (typeof value !== 'number' || Number.isNaN(value)) {
-        SetExceptionClass(exception, NumberError);
-        const actualType = Number.isNaN(value) ? 'NaN' : typeof value;
-        SetExceptionMessage(exception, `Expected number but received ${actualType}: ${JSON.stringify(value)}`);
+    SetExceptionClass(exception, NumberError);
+    AssertValueType(value, 'number', exception);
+    // Type is narrowed by AssertValueType; cast for TypeScript
+    const num = value;
+    SetExceptionClass(exception, NumberRangeError, true);
+    // Validate finite constraint (if specified, value must be finite)
+    if (args.finite === true && !Number.isFinite(num)) {
+        SetExceptionMessage(exception, `Expected finite number but received ${num}`);
         ThrowException(exception);
     }
-    else {
-        SetExceptionClass(exception, NumberRangeError);
-        // Validate finite constraint (if specified, value must be finite)
-        if (args.finite === true && !Number.isFinite(value)) {
-            SetExceptionMessage(exception, `Expected finite number but received ${value}`);
-            ThrowException(exception);
-        }
-        // Validate integer constraint (if specified, value must be an integer)
-        if (args.integer === true && !Number.isInteger(value)) {
-            SetExceptionMessage(exception, `Expected integer but received ${value}`);
-            ThrowException(exception);
-        }
-        // Validate equality constraint (if specified, value must exactly match)
-        if (args.eq !== undefined && value !== args.eq) {
-            SetExceptionMessage(exception, `Expected value to equal ${args.eq} but received ${value}`);
-            ThrowException(exception);
-        }
-        // Validate greater than constraint (exclusive - value must be strictly greater)
-        if (args.gt !== undefined && value <= args.gt) {
-            SetExceptionMessage(exception, `Expected value > ${args.gt} but received ${value}`);
-            ThrowException(exception);
-        }
-        // Validate greater than or equal constraint (inclusive - value can equal the bound)
-        if (args.gte !== undefined && value < args.gte) {
-            SetExceptionMessage(exception, `Expected value >= ${args.gte} but received ${value}`);
-            ThrowException(exception);
-        }
-        // Validate less than constraint (exclusive - value must be strictly less)
-        if (args.lt !== undefined && value >= args.lt) {
-            SetExceptionMessage(exception, `Expected value < ${args.lt} but received ${value}`);
-            ThrowException(exception);
-        }
-        // Validate less than or equal constraint (inclusive - value can equal the bound)
-        if (args.lte !== undefined && value > args.lte) {
-            SetExceptionMessage(exception, `Expected value <= ${args.lte} but received ${value}`);
-            ThrowException(exception);
-        }
+    // Validate integer constraint (if specified, value must be an integer)
+    if (args.integer === true && !Number.isInteger(num)) {
+        SetExceptionMessage(exception, `Expected integer but received ${num}`);
+        ThrowException(exception);
+    }
+    // Validate equality constraint (if specified, value must exactly match)
+    if (args.eq !== undefined && num !== args.eq) {
+        SetExceptionMessage(exception, `Expected value to equal ${args.eq} but received ${num}`);
+        ThrowException(exception);
+    }
+    // Validate greater than constraint (exclusive - value must be strictly greater)
+    if (args.gt !== undefined && num <= args.gt) {
+        SetExceptionMessage(exception, `Expected value > ${args.gt} but received ${num}`);
+        ThrowException(exception);
+    }
+    // Validate greater than or equal constraint (inclusive - value can equal the bound)
+    if (args.gte !== undefined && num < args.gte) {
+        SetExceptionMessage(exception, `Expected value >= ${args.gte} but received ${num}`);
+        ThrowException(exception);
+    }
+    // Validate less than constraint (exclusive - value must be strictly less)
+    if (args.lt !== undefined && num >= args.lt) {
+        SetExceptionMessage(exception, `Expected value < ${args.lt} but received ${num}`);
+        ThrowException(exception);
+    }
+    // Validate less than or equal constraint (inclusive - value can equal the bound)
+    if (args.lte !== undefined && num > args.lte) {
+        SetExceptionMessage(exception, `Expected value <= ${args.lte} but received ${num}`);
+        ThrowException(exception);
     }
 }
-//# sourceMappingURL=assert.js.map