@pawells/typescript-common 1.4.1 → 2.1.5

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,CA0DxE;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,14 +56,17 @@ 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)) {
             copy[key] = ObjectClone(safeObj[key], visited);
         }
+        // Note: Symbol properties are intentionally not cloned. Symbols often represent
+        // object identity or metadata that should not be duplicated across instances.
+        // If symbol cloning is needed, use Object.getOwnPropertySymbols() manually.
         visited.delete(obj); // Backtrack for the same reason as Date above.
         return copy;
     }
@@ -69,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.`);
 }
@@ -102,4 +109,3 @@ export function TransformObject(obj, transformer) {
     }
     return transformer(obj);
 }
-//# sourceMappingURL=clone.js.map

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

@@ -40,5 +40,5 @@
  * ObjectEquals(null, undefined); // false
  * ```
  */
-export declare function ObjectEquals(a: any, b: any): boolean;
+export declare function ObjectEquals(a: unknown, b: unknown): boolean;
 //# sourceMappingURL=equals.d.ts.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,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAgEpD"}
+{"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,13 +48,15 @@ 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;
+    const aObj = a;
+    const bObj = b;
     // Handle Date objects
     if (a instanceof Date && b instanceof Date) {
         return a.getTime() === b.getTime();
@@ -78,27 +80,28 @@ export function ObjectEquals(a, b) {
     if (Array.isArray(a) !== Array.isArray(b))
         return false;
     // Compare object properties
-    const keysA = Object.keys(a);
-    const keysB = Object.keys(b);
+    const keysA = Object.keys(aObj);
+    const keysB = Object.keys(bObj);
     if (keysA.length !== keysB.length)
         return false;
     // Also compare symbol properties
-    const symbolsA = Object.getOwnPropertySymbols(a);
-    const symbolsB = Object.getOwnPropertySymbols(b);
+    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) {
-        if (!Object.hasOwn(b, key))
+        if (!Object.hasOwn(bObj, key))
             return false;
-        if (!ObjectEquals(a[key], b[key]))
+        if (!ObjectEquals(aObj[key], bObj[key]))
             return false;
     }
     for (const symbol of symbolsA) {
         if (!symbolsB.includes(symbol))
             return false;
-        if (!ObjectEquals(a[symbol], b[symbol]))
+        if (!ObjectEquals(aObj[symbol], bObj[symbol]))
             return false;
     }
     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

@@ -64,7 +64,7 @@ import type { IObjectFilterOptions, TPropertyFilter } from './types.js';
  * ObjectFilter(user, { age: (v) => v < 18 }); // false
  * ```
  */
-export declare function ObjectFilter<T>(object: T, filter: Record<string, any>, options?: IObjectFilterOptions): boolean;
+export declare function ObjectFilter<T>(object: T, filter: Record<string, unknown>, options?: IObjectFilterOptions): boolean;
 /**
  * Filters an object's properties using a predicate function.
  * Creates a new object containing only the properties for which the predicate returns true.

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

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/object/filter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAgHxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAgDnH;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,40 +1,48 @@
 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';
 /**
- * Compares two objects using deep equality logic for ObjectFilter
+ * Compares two values for ObjectFilter with support for predicates, case-insensitive strings,
+ * and deep equality via ObjectEquals.
  *
  * @param objValue - The object value to compare
  * @param filterValue - The filter value to compare against
  * @param caseInsensitiveStrings - Whether to use case-insensitive string comparison
- * @returns True if the values match according to deep equality rules
+ * @param useDeepEqual - Whether to use deep equality for nested objects
+ * @returns True if the values match according to filter comparison rules
  */
-function objectDeepComparison(objValue, filterValue, caseInsensitiveStrings = false) {
+function compareValuesForFilter(objValue, filterValue, caseInsensitiveStrings = false, useDeepEqual = false) {
     // Handle function as predicate
     if (typeof filterValue === 'function') {
         return filterValue(objValue);
     }
-    // Handle string comparison with case insensitivity option
+    // Handle case-insensitive string comparison (filter-specific feature)
     if (caseInsensitiveStrings && typeof objValue === 'string' && typeof filterValue === 'string') {
-        return objValue.toLowerCase() === filterValue.toLowerCase();
+        return StringEquals(objValue, filterValue, true);
     }
-    // Special handling for Date objects
-    if (objValue instanceof Date && filterValue instanceof Date) {
-        return objValue.getTime() === filterValue.getTime();
+    // Special handling for NaN - ObjectEquals handles this, but strict equality doesn't
+    if (typeof objValue === 'number' && typeof filterValue === 'number' && isNaN(objValue) && isNaN(filterValue)) {
+        return true;
     }
     // Handle array cases: if objValue is an array, use array comparison logic
     if (Array.isArray(objValue)) {
-        return objectHandleArrayComparison(objValue, filterValue, caseInsensitiveStrings, true);
+        return objectHandleArrayComparison(objValue, filterValue, caseInsensitiveStrings, useDeepEqual);
     }
     // For deeply nested structures, check if filter is a subset of the object
     if (typeof objValue === 'object' && objValue !== null && typeof filterValue === 'object' && filterValue !== null && !Array.isArray(filterValue)) {
         return ObjectFilter(objValue, filterValue, { useDeepEqual: true, caseInsensitiveStrings });
     }
-    // Default case: use full object equality
-    return ObjectEquals(objValue, filterValue);
+    // Use deep equality if requested; otherwise use strict equality
+    if (useDeepEqual) {
+        return ObjectEquals(objValue, filterValue);
+    }
+    // Default: strict equality
+    return objValue === filterValue;
 }
 /**
- * Handles array filtering logic with support for string inclusion and subset matching
+ * Handles array filtering logic with support for string inclusion and subset matching.
+ * Uses compareValuesForFilter for consistent comparison logic.
  *
  * @param objValue - The array value from the object
  * @param filterValue - The filter value to match against
@@ -46,53 +54,24 @@ function objectHandleArrayComparison(objValue, filterValue, caseInsensitiveStrin
     // If filterValue is a string, check if it exists in the array
     if (typeof filterValue === 'string') {
         if (caseInsensitiveStrings) {
-            return objValue.some((item) => typeof item === 'string' && item.toLowerCase() === filterValue.toLowerCase());
+            return objValue.some((item) => typeof item === 'string' && StringEquals(item, filterValue, true));
         }
         return objValue.includes(filterValue);
     }
     // If filterValue is also an array, check if it's a subset
     if (Array.isArray(filterValue)) {
-        return filterValue.every((item) => objValue.some((objItem) => objectCompareValues(objItem, item, caseInsensitiveStrings, useDeepEqual)));
+        // 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
-    return objValue.some((item) => objectCompareValues(item, filterValue, caseInsensitiveStrings, useDeepEqual));
-}
-/**
- * Compare values based on filter criteria
- *
- * @param objValue The object value
- * @param filterValue The filter value to compare against
- * @param caseInsensitiveStrings Whether to do case-insensitive string comparison
- * @param useDeepEqual Whether to use deep equality for nested objects
- * @returns True if values match according to specified criteria
- */
-function objectCompareValues(objValue, filterValue, caseInsensitiveStrings, useDeepEqual = false) {
-    // Handle function as predicate
-    if (typeof filterValue === 'function') {
-        return filterValue(objValue);
-    }
-    // Check if objValue is an array
-    if (Array.isArray(objValue)) {
-        return objectHandleArrayComparison(objValue, filterValue, caseInsensitiveStrings, useDeepEqual);
-    }
-    // Handle string comparison with case insensitivity option
-    if (caseInsensitiveStrings && typeof objValue === 'string' && typeof filterValue === 'string') {
-        return objValue.toLowerCase() === filterValue.toLowerCase();
-    }
-    // Special handling for NaN
-    if (typeof objValue === 'number' && typeof filterValue === 'number' && isNaN(objValue) && isNaN(filterValue)) {
-        return true;
-    }
-    // For object filtering with useDeepEqual, check if filterValue is a subset of objValue
-    if (useDeepEqual && typeof objValue === 'object' && objValue !== null && typeof filterValue === 'object' && filterValue !== null && !Array.isArray(filterValue)) {
-        return ObjectFilter(objValue, filterValue, { useDeepEqual: true, caseInsensitiveStrings });
-    }
-    // Use deep equality if requested
-    if (useDeepEqual) {
-        return ObjectEquals(objValue, filterValue);
-    }
-    // Default strict equality
-    return objValue === filterValue;
+    return objValue.some((item) => compareValuesForFilter(item, filterValue, caseInsensitiveStrings, useDeepEqual));
 }
 /**
  * Filters an object based on a provided filter using flexible matching criteria.
@@ -163,26 +142,21 @@ 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);
             if (objValue === undefined) {
                 return false;
             }
-            // Compare the values
+            // Compare the values using the consolidated function
             const filterValue = filter[key];
-            if (useDeepEqual) {
-                if (!objectDeepComparison(objValue, filterValue, caseInsensitiveStrings)) {
-                    return false;
-                }
-            }
-            else if (!objectCompareValues(objValue, filterValue, caseInsensitiveStrings, useDeepEqual)) {
+            if (!compareValuesForFilter(objValue, filterValue, caseInsensitiveStrings, useDeepEqual)) {
                 return false;
             }
         }
@@ -193,12 +167,7 @@ export function ObjectFilter(object, filter, options = {}) {
             if (!(key in object)) {
                 return false;
             }
-            if (useDeepEqual) {
-                if (!objectDeepComparison(objValue, filterValue, caseInsensitiveStrings)) {
-                    return false;
-                }
-            }
-            else if (!objectCompareValues(objValue, filterValue, caseInsensitiveStrings, useDeepEqual)) {
+            if (!compareValuesForFilter(objValue, filterValue, caseInsensitiveStrings, useDeepEqual)) {
                 return false;
             }
         }
@@ -242,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
@@ -23,5 +27,5 @@
  * );
  * ```
  */
-export declare function ObjectHash(obj: any, hashFunction?: (data: string) => string): string;
+export declare function ObjectHash(obj: unknown, hashFunction?: (data: string) => string): string;
 //# sourceMappingURL=hash.d.ts.map

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