@pawells/typescript-common 2.0.0 → 2.1.6

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;;;;;;;;;;;;;;;;;;;;;;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

@@ -11,10 +11,15 @@ const CACHE_EVICTION_PERCENTAGE = 0.2; // 20%
  * 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>`
- *
+ * @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 });
@@ -31,6 +36,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 +57,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 +71,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 +137,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;AAmGxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,7 +1,16 @@
 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';
+/**
+ * Type guard to safely identify a filter predicate function.
+ *
+ * @param v - The value to check
+ * @returns True if the value is a function that can be used as a filter predicate
+ */
+function isFilterPredicate(v) {
+    return typeof v === 'function';
+}
 /**
  * Compares two values for ObjectFilter with support for predicates, case-insensitive strings,
  * and deep equality via ObjectEquals.
@@ -14,7 +23,7 @@ import { StringEquals } from '../string/comparison.js';
  */
 function compareValuesForFilter(objValue, filterValue, caseInsensitiveStrings = false, useDeepEqual = false) {
     // Handle function as predicate
-    if (typeof filterValue === 'function') {
+    if (isFilterPredicate(filterValue)) {
         return filterValue(objValue);
     }
     // Handle case-insensitive string comparison (filter-specific feature)
@@ -60,6 +69,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 +151,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 +220,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', { cause: e });
+        }
+        throw new Error('Cannot hash object: JSON.stringify failed', { cause: e });
     }
-    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 { 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,2BAA2B,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGjN,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

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

@@ -0,0 +1,31 @@
+import type { TPropertyMapper, ICachedObjectMapOptions } from './types.js';
+/**
+ * Creates a cached version of {@link MapObject} for improved performance
+ * when mapping the same objects repeatedly.
+ *
+ * Results are cached by hashing the object. Cache entries are evicted in
+ * approximately 20% batches when the limit is reached.
+ *
+ * @template T - The object type being mapped
+ * @param options - Configuration options for cache behaviour
+ * @returns A cached map function with parameters:
+ *   - `cursor` - The object to be mapped
+ *   - `mapper` - Function to map each property value
+ *   - `mapperKey` - Optional stable string identifier for the mapper. When omitted,
+ *     `Function.toString()` is used as the cache key, which may cause cache collisions
+ *     for closures with identical source text but different captured variables.
+ *     Always provide an explicit `mapperKey` when the mapper captures mutable state.
+ *
+ * @warning When `mapperKey` is not provided, the function uses `Function.toString()` as
+ * the cache key. This approach is expensive for large functions and causes cache collisions
+ * for closures with identical source code but different captured values. Always supply an
+ * explicit `mapperKey` to avoid unexpected cache behavior.
+ *
+ * @example
+ * ```typescript
+ * const cachedMap = MapObjectCached<User>();
+ * const display = await cachedMap(user, (key, value) => String(value));
+ * ```
+ */
+export declare function MapObjectCached<T extends object>(options?: ICachedObjectMapOptions): (cursor: T, mapper: TPropertyMapper<T>, mapperKey?: string) => Promise<Record<keyof T, unknown>>;
+//# sourceMappingURL=map-cached.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"map-cached.d.ts","sourceRoot":"","sources":["../../src/object/map-cached.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAmHzL"}

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

@@ -12,7 +12,18 @@ const CACHE_EVICTION_PERCENTAGE = 0.2; // 20%
  *
  * @template T - The object type being mapped
  * @param options - Configuration options for cache behaviour
- * @returns A cached map function `(cursor, mapper, mapperKey?) => Promise<Record<keyof T, unknown>>`
+ * @returns A cached map function with parameters:
+ *   - `cursor` - The object to be mapped
+ *   - `mapper` - Function to map each property value
+ *   - `mapperKey` - Optional stable string identifier for the mapper. When omitted,
+ *     `Function.toString()` is used as the cache key, which may cause cache collisions
+ *     for closures with identical source text but different captured variables.
+ *     Always provide an explicit `mapperKey` when the mapper captures mutable state.
+ *
+ * @warning When `mapperKey` is not provided, the function uses `Function.toString()` as
+ * the cache key. This approach is expensive for large functions and causes cache collisions
+ * for closures with identical source code but different captured values. Always supply an
+ * explicit `mapperKey` to avoid unexpected cache behavior.
  *
  * @example
  * ```typescript
@@ -30,6 +41,11 @@ export function MapObjectCached(options = {}) {
      *
      * The eviction strategy targets the most-populated bucket to reclaim the most
      * memory in a single pass while preserving results for other active mappers.
+     *
+     * PERFORMANCE NOTE: For distributed mapper load, eviction triggers too frequently.
+     * A true global LRU across all mappers would be more efficient but would require
+     * tracking access order globally. Refactoring to use the library's own LRUCache
+     * (if available) instead of per-mapper Maps would improve this further.
      */
     const clearOldestEntries = () => {
         if (cache.size === 0)
@@ -46,6 +62,8 @@ export function MapObjectCached(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;
@@ -58,8 +76,13 @@ export function MapObjectCached(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;
+            }
+            else {
+                // Only remove the entries we explicitly deleted
+                totalCachedEntries -= removed;
             }
-            totalCachedEntries -= removed;
         }
     };
     return (cursor, mapper, mapperKey) => {
@@ -68,9 +91,10 @@ export function MapObjectCached(options = {}) {
             return Promise.resolve({});
         }
         // Use the explicitly provided mapperKey when available.
-        // WARNING: If mapperKey is omitted and mapper is a closure, two closures with
-        // identical source code but different captured values will incorrectly share cache
-        // entries. Always provide an explicit mapperKey when using closure mappers.
+        // NOTE: When mapperKey is not provided, uses Function.toString() as cache key.
+        // This is expensive for large functions and causes cache collisions for closures
+        // with identical source code but different captured values.
+        // Always provide explicit mapperKey for correct behavior.
         const resolvedMapperKey = mapperKey ?? mapper.toString();
         // Try to get the object cache for this mapper
         let objectCache = cache.get(resolvedMapperKey);
@@ -100,8 +124,12 @@ export function MapObjectCached(options = {}) {
         // Ensure the cache size does not exceed the limit
         if (totalCachedEntries > maxCacheSize) {
             clearOldestEntries();
+            // Recompute counter to eliminate drift
+            totalCachedEntries = 0;
+            for (const bucket of cache.values()) {
+                totalCachedEntries += bucket.size;
+            }
         }
         return Promise.resolve(result);
     };
 }
-//# sourceMappingURL=map-cached.js.map

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

@@ -37,4 +37,3 @@ export function MapObject(obj, mapper) {
     }
     return result;
 }
-//# sourceMappingURL=map.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/object/merge.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAyBvF"}
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/object/merge.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CA0BvF"}

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

@@ -1,4 +1,4 @@
-import { filterDangerousKeys } from './security-utils.js';
+import { FilterDangerousKeys } from './security-utils.js';
 /**
  * Merges two objects deeply with security protections.
  *
@@ -28,22 +28,22 @@ export function ObjectMerge(target, source) {
     if (!source || typeof source !== 'object')
         return target;
     // Security: Filter out dangerous keys from source object
-    const safeSource = filterDangerousKeys(source);
+    const safeSource = FilterDangerousKeys(source);
     const output = { ...target };
     // Object.keys() returns only own enumerable properties — no further guard needed.
     for (const key of Object.keys(safeSource)) {
-        const targetValue = output[key];
+        const outputRecord = output;
+        const targetValue = outputRecord[key];
         const sourceValue = safeSource[key];
         if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {
-            output[key] = [...targetValue, ...sourceValue];
+            outputRecord[key] = [...targetValue, ...sourceValue];
         }
         else if (targetValue && typeof targetValue === 'object' && sourceValue && typeof sourceValue === 'object') {
-            output[key] = ObjectMerge(targetValue, sourceValue);
+            outputRecord[key] = ObjectMerge(targetValue, sourceValue);
         }
         else {
-            output[key] = sourceValue;
+            outputRecord[key] = sourceValue;
         }
     }
     return output;
 }
-//# sourceMappingURL=merge.js.map

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

@@ -16,8 +16,8 @@ export interface IObjectDiffResult {
  * Returns three groups:
  * - **added** — keys in `objB` that are absent from `objA`
  * - **removed** — keys in `objA` that are absent from `objB`
- * - **changed** — keys present in both whose values are not strictly equal
- *   (compared via `JSON.stringify` for deep value equality)
+ * - **changed** — keys present in both whose values differ
+ *   (compared via `ObjectEquals` for deep value equality)
  *
  * **Important**: Comparison is performed with deep equality (`ObjectEquals`),
  * which correctly handles nested objects regardless of key insertion order,

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

@@ -1 +1 @@
-{"version":3,"file":"object-diff.d.ts","sourceRoot":"","sources":["../../src/object/object-diff.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IACjC,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,iBAAiB,CAkBnB"}
+{"version":3,"file":"object-diff.d.ts","sourceRoot":"","sources":["../../src/object/object-diff.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IACjC,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,iBAAiB,CA0BnB"}

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

@@ -5,8 +5,8 @@ import { ObjectEquals } from './equals.js';
  * Returns three groups:
  * - **added** — keys in `objB` that are absent from `objA`
  * - **removed** — keys in `objA` that are absent from `objB`
- * - **changed** — keys present in both whose values are not strictly equal
- *   (compared via `JSON.stringify` for deep value equality)
+ * - **changed** — keys present in both whose values differ
+ *   (compared via `ObjectEquals` for deep value equality)
  *
  * **Important**: Comparison is performed with deep equality (`ObjectEquals`),
  * which correctly handles nested objects regardless of key insertion order,
@@ -32,8 +32,15 @@ import { ObjectEquals } from './equals.js';
  */
 export function ObjectDiff(objA, objB) {
     const result = { added: {}, removed: {}, changed: {} };
-    const allKeys = new Set([...Object.keys(objA), ...Object.keys(objB)]);
-    for (const key of allKeys) {
+    // Combine keys from both objects efficiently
+    const allKeys = new Map();
+    for (const key of Object.keys(objA)) {
+        allKeys.set(key, true);
+    }
+    for (const key of Object.keys(objB)) {
+        allKeys.set(key, true);
+    }
+    for (const key of allKeys.keys()) {
         const inA = Object.hasOwn(objA, key);
         const inB = Object.hasOwn(objB, key);
         if (inA && !inB) {
@@ -48,4 +55,3 @@ export function ObjectDiff(objA, objB) {
     }
     return result;
 }
-//# sourceMappingURL=object-diff.js.map

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

@@ -18,5 +18,5 @@
  * // { 'a/b': 1 }
  * ```
  */
-export declare function ObjectFlatten(obj: Record<string, unknown>, separator?: string, _prefix?: string): Record<string, unknown>;
+export declare function ObjectFlatten(obj: Record<string, unknown>, separator?: string): Record<string, unknown>;
 //# sourceMappingURL=object-flatten.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"object-flatten.d.ts","sourceRoot":"","sources":["../../src/object/object-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,SAAM,EACf,OAAO,SAAK,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB"}
+{"version":3,"file":"object-flatten.d.ts","sourceRoot":"","sources":["../../src/object/object-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,SAAM,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB"}

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

@@ -18,16 +18,23 @@
  * // { 'a/b': 1 }
  * ```
  */
-export function ObjectFlatten(obj, separator = '.', _prefix = '') {
+export function ObjectFlatten(obj, separator = '.') {
+    return flattenRecursive(obj, separator, '');
+}
+/**
+ * @internal Recursion helper; not part of the public API.
+ * @param prefix - Accumulated key prefix from parent recursion level
+ */
+function flattenRecursive(obj, separator, prefix) {
     const result = {};
     for (const key of Object.keys(obj)) {
         const value = obj[key];
-        const newKey = _prefix ? `${_prefix}${separator}${key}` : key;
+        const newKey = prefix ? `${prefix}${separator}${key}` : key;
         if (value !== null &&
             typeof value === 'object' &&
             !Array.isArray(value) &&
             !(value instanceof Date)) {
-            Object.assign(result, ObjectFlatten(value, separator, newKey));
+            Object.assign(result, flattenRecursive(value, separator, newKey));
         }
         else {
             result[newKey] = value;
@@ -35,4 +42,3 @@ export function ObjectFlatten(obj, separator = '.', _prefix = '') {
     }
     return result;
 }
-//# sourceMappingURL=object-flatten.js.map

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

@@ -23,4 +23,3 @@ export function ObjectInvert(obj) {
     }
     return result;
 }
-//# sourceMappingURL=object-invert.js.map

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

@@ -23,4 +23,3 @@ export function ObjectOmit(obj, keys) {
     });
     return result;
 }
-//# sourceMappingURL=omit.js.map

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

@@ -57,4 +57,3 @@ export function ObjectPick(obj, keys) {
         return result;
     }, {});
 }
-//# sourceMappingURL=pick.js.map

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

@@ -68,6 +68,8 @@ export declare function ObjectGetPropertyByPath<T = unknown>(obj: unknown, path:
  * @param obj - Target object to modify
  * @param path - Path to the property using dot notation (e.g., 'user.address.street')
  * @param value - Value to set at the specified path
+ * @throws Throws if `path` contains dangerous keys (`__proto__`, `constructor`, `prototype`)
+ * @throws Throws if `path` is invalid or contains non-string segments
  *
  * @example
  * ```typescript

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

@@ -1 +1 @@
-{"version":3,"file":"property-paths.d.ts","sourceRoot":"","sources":["../../src/object/property-paths.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAiChH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAyC/F"}
+{"version":3,"file":"property-paths.d.ts","sourceRoot":"","sources":["../../src/object/property-paths.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAiChH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAyC/F"}