@js-utils-kit/object 1.0.0 → 1.2.0

package/dist/index.cjs

@@ -1 +1 @@
-function e(t=!1,...n){let r=e=>typeof e==`object`&&!!e,i={};for(let a of n)if(r(a))for(let n of Object.keys(a)){let o=a[n],s=i[n];Array.isArray(o)?i[n]=t&&Array.isArray(s)?[...s,...o]:[...o]:r(o)&&!Array.isArray(o)?i[n]=r(s)&&!Array.isArray(s)?e(t,s,o):e(t,{},o):i[n]=o}return i}exports.mergeObj=e;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@js-utils-kit/valid`);function t(e,n=new WeakSet){if(e===null||typeof e!=`object`&&typeof e!=`function`)return e;let r=e;if(n.has(r))return e;n.add(r);let i=r;for(let e of Reflect.ownKeys(i)){let r=i[e];r!==null&&(typeof r==`object`||typeof r==`function`)&&t(r,n)}return Object.freeze(e)}const n=[`arrayStrategy`];function r(t){return(0,e.isObject)(t)?Object.keys(t).every(e=>n.includes(e)):!1}function i(...t){let n={};t.length>0&&r(t[t.length-1])&&(n=t.pop());let a={},{arrayStrategy:o=`replace`}=n;for(let n of t)if((0,e.isObject)(n))for(let t of Object.keys(n)){if(t===`__proto__`||t===`constructor`||t===`prototype`)continue;let r=n[t],s=a[t];if((0,e.isArray)(s)&&(0,e.isArray)(r)){switch(o){case`concat`:a[t]=[...s,...r];break;case`merge`:a[t]=[...new Set([...s,...r])];break;default:a[t]=[...r]}continue}if((0,e.isObject)(r)){a[t]=(0,e.isObject)(s)&&!Array.isArray(s)?i(s,r,{arrayStrategy:o}):i({},r,{arrayStrategy:o});continue}a[t]=r}return a}function a(e=!1,...t){let n=e=>typeof e==`object`&&!!e,r={};for(let i of t)if(n(i))for(let t of Object.keys(i)){let o=i[t],s=r[t];Array.isArray(o)?r[t]=e&&Array.isArray(s)?[...s,...o]:[...o]:n(o)&&!Array.isArray(o)?r[t]=n(s)&&!Array.isArray(s)?a(e,s,o):a(e,{},o):r[t]=o}return r}exports.deepFreeze=t,exports.deepMerge=i,exports.mergeObj=a;

package/dist/index.d.cts

@@ -1,3 +1,201 @@
+import { PlainObject } from "@js-utils-kit/types";
+
+//#region src/deepFreeze.d.ts
+/**
+ * Recursively freezes an object and all of its nested properties.
+ *
+ * @remarks
+ * This function performs a deep, immutable freeze:
+ * - Safely handles circular references
+ * - Freezes symbol and non-enumerable properties
+ * - Prevents repeated processing of shared references
+ * - Uses `WeakSet` internally to avoid memory leaks
+ *
+ * @typeParam T - The type of the value to freeze
+ *
+ * @returns The same value, deeply frozen and typed as `Readonly<T>`
+ *
+ * @example Basic usage
+ * ```ts
+ * const config = deepFreeze({
+ *   api: {
+ *     url: 'https://example.com',
+ *     timeout: 5000
+ *   }
+ * });
+ *
+ * // Compile-time error and runtime TypeError
+ * config.api.url = 'https://evil.com';
+ * ```
+ *
+ * @example Freezing arrays
+ * ```ts
+ * const list = deepFreeze([1, 2, { value: 3 }]);
+ *
+ * // Runtime TypeError
+ * list.push(4);
+ *
+ * // Runtime TypeError
+ * list[2].value = 10;
+ * ```
+ *
+ * @example Circular references
+ * ```ts
+ * const obj: any = { name: 'circle' };
+ * obj.self = obj;
+ *
+ * // Does not throw or recurse infinitely
+ * deepFreeze(obj);
+ *
+ * // Runtime TypeError
+ * obj.name = 'x';
+ * ```
+ *
+ * @example Shared references
+ * ```ts
+ * const shared = { count: 0 };
+ *
+ * const state = deepFreeze({
+ *   a: shared,
+ *   b: shared
+ * });
+ *
+ * // Runtime TypeError
+ * state.a.count = 1;
+ *
+ * // Runtime TypeError
+ * state.b.count = 2;
+ * ```
+ *
+ * @example Symbol and non-enumerable properties
+ * ```ts
+ * const secret = Symbol('secret');
+ *
+ * const obj = {};
+ * Object.defineProperty(obj, 'hidden', {
+ *   value: { token: '123' },
+ *   enumerable: false
+ * });
+ *
+ * (obj as any)[secret] = { enabled: true };
+ *
+ * deepFreeze(obj);
+ *
+ * // Runtime TypeError
+ * obj.hidden.token = '456';
+ *
+ * // Runtime TypeError
+ * (obj as any)[secret].enabled = false;
+ * ```
+ *
+ * @example Functions with properties
+ * ```ts
+ * function task() {}
+ * (task as any).meta = { active: true };
+ *
+ * deepFreeze(task);
+ *
+ * // Runtime TypeError
+ * (task as any).meta.active = false;
+ * ```
+ */
+declare function deepFreeze<T>(
+/**
+ * The value to deeply freeze.
+ */
+obj: T,
+/**
+ * Internal WeakSet used to track visited objects during recursion.
+ *
+ * @internal
+ */
+visited?: WeakSet<object>): Readonly<T>;
+//#endregion
+//#region src/deepMerge.d.ts
+/**
+ * Configuration options for {@link deepMerge}.
+ */
+interface DeepMergeOptions {
+  /**
+   * Defines how arrays should be handled when merging.
+   *
+   * - `replace` - the incoming array replaces the existing array
+   * - `concat` - arrays are concatenated
+   * - `merge` - arrays are merged with duplicate values removed
+   *
+   * @defaultValue "replace"
+   */
+  arrayStrategy?: 'replace' | 'merge' | 'concat';
+}
+/**
+ * Deeply merges multiple objects into a new object.
+ *
+ * Later objects override properties from earlier ones.
+ *
+ * @remarks
+ * - The merge is **immutable** input objects are never modified.
+ * - Primitive values from later objects override earlier values.
+ * - Nested objects are merged recursively.
+ * - Arrays are handled based on {@link DeepMergeOptions.arrayStrategy | arrayStrategy}.
+ *
+ * @typeParam T - The object type being merged.
+ *
+ * @returns A new object containing the merged properties.
+ *
+ * @example Basic merge
+ * ```ts
+ * deepMerge(
+ *   { a: 1 },
+ *   { b: 2 }
+ * )
+ *
+ * // Result
+ * { a: 1, b: 2 }
+ * ```
+ *
+ * @example Nested object merge
+ * ```ts
+ * deepMerge(
+ *   { config: { port: 3000 } },
+ *   { config: { host: "localhost" } }
+ * )
+ *
+ * // Result
+ * { config: { port: 3000, host: "localhost" } }
+ * ```
+ *
+ * @example Array concatenation
+ * ```ts
+ * deepMerge(
+ *   { items: [1, 2] },
+ *   { items: [3] },
+ *   { arrayStrategy: "concat" }
+ * )
+ *
+ * // Result
+ * { items: [1, 2, 3] }
+ * ```
+ *
+ * @example Array merge (deduplicated)
+ * ```ts
+ * deepMerge(
+ *   { items: [1, 2] },
+ *   { items: [2, 3] },
+ *   { arrayStrategy: "merge" }
+ * )
+ *
+ * // Result
+ * { items: [1, 2, 3] }
+ * ```
+ */
+declare function deepMerge<T extends PlainObject>(
+/**
+ * Objects to merge.
+ *
+ * The last argument may optionally be a {@link DeepMergeOptions} object.
+ */
+...params: (T | DeepMergeOptions)[]): T;
+//#endregion
 //#region src/mergeObj.d.ts
 /**
  * Deeply merges multiple source objects into one.
@@ -16,6 +214,7 @@
  *
  * @returns A new object containing deeply merged keys and values.
  *
+ * @deprecated Use {@link deepMerge} instead.
  *
  * @example
  * ```ts
@@ -43,7 +242,7 @@ declare function mergeObj(
  *
  * @default false
  */
-appendArray?: boolean, /** One or more objects to deeply merge */
-...sources: object[]): object;
+
+appendArray?: boolean, /** One or more objects to deeply merge */...sources: object[]): object;
 //#endregion
-export { mergeObj };
+export { DeepMergeOptions, deepFreeze, deepMerge, mergeObj };

package/dist/index.d.mts

@@ -1,3 +1,201 @@
+import { PlainObject } from "@js-utils-kit/types";
+
+//#region src/deepFreeze.d.ts
+/**
+ * Recursively freezes an object and all of its nested properties.
+ *
+ * @remarks
+ * This function performs a deep, immutable freeze:
+ * - Safely handles circular references
+ * - Freezes symbol and non-enumerable properties
+ * - Prevents repeated processing of shared references
+ * - Uses `WeakSet` internally to avoid memory leaks
+ *
+ * @typeParam T - The type of the value to freeze
+ *
+ * @returns The same value, deeply frozen and typed as `Readonly<T>`
+ *
+ * @example Basic usage
+ * ```ts
+ * const config = deepFreeze({
+ *   api: {
+ *     url: 'https://example.com',
+ *     timeout: 5000
+ *   }
+ * });
+ *
+ * // Compile-time error and runtime TypeError
+ * config.api.url = 'https://evil.com';
+ * ```
+ *
+ * @example Freezing arrays
+ * ```ts
+ * const list = deepFreeze([1, 2, { value: 3 }]);
+ *
+ * // Runtime TypeError
+ * list.push(4);
+ *
+ * // Runtime TypeError
+ * list[2].value = 10;
+ * ```
+ *
+ * @example Circular references
+ * ```ts
+ * const obj: any = { name: 'circle' };
+ * obj.self = obj;
+ *
+ * // Does not throw or recurse infinitely
+ * deepFreeze(obj);
+ *
+ * // Runtime TypeError
+ * obj.name = 'x';
+ * ```
+ *
+ * @example Shared references
+ * ```ts
+ * const shared = { count: 0 };
+ *
+ * const state = deepFreeze({
+ *   a: shared,
+ *   b: shared
+ * });
+ *
+ * // Runtime TypeError
+ * state.a.count = 1;
+ *
+ * // Runtime TypeError
+ * state.b.count = 2;
+ * ```
+ *
+ * @example Symbol and non-enumerable properties
+ * ```ts
+ * const secret = Symbol('secret');
+ *
+ * const obj = {};
+ * Object.defineProperty(obj, 'hidden', {
+ *   value: { token: '123' },
+ *   enumerable: false
+ * });
+ *
+ * (obj as any)[secret] = { enabled: true };
+ *
+ * deepFreeze(obj);
+ *
+ * // Runtime TypeError
+ * obj.hidden.token = '456';
+ *
+ * // Runtime TypeError
+ * (obj as any)[secret].enabled = false;
+ * ```
+ *
+ * @example Functions with properties
+ * ```ts
+ * function task() {}
+ * (task as any).meta = { active: true };
+ *
+ * deepFreeze(task);
+ *
+ * // Runtime TypeError
+ * (task as any).meta.active = false;
+ * ```
+ */
+declare function deepFreeze<T>(
+/**
+ * The value to deeply freeze.
+ */
+obj: T,
+/**
+ * Internal WeakSet used to track visited objects during recursion.
+ *
+ * @internal
+ */
+visited?: WeakSet<object>): Readonly<T>;
+//#endregion
+//#region src/deepMerge.d.ts
+/**
+ * Configuration options for {@link deepMerge}.
+ */
+interface DeepMergeOptions {
+  /**
+   * Defines how arrays should be handled when merging.
+   *
+   * - `replace` - the incoming array replaces the existing array
+   * - `concat` - arrays are concatenated
+   * - `merge` - arrays are merged with duplicate values removed
+   *
+   * @defaultValue "replace"
+   */
+  arrayStrategy?: 'replace' | 'merge' | 'concat';
+}
+/**
+ * Deeply merges multiple objects into a new object.
+ *
+ * Later objects override properties from earlier ones.
+ *
+ * @remarks
+ * - The merge is **immutable** input objects are never modified.
+ * - Primitive values from later objects override earlier values.
+ * - Nested objects are merged recursively.
+ * - Arrays are handled based on {@link DeepMergeOptions.arrayStrategy | arrayStrategy}.
+ *
+ * @typeParam T - The object type being merged.
+ *
+ * @returns A new object containing the merged properties.
+ *
+ * @example Basic merge
+ * ```ts
+ * deepMerge(
+ *   { a: 1 },
+ *   { b: 2 }
+ * )
+ *
+ * // Result
+ * { a: 1, b: 2 }
+ * ```
+ *
+ * @example Nested object merge
+ * ```ts
+ * deepMerge(
+ *   { config: { port: 3000 } },
+ *   { config: { host: "localhost" } }
+ * )
+ *
+ * // Result
+ * { config: { port: 3000, host: "localhost" } }
+ * ```
+ *
+ * @example Array concatenation
+ * ```ts
+ * deepMerge(
+ *   { items: [1, 2] },
+ *   { items: [3] },
+ *   { arrayStrategy: "concat" }
+ * )
+ *
+ * // Result
+ * { items: [1, 2, 3] }
+ * ```
+ *
+ * @example Array merge (deduplicated)
+ * ```ts
+ * deepMerge(
+ *   { items: [1, 2] },
+ *   { items: [2, 3] },
+ *   { arrayStrategy: "merge" }
+ * )
+ *
+ * // Result
+ * { items: [1, 2, 3] }
+ * ```
+ */
+declare function deepMerge<T extends PlainObject>(
+/**
+ * Objects to merge.
+ *
+ * The last argument may optionally be a {@link DeepMergeOptions} object.
+ */
+...params: (T | DeepMergeOptions)[]): T;
+//#endregion
 //#region src/mergeObj.d.ts
 /**
  * Deeply merges multiple source objects into one.
@@ -16,6 +214,7 @@
  *
  * @returns A new object containing deeply merged keys and values.
  *
+ * @deprecated Use {@link deepMerge} instead.
  *
  * @example
  * ```ts
@@ -43,7 +242,7 @@ declare function mergeObj(
  *
  * @default false
  */
-appendArray?: boolean, /** One or more objects to deeply merge */
-...sources: object[]): object;
+
+appendArray?: boolean, /** One or more objects to deeply merge */...sources: object[]): object;
 //#endregion
-export { mergeObj };
+export { DeepMergeOptions, deepFreeze, deepMerge, mergeObj };

package/dist/index.mjs

@@ -1 +1 @@
-function e(t=!1,...n){let r=e=>typeof e==`object`&&!!e,i={};for(let a of n)if(r(a))for(let n of Object.keys(a)){let o=a[n],s=i[n];Array.isArray(o)?i[n]=t&&Array.isArray(s)?[...s,...o]:[...o]:r(o)&&!Array.isArray(o)?i[n]=r(s)&&!Array.isArray(s)?e(t,s,o):e(t,{},o):i[n]=o}return i}export{e as mergeObj};
+import{isArray as e,isObject as t}from"@js-utils-kit/valid";function n(e,t=new WeakSet){if(e===null||typeof e!=`object`&&typeof e!=`function`)return e;let r=e;if(t.has(r))return e;t.add(r);let i=r;for(let e of Reflect.ownKeys(i)){let r=i[e];r!==null&&(typeof r==`object`||typeof r==`function`)&&n(r,t)}return Object.freeze(e)}const r=[`arrayStrategy`];function i(e){return t(e)?Object.keys(e).every(e=>r.includes(e)):!1}function a(...n){let r={};n.length>0&&i(n[n.length-1])&&(r=n.pop());let o={},{arrayStrategy:s=`replace`}=r;for(let r of n)if(t(r))for(let n of Object.keys(r)){if(n===`__proto__`||n===`constructor`||n===`prototype`)continue;let i=r[n],c=o[n];if(e(c)&&e(i)){switch(s){case`concat`:o[n]=[...c,...i];break;case`merge`:o[n]=[...new Set([...c,...i])];break;default:o[n]=[...i]}continue}if(t(i)){o[n]=t(c)&&!Array.isArray(c)?a(c,i,{arrayStrategy:s}):a({},i,{arrayStrategy:s});continue}o[n]=i}return o}function o(e=!1,...t){let n=e=>typeof e==`object`&&!!e,r={};for(let i of t)if(n(i))for(let t of Object.keys(i)){let a=i[t],s=r[t];Array.isArray(a)?r[t]=e&&Array.isArray(s)?[...s,...a]:[...a]:n(a)&&!Array.isArray(a)?r[t]=n(s)&&!Array.isArray(s)?o(e,s,a):o(e,{},a):r[t]=a}return r}export{n as deepFreeze,a as deepMerge,o as mergeObj};

package/package.json

@@ -1,14 +1,7 @@
 {
   "name": "@js-utils-kit/object",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Object utilities",
-  "private": false,
-  "license": "MIT",
-  "author": {
-    "name": "Sriman",
-    "email": "136729116+TenEplaysOfficial@users.noreply.github.com",
-    "url": "https://tene.vercel.app"
-  },
   "homepage": "https://js-utils.js.org",
   "repository": {
     "type": "git",
@@ -18,23 +11,33 @@
   "bugs": {
     "url": "https://github.com/teneplaysofficial/js-utils-kit/issues"
   },
+  "license": "MIT",
+  "author": {
+    "name": "Sriman",
+    "email": "136729116+TenEplaysOfficial@users.noreply.github.com",
+    "url": "https://tene.vercel.app"
+  },
+  "private": false,
   "files": [
     "dist"
   ],
-  "engines": {
-    "node": ">=22"
-  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
-  "types": "./dist/index.d.cts",
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     }
   },
-  "dependencies": {},
+  "types": "./dist/index.d.cts",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@js-utils-kit/types": "1.5.0",
+    "@js-utils-kit/valid": "2.0.0"
+  },
   "scripts": {
     "build": "tsdown",
     "test": "vitest run"