@pawells/typescript-common 2.0.0 → 2.1.5

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,19 @@
  * // { 'a/b': 1 }
  * ```
  */
-export function ObjectFlatten(obj, separator = '.', _prefix = '') {
+export function ObjectFlatten(obj, separator = '.') {
+    return flattenRecursive(obj, separator, '');
+}
+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 +38,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.js

@@ -1,4 +1,4 @@
-import { isPropertyPathSafe, isPropertyKeySafe } from './security-utils.js';
+import { IsPropertyPathSafe, IsPropertyKeySafe } from './security-utils.js';
 /**
  * Safely gets a nested property from an object using a path string with dot notation.
  * Returns the default value if the path doesn't exist or any intermediate value is null/undefined.
@@ -59,14 +59,14 @@ export function ObjectGetPropertyByPath(obj, path, defaultValue) {
         return defaultValue;
     }
     // Security validation: Check if the path is safe
-    if (!isPropertyPathSafe(path)) {
+    if (!IsPropertyPathSafe(path)) {
         return defaultValue;
     }
     const keys = path.split('.');
     let result = obj;
     for (const key of keys) {
         // Security check for each key
-        if (!isPropertyKeySafe(key)) {
+        if (!IsPropertyKeySafe(key)) {
             return defaultValue;
         }
         if (result === null || result === undefined || typeof result !== 'object') {
@@ -147,7 +147,7 @@ export function ObjectSetPropertyByPath(obj, path, value) {
         return;
     }
     // Security validation: Check if the path is safe
-    if (!isPropertyPathSafe(path)) {
+    if (!IsPropertyPathSafe(path)) {
         return;
     }
     const keys = path.split('.');
@@ -156,13 +156,13 @@ export function ObjectSetPropertyByPath(obj, path, value) {
         return;
     }
     // Additional security check for the final key
-    if (!isPropertyKeySafe(lastKey)) {
+    if (!IsPropertyKeySafe(lastKey)) {
         return;
     }
     let current = obj;
     for (const key of keys) {
         // Security check for each intermediate key
-        if (!isPropertyKeySafe(key)) {
+        if (!IsPropertyKeySafe(key)) {
             return;
         }
         if (current[key] === null || current[key] === undefined || typeof current[key] !== 'object') {
@@ -172,4 +172,3 @@ export function ObjectSetPropertyByPath(obj, path, value) {
     }
     current[lastKey] = value;
 }
-//# sourceMappingURL=property-paths.js.map

package/dist/object/security-utils.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Security utilities for object manipulation functions
+ * Provides protection against prototype pollution, path traversal, and other security vulnerabilities
+ *
+ * Sensitive data patterns considered by these utilities include:
+ * - Prototype pollution vectors: `__proto__`, `constructor`, `prototype`
+ * - Path traversal sequences: `..`, encoded dots (`%2e%2e`, `%252e%252e`)
+ * - Null byte injections: `\0`, `%00`
+ * - Unicode attacks: BOM characters, reversed BOM, invalid unicode sequences
+ * - Malformed input: consecutive dots, leading/trailing dots, empty segments
+ *
+ * @author Security Auditor Agent
+ * @version 1.0.0
+ */
+/**
+ * Validates if a property key is safe to use (not dangerous for prototype pollution)
+ *
+ * Blocks dangerous property names and path traversal patterns:
+ * - Prototype pollution vectors: `__proto__`, `constructor`, `prototype`
+ * - Path traversal: `..`, URL-encoded variants (`%2e%2e`, `%252e%252e`)
+ * - Null bytes: `\0` (literal), `%00` (URL-encoded)
+ * - Unicode attacks: BOM characters and invalid sequences
+ *
+ * @param key - The property key to validate
+ * @returns True if the key is safe to use as an object property, false if it's a known attack vector
+ *
+ * @example
+ * ```typescript
+ * IsPropertyKeySafe('name');           // true
+ * IsPropertyKeySafe('user_id');        // true
+ * IsPropertyKeySafe('__proto__');      // false (prototype pollution)
+ * IsPropertyKeySafe('constructor');    // false (prototype pollution)
+ * IsPropertyKeySafe('..');             // false (path traversal)
+ * IsPropertyKeySafe('%2e%2e');         // false (encoded path traversal)
+ * ```
+ */
+export declare function IsPropertyKeySafe(key: string): boolean;
+/**
+ * Validates a property path for security issues
+ *
+ * Detects and blocks malformed or dangerous paths:
+ * - Leading or trailing dots: `.name`, `path.`
+ * - Consecutive dots: `user..name` (double dot traversal)
+ * - Each path segment is validated via `IsPropertyKeySafe`
+ *
+ * Used by `ObjectGetPropertyByPath` and `ObjectSetPropertyByPath` to prevent
+ * prototype pollution and path traversal attacks. Safe for untrusted input
+ * when `validatePaths: true` is passed to ObjectFilter.
+ *
+ * @param path - The property path to validate using dot notation (e.g., `user.profile.name`)
+ * @returns True if the path is safe, false if it contains security risks
+ *
+ * @example
+ * ```typescript
+ * IsPropertyPathSafe('user.profile.name');  // true
+ * IsPropertyPathSafe('user..name');         // false (double dot)
+ * IsPropertyPathSafe('.user.name');         // false (leading dot)
+ * IsPropertyPathSafe('user.name.');         // false (trailing dot)
+ * IsPropertyPathSafe('user.__proto__.name'); // false (dangerous segment)
+ * ```
+ */
+export declare function IsPropertyPathSafe(path: string): boolean;
+/**
+ * Sanitizes a property key by removing or replacing dangerous characters
+ *
+ * Returns `null` if the key contains dangerous patterns (prototype pollution vectors,
+ * path traversal sequences) that cannot be safely sanitized. Otherwise returns the
+ * key with leading/trailing whitespace trimmed.
+ *
+ * @param key - The property key to sanitize
+ * @returns The sanitized key (with whitespace trimmed), or `null` if the key is dangerous
+ *
+ * @example
+ * ```typescript
+ * SanitizePropertyKey('  user.name  '); // 'user.name'
+ * SanitizePropertyKey('__proto__');     // null (dangerous)
+ * SanitizePropertyKey('valid-key');     // 'valid-key'
+ * ```
+ */
+export declare function SanitizePropertyKey(key: string): string | null;
+/**
+ * Filters out dangerous keys from an object
+ *
+ * Creates a new object containing only properties whose keys pass the `IsPropertyKeySafe` check.
+ * Blocks prototype pollution vectors: `__proto__`, `constructor`, `prototype`.
+ * Safe for untrusted input. Used internally by ObjectClone and ObjectMerge.
+ *
+ * @template T - The type of the object
+ * @param obj - The object to filter
+ * @returns New object with only safe keys (subset of input properties)
+ *
+ * @example
+ * ```typescript
+ * FilterDangerousKeys({ name: 'John', __proto__: {}, valid: true });
+ * // { name: 'John', valid: true }
+ *
+ * FilterDangerousKeys({ a: 1, constructor: 'bad', b: 2 });
+ * // { a: 1, b: 2 }
+ * ```
+ */
+export declare function FilterDangerousKeys<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/**
+ * Interface for circular reference detection utility
+ *
+ * Provides methods to track visited objects during recursive traversal,
+ * enabling detection and handling of circular references in object graphs.
+ *
+ * @remarks
+ * Uses a WeakSet internally for memory-efficient object tracking. Suitable for
+ * single-threaded traversal; not thread-safe for concurrent use.
+ */
+export interface ICircularReferenceDetector {
+    /**
+     * Marks an object as visited
+     * @param obj - Object to mark as visited
+     */
+    markVisited(obj: object): void;
+    /**
+     * Checks if an object has been visited (circular reference indicator)
+     * @param obj - Object to check
+     * @returns True if object was already marked as visited
+     */
+    isVisited(obj: object): boolean;
+    /**
+     * Clears all visited object entries, resetting the detector
+     */
+    clear(): void;
+}
+/**
+ * Creates a circular reference detection utility using WeakSet
+ *
+ * Provides an efficient way to track visited objects during recursive traversal
+ * of object graphs, enabling detection and handling of circular references.
+ * The internal WeakSet allows garbage collection of visited objects when they
+ * are no longer referenced elsewhere.
+ *
+ * @returns An {@link ICircularReferenceDetector} instance with methods to track visited objects
+ *
+ * @example
+ * ```typescript
+ * // Create detector once and reuse across multiple calls:
+ * const detector = CreateCircularReferenceDetector();
+ *
+ * function traverse(obj: unknown): void {
+ *   if (typeof obj !== 'object' || obj === null) return;
+ *
+ *   if (detector.isVisited(obj)) {
+ *     console.log('Circular reference detected!');
+ *     return;
+ *   }
+ *
+ *   detector.markVisited(obj);
+ *   // Process obj...
+ * }
+ *
+ * for (const obj of objects) {
+ *   detector.clear(); // Reset between unrelated traversals
+ *   traverse(obj);
+ * }
+ * ```
+ *
+ * @remarks
+ * Do NOT create a new detector inside a loop for each object. Create once and reuse,
+ * calling `clear()` between unrelated traversals. Each call to this function creates
+ * a new WeakSet instance, so reusing is more efficient.
+ */
+export declare function CreateCircularReferenceDetector(): ICircularReferenceDetector;
+/**
+ * Validates input for common security issues
+ *
+ * Checks for:
+ * - String length exceeding `maxLength` (default: 10,000 chars) to prevent DoS
+ * - Path traversal patterns: `..`, encoded variants, null bytes, unicode attacks
+ * - Null/undefined are considered safe (falsy validation only)
+ *
+ * Designed primarily for property path validation in `ObjectSetPropertyByPath` and
+ * related functions. Not a general-purpose string validator.
+ *
+ * @param input - Input to validate (typically a property path or key string)
+ * @param maxLength - Maximum allowed string length in characters (default: 10,000)
+ * @returns True if input is safe, false if it exceeds length or contains attack patterns
+ *
+ * @example
+ * ```typescript
+ * IsInputSafe('user.profile.name');     // true
+ * IsInputSafe('user..name');            // false (path traversal)
+ * IsInputSafe('a'.repeat(20000));       // false (exceeds default length)
+ * IsInputSafe(null);                    // true (null is safe)
+ * IsInputSafe('%2e%2e');                // false (encoded traversal)
+ * ```
+ */
+export declare function IsInputSafe(input: unknown, maxLength?: number): boolean;
+//# sourceMappingURL=security-utils.d.ts.map

package/dist/object/security-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-utils.d.ts","sourceRoot":"","sources":["../../src/object/security-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA+CH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAkBtD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkBxD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAUzF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAEhC;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,+BAA+B,IAAI,0BAA0B,CA6B5E;AAKD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,MAAiC,GAAG,OAAO,CAqBjG"}