@sohanemon/utils 5.2.5 → 5.2.6

package/dist/functions/hydrate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Deeply cleans any value by converting all `null` values to `undefined`,
+ * and merges in a fallback object for default values.
+ *
+ * Features:
+ * - Circular reference detection to prevent infinite loops
+ * - Proper handling of special objects (Date, Map, Set, RegExp, etc.)
+ * - Strict type safety with improved generics
+ * - Better error messages and validation
+ * - Support for nested structures with Symbol properties
+ * - Optional maximum recursion depth to prevent stack overflow
+ * - Configurable null-to-undefined conversion
+ *
+ * @param data - Any input data (object, array, primitive)
+ * @param fallback - Optional fallback values to merge with
+ * @param options - Configuration options
+ * @param options.maxDepth - Maximum recursion depth (default: 100)
+ * @param options.throwOnCircular - Whether to throw on circular refs (default: false)
+ * @param options.convertNullToUndefined - Convert null to undefined (default: true)
+ * @returns Same type as input, but with all nulls replaced by undefined
+ *
+ * @throws {TypeError} If data or fallback are invalid types when strict validation is enabled
+ * @throws {RangeError} If circular reference detected and throwOnCircular is true
+ *
+ * @example
+ * // Basic usage
+ * hydrate({ a: null, b: 'test' }) // { a: undefined, b: 'test' }
+ *
+ * @example
+ * // With fallback values
+ * hydrate({ a: null }, { a: 'default' }) // { a: 'default' }
+ *
+ * @example
+ * // Keep nulls as-is
+ * hydrate({ a: null }, undefined, { convertNullToUndefined: false }) // { a: null }
+ */
+export declare function hydrate<T>(data: T, fallback?: Partial<T>, options?: {
+    maxDepth?: number;
+    throwOnCircular?: boolean;
+    convertNullToUndefined?: boolean;
+}): T;
+/**
+ * Type guard utility for checking if a value is an object with a specific shape
+ */
+export declare function isWithFallbackCompatible<T extends object>(value: unknown): value is T;

package/dist/functions/hydrate.js

@@ -0,0 +1,155 @@
+/**
+ * Deeply cleans any value by converting all `null` values to `undefined`,
+ * and merges in a fallback object for default values.
+ *
+ * Features:
+ * - Circular reference detection to prevent infinite loops
+ * - Proper handling of special objects (Date, Map, Set, RegExp, etc.)
+ * - Strict type safety with improved generics
+ * - Better error messages and validation
+ * - Support for nested structures with Symbol properties
+ * - Optional maximum recursion depth to prevent stack overflow
+ * - Configurable null-to-undefined conversion
+ *
+ * @param data - Any input data (object, array, primitive)
+ * @param fallback - Optional fallback values to merge with
+ * @param options - Configuration options
+ * @param options.maxDepth - Maximum recursion depth (default: 100)
+ * @param options.throwOnCircular - Whether to throw on circular refs (default: false)
+ * @param options.convertNullToUndefined - Convert null to undefined (default: true)
+ * @returns Same type as input, but with all nulls replaced by undefined
+ *
+ * @throws {TypeError} If data or fallback are invalid types when strict validation is enabled
+ * @throws {RangeError} If circular reference detected and throwOnCircular is true
+ *
+ * @example
+ * // Basic usage
+ * hydrate({ a: null, b: 'test' }) // { a: undefined, b: 'test' }
+ *
+ * @example
+ * // With fallback values
+ * hydrate({ a: null }, { a: 'default' }) // { a: 'default' }
+ *
+ * @example
+ * // Keep nulls as-is
+ * hydrate({ a: null }, undefined, { convertNullToUndefined: false }) // { a: null }
+ */
+export function hydrate(data, fallback, options) {
+    const maxDepth = options?.maxDepth ?? 100;
+    const throwOnCircular = options?.throwOnCircular ?? false;
+    const convertNullToUndefined = options?.convertNullToUndefined ?? true;
+    // Use WeakSet for O(1) circular reference detection
+    const visited = new WeakSet();
+    return processValue(data, fallback, 0, visited);
+    function processValue(value, fallbackValue, depth, visited) {
+        // Check recursion depth
+        if (depth > maxDepth) {
+            console.warn(`[hydrate] Maximum recursion depth (${maxDepth}) exceeded. Returning value as-is.`);
+            return value ?? fallbackValue;
+        }
+        if (value === null) {
+            return convertNullToUndefined ? undefined : (fallbackValue ?? null);
+        }
+        // Handle undefined - use fallback or return undefined
+        if (value === undefined) {
+            return fallbackValue ?? undefined;
+        }
+        // Handle primitives: string, number, boolean, symbol, bigint
+        const type = typeof value;
+        if (type !== 'object') {
+            return value;
+        }
+        if (visited.has(value)) {
+            if (throwOnCircular) {
+                throw new RangeError('[hydrate] Circular reference detected');
+            }
+            // Return the value as-is to break the cycle
+            return value;
+        }
+        // Mark as visited to detect circular references
+        visited.add(value);
+        if (isSpecialObject(value)) {
+            return handleSpecialObject(value, fallbackValue);
+        }
+        // Handle arrays
+        if (Array.isArray(value)) {
+            const fallbackArray = Array.isArray(fallbackValue)
+                ? fallbackValue
+                : undefined;
+            return value.map((item, index) => processValue(item, fallbackArray?.[index], depth + 1, visited));
+        }
+        // Handle plain objects
+        if (isPlainObject(value)) {
+            const fallbackObj = isPlainObject(fallbackValue)
+                ? fallbackValue
+                : {};
+            const result = { ...fallbackObj };
+            // Process all enumerable properties including symbols
+            const keys = [
+                ...Object.keys(value),
+                ...Object.getOwnPropertySymbols(value),
+            ];
+            for (const k of keys) {
+                const propValue = value[k];
+                const fallbackProp = fallbackObj[k];
+                result[k] = processValue(propValue, fallbackProp, depth + 1, visited);
+            }
+            return result;
+        }
+        // For other objects, return as-is (instances, etc.)
+        return value ?? fallbackValue;
+    }
+}
+/**
+ * Checks if a value is a plain object (not a special type)
+ */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (Object.prototype.toString.call(value) !== '[object Object]') {
+        return false;
+    }
+    // Objects with null prototype are still plain objects
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+/**
+ * Checks if a value is a special object type that needs custom handling
+ */
+function isSpecialObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const stringTag = Object.prototype.toString.call(value);
+    const specialTypes = [
+        '[object Date]',
+        '[object RegExp]',
+        '[object Map]',
+        '[object Set]',
+        '[object WeakMap]',
+        '[object WeakSet]',
+        '[object Promise]',
+        '[object Error]',
+        '[object ArrayBuffer]',
+    ];
+    return specialTypes.includes(stringTag);
+}
+/**
+ * Handles special object types that shouldn't be deeply cloned
+ */
+function handleSpecialObject(value, fallbackValue) {
+    // For special types, return the original value or fallback
+    // These shouldn't be deeply cloned as they have internal state
+    return value ?? fallbackValue;
+}
+/**
+ * Type guard utility for checking if a value is an object with a specific shape
+ */
+export function isWithFallbackCompatible(value) {
+    return (typeof value === 'object' &&
+        (value === null ||
+            Array.isArray(value) ||
+            (typeof value === 'object' &&
+                Object.prototype.toString.call(value) === '[object Object]')));
+}

package/dist/functions/index.d.ts

@@ -1,4 +1,5 @@
 export * from './cookie';
+export * from './hydrate';
 export * from './object';
 export * from './poll';
 export * from './schedule';

package/dist/functions/index.js

@@ -1,4 +1,5 @@
 export * from './cookie';
+export * from './hydrate';
 export * from './object';
 export * from './poll';
 export * from './schedule';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohanemon/utils",
-  "version": "5.2.5",
+  "version": "5.2.6",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",