@pawells/typescript-common 2.0.0 → 2.1.6

package/dist/function/memoize.js

@@ -0,0 +1,72 @@
+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
+ * ```
+ */
+/**
+ * Memoizes a function using an LRU cache.
+ *
+ * @remarks
+ * - Default key function uses JSON.stringify(args)
+ * - Non-serializable arguments (functions, symbols, circular refs) will produce incorrect cache behavior
+ * - Supply a custom `keyFn` for non-serializable arguments or for content-addressed keys
+ *
+ * @param fn - The function to memoize
+ * @param keyFn - Optional custom cache key function; defaults to JSON.stringify(args)
+ * @param maxCacheSize - Maximum number of entries in the cache; defaults to 1000
+ * @returns Memoized version of the function
+ */
+// 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,14 @@
+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';
+export * from './array/iterators.js';
+export * from './json.sanitization.js';
+export * from './zod-util.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;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+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';
+export * from './array/iterators.js';
+export * from './json.sanitization.js';
+export * from './zod-util.js';

package/dist/json.sanitization.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Sanitizes a JSON Schema object by recursively removing all keys that start with "$".
+ * This prevents Mongoose Map field errors when storing JSON Schema definitions with
+ * metadata properties like $schema, $id, $defs, etc.
+ *
+ * @param schema - The JSON Schema object to sanitize
+ * @returns The sanitized schema object with all "$"-prefixed keys removed
+ * @example
+ * const schema = { type: 'object', $schema: 'http://...', properties: { ... } };
+ * const clean = SanitizeJsonSchema(schema);
+ * // Result: { type: 'object', properties: { ... } }
+ */
+export declare function SanitizeJsonSchema(schema: unknown): Record<string, unknown>;
+//# sourceMappingURL=json.sanitization.d.ts.map

package/dist/json.sanitization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.sanitization.d.ts","sourceRoot":"","sources":["../src/json.sanitization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM3E"}

package/dist/json.sanitization.js

@@ -0,0 +1,37 @@
+/**
+ * Sanitizes a JSON Schema object by recursively removing all keys that start with "$".
+ * This prevents Mongoose Map field errors when storing JSON Schema definitions with
+ * metadata properties like $schema, $id, $defs, etc.
+ *
+ * @param schema - The JSON Schema object to sanitize
+ * @returns The sanitized schema object with all "$"-prefixed keys removed
+ * @example
+ * const schema = { type: 'object', $schema: 'http://...', properties: { ... } };
+ * const clean = SanitizeJsonSchema(schema);
+ * // Result: { type: 'object', properties: { ... } }
+ */
+export function SanitizeJsonSchema(schema) {
+    const result = sanitizeJsonSchemaInternal(schema);
+    if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
+        return result;
+    }
+    return {};
+}
+function sanitizeJsonSchemaInternal(schema) {
+    if (schema === null || schema === undefined) {
+        return schema;
+    }
+    if (Array.isArray(schema)) {
+        return schema.map((item) => sanitizeJsonSchemaInternal(item));
+    }
+    if (typeof schema !== 'object') {
+        return schema;
+    }
+    const cleanSchema = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (!key.startsWith('$')) {
+            cleanSchema[key] = sanitizeJsonSchemaInternal(value);
+        }
+    }
+    return cleanSchema;
+}

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

@@ -143,4 +143,3 @@ export function AssertNumber(value, args = {}, exception = {}) {
         ThrowException(exception);
     }
 }
-//# sourceMappingURL=assert.js.map

package/dist/number/index.d.ts

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

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

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

package/dist/number/index.js

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

package/{build → dist}/object/assert-object.d.ts

@@ -1,6 +1,10 @@
 /**
  * Type guard that checks if the provided value is a non-null, non-array object.
  *
+ * NOTE: Despite the `assert-` prefix, this file exports a type guard predicate (`IsObject`),
+ * not an assertion function that throws. Type narrowing predicates are grouped here by
+ * convention alongside related assertion functions (see `AssertObject` in the asserts module).
+ *
  * Use this for type narrowing in conditionals. For runtime assertions that
  * throw on failure, use {@link AssertObject} from the asserts module.
  *
@@ -15,5 +19,5 @@
  * }
  * ```
  */
-export declare function IsObject(item: unknown): item is Record<string, any>;
+export declare function IsObject(item: unknown): item is Record<string, unknown>;
 //# sourceMappingURL=assert-object.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"assert-object.d.ts","sourceRoot":"","sources":["../../src/object/assert-object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAEnE"}
+{"version":3,"file":"assert-object.d.ts","sourceRoot":"","sources":["../../src/object/assert-object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEvE"}

package/{build → dist}/object/assert-object.js

@@ -1,6 +1,10 @@
 /**
  * Type guard that checks if the provided value is a non-null, non-array object.
  *
+ * NOTE: Despite the `assert-` prefix, this file exports a type guard predicate (`IsObject`),
+ * not an assertion function that throws. Type narrowing predicates are grouped here by
+ * convention alongside related assertion functions (see `AssertObject` in the asserts module).
+ *
  * Use this for type narrowing in conditionals. For runtime assertions that
  * throw on failure, use {@link AssertObject} from the asserts module.
  *
@@ -18,4 +22,3 @@
 export function IsObject(item) {
     return item !== null && typeof item === 'object' && !Array.isArray(item);
 }
-//# sourceMappingURL=assert-object.js.map

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

@@ -1,4 +1,4 @@
-import { IAssertException } from '../asserts/types.js';
+import type { IAssertException } from '../asserts/types.js';
 import { SimpleError } from '../asserts/errors.js';
 /**
  * Error thrown when a value is not a valid object or fails an object assertion.

package/dist/object/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/object/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,WAAW;gBAC/B,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;gBACvC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASvH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAU9I;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAUjJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAW9I"}

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

@@ -1,7 +1,6 @@
 import { SetExceptionClass, SetExceptionMessage, ThrowException } from '../asserts/utils.js';
 import { SimpleError } from '../asserts/errors.js';
-/** Maximum number of characters to include from a value in an error message. */
-const MAX_VALUE_DISPLAY_LENGTH = 100;
+import { safeDisplay } from '../asserts/generic.js';
 /**
  * Error thrown when a value is not a valid object or fails an object assertion.
  *
@@ -52,28 +51,8 @@ export function AssertObject(value, exception = {}) {
     SetExceptionClass(exception, ObjectError);
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         const actualType = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
-        let valueStr;
-        try {
-            if (typeof value === 'function') {
-                valueStr = '[Function]';
-            }
-            else if (value === null) {
-                valueStr = 'null';
-            }
-            else if (value === undefined) {
-                valueStr = 'undefined';
-            }
-            else if (typeof value === 'symbol') {
-                valueStr = `[Symbol: ${String(value)}]`;
-            }
-            else {
-                valueStr = JSON.stringify(value);
-            }
-        }
-        catch {
-            valueStr = String(value);
-        }
-        SetExceptionMessage(exception, `Expected object but received ${actualType}: ${valueStr.slice(0, MAX_VALUE_DISPLAY_LENGTH)}`);
+        const valueStr = safeDisplay(value);
+        SetExceptionMessage(exception, `Expected object but received ${actualType}: ${valueStr}`);
         ThrowException(exception);
     }
 }
@@ -109,8 +88,8 @@ export function AssertObject(value, exception = {}) {
  * ```
  */
 export function AssertObjectHasProperty(value, property, exception = {}) {
-    // First check if value is an object, using ObjectError
-    AssertObject(value, { class: ObjectError });
+    // First check if value is an object, using the configured exception class or ObjectError
+    AssertObject(value, { class: exception?.class ?? ObjectError });
     // Then check for property existence, using the configured exception class or default
     SetExceptionClass(exception, ObjectPropertyError);
     if (!(property in value)) {
@@ -149,8 +128,8 @@ export function AssertObjectHasProperty(value, property, exception = {}) {
  * ```
  */
 export function AssertObjectHasOwnProperty(value, property, exception = {}) {
-    // First check if value is an object, using ObjectError
-    AssertObject(value, { class: ObjectError });
+    // First check if value is an object, using the configured exception class or ObjectError
+    AssertObject(value, { class: exception?.class ?? ObjectError });
     // Then check for own property existence, using the configured exception class or default
     SetExceptionClass(exception, ObjectPropertyError);
     if (!Object.hasOwn(value, property)) {
@@ -198,4 +177,3 @@ export function AssertObjectPropertyNotNull(value, property, exception = {}) {
         ThrowException(exception);
     }
 }
-//# sourceMappingURL=assert.js.map

package/{build → dist}/object/clone.d.ts

@@ -21,6 +21,12 @@ import type { TObjectTransformer } from './types.js';
  * clone.b.c = 99;
  * console.log(original.b.c); // 2  (original is not affected)
  * ```
+ * @example
+ * ```typescript
+ * const nullProtoObj = Object.create(null);
+ * nullProtoObj.x = 1;
+ * const cloned = ObjectClone(nullProtoObj); // Works correctly even for null-prototype objects
+ * ```
  */
 export declare function ObjectClone<T>(obj: T, visitedInput?: WeakSet<object>): T;
 /**

package/dist/object/clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone.d.ts","sourceRoot":"","sources":["../../src/object/clone.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAkExE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,SAAS,MAAM,EAC5E,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9C,OAAO,CAMT"}

package/{build → dist}/object/clone.js

@@ -1,4 +1,4 @@
-import { filterDangerousKeys } from './security-utils.js';
+import { FilterDangerousKeys } from './security-utils.js';
 /**
  * Creates a deep clone of an object with security protections.
  *
@@ -21,6 +21,12 @@ import { filterDangerousKeys } from './security-utils.js';
  * clone.b.c = 99;
  * console.log(original.b.c); // 2  (original is not affected)
  * ```
+ * @example
+ * ```typescript
+ * const nullProtoObj = Object.create(null);
+ * nullProtoObj.x = 1;
+ * const cloned = ObjectClone(nullProtoObj); // Works correctly even for null-prototype objects
+ * ```
  */
 export function ObjectClone(obj, visitedInput) {
     if (obj === null || obj === undefined) {
@@ -37,6 +43,10 @@ export function ObjectClone(obj, visitedInput) {
         // Mark this object as visited
         visited.add(obj);
     }
+    // PERFORMANCE NOTE: The backtrack pattern (visited.delete() after processing composite types)
+    // uses delete/add operations on WeakSet for each Date, Array, and Object. For deeply nested
+    // structures (100+ levels), this delete/add cost accumulates. Depth tracking would optimize
+    // this, but the current implementation is correct for circular reference handling.
     // Handle Date
     if (obj instanceof Date) {
         const result = new Date(obj.getTime());
@@ -52,9 +62,9 @@ export function ObjectClone(obj, visitedInput) {
         return result;
     }
     // Handle plain objects only
-    if (obj.constructor === Object) {
+    if (Object.getPrototypeOf(obj) === null || obj.constructor === Object) {
         // Security: Filter out dangerous keys
-        const safeObj = filterDangerousKeys(obj);
+        const safeObj = FilterDangerousKeys(obj);
         const copy = {};
         // Object.keys() returns only own enumerable properties — no further guard needed.
         for (const key of Object.keys(safeObj)) {
@@ -72,7 +82,7 @@ export function ObjectClone(obj, visitedInput) {
     }
     // Provide detailed error message for unsupported types
     const typeName = typeof obj === 'object'
-        ? obj.constructor.name
+        ? Object.getPrototypeOf(obj)?.constructor?.name ?? 'Object'
         : typeof obj;
     throw new Error(`ObjectClone: ${typeName} objects are not supported. Create a new ${typeName} instance manually.`);
 }
@@ -105,4 +115,3 @@ export function TransformObject(obj, transformer) {
     }
     return transformer(obj);
 }
-//# sourceMappingURL=clone.js.map

package/{build → dist}/object/equals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"equals.d.ts","sourceRoot":"","sources":["../../src/object/equals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAuE5D"}
+{"version":3,"file":"equals.d.ts","sourceRoot":"","sources":["../../src/object/equals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAqE5D"}

package/{build → dist}/object/equals.js

@@ -48,18 +48,13 @@ export function ObjectEquals(a, b) {
     if (typeof a === 'number' && typeof b === 'number' && isNaN(a) && isNaN(b)) {
         return true;
     }
-    // If either value is null, undefined, or not an object, they can't be equivalent
+    // Null/undefined guards — all subsequent branches assume non-null objects.
     if (a === null || b === null || a === undefined || b === undefined)
         return false;
     if (typeof a !== typeof b)
         return false;
     if (typeof a !== 'object')
         return false;
-    // Type guards for object types after typeof check
-    if (a === null || b === null)
-        return false;
-    if (a === undefined || b === undefined)
-        return false;
     const aObj = a;
     const bObj = b;
     // Handle Date objects
@@ -92,6 +87,8 @@ export function ObjectEquals(a, b) {
     // Also compare symbol properties
     const symbolsA = Object.getOwnPropertySymbols(aObj);
     const symbolsB = Object.getOwnPropertySymbols(bObj);
+    // Early exit if neither object has symbols — REMOVED: this skips property value comparison
+    // if (symbolsA.length === 0 && symbolsB.length === 0) return true;
     if (symbolsA.length !== symbolsB.length)
         return false;
     for (const key of keysA) {
@@ -108,4 +105,3 @@ export function ObjectEquals(a, b) {
     }
     return true;
 }
-//# sourceMappingURL=equals.js.map

package/dist/object/filter-cached.d.ts

@@ -0,0 +1,26 @@
+import type { ICachedObjectFilterOptions, TCachedObjectFilterFunction } from './types.js';
+/**
+ * Creates a cached version of {@link ObjectFilter} for improved performance
+ * when filtering the same objects repeatedly.
+ *
+ * Results are cached by hashing the filter and object together. When the cache
+ * exceeds `maxCacheSize`, approximately 20% of the entries in the largest
+ * per-filter bucket are evicted.
+ *
+ * @template T — The object type being filtered
+ * @param options — Configuration for both the cache and the underlying filter
+ * @returns — A cached filter function `(cursor, filter) => Promise<boolean>` that returns
+ * `true` if the object matches the filter criteria, or `false` if it does not. An empty
+ * filter argument (no properties) matches all objects.
+ * @warning Filter objects with function-valued properties are not safely cacheable because
+ * {@link ObjectHash} cannot deterministically hash function references. Two different function
+ * instances with identical behavior will hash to different values, bypassing the cache and
+ * potentially causing unexpected behavior. Avoid passing filters with methods or callbacks.
+ * @example
+ * ```typescript
+ * const cachedFilter = ObjectFilterCached<User>({ maxCacheSize: 500 });
+ * const isAdmin = await cachedFilter(user, { role: 'admin' });
+ * ```
+ */
+export declare function ObjectFilterCached<T extends object>(options?: ICachedObjectFilterOptions): TCachedObjectFilterFunction<T>;
+//# sourceMappingURL=filter-cached.d.ts.map