@pawells/typescript-common 2.1.5 → 2.1.6

package/README.md

@@ -1,6 +1,6 @@
 # @pawells/typescript-common
 
-[![CI](https://github.com/PhillipAWells/typescript-common/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/typescript-common/actions/workflows/ci.yml)
+[![CI](https://github.com/PhillipAWells/common/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/common/actions/workflows/ci.yml)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
 [![npm version](https://img.shields.io/npm/v/@pawells/typescript-common.svg)](https://www.npmjs.com/package/@pawells/typescript-common)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
@@ -409,6 +409,27 @@ console.log(stopwatch.elapsed().toString()); // Duration of work
 | `Stopwatch` | Utility for recording timestamped events and intervals |
 | `StopwatchEntry` | Represents single stopwatch event (start, stop, lap, etc.) |
 
+### Iterators
+
+| Symbol | Description |
+|--------|-------------|
+| `FilteredIterator` | Async generator that filters array elements based on a predicate and optional filter criteria |
+
+### Zod Utilities
+
+Pre-built Zod schemas and types for common runtime validation scenarios.
+
+| Symbol | Description |
+|--------|-------------|
+| `OBJECT_ID_SCHEMA` | Zod schema for MongoDB ObjectId validation (24-char hex string) |
+| `TObjectId` | Type inferred from OBJECT_ID_SCHEMA; represents valid ObjectId string |
+| `SEMVER_SCHEMA` | Zod schema for semantic version validation; transforms to SemVer instance |
+| `TZodObjectSchema` | Type for Zod object schema instances; result of z.object() |
+| `JSON_SERIALIZABLE_SCHEMA` | Zod schema for generic JSON-serializable values (primitives, arrays, objects) |
+| `TJSONSerializable` | Recursive type for JSON-serializable values (excludes undefined and functions) |
+| `JSON_OBJECT_SCHEMA` | Zod schema for JSON objects with string keys and serializable values |
+| `JSON_DATE_SCHEMA` | Zod schema for date strings; transforms to Date instances |
+
 ## License
 
 MIT — See [LICENSE](../../LICENSE) for details.

package/dist/array/index.d.ts

@@ -25,4 +25,5 @@ export * from './array-sample.js';
 export type * from './array-element.js';
 export type { TPredicate, TTransform, TComparator, TEqualityComparator } from './types.js';
 export * from './assert.js';
+export * from './iterators.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,mBAAmB,oBAAoB,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC3F,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,mBAAmB,oBAAoB,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC3F,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC"}

package/dist/array/index.js

@@ -23,3 +23,4 @@ export * from './array-sort-by.js';
 export * from './array-count-by.js';
 export * from './array-sample.js';
 export * from './assert.js';
+export * from './iterators.js';

package/dist/array/iterators.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Async generator function that filters array elements based on a predicate and optional filter criteria.
+ *
+ * Yields only elements that pass both the optional validator function and the filter criteria object.
+ * This is useful for streaming large datasets through memory-efficient async iteration.
+ *
+ * @template TObject The type of elements in the iterator
+ * @template TArgs The type of filter criteria object (extends Record<string, unknown>)
+ *
+ * @param iterator The async iterable to filter
+ * @param args Optional filter criteria object; if provided, only elements matching all criteria are yielded
+ * @param validator Optional predicate function returning true for elements to keep; called before filter criteria
+ *
+ * @returns {AsyncGenerator<TObject, void, unknown>} Async generator that yields filtered elements
+ *
+ * @remarks
+ * Elements are evaluated one at a time without batching. The validator is applied first; if it rejects
+ * an element, the filter criteria are not evaluated. If no args are provided, all elements (passing the
+ * validator if present) are passed through unchanged.
+ *
+ * @example
+ * async function* items() {
+ *   yield { id: 1, status: 'active' };
+ *   yield { id: 2, status: 'inactive' };
+ *   yield { id: 3, status: 'active' };
+ * }
+ *
+ * for await (const item of FilteredIterator(items(), { status: 'active' })) {
+ *   console.log(item); // Only logs items with status: 'active'
+ * }
+ *
+ * @example
+ * for await (const item of FilteredIterator(items(), undefined, (obj) => obj.id > 1)) {
+ *   console.log(item); // Only logs items with id > 1
+ * }
+ *
+ * @throws {TypeError} if iterator is null or undefined
+ */
+export declare function FilteredIterator<TObject, TArgs extends Record<string, unknown>>(iterator: AsyncIterable<TObject>, args?: TArgs, validator?: (obj: TObject) => boolean): AsyncGenerator<TObject, void, unknown>;
+//# sourceMappingURL=iterators.d.ts.map

package/dist/array/iterators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterators.d.ts","sourceRoot":"","sources":["../../src/array/iterators.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAuB,gBAAgB,CAAC,OAAO,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAcrN"}

package/dist/array/iterators.js

@@ -0,0 +1,54 @@
+import { ObjectFilter } from '../object/filter.js';
+/**
+ * Async generator function that filters array elements based on a predicate and optional filter criteria.
+ *
+ * Yields only elements that pass both the optional validator function and the filter criteria object.
+ * This is useful for streaming large datasets through memory-efficient async iteration.
+ *
+ * @template TObject The type of elements in the iterator
+ * @template TArgs The type of filter criteria object (extends Record<string, unknown>)
+ *
+ * @param iterator The async iterable to filter
+ * @param args Optional filter criteria object; if provided, only elements matching all criteria are yielded
+ * @param validator Optional predicate function returning true for elements to keep; called before filter criteria
+ *
+ * @returns {AsyncGenerator<TObject, void, unknown>} Async generator that yields filtered elements
+ *
+ * @remarks
+ * Elements are evaluated one at a time without batching. The validator is applied first; if it rejects
+ * an element, the filter criteria are not evaluated. If no args are provided, all elements (passing the
+ * validator if present) are passed through unchanged.
+ *
+ * @example
+ * async function* items() {
+ *   yield { id: 1, status: 'active' };
+ *   yield { id: 2, status: 'inactive' };
+ *   yield { id: 3, status: 'active' };
+ * }
+ *
+ * for await (const item of FilteredIterator(items(), { status: 'active' })) {
+ *   console.log(item); // Only logs items with status: 'active'
+ * }
+ *
+ * @example
+ * for await (const item of FilteredIterator(items(), undefined, (obj) => obj.id > 1)) {
+ *   console.log(item); // Only logs items with id > 1
+ * }
+ *
+ * @throws {TypeError} if iterator is null or undefined
+ */
+export async function* FilteredIterator(iterator, args, validator) {
+    for await (const obj of iterator) {
+        // Validate entity before filtering/yielding
+        if (validator && !validator(obj))
+            continue;
+        // If no filter args provided, pass through all events
+        if (!args || typeof args !== 'object' || Object.keys(args).length === 0) {
+            yield obj;
+            continue;
+        }
+        // Apply filter criteria
+        if (ObjectFilter(obj, args))
+            yield obj;
+    }
+}

package/dist/asserts/generic.d.ts

@@ -9,7 +9,7 @@ import { SimpleError } from './errors.js';
  * - Handling non-serializable values gracefully
  *
  * @param value - The value to serialize for display
- * @param maxLength - Maximum characters to display for primitives (default: 50, capped at 10,000)
+ * @param maxLength - Maximum characters to display for primitives (default: 100, capped at 10,000)
  * @returns A safe string representation (at most maxLength chars plus "[truncated]" suffix)
  *
  * @example

package/dist/asserts/generic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generic.d.ts","sourceRoot":"","sources":["../../src/asserts/generic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generic.d.ts","sourceRoot":"","sources":["../../src/asserts/generic.ts"],"names":[],"mappings":"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"}

package/dist/asserts/generic.js

@@ -1,6 +1,11 @@
 import { ObjectEquals } from './internal-utils.js';
 import { SetExceptionClass, SetExceptionMessage, ThrowException } from './utils.js';
 import { AssertionError, SimpleError } from './errors.js';
+/**
+ * Maximum length for safe value display in assertion error messages.
+ * Prevents verbose output and potential information disclosure.
+ */
+const MAX_SAFE_DISPLAY_LENGTH = 100;
 /**
  * Serializes a value to a human-readable string, safe for any value type.
  *
@@ -10,7 +15,7 @@ import { AssertionError, SimpleError } from './errors.js';
  * - Handling non-serializable values gracefully
  *
  * @param value - The value to serialize for display
- * @param maxLength - Maximum characters to display for primitives (default: 50, capped at 10,000)
+ * @param maxLength - Maximum characters to display for primitives (default: 100, capped at 10,000)
  * @returns A safe string representation (at most maxLength chars plus "[truncated]" suffix)
  *
  * @example
@@ -20,7 +25,7 @@ import { AssertionError, SimpleError } from './errors.js';
  *
  * @internal Used internally by assertion functions to safely display values in error messages
  */
-export function safeDisplay(value, maxLength = 50) {
+export function safeDisplay(value, maxLength = MAX_SAFE_DISPLAY_LENGTH) {
     // Cap maxLength to prevent memory exhaustion from extremely large values
     const effectiveMaxLength = Math.min(maxLength, 10_000);
     // For objects, use type name instead of full serialization to avoid leaking structure
@@ -203,6 +208,7 @@ export class ExtendsError extends SimpleError {
  * });                                               // ✗ Throws with custom message
  * ```
  */
+// @internal — Do not import from this module directly. Use asserts/index.ts instead.
 export function AssertEquals(value, expected, exception = {}) {
     SetExceptionClass(exception, AssertionError);
     if (!ObjectEquals(value, expected)) {

package/dist/asserts/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/asserts/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAKhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,oBAAoB,EAAE,KAAK,UAAQ,GAAG,IAAI,CAGpH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,IAAI,CAGrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,EAClE,SAAS,EAAE,gBAAgB,GACzB,OAAO,CAAC,KAAK,CAuCf"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/asserts/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAIhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,oBAAoB,EAAE,KAAK,UAAQ,GAAG,IAAI,CAGpH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,IAAI,CAGrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,EAClE,SAAS,EAAE,gBAAgB,GACzB,OAAO,CAAC,KAAK,CAuCf"}

package/dist/asserts/utils.js

@@ -29,9 +29,8 @@ import { safeDisplay, GetValueType } from './generic.js';
  * ```
  */
 export function ThrowException(exception) {
-    if (!exception.class) {
-        throw new Error(exception.message ?? 'An assertion error occurred');
-    }
+    // exception.class is always set by SetExceptionClass before this is called
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     throw new exception.class(exception.message ?? 'An assertion error occurred');
 }
 /**

package/dist/enum/index.d.ts

@@ -7,11 +7,11 @@
  *
  * @module enum
  */
-export * from './types.js';
 export * from './enum-keys.js';
 export * from './enum-values.js';
 export * from './enum-entries.js';
 export * from './validate-enum-value.js';
 export * from './enum-key-by-value.js';
 export * from './enum-safe-value.js';
+export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/enum/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/enum/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC"}

package/dist/enum/index.js

@@ -7,10 +7,10 @@
  *
  * @module enum
  */
-export * from './types.js';
 export * from './enum-keys.js';
 export * from './enum-values.js';
 export * from './enum-entries.js';
 export * from './validate-enum-value.js';
 export * from './enum-key-by-value.js';
 export * from './enum-safe-value.js';
+export * from './types.js';

package/dist/function/memoize.d.ts

@@ -39,5 +39,18 @@
  * console.log(cachedAdd(1, 2)); // Returns cached result: 3
  * ```
  */
+/**
+ * Memoizes a function using an LRU cache.
+ *
+ * @remarks
+ * - Default key function uses JSON.stringify(args)
+ * - Non-serializable arguments (functions, symbols, circular refs) will produce incorrect cache behavior
+ * - Supply a custom `keyFn` for non-serializable arguments or for content-addressed keys
+ *
+ * @param fn - The function to memoize
+ * @param keyFn - Optional custom cache key function; defaults to JSON.stringify(args)
+ * @param maxCacheSize - Maximum number of entries in the cache; defaults to 1000
+ * @returns Memoized version of the function
+ */
 export declare function Memoize<T extends (...args: any[]) => any>(fn: T, keyFn?: (...args: Parameters<T>) => string, maxCacheSize?: number): T;
 //# sourceMappingURL=memoize.d.ts.map

package/dist/function/memoize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../src/function/memoize.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxD,EAAE,EAAE,CAAC,EACL,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,EAC1C,YAAY,SAAO,GACjB,CAAC,CAkBH"}
+{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../src/function/memoize.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;;;;;;;;;;;;GAYG;AAEH,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxD,EAAE,EAAE,CAAC,EACL,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,EAC1C,YAAY,SAAO,GACjB,CAAC,CAkBH"}

package/dist/function/memoize.js

@@ -40,6 +40,19 @@ import { LRUCache } from '../lru-cache.js';
  * console.log(cachedAdd(1, 2)); // Returns cached result: 3
  * ```
  */
+/**
+ * Memoizes a function using an LRU cache.
+ *
+ * @remarks
+ * - Default key function uses JSON.stringify(args)
+ * - Non-serializable arguments (functions, symbols, circular refs) will produce incorrect cache behavior
+ * - Supply a custom `keyFn` for non-serializable arguments or for content-addressed keys
+ *
+ * @param fn - The function to memoize
+ * @param keyFn - Optional custom cache key function; defaults to JSON.stringify(args)
+ * @param maxCacheSize - Maximum number of entries in the cache; defaults to 1000
+ * @returns Memoized version of the function
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function Memoize(fn, keyFn, maxCacheSize = 1000) {
     const cache = new LRUCache(maxCacheSize);

package/dist/index.d.ts

@@ -8,4 +8,7 @@ export * from './number/index.js';
 export * from './object/index.js';
 export * from './string/index.js';
 export * from './time/index.js';
+export * from './array/iterators.js';
+export * from './json.sanitization.js';
+export * from './zod-util.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -8,3 +8,6 @@ export * from './number/index.js';
 export * from './object/index.js';
 export * from './string/index.js';
 export * from './time/index.js';
+export * from './array/iterators.js';
+export * from './json.sanitization.js';
+export * from './zod-util.js';

package/dist/json.sanitization.d.ts

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

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

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

package/dist/json.sanitization.js

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

package/dist/object/clone.d.ts

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

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

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

package/dist/object/clone.js

@@ -21,6 +21,12 @@ import { FilterDangerousKeys } from './security-utils.js';
  * clone.b.c = 99;
  * console.log(original.b.c); // 2  (original is not affected)
  * ```
+ * @example
+ * ```typescript
+ * const nullProtoObj = Object.create(null);
+ * nullProtoObj.x = 1;
+ * const cloned = ObjectClone(nullProtoObj); // Works correctly even for null-prototype objects
+ * ```
  */
 export function ObjectClone(obj, visitedInput) {
     if (obj === null || obj === undefined) {
@@ -56,7 +62,7 @@ export function ObjectClone(obj, visitedInput) {
         return result;
     }
     // Handle plain objects only
-    if (obj.constructor === Object || Object.getPrototypeOf(obj) === null) {
+    if (Object.getPrototypeOf(obj) === null || obj.constructor === Object) {
         // Security: Filter out dangerous keys
         const safeObj = FilterDangerousKeys(obj);
         const copy = {};

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

@@ -1,22 +1,4 @@
 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.

package/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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,2BAA2B,CAAC,CAAC,CAAC,CAmI7H"}
+{"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/dist/object/filter-cached.js

@@ -3,24 +3,6 @@ import { ObjectHash } from './hash.js';
 // Cache configuration constants
 const DEFAULT_MAX_CACHE_SIZE = 1000;
 const CACHE_EVICTION_PERCENTAGE = 0.2; // 20%
-/**
- * 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.

package/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;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"}
+{"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/dist/object/filter.js

@@ -2,6 +2,15 @@ import { ObjectEquals } from './equals.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)

package/dist/object/hash.js

@@ -69,9 +69,9 @@ export function ObjectHash(obj, hashFunction) {
     }
     catch (e) {
         if (e instanceof TypeError && e.message.includes('circular')) {
-            throw new Error('Cannot hash object with circular references');
+            throw new Error('Cannot hash object with circular references', { cause: e });
         }
-        throw new Error('Cannot hash object: JSON.stringify failed');
+        throw new Error('Cannot hash object: JSON.stringify failed', { cause: e });
     }
     // Handle cases where JSON.stringify returns undefined
     if (jsonString === undefined) {

package/dist/object/index.d.ts

@@ -29,6 +29,6 @@ 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 { 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/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,0BAA0B,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7O,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}
+{"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/dist/object/object-flatten.js

@@ -21,6 +21,10 @@
 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)) {

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

package/dist/object/property-paths.js

@@ -95,6 +95,8 @@ export function ObjectGetPropertyByPath(obj, path, defaultValue) {
  * @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/dist/object/security-utils.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"security-utils.d.ts","sourceRoot":"","sources":["../../src/object/security-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsDH;;;;;;;;;;;;;;;;;;;;;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"}