@pawells/typescript-common 2.0.0 → 2.1.5

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

@@ -1 +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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CA6DxE;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"}
+{"version":3,"file":"clone.d.ts","sourceRoot":"","sources":["../../src/object/clone.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;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.
  *
@@ -37,6 +37,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 +56,9 @@ export function ObjectClone(obj, visitedInput) {
         return result;
     }
     // Handle plain objects only
-    if (obj.constructor === Object) {
+    if (obj.constructor === Object || Object.getPrototypeOf(obj) === null) {
         // 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 +76,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 +109,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,44 @@
+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>`
+ *
+ * @example
+ * ```typescript
+ * const cachedFilter = ObjectFilterCached<User>({ maxCacheSize: 500 });
+ * const isAdmin = await cachedFilter(user, { role: 'admin' });
+ * ```
+ */
+/**
+ * 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

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

@@ -1 +1 @@
-{"version":3,"file":"filter-cached.d.ts","sourceRoot":"","sources":["../../src/object/filter-cached.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,0BAA0B,EAAE,2BAA2B,EAAwB,MAAM,YAAY,CAAC;AAMhH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,2BAA2B,CAAC,CAAC,CAAC,CAkH7H"}
+{"version":3,"file":"filter-cached.d.ts","sourceRoot":"","sources":["../../src/object/filter-cached.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,0BAA0B,EAAE,2BAA2B,EAAwB,MAAM,YAAY,CAAC;AAMhH;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,2BAA2B,CAAC,CAAC,CAAC,CAmI7H"}

package/{build → dist}/object/filter-cached.js

@@ -21,6 +21,29 @@ const CACHE_EVICTION_PERCENTAGE = 0.2; // 20%
  * const isAdmin = await cachedFilter(user, { role: 'admin' });
  * ```
  */
+/**
+ * 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 function ObjectFilterCached(options = {}) {
     const { maxCacheSize = DEFAULT_MAX_CACHE_SIZE, useDeepEqual = false, caseInsensitiveStrings = false, validatePaths = true, } = options;
     const cache = new Map();
@@ -31,6 +54,11 @@ export function ObjectFilterCached(options = {}) {
      *
      * The eviction strategy targets the most-populated bucket to reclaim the most
      * memory in a single pass while preserving results for other active filters.
+     *
+     * PERFORMANCE NOTE: For distributed filter load, eviction triggers too frequently.
+     * A true global LRU across all filters would be more efficient but would require
+     * tracking access order globally. Refactoring to use the library's own LRUCache
+     * (if available) instead of per-filter Maps would improve this further.
      */
     const clearOldestEntries = () => {
         if (cache.size === 0)
@@ -47,6 +75,8 @@ export function ObjectFilterCached(options = {}) {
             }
         }
         if (largestCache) {
+            // Capture the original bucket size before eviction
+            const originalBucketSize = largestCache.size;
             // Remove approximately 20% of entries from the largest cache
             const entriesToRemove = Math.ceil(largestSize * CACHE_EVICTION_PERCENTAGE);
             let removed = 0;
@@ -59,8 +89,18 @@ export function ObjectFilterCached(options = {}) {
             // If the cache is now empty, remove it completely
             if (largestCache.size === 0) {
                 cache.delete(largestCacheKey);
+                // Account for all entries that were in the bucket (not just the ones we explicitly removed)
+                totalCachedEntries -= originalBucketSize;
             }
-            totalCachedEntries -= removed;
+            else {
+                // Only remove the entries we explicitly deleted
+                totalCachedEntries -= removed;
+            }
+        }
+        // Recompute counter to eliminate drift
+        totalCachedEntries = 0;
+        for (const bucket of cache.values()) {
+            totalCachedEntries += bucket.size;
         }
     };
     return (cursor, filter) => {
@@ -115,4 +155,3 @@ export function ObjectFilterCached(options = {}) {
         return Promise.resolve(result);
     };
 }
-//# sourceMappingURL=filter-cached.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/object/filter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiFxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAwCvH;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAiBhG"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/object/filter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAyFxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAyCvH;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAiBhG"}

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

@@ -1,5 +1,5 @@
 import { ObjectEquals } from './equals.js';
-import { isPropertyPathSafe } from './security-utils.js';
+import { IsPropertyPathSafe } from './security-utils.js';
 import { ObjectGetPropertyByPath } from './property-paths.js';
 import { StringEquals } from '../string/comparison.js';
 /**
@@ -60,6 +60,14 @@ function objectHandleArrayComparison(objValue, filterValue, caseInsensitiveStrin
     }
     // If filterValue is also an array, check if it's a subset
     if (Array.isArray(filterValue)) {
+        // PERFORMANCE: For arrays of primitives without deep equality or case-insensitive matching,
+        // use a Set-based approach for O(n+m) performance instead of nested loops.
+        if (!useDeepEqual && !caseInsensitiveStrings && filterValue.every((item) => typeof item !== 'object' || item === null)) {
+            const objSet = new Set(objValue);
+            return filterValue.every((item) => objSet.has(item));
+        }
+        // For object arrays or when deep equality is enabled, fall back to nested loop comparison
+        // (reference equality for objects, deep equality if requested)
         return filterValue.every((item) => objValue.some((objItem) => compareValuesForFilter(objItem, item, caseInsensitiveStrings, useDeepEqual)));
     }
     // For non-string, non-array filter values, check direct inclusion
@@ -134,12 +142,12 @@ export function ObjectFilter(object, filter, options = {}) {
     // Default options
     const { useDeepEqual = false, caseInsensitiveStrings = false, validatePaths = false } = options;
     for (const key in filter) {
-        // Skip properties that are not own properties of the filter object
-        if (!Object.hasOwn(filter, key))
+        if (!Object.hasOwn(filter, key)) {
             continue;
+        }
         // Handle dot notation paths
         if (key.includes('.')) {
-            if (validatePaths && !isPropertyPathSafe(key)) {
+            if (validatePaths && !IsPropertyPathSafe(key)) {
                 return false;
             }
             const objValue = ObjectGetPropertyByPath(object, key);
@@ -203,4 +211,3 @@ export function FilterObject(obj, predicate) {
     }
     return result;
 }
-//# sourceMappingURL=filter.js.map

package/{build → dist}/object/has-circular-reference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"has-circular-reference.d.ts","sourceRoot":"","sources":["../../src/object/has-circular-reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CA8ChE"}
+{"version":3,"file":"has-circular-reference.d.ts","sourceRoot":"","sources":["../../src/object/has-circular-reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAiDhE"}

package/{build → dist}/object/has-circular-reference.js

@@ -45,10 +45,12 @@ export function ObjectHasCircularReference(obj) {
                 return true;
             }
         }
-        // Backtrack: same reason as the array case above.
+        // Backtrack: remove from visited set after traversal to allow the same object
+        // to appear via multiple non-circular paths. This correctly distinguishes shared
+        // references (allowed) from circular references (detected). Note: this assumes
+        // single-threaded synchronous traversal.
         seen.delete(value);
         return false;
     };
     return detectCircular(obj);
 }
-//# sourceMappingURL=has-circular-reference.js.map

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

@@ -1,4 +1,8 @@
 /**
+ * SECURITY WARNING: This hash is NON-CRYPTOGRAPHIC (cyrb53, 64-bit).
+ * Do NOT use for passwords, tokens, signatures, or any security-sensitive operation.
+ * For cryptographic hashing, use `crypto.subtle.digest('SHA-256', ...)` instead.
+ *
  * Creates a hash of an object.
  *
  * By default a fast, non-cryptographic 64-bit hash is used that works in all

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/object/hash.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAkBxF"}

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

@@ -1,4 +1,3 @@
-import { ObjectHasCircularReference } from './has-circular-reference.js';
 // cyrb53-style hash mixing constants (chosen for good avalanche properties)
 const HASH_SEED_1 = 0xdeadbeef;
 const HASH_SEED_2 = 0x41c6ce57;
@@ -15,6 +14,13 @@ const HEXADECIMAL_RADIX = 16;
  * Browser-compatible and synchronous — no Node.js APIs required.
  * Returns a 16-character lowercase hex string.
  */
+/**
+ * 64-bit cyrb53 hash function.
+ *
+ * PERFORMANCE NOTE: This hash has 2^64 output space; collisions are theoretically
+ * possible with large datasets. For cryptographic applications requiring collision
+ * resistance, use crypto.subtle.digest instead.
+ */
 function defaultHash(data) {
     let h1 = HASH_SEED_1;
     let h2 = HASH_SEED_2;
@@ -28,6 +34,10 @@ function defaultHash(data) {
     return h1.toString(HEXADECIMAL_RADIX).padStart(HASH_PAD_WIDTH, '0') + h2.toString(HEXADECIMAL_RADIX).padStart(HASH_PAD_WIDTH, '0');
 }
 /**
+ * SECURITY WARNING: This hash is NON-CRYPTOGRAPHIC (cyrb53, 64-bit).
+ * Do NOT use for passwords, tokens, signatures, or any security-sensitive operation.
+ * For cryptographic hashing, use `crypto.subtle.digest('SHA-256', ...)` instead.
+ *
  * Creates a hash of an object.
  *
  * By default a fast, non-cryptographic 64-bit hash is used that works in all
@@ -53,16 +63,19 @@ function defaultHash(data) {
  * ```
  */
 export function ObjectHash(obj, hashFunction) {
-    // Type guard - obj is used as-is since JSON.stringify accepts unknown
-    // Check for circular references before attempting to stringify
-    if (ObjectHasCircularReference(obj)) {
-        throw new Error('Cannot hash object with circular references');
+    let jsonString;
+    try {
+        jsonString = JSON.stringify(obj);
+    }
+    catch (e) {
+        if (e instanceof TypeError && e.message.includes('circular')) {
+            throw new Error('Cannot hash object with circular references');
+        }
+        throw new Error('Cannot hash object: JSON.stringify failed');
     }
-    const jsonString = JSON.stringify(obj);
     // Handle cases where JSON.stringify returns undefined
     if (jsonString === undefined) {
         throw new Error('Cannot hash object: JSON.stringify returned undefined');
     }
     return hashFunction ? hashFunction(jsonString) : defaultHash(jsonString);
 }
-//# sourceMappingURL=hash.js.map

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

@@ -23,12 +23,12 @@ export { ObjectPick } from './pick.js';
 export { ObjectOmit } from './omit.js';
 export { ObjectMerge } from './merge.js';
 export { IsObject } from './assert-object.js';
-export { isPropertyKeySafe, isPropertyPathSafe, sanitizePropertyKey, filterDangerousKeys, createCircularReferenceDetector, isInputSafe } from './security-utils.js';
+export { IsPropertyKeySafe, IsPropertyPathSafe, SanitizePropertyKey, FilterDangerousKeys, CreateCircularReferenceDetector, IsInputSafe } from './security-utils.js';
 export { ObjectInvert } from './object-invert.js';
 export { ObjectFlatten } from './object-flatten.js';
 export { ObjectDiff } from './object-diff.js';
 export { AssertObject, ObjectError, ObjectPropertyError, AssertObjectHasProperty, AssertObjectHasOwnProperty, AssertObjectPropertyNotNull } from './assert.js';
 export type { IObjectDiffResult } from './object-diff.js';
-export type { TConstructableObject, TObjectOmitExtraProperties, TCachedObjectFilterFunction, TCachedObjectMapperFunction, TObjectPredicate, TObjectTransformer, TObjectComparator, TObjectEqualityComparator, TPropertyMapper, TPropertyFilter } from './types.js';
+export type { TObjectOmitExtraProperties, TCachedObjectFilterFunction, TCachedObjectMapperFunction, TObjectPredicate, TObjectTransformer, TObjectComparator, TObjectEqualityComparator, TPropertyMapper, TPropertyFilter } from './types.js';
 export type { IObjectFilterOptions, ICachedObjectFilterOptions, ICachedObjectMapOptions } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/object/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,+BAA+B,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpK,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/J,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGnQ,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/object/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,+BAA+B,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpK,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/J,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,YAAY,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7O,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

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

@@ -24,9 +24,8 @@ export { ObjectPick } from './pick.js';
 export { ObjectOmit } from './omit.js';
 export { ObjectMerge } from './merge.js';
 export { IsObject } from './assert-object.js';
-export { isPropertyKeySafe, isPropertyPathSafe, sanitizePropertyKey, filterDangerousKeys, createCircularReferenceDetector, isInputSafe } from './security-utils.js';
+export { IsPropertyKeySafe, IsPropertyPathSafe, SanitizePropertyKey, FilterDangerousKeys, CreateCircularReferenceDetector, IsInputSafe } from './security-utils.js';
 export { ObjectInvert } from './object-invert.js';
 export { ObjectFlatten } from './object-flatten.js';
 export { ObjectDiff } from './object-diff.js';
 export { AssertObject, ObjectError, ObjectPropertyError, AssertObjectHasProperty, AssertObjectHasOwnProperty, AssertObjectPropertyNotNull } from './assert.js';
-//# sourceMappingURL=index.js.map

package/{build → dist}/object/json-circular-replacer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-circular-replacer.d.ts","sourceRoot":"","sources":["../../src/object/json-circular-replacer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,0BAA0B,CACzC,WAAW,GAAE,MAAqB,GAChC,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CA0BzD"}
+{"version":3,"file":"json-circular-replacer.d.ts","sourceRoot":"","sources":["../../src/object/json-circular-replacer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,0BAA0B,CACzC,WAAW,SAAe,GACxB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CA0BzD"}

package/{build → dist}/object/json-circular-replacer.js

@@ -57,4 +57,3 @@ export function CreateJsonCircularReplacer(placeholder = '[Circular]') {
         return value;
     };
 }
-//# sourceMappingURL=json-circular-replacer.js.map

package/{build → dist}/object/key-value-pairs.js

@@ -41,4 +41,3 @@ export function ObjectFromKeyValuePairs(entries) {
 export function ObjectToKeyValuePairs(obj) {
     return Object.entries(obj);
 }
-//# sourceMappingURL=key-value-pairs.js.map