@js-utils-kit/object 1.0.0 → 1.1.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;
+function e(t,n=new WeakSet){if(t===null||typeof t!=`object`&&typeof t!=`function`)return t;let r=t;if(n.has(r))return t;n.add(r);let i=r;for(let t of Reflect.ownKeys(i)){let r=i[t];r!==null&&(typeof r==`object`||typeof r==`function`)&&e(r,n)}return Object.freeze(t)}function t(e=!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]=e&&Array.isArray(s)?[...s,...o]:[...o]:r(o)&&!Array.isArray(o)?i[n]=r(s)&&!Array.isArray(s)?t(e,s,o):t(e,{},o):i[n]=o}return i}exports.deepFreeze=e,exports.mergeObj=t;

package/dist/index.d.cts

@@ -1,3 +1,114 @@
+//#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/mergeObj.d.ts
 /**
  * Deeply merges multiple source objects into one.
@@ -43,7 +154,6 @@ 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 { deepFreeze, mergeObj };

package/dist/index.d.mts

@@ -1,3 +1,114 @@
+//#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/mergeObj.d.ts
 /**
  * Deeply merges multiple source objects into one.
@@ -43,7 +154,6 @@ 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 { deepFreeze, 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};
+function e(t,n=new WeakSet){if(t===null||typeof t!=`object`&&typeof t!=`function`)return t;let r=t;if(n.has(r))return t;n.add(r);let i=r;for(let t of Reflect.ownKeys(i)){let r=i[t];r!==null&&(typeof r==`object`||typeof r==`function`)&&e(r,n)}return Object.freeze(t)}function t(e=!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]=e&&Array.isArray(s)?[...s,...o]:[...o]:r(o)&&!Array.isArray(o)?i[n]=r(s)&&!Array.isArray(s)?t(e,s,o):t(e,{},o):i[n]=o}return i}export{e as deepFreeze,t as mergeObj};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@js-utils-kit/object",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Object utilities",
   "private": false,
   "license": "MIT",
@@ -30,8 +30,8 @@
   "types": "./dist/index.d.cts",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
     }
   },
   "dependencies": {},