@pawells/typescript-common 2.0.0 → 2.1.5

package/{build → dist}/asserts/utils.js

@@ -1,30 +1,4 @@
-/**
- * Gets the actual type of a value for error messages.
- * Handles primitives, objects, arrays, null, and undefined.
- *
- * @param value - The value to get the type of
- * @returns A string representation suitable for error messages
- * @internal Used by assertion functions for consistent type naming
- *
- * @example
- * ```typescript
- * GetActualType(null);         // "null"
- * GetActualType(undefined);    // "undefined"
- * GetActualType([1, 2, 3]);    // "array"
- * GetActualType({a: 1});       // "object"
- * GetActualType("hello");      // "string"
- * GetActualType(42);           // "number"
- * ```
- */
-export function GetActualType(value) {
-    if (value === null)
-        return 'null';
-    if (value === undefined)
-        return 'undefined';
-    if (Array.isArray(value))
-        return 'array';
-    return typeof value;
-}
+import { safeDisplay, GetValueType } from './generic.js';
 /**
  * Throws an exception using the configured error class and message.
  *
@@ -35,6 +9,7 @@ export function GetActualType(value) {
  *
  * @param exception - Exception configuration containing error class and/or message
  * @throws {Error} The configured error class with the specified message, or generic Error if no class specified
+ * @internal
  *
  * @example
  * ```typescript
@@ -70,6 +45,7 @@ export function ThrowException(exception) {
  * @param exception - Exception configuration object to modify
  * @param errorClass - The error class constructor to set as default
  * @param force - Whether to override existing error class configuration (default: false)
+ * @internal
  *
  * @example
  * ```typescript
@@ -104,6 +80,7 @@ export function SetExceptionClass(exception, errorClass, force = false) {
  * @param exception - Exception configuration object to modify
  * @param message - The error message to set as default
  * @param force - Whether to override existing error message configuration (default: false)
+ * @internal
  *
  * @example
  * ```typescript
@@ -150,33 +127,32 @@ export function AssertValueType(value, expectedType, exception) {
     }
     if (expectedType === 'array') {
         if (!Array.isArray(value)) {
-            const actualType = GetActualType(value);
-            SetExceptionMessage(exception, `Expected array but received ${actualType}: ${String(value)}`);
+            const actualType = GetValueType(value);
+            SetExceptionMessage(exception, `Expected array but received ${actualType}: ${safeDisplay(value)}`);
             ThrowException(exception);
         }
         return;
     }
     if (expectedType === 'object') {
         if (typeof value !== 'object') {
-            const actualType = GetActualType(value);
-            SetExceptionMessage(exception, `Expected object but received ${actualType}: ${String(value)}`);
+            const actualType = GetValueType(value);
+            SetExceptionMessage(exception, `Expected object but received ${actualType}: ${safeDisplay(value)}`);
             ThrowException(exception);
         }
         return;
     }
     if (expectedType === 'number') {
         if (typeof value !== 'number' || Number.isNaN(value)) {
-            const actualType = typeof value === 'number' ? 'NaN' : GetActualType(value);
-            SetExceptionMessage(exception, `Expected number but received ${actualType}: ${JSON.stringify(value)}`);
+            const actualType = typeof value === 'number' ? 'NaN' : GetValueType(value);
+            SetExceptionMessage(exception, `Expected number but received ${actualType}: ${safeDisplay(value)}`);
             ThrowException(exception);
         }
         return;
     }
     // For string and boolean
-    const actualType = GetActualType(value);
+    const actualType = GetValueType(value);
     if (actualType !== expectedType) {
-        SetExceptionMessage(exception, `Expected ${expectedType} but received ${actualType}: ${String(value)}`);
+        SetExceptionMessage(exception, `Expected ${expectedType} but received ${actualType}: ${safeDisplay(value)}`);
         ThrowException(exception);
     }
 }
-//# sourceMappingURL=utils.js.map

package/{build → dist}/boolean/assert.d.ts

@@ -24,8 +24,7 @@ export declare class BooleanError extends SimpleError {
  * @param value - The value to validate and assert as a boolean primitive
  * @param exception - Optional exception configuration for custom error handling.
  *                   Can include custom error message, error type, or other metadata.
- * @throws {Error} When value is not a boolean primitive. The specific error type
- *                 depends on the exception configuration provided.
+ * @throws {BooleanError} When value is not a boolean primitive
  *
  * @example
  * Basic usage with valid boolean values:

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

@@ -1 +1 @@
-{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/boolean/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAChC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAGxG"}
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/boolean/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAChC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAGxG"}

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

@@ -26,8 +26,7 @@ export class BooleanError extends SimpleError {
  * @param value - The value to validate and assert as a boolean primitive
  * @param exception - Optional exception configuration for custom error handling.
  *                   Can include custom error message, error type, or other metadata.
- * @throws {Error} When value is not a boolean primitive. The specific error type
- *                 depends on the exception configuration provided.
+ * @throws {BooleanError} When value is not a boolean primitive
  *
  * @example
  * Basic usage with valid boolean values:
@@ -69,4 +68,3 @@ export function AssertBoolean(value, exception = {}) {
     SetExceptionClass(exception, BooleanError);
     AssertValueType(value, 'boolean', exception);
 }
-//# sourceMappingURL=assert.js.map

package/dist/boolean/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Boolean assertion functions and types.
+ *
+ * Provides assertion helpers for validating boolean values at runtime.
+ *
+ * Currently contains only assertion utilities. This module structure is designed
+ * to accommodate additional boolean utilities in the future (e.g., conversion,
+ * parsing functions).
+ *
+ * @module boolean
+ */
+export * from './assert.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/boolean/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,aAAa,CAAC"}

package/dist/boolean/index.js

@@ -0,0 +1,12 @@
+/**
+ * Boolean assertion functions and types.
+ *
+ * Provides assertion helpers for validating boolean values at runtime.
+ *
+ * Currently contains only assertion utilities. This module structure is designed
+ * to accommodate additional boolean utilities in the future (e.g., conversion,
+ * parsing functions).
+ *
+ * @module boolean
+ */
+export * from './assert.js';

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

@@ -1,4 +1,4 @@
-import { TEnumType, TEnumValue } from './types.js';
+import type { TEnumType, TEnumValue } from './types.js';
 /**
  * Returns non-numeric key-value pairs from an enum.
  *

package/dist/enum/enum-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-entries.d.ts","sourceRoot":"","sources":["../../src/enum/enum-entries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAIzF"}

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

@@ -16,4 +16,3 @@ export function EnumEntries(e) {
         return [];
     return Object.entries(e).filter(([key]) => Number.isNaN(Number(key)));
 }
-//# sourceMappingURL=enum-entries.js.map

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

@@ -1,4 +1,4 @@
-import { TEnumType, TEnumValue } from './types.js';
+import type { TEnumType, TEnumValue } from './types.js';
 /**
  * Gets the enum key for a given value.
  *

package/dist/enum/enum-key-by-value.d.ts.map

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

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

@@ -23,4 +23,3 @@ export function EnumKeyByValue(e, value) {
         return found[0];
     return undefined;
 }
-//# sourceMappingURL=enum-key-by-value.js.map

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

@@ -20,4 +20,3 @@ export function EnumKeys(obj) {
         return [];
     return Object.keys(obj).filter((k) => Number.isNaN(Number(k)));
 }
-//# sourceMappingURL=enum-keys.js.map

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

@@ -1,4 +1,4 @@
-import { TEnumType, TEnumValue } from './types.js';
+import type { TEnumType, TEnumValue } from './types.js';
 /**
  * Gets an enum value safely, returning a fallback if the value is not a valid enum member.
  *

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

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

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

@@ -18,4 +18,3 @@ import { ValidateEnumValue } from './validate-enum-value.js';
 export function EnumSafeValue(e, value, fallback) {
     return ValidateEnumValue(e, value) ? value : fallback;
 }
-//# sourceMappingURL=enum-safe-value.js.map

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

@@ -5,6 +5,9 @@ import type { TAnyFunction } from './types.js';
  * 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);
@@ -23,6 +26,9 @@ export declare function Compose(...fns: TAnyFunction[]): TAnyFunction;
  * 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);

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/function/compose.ts"],"names":[],"mappings":"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"}

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

@@ -6,6 +6,12 @@ import type { TAnyFunction } from './types.js';
  * 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

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.map

@@ -1 +1 @@
-{"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../../src/function/once.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;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

@@ -14,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;
@@ -37,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/{build → dist}/function/throttle.d.ts

@@ -3,6 +3,13 @@ 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

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"}