@pawells/typescript-common 1.4.1 → 2.1.5

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

package/dist/object/security-utils.js

@@ -0,0 +1,297 @@
+/**
+ * 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
+ */
+/**
+ * List of dangerous property names that should be blocked to prevent prototype pollution.
+ * Only the three canonical prototype-pollution vectors are blocked; other Object.prototype
+ * methods (toString, valueOf, hasOwnProperty, etc.) are legitimate property names.
+ */
+const /**
+ * Property names that are commonly used in prototype pollution attacks.
+ *
+ * This list blocks direct assignment to the most common attack vectors
+ * (__proto__, constructor, prototype) but is not a complete sandbox.
+ * It prevents the most obvious exploitation paths and should be combined
+ * with other security measures such as object freezing and deep cloning
+ * for sensitive data structures.
+ */ DANGEROUS_PROPERTY_NAMES = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+/**
+ * Regular expression patterns for detecting path traversal attempts.
+ *
+ * Includes:
+ * - URL-encoded dots (both single and double encoding)
+ * - Null byte injection (both as \0 literal and %00 URL-encoded)
+ * - Unicode BOM and invalid character sequences
+ *
+ * NOTE: Null byte detection is informational and defensive-in-depth.
+ * JavaScript strings handle null bytes safely by design — they do not
+ * truncate at null bytes like C strings do. This pattern is included
+ * to flag suspicious input that may have been crafted for other contexts.
+ *
+ * PERFORMANCE NOTE: All patterns avoid nested quantifiers that could cause
+ * ReDoS (Regular Expression Denial of Service). Each pattern is simple and
+ * anchored to prevent catastrophic backtracking.
+ */
+const PATH_TRAVERSAL_PATTERNS = [
+    /%2e%2e/i, // URL encoded ..
+    /%252e%252e/i, // Double URL encoded ..
+    new RegExp(String.fromCharCode(0)), // Null byte injection
+    /%00/i, // URL encoded null byte
+    new RegExp('[\\u200b\\ufeff\\ufffe\\uffff]'), // Unicode BOM, reversed BOM, and invalid characters
+];
+/**
+ * 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 function IsPropertyKeySafe(key) {
+    if (typeof key !== 'string') {
+        return false;
+    }
+    // Check against dangerous property names
+    if (DANGEROUS_PROPERTY_NAMES.has(key)) {
+        return false;
+    }
+    // Check for path traversal patterns
+    for (const pattern of PATH_TRAVERSAL_PATTERNS) {
+        if (pattern.test(key)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 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 function IsPropertyPathSafe(path) {
+    if (!path || typeof path !== 'string') {
+        return false;
+    }
+    // Check if path starts or ends with a dot
+    if (path.startsWith('.') || path.endsWith('.')) {
+        return false;
+    }
+    // Check for consecutive dots (potential traversal)
+    if (path.includes('..')) {
+        return false;
+    }
+    // Validate each segment of the path
+    const segments = path.split('.');
+    return segments.every((segment) => IsPropertyKeySafe(segment));
+}
+/**
+ * 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 function SanitizePropertyKey(key) {
+    if (!IsPropertyKeySafe(key)) {
+        return null;
+    }
+    // Additional sanitization for edge cases
+    return key.trim();
+}
+/**
+ * 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 function FilterDangerousKeys(obj) {
+    const filtered = {};
+    for (const key in obj) {
+        if (Object.hasOwn(obj, key) && IsPropertyKeySafe(key)) {
+            filtered[key] = obj[key];
+        }
+    }
+    return filtered;
+}
+/**
+ * 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 function CreateCircularReferenceDetector() {
+    let visited = new WeakSet();
+    return {
+        /**
+         * Marks an object as visited
+         * @param obj - Object to mark as visited
+         */
+        markVisited(obj) {
+            visited.add(obj);
+        },
+        /**
+         * Checks if an object has been visited (circular reference)
+         * @param obj - Object to check
+         * @returns True if object was already visited
+         */
+        isVisited(obj) {
+            return visited.has(obj);
+        },
+        /**
+         * Clears the visited objects set
+         */
+        clear() {
+            // WeakSet doesn't have a clear method, so we create a new one
+            visited = new WeakSet();
+        },
+    };
+}
+/** Default maximum input length for security validation */
+const DEFAULT_MAX_INPUT_LENGTH = 10000;
+/**
+ * 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 function IsInputSafe(input, maxLength = DEFAULT_MAX_INPUT_LENGTH) {
+    // Check for null/undefined
+    if (input === null || input === undefined) {
+        return true;
+    }
+    // Check string length to prevent DoS
+    if (typeof input === 'string' && input.length > maxLength) {
+        return false;
+    }
+    // Check for dangerous string patterns
+    if (typeof input === 'string') {
+        for (const pattern of PATH_TRAVERSAL_PATTERNS) {
+            if (pattern.test(input)) {
+                return false;
+            }
+        }
+    }
+    return true;
+}

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

@@ -22,5 +22,5 @@
  * // Result: { active: true, age: 30, email: 'john@example.com', name: 'John' }
  * ```
  */
-export declare function ObjectSortKeys<T extends Record<string, any>>(object: T): T;
+export declare function ObjectSortKeys<T extends Record<string, unknown>>(object: T): T;
 //# sourceMappingURL=sort-keys.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sort-keys.d.ts","sourceRoot":"","sources":["../../src/object/sort-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CA+B1E"}
+{"version":3,"file":"sort-keys.d.ts","sourceRoot":"","sources":["../../src/object/sort-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAuC9E"}

package/{build → dist}/object/sort-keys.js

@@ -26,7 +26,21 @@ export function ObjectSortKeys(object) {
     if (!object || typeof object !== 'object' || Array.isArray(object)) {
         return object;
     }
-    const sorted = Object.keys(object).sort((a, b) => {
+    // Single-pass collection: get all property names and classify them by enumerability
+    const allKeys = Object.getOwnPropertyNames(object);
+    const enumerableKeys = [];
+    const nonEnumerableDescriptors = [];
+    for (const key of allKeys) {
+        const descriptor = Object.getOwnPropertyDescriptor(object, key);
+        if (descriptor?.enumerable) {
+            enumerableKeys.push(key);
+        }
+        else if (descriptor) {
+            nonEnumerableDescriptors.push([key, descriptor]);
+        }
+    }
+    // Sort enumerable keys and build result with them
+    const sorted = enumerableKeys.sort((a, b) => {
         if (a < b)
             return -1;
         if (a > b)
@@ -37,16 +51,9 @@ export function ObjectSortKeys(object) {
         entry[key] = object[key];
         return entry;
     }, {});
-    // Preserve non-enumerable properties
-    const allKeys = Object.getOwnPropertyNames(object);
-    for (const key of allKeys) {
-        if (!Object.hasOwn(sorted, key)) {
-            const descriptor = Object.getOwnPropertyDescriptor(object, key);
-            if (descriptor) {
-                Object.defineProperty(sorted, key, descriptor);
-            }
-        }
+    // Restore non-enumerable properties with their original descriptors
+    for (const [key, descriptor] of nonEnumerableDescriptors) {
+        Object.defineProperty(sorted, key, descriptor);
     }
     return sorted;
 }
-//# sourceMappingURL=sort-keys.js.map

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

@@ -1,60 +1,101 @@
-/**
- * A constructor function type for creating objects of type O.
- * @template O The object type to construct.
- */
-export type TConstructableObject<O extends object = object> = new (...args: any[]) => O;
 /**
  * Omits properties from B that are not in A.
- * @template A Base type.
- * @template B Type to filter.
+ *
+ * @template A - Base type.
+ * @template B - Type to filter.
+ *
+ * @remarks
+ * Currently exported but not used by public API functions. Reserved for future use
+ * as an extension point for constrained object transformations or validation scenarios.
  */
 export type TObjectOmitExtraProperties<A, B> = {
     [K in keyof B]: K extends A ? B[K] : never;
 };
 /**
  * Extracts the property keys of an object type.
- * @template O The object type.
+ *
+ * @template O - The object type.
+ *
+ * @remarks
+ * Currently exported but not used by public API functions. Reserved for future use
+ * as a generic property introspection utility or type constraint.
  */
 export type TObjectProperties<O extends object> = keyof O;
 /**
  * Extracts property keys of a specific type from an object.
- * @template O Object type.
- * @template PropertyType The type to match.
+ *
+ * @template O - Object type.
+ * @template PropertyType - The type to match.
+ *
+ * @remarks
+ * Currently exported but not used by public API functions. Reserved for future use
+ * in type-filtered property transformations or validations (e.g., filtering all
+ * string properties, all optional properties, or all array properties).
  */
 export type TObjectPropertiesOfType<O extends object, PropertyType> = keyof {
-    [K in keyof O as O[K] extends PropertyType ? K : never]: any;
+    [K in keyof O as O[K] extends PropertyType ? K : never]: unknown;
 };
 /**
  * Omits properties of a specific type from an object.
- * @template O Object type.
- * @template PropertyType The type to omit.
+ *
+ * @template O - Object type.
+ * @template PropertyType - The type to omit.
+ *
+ * @remarks
+ * Currently exported but not used by public API functions. Reserved for future use
+ * in scenarios requiring conditional property exclusion based on value type
+ * (e.g., extracting only non-array properties, or excluding optional properties).
  */
 export type TObjectOmitPropertiesOfType<O extends object, PropertyType> = {
     [K in keyof O as O[K] extends PropertyType ? never : K]: O[K];
 };
 /**
  * Represents the union of all property values in an object.
- * @template T Object type.
+ *
+ * @template T - Object type.
+ *
+ * @remarks
+ * Currently exported but not used by public API functions. Reserved for future use
+ * in generic object value introspection or validation scenarios.
  */
 export type TObjectPropertyType<T extends object> = T[keyof T];
 /**
  * Extracts properties shared between two object types.
- * @template A First object type.
- * @template B Second object type.
+ *
+ * @template A - First object type.
+ * @template B - Second object type.
+ *
+ * @remarks
+ * Currently exported but not used by public API functions. Reserved for future use
+ * in scenarios requiring intersection of object types or common property extraction
+ * for schema validation or type merging operations.
  */
 export type TObjectSharedProperties<A extends object, B extends object> = {
     [K in keyof A & keyof B]: K extends keyof A ? A[K] : never;
 };
 /**
  * Extracts keys of array properties from an object type.
- * @template T Object type.
+ *
+ * @template T - Object type.
+ *
+ * @remarks
+ * Currently exported but not used by public API functions. Reserved for future use
+ * in scenarios requiring filtering of array-typed properties, such as validating
+ * array field schemas or transforming only array properties in an object.
  */
 export type TObjectArrayProperties<T extends object> = {
-    [K in keyof T]: T[K] extends Array<any> ? K : never;
+    [K in keyof T]: T[K] extends Array<unknown> ? K : never;
 }[keyof T];
 /**
  * Generates nested dot-notation keys for an object type.
- * @template ObjectType The object type.
+ *
+ * @template ObjectType - The object type to generate keys for.
+ *
+ * @remarks
+ * Currently exported but not used by public API functions. Reserved for future use
+ * in scenarios requiring type-safe nested property access, such as advanced path
+ * navigation utilities or deep property validation frameworks that benefit from
+ * compile-time validation of dot-notation paths.
  */
 export type TObjectNestedKeyOf<ObjectType extends object> = {
     [Key in keyof ObjectType & (string | number)]: ObjectType[Key] extends object ? `${Key}` | `${Key}.${TObjectNestedKeyOf<ObjectType[Key]>}` : `${Key}`;
@@ -94,7 +135,7 @@ export interface ICachedObjectMapOptions {
  * Type for cached object filter functions.
  * @template T The object type being filtered.
  */
-export type TCachedObjectFilterFunction<T extends object> = (cursor: T, filter: Partial<Record<string, any>>) => Promise<boolean>;
+export type TCachedObjectFilterFunction<T extends object> = (cursor: T, filter: Partial<Record<string, unknown>>) => Promise<boolean>;
 /**
  * Type for cached object map functions.
  * @template T The object type being mapped.