@catbee/utils 2.0.0-next.0 → 2.0.0

package/object/index.cjs

@@ -0,0 +1,379 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/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.
+ */
+
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/object/object.utils.ts
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+__name(isObject, "isObject");
+function isObjEmpty(obj) {
+  return isObject(obj) && Object.keys(obj).length === 0;
+}
+__name(isObjEmpty, "isObjEmpty");
+function pick(obj, keys) {
+  return Object.fromEntries(keys.map((key) => [
+    key,
+    obj[key]
+  ]));
+}
+__name(pick, "pick");
+function omit(obj, keys) {
+  return Object.fromEntries(Object.entries(obj).filter(([key]) => !keys.includes(key)));
+}
+__name(omit, "omit");
+function deepObjMerge(target, ...sources) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  for (const s of sources) {
+    target = mergeInto(target, s, seen);
+  }
+  return target;
+}
+__name(deepObjMerge, "deepObjMerge");
+function mergeInto(t, s, seen) {
+  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 (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;
+    }
+    if (!t || typeof t !== "object") {
+      t = Object.create(Object.getPrototypeOf(s));
+    }
+    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, seen);
+    }
+    return t;
+  }
+  return s;
+}
+__name(mergeInto, "mergeInto");
+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;
+}
+__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 {
+      acc[newKey] = value;
+    }
+    return acc;
+  }, {});
+}
+__name(flattenObject, "flattenObject");
+function getValueByPath(obj, path) {
+  if (!obj || typeof obj !== "object") return void 0;
+  const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  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 clone;
+  const forbiddenKeys = /* @__PURE__ */ new Set([
+    "__proto__",
+    "prototype",
+    "constructor"
+  ]);
+  let current = clone;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    if (forbiddenKeys.has(key)) return clone;
+    const nextKey = parts[i + 1];
+    const nextIsIndex = !Number.isNaN(Number(nextKey));
+    current[key] = ensureNextContainer(current[key], nextIsIndex);
+    current = current[key];
+  }
+  const finalKey = parts.at(-1);
+  if (forbiddenKeys.has(finalKey)) return clone;
+  current[finalKey] = value;
+  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 equalDates(a, b);
+  if (a instanceof RegExp && b instanceof RegExp) return equalRegExp(a, b);
+  if (a instanceof Set && b instanceof Set) return equalSet(a, b);
+  if (a instanceof Map && b instanceof Map) return equalMap(a, b);
+  if (a instanceof ArrayBuffer && b instanceof ArrayBuffer) return equalArrayBuffer(a, b);
+  if (Array.isArray(a) && Array.isArray(b)) return equalArray(a, b);
+  return equalPlainObjects(a, b);
+}
+__name(isEqual, "isEqual");
+function equalDates(a, b) {
+  return a.getTime() === b.getTime();
+}
+__name(equalDates, "equalDates");
+function equalRegExp(a, b) {
+  return a.source === b.source && a.flags === b.flags;
+}
+__name(equalRegExp, "equalRegExp");
+function equalSet(a, b) {
+  if (a.size !== b.size) return false;
+  for (const v of a) if (!b.has(v)) return false;
+  return true;
+}
+__name(equalSet, "equalSet");
+function equalMap(a, b) {
+  if (a.size !== b.size) return false;
+  for (const [k, v] of a) {
+    if (!b.has(k)) return false;
+    if (!isEqual(v, b.get(k))) return false;
+  }
+  return true;
+}
+__name(equalMap, "equalMap");
+function equalArrayBuffer(a, b) {
+  return isEqual(new Uint8Array(a), new Uint8Array(b));
+}
+__name(equalArrayBuffer, "equalArrayBuffer");
+function equalArray(a, 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;
+}
+__name(equalArray, "equalArray");
+function equalPlainObjects(a, b) {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.hasOwn(b, key)) return false;
+    if (!isEqual(a[key], b[key])) return false;
+  }
+  return true;
+}
+__name(equalPlainObjects, "equalPlainObjects");
+function filterObject(obj, predicate) {
+  return Object.fromEntries(Object.entries(obj).filter(([key, value]) => predicate(value, key, obj)));
+}
+__name(filterObject, "filterObject");
+function mapObject(obj, mapFn) {
+  return Object.fromEntries(Object.entries(obj).map(([key, value]) => [
+    key,
+    mapFn(value, key, obj)
+  ]));
+}
+__name(mapObject, "mapObject");
+function _deepClone(value, seen) {
+  if (typeof value === "function" || typeof value === "symbol") return value;
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return seen.get(value);
+  if (Array.isArray(value)) return cloneArray(value, seen);
+  if (value instanceof Date) return cloneDate(value);
+  if (value instanceof Map) return cloneMap(value, seen);
+  if (value instanceof Set) return cloneSet(value, seen);
+  if (value instanceof RegExp) return cloneRegExp(value);
+  if (ArrayBuffer.isView(value)) return cloneArrayBufferView(value, seen);
+  if (value instanceof ArrayBuffer) return cloneArrayBuffer(value, seen);
+  return cloneObject(value, seen);
+}
+__name(_deepClone, "_deepClone");
+function cloneArray(arr, seen) {
+  const result = [];
+  seen.set(arr, result);
+  for (const item of arr) result.push(_deepClone(item, seen));
+  return result;
+}
+__name(cloneArray, "cloneArray");
+function cloneDate(d) {
+  const r = new Date(d.getTime());
+  return r;
+}
+__name(cloneDate, "cloneDate");
+function cloneMap(m, seen) {
+  const result = /* @__PURE__ */ new Map();
+  seen.set(m, result);
+  for (const [k, v] of m) result.set(_deepClone(k, seen), _deepClone(v, seen));
+  return result;
+}
+__name(cloneMap, "cloneMap");
+function cloneSet(s, seen) {
+  const result = /* @__PURE__ */ new Set();
+  seen.set(s, result);
+  for (const v of s) result.add(_deepClone(v, seen));
+  return result;
+}
+__name(cloneSet, "cloneSet");
+function cloneRegExp(r) {
+  const result = new RegExp(r.source, r.flags);
+  return result;
+}
+__name(cloneRegExp, "cloneRegExp");
+function cloneArrayBufferView(view, seen) {
+  if (view instanceof DataView) {
+    const buf2 = _deepClone(view.buffer, seen);
+    const clone2 = new DataView(buf2, view.byteOffset, view.byteLength);
+    seen.set(view, clone2);
+    return clone2;
+  }
+  const typed = view;
+  const buf = _deepClone(typed.buffer, seen);
+  const clone = new typed.constructor(buf, typed.byteOffset, typed.length);
+  seen.set(view, clone);
+  return clone;
+}
+__name(cloneArrayBufferView, "cloneArrayBufferView");
+function cloneArrayBuffer(buf, seen) {
+  const result = buf.slice(0);
+  seen.set(buf, result);
+  return result;
+}
+__name(cloneArrayBuffer, "cloneArrayBuffer");
+function cloneObject(obj, seen) {
+  const result = Object.create(Object.getPrototypeOf(obj));
+  seen.set(obj, result);
+  for (const key of Reflect.ownKeys(obj)) {
+    const desc = Object.getOwnPropertyDescriptor(obj, 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(obj[key], seen),
+        writable: desc?.writable ?? true,
+        enumerable: desc?.enumerable ?? true,
+        configurable: desc?.configurable ?? true
+      });
+    }
+  }
+  return result;
+}
+__name(cloneObject, "cloneObject");
+function deepClone(value) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  return _deepClone(value, seen);
+}
+__name(deepClone, "deepClone");
+function deepFreeze(obj) {
+  Object.freeze(obj);
+  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 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
+    ];
+  });
+}
+__name(getAllPaths, "getAllPaths");
+function invert(obj) {
+  if (!isObject(obj)) return {};
+  return Object.fromEntries(Object.entries(obj).map(([k, v]) => [
+    String(v),
+    k
+  ]));
+}
+__name(invert, "invert");
+function invertBy(obj, keyFn) {
+  if (!isObject(obj)) return {};
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const newKey = keyFn(value);
+    if (!result[newKey]) result[newKey] = [];
+    result[newKey].push(key);
+  }
+  return result;
+}
+__name(invertBy, "invertBy");
+function transform(obj, fn) {
+  if (!isObject(obj)) return {};
+  return Object.fromEntries(Object.entries(obj).map(([k, v]) => [
+    k,
+    fn(v, k)
+  ]));
+}
+__name(transform, "transform");
+
+exports.deepClone = deepClone;
+exports.deepFreeze = deepFreeze;
+exports.deepObjMerge = deepObjMerge;
+exports.filterObject = filterObject;
+exports.flattenObject = flattenObject;
+exports.getAllPaths = getAllPaths;
+exports.getValueByPath = getValueByPath;
+exports.invert = invert;
+exports.invertBy = invertBy;
+exports.isEqual = isEqual;
+exports.isObjEmpty = isObjEmpty;
+exports.isObject = isObject;
+exports.isPlainObject = isPlainObject;
+exports.mapObject = mapObject;
+exports.omit = omit;
+exports.pick = pick;
+exports.setValueByPath = setValueByPath;
+exports.transform = transform;

package/{obj/obj.utils.d.ts → object/index.d.ts}

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/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
@@ -22,13 +22,20 @@
  * SOFTWARE.
  */
 
+/**
+ * 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.
  */
-export declare function isObjEmpty(obj: Record<any, any>): boolean;
+declare function isObjEmpty(obj: Record<any, any>): boolean;
 /**
  * Returns a new object with only the specified keys picked.
  *
@@ -38,7 +45,7 @@ export declare function isObjEmpty(obj: Record<any, any>): boolean;
  * @param {K[]} keys - Keys to pick from the object.
  * @returns {Pick<T, K>} New object with picked keys.
  */
-export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+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.
  *
@@ -48,32 +55,33 @@ export declare function pick<T extends object, K extends keyof T>(obj: T, keys:
  * @param {K[]} keys - Keys to omit from the object.
  * @returns {Omit<T, K>} New object without omitted keys.
  */
-export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
 /**
- * Deeply merges multiple objects into the target object (mutates and returns the target object, not pure).
+ * 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 as target).
+ * @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)
  */
-export declare function deepObjMerge<T extends object>(target: T, ...sources: any[]): T;
+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.
  */
-export declare function isPlainObject(value: any): value is Record<string, any>;
+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 }`).
+ * 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 declare function flattenObject<T extends Record<string, any>>(obj: T, prefix?: string): Record<string, any>;
+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.
  *
@@ -82,7 +90,7 @@ export declare function flattenObject<T extends Record<string, any>>(obj: T, pre
  * @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 declare function getValueByPath<T extends object>(obj: T, path: string): any;
+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.
@@ -91,9 +99,9 @@ export declare function getValueByPath<T extends object>(obj: T, path: string):
  * @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 modified object.
+ * @returns {T} The new object with the value set (original object is not mutated).
  */
-export declare function setValueByPath<T extends object>(obj: T, path: string, value: any): T;
+declare function setValueByPath<T extends object>(obj: T, path: string, value: any): T;
 /**
  * Performs a deep equality check between two objects.
  *
@@ -101,7 +109,7 @@ export declare function setValueByPath<T extends object>(obj: T, path: string, v
  * @param {any} b - Second value to compare.
  * @returns {boolean} True if values are deeply equal.
  */
-export declare function isEqual(a: any, b: any): boolean;
+declare function isEqual(a: any, b: any): boolean;
 /**
  * Filters object properties based on a predicate function.
  *
@@ -110,7 +118,7 @@ export declare function isEqual(a: any, b: any): boolean;
  * @param {(value: any, key: string, obj: T) => boolean} predicate - Filter function.
  * @returns {Partial<T>} New object with filtered properties.
  */
-export declare function filterObject<T extends object>(obj: T, predicate: (value: any, key: string, obj: T) => boolean): Partial<T>;
+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.
  *
@@ -120,16 +128,17 @@ export declare function filterObject<T extends object>(obj: T, predicate: (value
  * @param {(value: any, key: string, obj: T) => U} mapFn - Mapping function.
  * @returns {Record<keyof T, U>} New object with mapped values.
  */
-export declare function mapObject<T extends object, U>(obj: T, mapFn: (value: any, key: string, obj: T) => U): Record<keyof T, U>;
+declare function mapObject<T extends object, U>(obj: T, mapFn: (value: any, key: string, obj: T) => U): Record<keyof T, U>;
 /**
- * Create a deep clone of a value. Uses structuredClone when available, falls back to JSON
- * serialization as a best-effort fallback (may lose functions and special objects).
+ * Deeply clones any value.
+ * Preserves functions and symbols by reference.
+ * Handles circular references using `WeakMap`.
  *
- * @template T
- * @param {T} value
- * @returns {T}
+ * @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.
  */
-export declare function deepClone<T>(value: T): T;
+declare function deepClone<T>(value: T): T;
 /**
  * Recursively freezes an object and all its properties.
  * Makes an object immutable.
@@ -138,14 +147,7 @@ export declare function deepClone<T>(value: T): T;
  * @param {T} obj - The object to freeze.
  * @returns {Readonly<T>} The frozen object.
  */
-export declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
-/**
- * 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 declare function isObject(value: unknown): value is Record<string, any>;
+declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
 /**
  * Gets all paths in an object using dot notation.
  *
@@ -153,4 +155,42 @@ export declare function isObject(value: unknown): value is Record<string, any>;
  * @param {string} [parentPath=""] - Internal param for recursion.
  * @returns {string[]} Array of all paths in dot notation.
  */
-export declare function getAllPaths(obj: Record<string, any>, parentPath?: string): string[];
+declare function getAllPaths(obj: Record<string, any>, parentPath?: string): string[];
+/**
+ * Inverts an object's keys and values.
+ *
+ * @template T
+ * @param {T} obj - The object to invert.
+ * @returns {Record<string, string>} Inverted object.
+ *
+ * @example
+ * invert({ a: 'x', b: 'y' }); // { x: 'a', y: 'b' }
+ */
+declare function invert<T extends Record<string, any>>(obj: T): Record<string, string>;
+/**
+ * Inverts an object using a function to generate keys from values.
+ *
+ * @template T
+ * @param {T} obj - The object to invert.
+ * @param {(value: any) => string} keyFn - Function to generate new keys.
+ * @returns {Record<string, string[]>} Inverted object with arrays of keys.
+ *
+ * @example
+ * invertBy({ a: 1, b: 2, c: 1 }, v => String(v)); // { '1': ['a', 'c'], '2': ['b'] }
+ */
+declare function invertBy<T extends Record<string, any>>(obj: T, keyFn: (value: any) => string): Record<string, string[]>;
+/**
+ * Transforms object values using a mapping function.
+ *
+ * @template T
+ * @template U
+ * @param {T} obj - The source object.
+ * @param {(value: any, key: string) => U} fn - Transformation function.
+ * @returns {Record<string, U>} Object with transformed values.
+ *
+ * @example
+ * transform({ a: 1, b: 2 }, v => v * 2); // { a: 2, b: 4 }
+ */
+declare function transform<T extends Record<string, any>, U>(obj: T, fn: (value: any, key: string) => U): Record<string, U>;
+
+export { deepClone, deepFreeze, deepObjMerge, filterObject, flattenObject, getAllPaths, getValueByPath, invert, invertBy, isEqual, isObjEmpty, isObject, isPlainObject, mapObject, omit, pick, setValueByPath, transform };