@catbee/utils 2.0.0-next.0 → 2.0.0-next.1

package/obj/index.cjs

@@ -28,8 +28,12 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/obj/obj.utils.ts
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+__name(isObject, "isObject");
 function isObjEmpty(obj) {
-  return !!obj && typeof obj === "object" && Object.keys(obj).length === 0;
+  return isObject(obj) && Object.keys(obj).length === 0;
 }
 __name(isObjEmpty, "isObjEmpty");
 function pick(obj, keys) {
@@ -44,117 +48,38 @@ function omit(obj, keys) {
 }
 __name(omit, "omit");
 function deepObjMerge(target, ...sources) {
-  if (!sources.length) return target;
   const seen = /* @__PURE__ */ new WeakMap();
-  seen.set(target, target);
-  for (const s of sources) {
-    if (s && typeof s === "object") {
-      seen.set(s, target);
-    }
-  }
-  function deepClone2(value) {
-    if (value === null || typeof value !== "object") return value;
-    if (seen.has(value)) return seen.get(value);
-    if (value instanceof Date) {
-      return new Date(value.getTime());
-    }
-    if (Array.isArray(value)) {
-      const clone2 = [];
-      seen.set(value, clone2);
-      value.forEach((item, i) => clone2[i] = deepClone2(item));
-      return clone2;
-    }
-    if (value instanceof Set) {
-      const clone2 = /* @__PURE__ */ new Set();
-      seen.set(value, clone2);
-      value.forEach((item) => clone2.add(deepClone2(item)));
-      return clone2;
-    }
-    if (value instanceof Map) {
-      const clone2 = /* @__PURE__ */ new Map();
-      seen.set(value, clone2);
-      value.forEach((val, key) => clone2.set(key, deepClone2(val)));
-      return clone2;
-    }
-    if (value instanceof RegExp) {
-      return new RegExp(value.source, value.flags);
+  const mergeInto = /* @__PURE__ */ __name((t, s) => {
+    if (s === void 0) return t;
+    if (typeof s === "function" || typeof s === "symbol") return s;
+    if (Array.isArray(s)) {
+      const cloned = deepClone(s);
+      seen.set(s, cloned);
+      return cloned;
     }
-    if (value instanceof ArrayBuffer) {
-      return value.slice(0);
-    }
-    if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
-      const typed = value;
-      const ctor = typed.constructor;
-      const typedArrayCtors = [
-        Int8Array,
-        Uint8Array,
-        Uint8ClampedArray,
-        Int16Array,
-        Uint16Array,
-        Int32Array,
-        Uint32Array,
-        Float32Array,
-        Float64Array,
-        BigInt64Array,
-        BigUint64Array
-      ].filter(Boolean);
-      const typedArrayCtorSet = new Set(typedArrayCtors);
-      if (typeof ctor === "function" && typedArrayCtorSet.has(ctor)) {
-        const buffer = typed.buffer && typeof typed.buffer.slice === "function" ? typed.buffer.slice(0) : typed.buffer;
-        const clone2 = new ctor(buffer, typed.byteOffset, typed.length);
-        seen.set(value, clone2);
-        return clone2;
-      } else if (typeof typed.slice === "function") {
-        const clone2 = typed.slice();
-        seen.set(value, clone2);
-        return clone2;
-      } else {
-        throw new Error("Cannot deep clone unknown TypedArray type: " + (typed && typed.constructor && typed.constructor.name));
+    if (s && typeof s === "object") {
+      if (seen.has(s)) return seen.get(s);
+      if (s instanceof Date || s instanceof Map || s instanceof Set || s instanceof RegExp || s instanceof ArrayBuffer || ArrayBuffer.isView(s)) {
+        const cloned = deepClone(s);
+        seen.set(s, cloned);
+        return cloned;
       }
-    }
-    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] = deepClone2(value[key]);
+      if (!t || typeof t !== "object") {
+        t = Object.create(Object.getPrototypeOf(s));
       }
-    });
-    return clone;
-  }
-  __name(deepClone2, "deepClone");
-  function mergeProp(target2, source, key) {
-    const targetValue = target2[key];
-    const sourceValue = source[key];
-    if (sourceValue === void 0) return;
-    if (sourceValue === null || typeof sourceValue !== "object") {
-      target2[key] = sourceValue;
-      return;
-    }
-    if (Array.isArray(sourceValue)) {
-      target2[key] = deepClone2(sourceValue);
-      return;
-    }
-    if (sourceValue instanceof Date || sourceValue instanceof RegExp || sourceValue instanceof Set || sourceValue instanceof Map || sourceValue instanceof ArrayBuffer || ArrayBuffer.isView(sourceValue) && !(sourceValue instanceof DataView)) {
-      target2[key] = deepClone2(sourceValue);
-      return;
-    }
-    if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
-      for (const k of Reflect.ownKeys(sourceValue)) {
-        mergeProp(targetValue, sourceValue, k);
+      seen.set(s, t);
+      for (const key of Reflect.ownKeys(s)) {
+        if (key === "__proto__") continue;
+        const sv = s[key];
+        if (sv === void 0) continue;
+        t[key] = mergeInto(t[key], sv);
       }
-      return;
-    }
-    target2[key] = deepClone2(sourceValue);
-  }
-  __name(mergeProp, "mergeProp");
-  for (const source of sources) {
-    if (source == null) continue;
-    for (const key of Reflect.ownKeys(source)) {
-      mergeProp(target, source, key);
+      return t;
     }
+    return s;
+  }, "mergeInto");
+  for (const s of sources) {
+    target = mergeInto(target, s);
   }
   return target;
 }
@@ -169,6 +94,7 @@ __name(isPlainObject, "isPlainObject");
 function flattenObject(obj, prefix = "") {
   return Object.entries(obj).reduce((acc, [key, value]) => {
     const newKey = prefix ? `${prefix}.${key}` : key;
+    if (key === "__proto__") return acc;
     if (value && typeof value === "object" && !Array.isArray(value)) {
       Object.assign(acc, flattenObject(value, newKey));
     } else {
@@ -184,63 +110,52 @@ function getValueByPath(obj, path) {
   return parts.reduce((acc, key) => acc?.[key], obj);
 }
 __name(getValueByPath, "getValueByPath");
+function ensureNextContainer(curr, nextIsIndex) {
+  if (curr === void 0 || typeof curr !== "object" || curr === null) {
+    return nextIsIndex ? [] : /* @__PURE__ */ Object.create(null);
+  }
+  return curr;
+}
+__name(ensureNextContainer, "ensureNextContainer");
 function setValueByPath(obj, path, value) {
   if (!obj || typeof obj !== "object") return obj;
+  const clone = deepClone(obj);
   const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
-  if (parts.length === 0) return obj;
+  if (parts.length === 0) return clone;
   const forbiddenKeys = /* @__PURE__ */ new Set([
     "__proto__",
     "prototype",
     "constructor"
   ]);
-  let current = obj;
+  let current = clone;
   for (let i = 0; i < parts.length - 1; i++) {
     const key = parts[i];
-    if (forbiddenKeys.has(key)) {
-      return obj;
-    }
+    if (forbiddenKeys.has(key)) return clone;
     const nextKey = parts[i + 1];
-    const isArrayIndex = !isNaN(Number(nextKey));
-    if (current[key] === void 0) {
-      current[key] = isArrayIndex ? [] : /* @__PURE__ */ Object.create(null);
-    } else if (typeof current[key] !== "object" || current[key] === null) {
-      current[key] = isArrayIndex ? [] : /* @__PURE__ */ Object.create(null);
-    }
+    const nextIsIndex = !Number.isNaN(Number(nextKey));
+    current[key] = ensureNextContainer(current[key], nextIsIndex);
     current = current[key];
   }
-  const finalKey = parts[parts.length - 1];
-  if (forbiddenKeys.has(finalKey)) {
-    return obj;
-  }
+  const finalKey = parts.at(-1);
+  if (forbiddenKeys.has(finalKey)) return clone;
   current[finalKey] = value;
-  return obj;
+  return clone;
 }
 __name(setValueByPath, "setValueByPath");
 function isEqual(a, b) {
   if (a === b) return true;
-  if (a == null || b == null || typeof a !== "object" || typeof b !== "object") {
-    return false;
-  }
-  if (a instanceof Date && b instanceof Date) {
-    return a.getTime() === b.getTime();
-  }
-  if (a instanceof Date || b instanceof Date) {
-    return false;
-  }
-  if (Array.isArray(a) && Array.isArray(b)) {
-    if (a.length !== b.length) return false;
-    for (let i = 0; i < a.length; i++) {
-      if (!isEqual(a[i], b[i])) return false;
-    }
-    return true;
-  }
-  if (Array.isArray(a) || Array.isArray(b)) {
-    return false;
-  }
-  const keysA = Object.keys(a);
-  const keysB = Object.keys(b);
-  if (keysA.length !== keysB.length) return false;
-  return keysA.every((key) => Object.prototype.hasOwnProperty.call(b, key) && isEqual(a[key], b[key]));
+  if (a == null || b == null || typeof a !== "object" || typeof b !== "object") return false;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (a instanceof RegExp && b instanceof RegExp) return a.source === b.source && a.flags === b.flags;
+  if (a instanceof Set && b instanceof Set) return a.size === b.size && [
+    ...a
+  ].every((v) => b.has(v));
+  if (a instanceof Map && b instanceof Map) return a.size === b.size && [
+    ...a
+  ].every(([k, v]) => isEqual(v, b.get(k)));
+  if (a instanceof ArrayBuffer && b instanceof ArrayBuffer) return isEqual(new Uint8Array(a), new Uint8Array(b));
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => isEqual(v, b[i]));
+  return Object.keys(a).length === Object.keys(b).length && Object.keys(a).every((key) => isEqual(a[key], b[key]));
 }
 __name(isEqual, "isEqual");
 function filterObject(obj, predicate) {
@@ -254,35 +169,108 @@ function mapObject(obj, mapFn) {
   ]));
 }
 __name(mapObject, "mapObject");
-function deepClone(value) {
-  try {
-    if (typeof globalThis.structuredClone === "function") {
-      return globalThis.structuredClone(value);
-    }
-  } catch (_) {
+function _deepClone(value, seen) {
+  if (typeof value === "function" || typeof value === "symbol") {
+    return value;
   }
-  try {
-    return JSON.parse(JSON.stringify(value));
-  } catch (_) {
+  if (value === null || typeof value !== "object") {
     return value;
   }
+  if (seen.has(value)) {
+    return seen.get(value);
+  }
+  let result;
+  if (Array.isArray(value)) {
+    result = [];
+    seen.set(value, result);
+    for (const item of value) {
+      result.push(_deepClone(item, seen));
+    }
+    return result;
+  }
+  if (value instanceof Date) {
+    result = new Date(value.getTime());
+    seen.set(value, result);
+    return result;
+  }
+  if (value instanceof Map) {
+    result = /* @__PURE__ */ new Map();
+    seen.set(value, result);
+    for (const [k, v] of value) {
+      result.set(_deepClone(k, seen), _deepClone(v, seen));
+    }
+    return result;
+  }
+  if (value instanceof Set) {
+    result = /* @__PURE__ */ new Set();
+    seen.set(value, result);
+    for (const v of value) {
+      result.add(_deepClone(v, seen));
+    }
+    return result;
+  }
+  if (value instanceof RegExp) {
+    result = new RegExp(value.source, value.flags);
+    seen.set(value, result);
+    return result;
+  }
+  if (ArrayBuffer.isView(value)) {
+    if (value instanceof DataView) {
+      const buf2 = _deepClone(value.buffer, seen);
+      const clone2 = new DataView(buf2, value.byteOffset, value.byteLength);
+      seen.set(value, clone2);
+      return clone2;
+    }
+    const typed = value;
+    const buf = _deepClone(typed.buffer, seen);
+    const clone = new typed.constructor(buf, typed.byteOffset, typed.length);
+    seen.set(value, clone);
+    return clone;
+  }
+  if (value instanceof ArrayBuffer) {
+    result = value.slice(0);
+    seen.set(value, result);
+    return result;
+  }
+  result = Object.create(Object.getPrototypeOf(value));
+  seen.set(value, result);
+  for (const key of Reflect.ownKeys(value)) {
+    const desc = Object.getOwnPropertyDescriptor(value, key);
+    if (desc?.get || desc?.set) {
+      Object.defineProperty(result, key, {
+        get: desc.get,
+        set: desc.set,
+        enumerable: desc.enumerable,
+        configurable: desc.configurable
+      });
+    } else {
+      Object.defineProperty(result, key, {
+        value: _deepClone(value[key], seen),
+        writable: desc?.writable ?? true,
+        enumerable: desc?.enumerable ?? true,
+        configurable: desc?.configurable ?? true
+      });
+    }
+  }
+  return result;
+}
+__name(_deepClone, "_deepClone");
+function deepClone(value) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  return _deepClone(value, seen);
 }
 __name(deepClone, "deepClone");
 function deepFreeze(obj) {
   Object.freeze(obj);
-  for (const prop of Object.getOwnPropertyNames(obj)) {
-    const value = obj[prop];
-    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
-      deepFreeze(value);
+  for (const key of Reflect.ownKeys(obj)) {
+    const val = obj[key];
+    if (isObject(val) && !Object.isFrozen(val)) {
+      deepFreeze(val);
     }
   }
   return obj;
 }
 __name(deepFreeze, "deepFreeze");
-function isObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-__name(isObject, "isObject");
 function getAllPaths(obj, parentPath = "") {
   if (!isObject(obj)) return [];
   return Object.entries(obj).flatMap(([key, value]) => {

package/obj/index.d.ts

@@ -22,4 +22,139 @@
  * SOFTWARE.
  */
 
-export * from './obj.utils';
+/**
+ * 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.
+ */
+declare function isObject(value: unknown): value is Record<string, any>;
+/**
+ * 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.
+ */
+declare function isObjEmpty(obj: Record<any, any>): boolean;
+/**
+ * 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.
+ */
+declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * 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.
+ */
+declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * Deeply merges multiple sources into the target object (mutates and returns the target, not pure).
+ * Uses the project’s existing `deepClone` to handle all cloning and circular references.
+ *
+ * @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 reference as target)
+ */
+declare function deepObjMerge<T extends object>(target: T, ...sources: any[]): T;
+/**
+ * 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.
+ */
+declare function isPlainObject(value: any): value is Record<string, any>;
+/**
+ * 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.
+ */
+declare function flattenObject<T extends Record<string, any>>(obj: T, prefix?: string): Record<string, any>;
+/**
+ * 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.
+ */
+declare function getValueByPath<T extends object>(obj: T, path: string): any;
+/**
+ * Sets a value at a deeply nested key in an object using dot/bracket notation path.
+ * Secured against prototype pollution.
+ *
+ * @template T
+ * @param {T} obj - The object to modify.
+ * @param {string} path - Dot/bracket notation path (e.g., "user.friends[0].name").
+ * @param {any} value - Value to assign.
+ * @returns {T} The new object with the value set (original object is not mutated).
+ */
+declare function setValueByPath<T extends object>(obj: T, path: string, value: any): T;
+/**
+ * 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.
+ */
+declare function isEqual(a: any, b: any): boolean;
+/**
+ * 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.
+ */
+declare function filterObject<T extends object>(obj: T, predicate: (value: any, key: string, obj: T) => boolean): Partial<T>;
+/**
+ * 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.
+ */
+declare function mapObject<T extends object, U>(obj: T, mapFn: (value: any, key: string, obj: T) => U): Record<keyof T, U>;
+/**
+ * Deeply clones any value.
+ * Preserves functions and symbols by reference.
+ * Handles circular references using `WeakMap`.
+ *
+ * @template T The type of the value being cloned.
+ * @param value The value to deeply clone.
+ * @returns A fully deep-cloned copy of the input.
+ */
+declare function deepClone<T>(value: T): T;
+/**
+ * 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.
+ */
+declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
+/**
+ * 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.
+ */
+declare function getAllPaths(obj: Record<string, any>, parentPath?: string): string[];
+
+export { deepClone, deepFreeze, deepObjMerge, filterObject, flattenObject, getAllPaths, getValueByPath, isEqual, isObjEmpty, isObject, isPlainObject, mapObject, omit, pick, setValueByPath };