@catbee/utils 0.0.8-rc.1 → 0.0.8-rc.3

package/build/esnext/utils/middleware.utils.js

@@ -1,236 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-import { uuid } from './id.utils';
-import { HttpStatusCodes } from './http-status-codes';
-import { createFinalErrorResponse, ErrorResponse } from './response.utils';
-import { getLogger } from './logger.utils';
-import { ContextStore, StoreKeys } from './context-store.utils';
-import { RequestTimeoutException } from './exception.utils';
-/**
- * Attaches a unique request ID to each request.
- * Useful for request tracing and correlation between logs.
- *
- * @param {object} [options] - Configuration options
- * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID
- * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response
- * @param {() => string} [options.generator] - Custom ID generator function
- * @returns {Middleware} Express-compatible middleware
- */
-export function requestId(options) {
-    const headerName = (options === null || options === void 0 ? void 0 : options.headerName) || 'X-Request-ID';
-    const exposeHeader = (options === null || options === void 0 ? void 0 : options.exposeHeader) !== false;
-    const generateId = (options === null || options === void 0 ? void 0 : options.generator) || uuid;
-    return (req, res, next) => {
-        // Use existing request ID from header or generate a new one
-        const existingId = req.headers[headerName.toLowerCase()];
-        const id = existingId || generateId();
-        // Attach ID to request object
-        req.id = id;
-        // Add ID to response headers
-        if (exposeHeader) {
-            res.setHeader(headerName, id);
-        }
-        next();
-    };
-}
-/**
- * Measures request processing time and logs or adds it to response headers.
- *
- * @param {object} [options] - Configuration options
- * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header
- * @param {boolean} [options.logOnComplete=false] - Whether to log timing info
- * @returns {Middleware} Express-compatible middleware
- */
-export function responseTime(options) {
-    const addHeader = (options === null || options === void 0 ? void 0 : options.addHeader) !== false;
-    const logOnComplete = (options === null || options === void 0 ? void 0 : options.logOnComplete) === true;
-    return (req, res, next) => {
-        const start = process.hrtime();
-        // Function to calculate duration
-        const getDuration = () => {
-            const diff = process.hrtime(start);
-            return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);
-        };
-        if (addHeader) {
-            // Ensure header is set before response is sent
-            const originalWriteHead = res.writeHead;
-            res.writeHead = function (...args) {
-                res.setHeader('X-Response-Time', `${getDuration()}ms`);
-                return originalWriteHead.apply(this, args);
-            };
-        }
-        if (logOnComplete) {
-            res.on('finish', () => {
-                getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);
-            });
-        }
-        next();
-    };
-}
-/**
- * Request timeout middleware.
- * Aborts requests that take too long to process.
- *
- * @param {number} [timeoutMs=30000] - Timeout in milliseconds
- * @returns {Middleware} Express-compatible middleware
- */
-export function timeout(timeoutMs = 30000) {
-    return (_req, res, next) => {
-        // Set timeout for the request
-        const timer = setTimeout(() => {
-            const response = new RequestTimeoutException('Request timed out');
-            res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);
-        }, timeoutMs);
-        // Clear timeout when response is sent
-        res.on('finish', () => {
-            clearTimeout(timer);
-        });
-        next();
-    };
-}
-/**
- * Creates an Express middleware that initializes a per-request context.
- *
- * @param {object} [options] - Optional configuration
- * @param {string} [options.headerName='x-request-id'] - Header to look for request ID
- * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized
- * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function
- */
-export function setupRequestContext(options = {}) {
-    const { headerName = 'x-request-id', autoLog = true } = options;
-    return (req, _res, next) => {
-        // Generate or use existing request ID
-        const requestId = req.headers[headerName] || (req === null || req === void 0 ? void 0 : req['id']) || uuid();
-        ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {
-            // Create a child logger for this request
-            const childLogger = getLogger().child({
-                requestId,
-                method: req.method,
-                url: req.originalUrl || req.url
-            });
-            req.logger = childLogger;
-            // Store logger in context
-            ContextStore.set(StoreKeys.LOGGER, childLogger);
-            if (autoLog) {
-                req.logger.info('Request context initialized');
-            }
-            next();
-        });
-    };
-}
-/**
- * Global error handling middleware with enhanced features.
- *
- * @param {ErrorHandlerOptions} options - Error handler options
- * @param {boolean} [options.logErrors=true] - Whether to log errors
- * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production
- * @returns Error middleware
- *
- * @example
- * import express from 'express';
- * import { errorHandler } from '@catbee/utils';
- *
- * const app = express();
- *
- * // Your routes
- * app.get('/ping', (req, res) => {
- *   throw new Error('Something went wrong');
- * });
- *
- * // Error handler (must be last middleware)
- * app.use(errorHandler({ includeDetails: true }));
- *
- * app.listen(3000, () => {
- *   console.log('Server running on port 3000');
- * });
- */
-export function errorHandler(options) {
-    const logErrors = (options === null || options === void 0 ? void 0 : options.logErrors) !== false;
-    const includeDetails = (options === null || options === void 0 ? void 0 : options.includeDetails) === true;
-    return (err, req, res, _next) => {
-        // Determine status code
-        const status = (err === null || err === void 0 ? void 0 : err.status) || (err === null || err === void 0 ? void 0 : err.statusCode) || HttpStatusCodes.INTERNAL_SERVER_ERROR;
-        // Log error if enabled
-        if (logErrors) {
-            getLogger().error({ err }, `${err.message || 'Unknown error'}`);
-        }
-        // Handle ErrorResponse instances (our custom error class)
-        if (err instanceof ErrorResponse) {
-            const result = {
-                error: true,
-                message: err.message,
-                timestamp: err.timestamp,
-                requestId: (err === null || err === void 0 ? void 0 : err.requestId) || (req === null || req === void 0 ? void 0 : req.id) || uuid(),
-                status,
-                path: req.originalUrl || req.url
-            };
-            if (includeDetails && (err === null || err === void 0 ? void 0 : err.stack)) {
-                result.stack = err.stack.split('\n').map((line) => line.trim());
-            }
-            return res.status(status).json(result);
-        }
-        // Handle any other errors
-        return res
-            .status(status)
-            .json(createFinalErrorResponse(req, status, (err === null || err === void 0 ? void 0 : err.message) || 'Internal Server Error', err, { includeDetails }));
-    };
-}
-/**
- * Health check middleware for service status and custom checks.
- *
- * @param {object} [options] - Health check options
- * @param {string} [options.path='/healthz'] - Health check endpoint path
- * @param {Array<{name: string; check: () => Promise<boolean> | boolean}>} [options.checks] - Custom health checks
- * @param {boolean} [options.detailed=true] - Show detailed check results
- * @returns {Middleware} Express-compatible middleware
- */
-export function healthCheck(options) {
-    const path = (options === null || options === void 0 ? void 0 : options.path) || '/healthz';
-    const checks = (options === null || options === void 0 ? void 0 : options.checks) || [];
-    const detailed = (options === null || options === void 0 ? void 0 : options.detailed) !== false;
-    return async (req, res, next) => {
-        if (req.path !== path)
-            return next();
-        const results = {};
-        let allHealthy = true;
-        for (const check of checks) {
-            try {
-                const result = await Promise.resolve(check.check());
-                results[check.name] = !!result;
-                if (!result)
-                    allHealthy = false;
-            }
-            catch (_a) {
-                results[check.name] = false;
-                allHealthy = false;
-            }
-        }
-        const status = allHealthy ? HttpStatusCodes.OK : HttpStatusCodes.SERVICE_UNAVAILABLE;
-        const response = detailed
-            ? { status: allHealthy ? 'ok' : 'unhealthy', checks: results, timestamp: new Date().toISOString() }
-            : { status: allHealthy ? 'ok' : 'unhealthy' };
-        res.status(status).json(response);
-    };
-}
-//# sourceMappingURL=middleware.utils.js.map

package/build/esnext/utils/middleware.utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"middleware.utils.js","sourceRoot":"","sources":["../../../src/utils/middleware.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { createFinalErrorResponse, ErrorResponse } from './response.utils';\nimport { getLogger } from './logger.utils';\nimport type { Request, Response, NextFunction } from 'express';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { RequestTimeoutException } from './exception.utils';\nimport { ApiErrorResponse } from '../types/api-response';\n\nexport type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;\n\n/**\n * Attaches a unique request ID to each request.\n * Useful for request tracing and correlation between logs.\n *\n * @param {object} [options] - Configuration options\n * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID\n * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response\n * @param {() => string} [options.generator] - Custom ID generator function\n * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: {\n  headerName?: string;\n  exposeHeader?: boolean;\n  generator?: () => string;\n}): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\n  const generateId = options?.generator || uuid;\n\n  return (req, res, next) => {\n    // Use existing request ID from header or generate a new one\n    const existingId = req.headers[headerName.toLowerCase()];\n    const id = (existingId as string) || generateId();\n\n    // Attach ID to request object\n    req.id = id;\n\n    // Add ID to response headers\n    if (exposeHeader) {\n      res.setHeader(headerName, id);\n    }\n\n    next();\n  };\n}\n\n/**\n * Measures request processing time and logs or adds it to response headers.\n *\n * @param {object} [options] - Configuration options\n * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header\n * @param {boolean} [options.logOnComplete=false] - Whether to log timing info\n * @returns {Middleware} Express-compatible middleware\n */\nexport function responseTime(options?: { addHeader?: boolean; logOnComplete?: boolean }) {\n  const addHeader = options?.addHeader !== false;\n  const logOnComplete = options?.logOnComplete === true;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    const start = process.hrtime();\n\n    // Function to calculate duration\n    const getDuration = () => {\n      const diff = process.hrtime(start);\n      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);\n    };\n\n    if (addHeader) {\n      // Ensure header is set before response is sent\n      const originalWriteHead = res.writeHead;\n      res.writeHead = function (...args: any[]) {\n        res.setHeader('X-Response-Time', `${getDuration()}ms`);\n        return originalWriteHead.apply(this, args as any);\n      };\n    }\n\n    if (logOnComplete) {\n      res.on('finish', () => {\n        getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);\n      });\n    }\n\n    next();\n  };\n}\n\n/**\n * Request timeout middleware.\n * Aborts requests that take too long to process.\n *\n * @param {number} [timeoutMs=30000] - Timeout in milliseconds\n * @returns {Middleware} Express-compatible middleware\n */\nexport function timeout(timeoutMs: number = 30000): Middleware {\n  return (_req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      const response = new RequestTimeoutException('Request timed out');\n      res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);\n    }, timeoutMs);\n\n    // Clear timeout when response is sent\n    res.on('finish', () => {\n      clearTimeout(timer);\n    });\n\n    next();\n  };\n}\n\n/**\n * Creates an Express middleware that initializes a per-request context.\n *\n * @param {object} [options] - Optional configuration\n * @param {string} [options.headerName='x-request-id'] - Header to look for request ID\n * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized\n * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function\n */\nexport function setupRequestContext(options: { headerName?: string; autoLog?: boolean } = {}): Middleware {\n  const { headerName = 'x-request-id', autoLog = true } = options;\n  return (req, _res, next) => {\n    // Generate or use existing request ID\n    const requestId = (req.headers[headerName] as string) || req?.['id'] || uuid();\n\n    ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n      // Create a child logger for this request\n      const childLogger = getLogger().child({\n        requestId,\n        method: req.method,\n        url: req.originalUrl || req.url\n      });\n\n      req.logger = childLogger;\n\n      // Store logger in context\n      ContextStore.set(StoreKeys.LOGGER, childLogger);\n\n      if (autoLog) {\n        req.logger.info('Request context initialized');\n      }\n\n      next();\n    });\n  };\n}\n\nexport interface ErrorHandlerOptions {\n  /** Whether to log errors (default: true) */\n  logErrors?: boolean;\n  /** Whether to include error details in non-production (default: false) */\n  includeDetails?: boolean;\n}\n\n/**\n * Global error handling middleware with enhanced features.\n *\n * @param {ErrorHandlerOptions} options - Error handler options\n * @param {boolean} [options.logErrors=true] - Whether to log errors\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @returns Error middleware\n *\n * @example\n * import express from 'express';\n * import { errorHandler } from '@catbee/utils';\n *\n * const app = express();\n *\n * // Your routes\n * app.get('/ping', (req, res) => {\n *   throw new Error('Something went wrong');\n * });\n *\n * // Error handler (must be last middleware)\n * app.use(errorHandler({ includeDetails: true }));\n *\n * app.listen(3000, () => {\n *   console.log('Server running on port 3000');\n * });\n */\nexport function errorHandler(options?: ErrorHandlerOptions) {\n  const logErrors = options?.logErrors !== false;\n  const includeDetails = options?.includeDetails === true;\n\n  return (err: any, req: Request, res: Response, _next: NextFunction) => {\n    // Determine status code\n    const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;\n\n    // Log error if enabled\n    if (logErrors) {\n      getLogger().error({ err }, `${err.message || 'Unknown error'}`);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      const result: ApiErrorResponse = {\n        error: true,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err?.requestId || req?.id || uuid(),\n        status,\n        path: req.originalUrl || req.url\n      };\n\n      if (includeDetails && err?.stack) {\n        result.stack = err.stack.split('\\n').map((line: string) => line.trim());\n      }\n      return res.status(status).json(result);\n    }\n\n    // Handle any other errors\n    return res\n      .status(status)\n      .json(createFinalErrorResponse(req, status, err?.message || 'Internal Server Error', err, { includeDetails }));\n  };\n}\n\n/**\n * Health check middleware for service status and custom checks.\n *\n * @param {object} [options] - Health check options\n * @param {string} [options.path='/healthz'] - Health check endpoint path\n * @param {Array<{name: string; check: () => Promise<boolean> | boolean}>} [options.checks] - Custom health checks\n * @param {boolean} [options.detailed=true] - Show detailed check results\n * @returns {Middleware} Express-compatible middleware\n */\nexport function healthCheck(options?: {\n  path?: string;\n  checks?: Array<{ name: string; check: () => Promise<boolean> | boolean }>;\n  detailed?: boolean;\n}): Middleware {\n  const path = options?.path || '/healthz';\n  const checks = options?.checks || [];\n  const detailed = options?.detailed !== false;\n\n  return async (req, res, next) => {\n    if (req.path !== path) return next();\n    const results: Record<string, boolean> = {};\n    let allHealthy = true;\n    for (const check of checks) {\n      try {\n        const result = await Promise.resolve(check.check());\n        results[check.name] = !!result;\n        if (!result) allHealthy = false;\n      } catch {\n        results[check.name] = false;\n        allHealthy = false;\n      }\n    }\n    const status = allHealthy ? HttpStatusCodes.OK : HttpStatusCodes.SERVICE_UNAVAILABLE;\n    const response = detailed\n      ? { status: allHealthy ? 'ok' : 'unhealthy', checks: results, timestamp: new Date().toISOString() }\n      : { status: allHealthy ? 'ok' : 'unhealthy' };\n    res.status(status).json(response);\n  };\n}\n"]}

package/build/esnext/utils/obj.utils.js

@@ -1,413 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-/**
- * Checks whether the object has no own enumerable properties.
- *
- * @param {Record<any, any>} obj - The object to check.
- * @returns {boolean} True if the object is empty, false otherwise.
- */
-export function isObjEmpty(obj) {
-    return !!obj && typeof obj === 'object' && Object.keys(obj).length === 0;
-}
-/**
- * Returns a new object with only the specified keys picked.
- *
- * @template T
- * @template K
- * @param {T} obj - The source object.
- * @param {K[]} keys - Keys to pick from the object.
- * @returns {Pick<T, K>} New object with picked keys.
- */
-export function pick(obj, keys) {
-    return Object.fromEntries(keys.map(key => [key, obj[key]]));
-}
-/**
- * Returns a new object with the specified keys omitted.
- *
- * @template T
- * @template K
- * @param {T} obj - The source object.
- * @param {K[]} keys - Keys to omit from the object.
- * @returns {Omit<T, K>} New object without omitted keys.
- */
-export function omit(obj, keys) {
-    return Object.fromEntries(Object.entries(obj).filter(([key]) => !keys.includes(key)));
-}
-/**
- * Deeply merges multiple objects into the target object (mutates and returns the target object, not pure).
- *
- * @template T
- * @param {T} target - The object to merge into (will be mutated).
- * @param {...any[]} sources - The objects to merge from.
- * @returns {T} The merged object (same as target).
- */
-export function deepObjMerge(target, ...sources) {
-    if (!sources.length)
-        return target;
-    const seen = new WeakMap();
-    seen.set(target, target);
-    for (const s of sources) {
-        if (s && typeof s === 'object') {
-            seen.set(s, target);
-        }
-    }
-    function deepClone(value) {
-        if (value === null || typeof value !== 'object')
-            return value;
-        if (seen.has(value))
-            return seen.get(value);
-        // Date
-        if (value instanceof Date) {
-            return new Date(value.getTime());
-        }
-        // Array
-        if (Array.isArray(value)) {
-            const clone = [];
-            seen.set(value, clone);
-            value.forEach((item, i) => (clone[i] = deepClone(item)));
-            return clone;
-        }
-        // Set
-        if (value instanceof Set) {
-            const clone = new Set();
-            seen.set(value, clone);
-            value.forEach(item => clone.add(deepClone(item)));
-            return clone;
-        }
-        // Map
-        if (value instanceof Map) {
-            const clone = new Map();
-            seen.set(value, clone);
-            value.forEach((val, key) => clone.set(key, deepClone(val)));
-            return clone;
-        }
-        // RegExp
-        if (value instanceof RegExp) {
-            return new RegExp(value.source, value.flags);
-        }
-        // ArrayBuffer
-        if (value instanceof ArrayBuffer) {
-            return value.slice(0);
-        }
-        // TypedArrays
-        if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
-            const typed = value; // cast for TS
-            const ctor = typed.constructor;
-            // List of standard TypedArray constructors
-            const typedArrayCtors = [
-                Int8Array,
-                Uint8Array,
-                Uint8ClampedArray,
-                Int16Array,
-                Uint16Array,
-                Int32Array,
-                Uint32Array,
-                Float32Array,
-                Float64Array,
-                BigInt64Array,
-                BigUint64Array
-            ].filter(Boolean); // filter out undefined (for environments without BigInt)
-            const typedArrayCtorSet = new Set(typedArrayCtors);
-            if (typeof ctor === 'function' && typedArrayCtorSet.has(ctor)) {
-                // Defensive: ensure buffer is an ArrayBuffer and slice is available
-                const buffer = typed.buffer && typeof typed.buffer.slice === 'function' ? typed.buffer.slice(0) : typed.buffer;
-                const clone = new ctor(buffer, typed.byteOffset, typed.length);
-                seen.set(value, clone);
-                return clone;
-            }
-            else if (typeof typed.slice === 'function') {
-                // Fallback: try using slice if available (e.g., Node.js Buffer)
-                const clone = typed.slice();
-                seen.set(value, clone);
-                return clone;
-            }
-            else {
-                // Could not safely clone, throw an error for better debugging
-                throw new Error('Cannot deep clone unknown TypedArray type: ' + (typed && typed.constructor && typed.constructor.name));
-            }
-        }
-        const clone = Object.create(Object.getPrototypeOf(value));
-        seen.set(value, clone);
-        Reflect.ownKeys(value).forEach(key => {
-            const descriptor = Object.getOwnPropertyDescriptor(value, key);
-            if (descriptor.get || descriptor.set) {
-                Object.defineProperty(clone, key, descriptor);
-            }
-            else {
-                clone[key] = deepClone(value[key]);
-            }
-        });
-        return clone;
-    }
-    function mergeProp(target, source, key) {
-        const targetValue = target[key];
-        const sourceValue = source[key];
-        // Ignore undefined in source
-        if (sourceValue === undefined)
-            return;
-        // Primitives → overwrite directly
-        if (sourceValue === null || typeof sourceValue !== 'object') {
-            target[key] = sourceValue;
-            return;
-        }
-        // Arrays → replace (lodash behavior)
-        if (Array.isArray(sourceValue)) {
-            target[key] = deepClone(sourceValue);
-            return;
-        }
-        // Special cloneable objects
-        if (sourceValue instanceof Date ||
-            sourceValue instanceof RegExp ||
-            sourceValue instanceof Set ||
-            sourceValue instanceof Map ||
-            sourceValue instanceof ArrayBuffer ||
-            (ArrayBuffer.isView(sourceValue) && !(sourceValue instanceof DataView))) {
-            target[key] = deepClone(sourceValue);
-            return;
-        }
-        // Plain objects → recursive merge
-        if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
-            for (const k of Reflect.ownKeys(sourceValue)) {
-                mergeProp(targetValue, sourceValue, k);
-            }
-            return;
-        }
-        // Default → overwrite with clone
-        target[key] = deepClone(sourceValue);
-    }
-    for (const source of sources) {
-        if (source == null)
-            continue;
-        for (const key of Reflect.ownKeys(source)) {
-            mergeProp(target, source, key);
-        }
-    }
-    return target;
-}
-/**
- * Checks if a value is a plain object (i.e., not an array, null, or a built-in object).
- *
- * @param value - The value to check.
- * @returns True if the value is a plain object, false otherwise.
- */
-export function isPlainObject(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    if (Array.isArray(value))
-        return false;
-    const proto = Object.getPrototypeOf(value);
-    return proto === Object.prototype || proto === null;
-}
-/**
- * Flattens a nested object using dot notation for keys (e.g., `{a: {b: 1}}` → `{ "a.b": 1 }`).
- *
- * @template T
- * @param {T} obj - The object to flatten.
- * @param {string} [prefix=""] - Optional prefix for nested keys (used internally).
- * @returns {Record<string, any>} A new object with flattened keys.
- */
-export function flattenObject(obj, prefix = '') {
-    return Object.entries(obj).reduce((acc, [key, value]) => {
-        const newKey = prefix ? `${prefix}.${key}` : key;
-        if (value && typeof value === 'object' && !Array.isArray(value)) {
-            Object.assign(acc, flattenObject(value, newKey));
-        }
-        else {
-            acc[newKey] = value;
-        }
-        return acc;
-    }, {});
-}
-/**
- * Safely gets the value of a deeply nested key in an object using dot/bracket notation path.
- *
- * @template T
- * @param {T} obj - The object to extract from.
- * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').
- * @returns {any} The value at the given path, or undefined if not found.
- */
-export function getValueByPath(obj, path) {
-    if (!obj || typeof obj !== 'object')
-        return undefined;
-    // Convert path like "a.b[0].c" into ["a", "b", "0", "c"]
-    const parts = path
-        .replace(/\[(\d+)\]/g, '.$1') // convert [0] to .0
-        .split('.')
-        .filter(Boolean); // remove empty strings
-    return parts.reduce((acc, key) => acc === null || acc === void 0 ? void 0 : acc[key], obj);
-}
-/**
- * Sets a value at a deeply nested key in an object using dot/bracket notation path.
- * Creates intermediate objects and arrays as needed.
- *
- * @template T
- * @param {T} obj - The object to modify.
- * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').
- * @param {any} value - The value to set at the path.
- * @returns {T} The modified object.
- */
-export function setValueByPath(obj, path, value) {
-    if (!obj || typeof obj !== 'object')
-        return obj;
-    // Convert path like "a.b[0].c" into ["a", "b", "0", "c"]
-    const parts = path
-        .replace(/\[(\d+)\]/g, '.$1') // convert [0] to .0
-        .split('.')
-        .filter(Boolean); // remove empty strings
-    // Handle empty path
-    if (parts.length === 0)
-        return obj;
-    let current = obj;
-    // Navigate to the parent of the target property
-    for (let i = 0; i < parts.length - 1; i++) {
-        const key = parts[i];
-        const isArrayIndex = !isNaN(Number(parts[i + 1]));
-        if (current[key] === undefined) {
-            // Create intermediate object or array based on next key type
-            current[key] = isArrayIndex ? [] : {};
-        }
-        current = current[key];
-    }
-    // Set the value at the final key
-    const finalKey = parts[parts.length - 1];
-    current[finalKey] = value;
-    return obj;
-}
-/**
- * Performs a deep equality check between two objects.
- *
- * @param {any} a - First value to compare.
- * @param {any} b - Second value to compare.
- * @returns {boolean} True if values are deeply equal.
- */
-export function isEqual(a, b) {
-    // Check if primitives or references to the same object
-    if (a === b)
-        return true;
-    // Check if either is null/undefined or not an object
-    if (a == null || b == null || typeof a !== 'object' || typeof b !== 'object') {
-        return false;
-    }
-    // Handle Date objects
-    if (a instanceof Date && b instanceof Date) {
-        return a.getTime() === b.getTime();
-    }
-    // If one is Date but the other isn't
-    if (a instanceof Date || b instanceof Date) {
-        return false;
-    }
-    // Handle arrays
-    if (Array.isArray(a) && Array.isArray(b)) {
-        if (a.length !== b.length)
-            return false;
-        // Check each element
-        for (let i = 0; i < a.length; i++) {
-            if (!isEqual(a[i], b[i]))
-                return false;
-        }
-        return true;
-    }
-    // If one is Array but the other isn't
-    if (Array.isArray(a) || Array.isArray(b)) {
-        return false;
-    }
-    // Compare object keys
-    const keysA = Object.keys(a);
-    const keysB = Object.keys(b);
-    if (keysA.length !== keysB.length)
-        return false;
-    // Check if every key in A exists in B and has the same value
-    return keysA.every(key => Object.prototype.hasOwnProperty.call(b, key) && isEqual(a[key], b[key]));
-}
-/**
- * Filters object properties based on a predicate function.
- *
- * @template T
- * @param {T} obj - The source object.
- * @param {(value: any, key: string, obj: T) => boolean} predicate - Filter function.
- * @returns {Partial<T>} New object with filtered properties.
- */
-export function filterObject(obj, predicate) {
-    return Object.fromEntries(Object.entries(obj).filter(([key, value]) => predicate(value, key, obj)));
-}
-/**
- * Maps object values to new values using a mapping function.
- *
- * @template T
- * @template U
- * @param {T} obj - The source object.
- * @param {(value: any, key: string, obj: T) => U} mapFn - Mapping function.
- * @returns {Record<keyof T, U>} New object with mapped values.
- */
-export function mapObject(obj, mapFn) {
-    return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, mapFn(value, key, obj)]));
-}
-/**
- * Recursively freezes an object and all its properties.
- * Makes an object immutable.
- *
- * @template T
- * @param {T} obj - The object to freeze.
- * @returns {Readonly<T>} The frozen object.
- */
-export function deepFreeze(obj) {
-    // Freeze primitive properties
-    Object.freeze(obj);
-    // Recursively freeze nested objects
-    for (const prop of Object.getOwnPropertyNames(obj)) {
-        const value = obj[prop];
-        if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
-            deepFreeze(value);
-        }
-    }
-    return obj;
-}
-/**
- * Safely checks if a value is an object (not null, not array).
- *
- * @param {unknown} value - Value to check.
- * @returns {boolean} True if value is a non-null, non-array object.
- */
-export function isObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-/**
- * Gets all paths in an object using dot notation.
- *
- * @param {Record<string, any>} obj - Object to analyze.
- * @param {string} [parentPath=""] - Internal param for recursion.
- * @returns {string[]} Array of all paths in dot notation.
- */
-export function getAllPaths(obj, parentPath = '') {
-    if (!isObject(obj))
-        return [];
-    return Object.entries(obj).flatMap(([key, value]) => {
-        const currentPath = parentPath ? `${parentPath}.${key}` : key;
-        if (isObject(value)) {
-            return [currentPath, ...getAllPaths(value, currentPath)];
-        }
-        return [currentPath];
-    });
-}
-//# sourceMappingURL=obj.utils.js.map