utilitish 0.0.6 → 0.0.8

package/dist/map/map-prototype.spec.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("../map/map-prototype");
+describe('Map.prototype', () => {
+    describe('toList()', () => {
+        describe('type: entries', () => {
+            it('should return array of entries by default', () => {
+                const map = new Map([
+                    ['a', 1],
+                    ['b', 2],
+                ]);
+                expect(map.toList()).toEqual([
+                    ['a', 1],
+                    ['b', 2],
+                ]);
+            });
+            it('should return entries when type is "entries"', () => {
+                const map = new Map([['x', 42]]);
+                expect(map.toList('entries')).toEqual([['x', 42]]);
+            });
+            it('should return empty array when map is empty', () => {
+                const map = new Map();
+                expect(map.toList()).toEqual([]);
+            });
+        });
+        describe('type: keys', () => {
+            it('should return array of keys when type is "keys"', () => {
+                const map = new Map([
+                    ['a', 1],
+                    ['b', 2],
+                ]);
+                expect(map.toList('keys')).toEqual(['a', 'b']);
+            });
+            it('should return empty array of keys when map is empty', () => {
+                const map = new Map();
+                expect(map.toList('keys')).toEqual([]);
+            });
+        });
+        describe('type: values', () => {
+            it('should return array of values when type is "values"', () => {
+                const map = new Map([
+                    ['a', 1],
+                    ['b', 2],
+                ]);
+                expect(map.toList('values')).toEqual([1, 2]);
+            });
+            it('should return empty array of values when map is empty', () => {
+                const map = new Map();
+                expect(map.toList('values')).toEqual([]);
+            });
+        });
+        describe('type: object', () => {
+            it('should return object when type is "object" with string keys', () => {
+                const map = new Map([
+                    ['a', 1],
+                    ['b', 2],
+                ]);
+                expect(map.toList('object')).toEqual({ a: 1, b: 2 });
+            });
+            it('should return object with numeric keys converted to strings', () => {
+                const map = new Map([
+                    [1, 'x'],
+                    [2, 'y'],
+                ]);
+                expect(map.toList('object')).toEqual({ '1': 'x', '2': 'y' });
+            });
+            it('should return empty object when map is empty', () => {
+                const map = new Map();
+                expect(map.toList('object')).toEqual({});
+            });
+        });
+        describe('error handling', () => {
+            it('should throw TypeError when key is not string/number/symbol for object conversion', () => {
+                const map = new Map();
+                const key = { foo: 1 };
+                map.set(key, 42);
+                expect(() => map.toList('object')).toThrow(TypeError);
+            });
+            it('should throw TypeError on unknown type', () => {
+                const map = new Map();
+                // @ts-expect-error
+                expect(() => map.toList('unknown')).toThrow(TypeError);
+            });
+        });
+    });
+    describe('ensureArray()', () => {
+        describe('with non-existing keys', () => {
+            it('should return empty array and set it in map when key does not exist', () => {
+                const map = new Map();
+                const arr = map.ensureArray('foo');
+                expect(Array.isArray(arr)).toBe(true);
+                expect(arr).toEqual([]);
+                expect(map.get('foo')).toBe(arr);
+            });
+            it('should work with non-string keys', () => {
+                const key = { id: 1 };
+                const map = new Map();
+                const arr = map.ensureArray(key);
+                expect(Array.isArray(arr)).toBe(true);
+                expect(arr).toEqual([]);
+                expect(map.get(key)).toBe(arr);
+            });
+        });
+        describe('with existing array values', () => {
+            it('should return existing array for existing key', () => {
+                const map = new Map();
+                map.set('bar', [1, 2]);
+                const arr = map.ensureArray('bar');
+                expect(arr).toEqual([1, 2]);
+                expect(map.get('bar')).toBe(arr);
+            });
+        });
+        describe('error handling', () => {
+            it('should throw TypeError when key is null or undefined', () => {
+                const map = new Map();
+                expect(() => map.ensureArray(null)).toThrow(TypeError);
+                expect(() => map.ensureArray(undefined)).toThrow(TypeError);
+            });
+            it('should throw TypeError when value for key is not an array', () => {
+                const map = new Map();
+                map.set('baz', 123);
+                expect(() => map.ensureArray('baz')).toThrow(TypeError);
+            });
+        });
+    });
+    describe('toObject()', () => {
+        describe('with string keys', () => {
+            it('should convert Map with string keys to object', () => {
+                const map = new Map([
+                    ['a', 1],
+                    ['b', 2],
+                    ['c', 3],
+                ]);
+                const obj = map.toObject();
+                expect(obj).toEqual({ a: 1, b: 2, c: 3 });
+                expect(typeof obj).toBe('object');
+            });
+            it('should preserve insertion order for string keys', () => {
+                const map = new Map([
+                    ['z', 26],
+                    ['a', 1],
+                    ['m', 13],
+                ]);
+                const obj = map.toObject();
+                const keys = Object.keys(obj);
+                expect(keys).toEqual(['z', 'a', 'm']);
+            });
+        });
+        describe('with numeric keys', () => {
+            it('should convert Map with numeric keys to object', () => {
+                const map = new Map([
+                    [1, 'a'],
+                    [2, 'b'],
+                    [3, 'c'],
+                ]);
+                const obj = map.toObject();
+                expect(obj).toEqual({ 1: 'a', 2: 'b', 3: 'c' });
+            });
+            it('should convert Map with only numeric string keys', () => {
+                const map = new Map([
+                    ['1', 'one'],
+                    ['2', 'two'],
+                    ['3', 'three'],
+                ]);
+                const obj = map.toObject();
+                expect(obj).toEqual({ 1: 'one', 2: 'two', 3: 'three' });
+            });
+        });
+        describe('with mixed key types', () => {
+            it('should convert Map with mixed string and numeric keys', () => {
+                const map = new Map([
+                    ['name', 'Alice'],
+                    [1, 'one'],
+                    ['age', '30'],
+                    [2, 'two'],
+                ]);
+                const obj = map.toObject();
+                expect(obj).toEqual({
+                    name: 'Alice',
+                    1: 'one',
+                    age: '30',
+                    2: 'two',
+                });
+            });
+        });
+        describe('with symbol keys', () => {
+            it('should convert Map with symbol keys to object', () => {
+                const sym1 = Symbol('key1');
+                const sym2 = Symbol('key2');
+                const map = new Map([
+                    [sym1, 'value1'],
+                    [sym2, 'value2'],
+                ]);
+                const obj = map.toObject();
+                expect(obj[sym1]).toBe('value1');
+                expect(obj[sym2]).toBe('value2');
+            });
+        });
+        describe('with various value types', () => {
+            it('should convert Map with various value types', () => {
+                const map = new Map([
+                    ['string', 'hello'],
+                    ['number', 42],
+                    ['boolean', true],
+                    ['null', null],
+                    ['array', [1, 2, 3]],
+                    ['object', { nested: 'value' }],
+                ]);
+                const obj = map.toObject();
+                expect(obj).toEqual({
+                    string: 'hello',
+                    number: 42,
+                    boolean: true,
+                    null: null,
+                    array: [1, 2, 3],
+                    object: { nested: 'value' },
+                });
+            });
+        });
+        describe('with empty map', () => {
+            it('should convert empty Map to empty object', () => {
+                const map = new Map();
+                const obj = map.toObject();
+                expect(obj).toEqual({});
+            });
+        });
+        describe('error handling', () => {
+            it('should throw TypeError when key is null', () => {
+                const map = new Map();
+                map.set('valid', 1);
+                map.set(null, 2);
+                expect(() => map.toObject()).toThrow(TypeError);
+            });
+            it('should throw TypeError when key is undefined', () => {
+                const map = new Map();
+                map.set('valid', 1);
+                map.set(undefined, 3);
+                expect(() => map.toObject()).toThrow(TypeError);
+            });
+            it('should throw TypeError when key is an object type', () => {
+                const map = new Map();
+                map.set({ invalid: 'key' }, 1);
+                expect(() => map.toObject()).toThrow(TypeError);
+            });
+            it('should throw TypeError when key is an array type', () => {
+                const map = new Map();
+                map.set(['invalid'], 'value');
+                expect(() => map.toObject()).toThrow(TypeError);
+            });
+        });
+        describe('with duplicate keys', () => {
+            it('should overwrite earlier keys with the same name', () => {
+                const map = new Map();
+                map.set('key', 1);
+                map.set('key', 2);
+                const obj = map.toObject();
+                expect(obj).toEqual({ key: 2 });
+            });
+        });
+    });
+});

package/dist/object/object-prototype.d.ts

@@ -1,22 +1,113 @@
-export {};
 declare global {
     interface Object {
         /**
-         * Creates a deep clone of the object.
-         * @returns A deep copy of the original object.
+         * Creates a deep clone of the object using the structured clone algorithm.
+         * This preserves object types, reference integrity, and works with cyclic references.
+         *
+         * @template T The type of the object being cloned
+         * @this {T} The object to clone
+         * @returns {T} A deep copy of the original object with all nested objects and arrays cloned
+         * @throws {TypeError} If the object contains uncloneable values (functions, symbols, etc.)
+         *
+         * @example
+         * const original = { a: { b: 1 }, c: [2, 3] };
+         * const cloned = original.deepClone();
+         * cloned.a.b = 999;
+         * console.log(original.a.b); // 1 (original unchanged)
+         *
+         * @remarks
+         * Uses the native `structuredClone()` API which provides:
+         * - Support for Date, Map, Set, TypedArray objects
+         * - Preservation of prototype chains for built-in types
+         * - Proper handling of circular references
          */
         deepClone<T>(): T;
         /**
-         * Deeply merges another object into the current object.
-         * @param source - The object to merge from.
-         * @returns The merged object (this).
+         * Deeply merges another object into the current object, recursively combining nested objects.
+         * Arrays and primitives are replaced (not merged). Modifies the current object in place.
+         *
+         * @template T The type of the object being merged into
+         * @this {T} The target object to merge into (will be modified)
+         * @param {object} source - The source object to merge from (must be a non-null object)
+         * @returns {T} The merged object (same as this)
+         * @throws {TypeError} If source is not a non-null object
+         *
+         * @example
+         * const target = { a: 1, b: { c: 2 } };
+         * const source = { b: { d: 3 }, e: 4 };
+         * target.deepMerge(source);
+         * // target: { a: 1, b: { c: 2, d: 3 }, e: 4 }
+         *
+         * @remarks
+         * - Primitive values in the source overwrite target values
+         * - Arrays in the source completely replace target arrays (not merged element-wise)
+         * - Only enumerable own properties are merged
+         * - The merge is performed recursively for nested objects
          */
         deepMerge<T>(source: any): T | typeof source;
         /**
-         * Checks for deep equality with another object.
-         * @param other - The object to compare with.
-         * @returns True if deeply equal, false otherwise.
+         * Checks for deep equality with another object, comparing all nested properties recursively.
+         * Uses strict equality for primitives and deep comparison for objects.
+         *
+         * @template T The type of the object
+         * @this {T} The object to compare
+         * @param {unknown} other - The object to compare with
+         * @returns {boolean} True if both objects are deeply equal, false otherwise
+         *
+         * @example
+         * const obj1 = { a: { b: 1 }, c: [2, 3] };
+         * const obj2 = { a: { b: 1 }, c: [2, 3] };
+         * console.log(obj1.deepEquals(obj2)); // true
+         *
+         * const obj3 = { a: { b: 2 }, c: [2, 3] };
+         * console.log(obj1.deepEquals(obj3)); // false
+         *
+         * @remarks
+         * - Primitives are compared with strict equality (===)
+         * - Objects are compared property by property recursively
+         * - Array length and element order are considered
+         * - only enumerable own properties are compared
+         * - null and undefined are handled correctly
          */
         deepEquals(other: unknown): boolean;
+        /**
+         * Converts the object to a stable string representation with sorted keys.
+         * The resulting string is deterministic: the same object will always produce the same string.
+         *
+         * @returns {string} A stable string representation of the object
+         *
+         * @example
+         * const obj = { b: 2, a: 1 };
+         * obj.stableStringify(); // '{"a":1,"b":2}'
+         *
+         * const obj2 = { a: 1, b: 2 };
+         * obj2.stableStringify(); // '{"a":1,"b":2}' (same result, different key order)
+         *
+         * @remarks
+         * - Object keys are sorted alphabetically to ensure stable output
+         * - Arrays maintain their element order
+         * - Null and primitives are handled using JSON.stringify
+         */
+        stableStringify(): string;
+        /**
+         * Generates a stable hash of the object using FNV-1a algorithm.
+         * The hash is deterministic: the same object will always produce the same hash.
+         *
+         * @returns {string} A hexadecimal string representing the hash of the object
+         *
+         * @example
+         * const obj = { b: 2, a: 1 };
+         * obj.stableHash(); // '7a8c9f2b'
+         *
+         * const obj2 = { a: 1, b: 2 };
+         * obj2.stableHash(); // '7a8c9f2b' (same hash, different key order)
+         *
+         * @remarks
+         * - Uses FNV-1a (Fowler–Noll–Vo) hashing algorithm
+         * - The object is first converted to a stable string using stableStringify()
+         * - The hash is returned as a hexadecimal string
+         */
+        stableHash(): string;
     }
 }
+export {};

package/dist/object/object-prototype.js

@@ -1,20 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const defineIfNotExists = (name, fn) => {
-    const descriptor = Object.getOwnPropertyDescriptor(Object.prototype, name);
-    if (!descriptor || descriptor.writable || descriptor.configurable) {
-        Object.defineProperty(Object.prototype, name, {
-            value: fn,
-            enumerable: false,
-            configurable: true,
-            writable: true,
-        });
-    }
-};
-defineIfNotExists('deepClone', function () {
+const core_utils_1 = require("../utils/core.utils");
+/**
+ * @see Object.prototype.deepClone
+ */
+(0, core_utils_1.defineIfNotExists)(Object.prototype, 'deepClone', function () {
     return structuredClone(this);
 });
-defineIfNotExists('deepMerge', function (source) {
+/**
+ * @see Object.prototype.deepMerge
+ */
+(0, core_utils_1.defineIfNotExists)(Object.prototype, 'deepMerge', function (source) {
     if (typeof source !== 'object' || source === null) {
         throw new TypeError('Source must be a non-null object');
     }
@@ -34,7 +30,10 @@ defineIfNotExists('deepMerge', function (source) {
     };
     return merge(this.deepClone(), source);
 });
-defineIfNotExists('deepEquals', function (other) {
+/**
+ * @see Object.prototype.deepEquals
+ */
+(0, core_utils_1.defineIfNotExists)(Object.prototype, 'deepEquals', function (other) {
     function eq(a, b) {
         // Functions: always false (even if code is the same)
         if (typeof a === 'function' || typeof b === 'function') {
@@ -86,3 +85,33 @@ defineIfNotExists('deepEquals', function (other) {
     }
     return eq(this, other);
 });
+/**
+ * @see Object.prototype.stableStringify
+ */
+(0, core_utils_1.defineIfNotExists)(Object.prototype, 'stableStringify', function () {
+    const stringify = (v) => {
+        if (v === null || typeof v !== 'object') {
+            return JSON.stringify(v);
+        }
+        if (Array.isArray(v)) {
+            return '[' + v.map(stringify).join(',') + ']';
+        }
+        const obj = v;
+        const keys = Object.keys(obj).sort();
+        const entries = keys.map((key) => JSON.stringify(key) + ':' + stringify(obj[key]));
+        return '{' + entries.join(',') + '}';
+    };
+    return stringify(this);
+});
+/**
+ * @see Object.prototype.stableHash
+ */
+(0, core_utils_1.defineIfNotExists)(Object.prototype, 'stableHash', function () {
+    const str = this.stableStringify();
+    let hash = 2166136261;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(16);
+});

package/dist/object/object-prototype.spec.d.ts

@@ -0,0 +1 @@
+import './object-prototype';

package/dist/object/object-prototype.spec.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("./object-prototype");
+describe('Object.prototype', () => {
+    describe('deepClone()', () => {
+        it('should deeply clone a plain object', () => {
+            const obj = { a: 1, b: { c: 2 } };
+            const clone = structuredClone(obj);
+            expect(clone).toEqual(obj);
+            expect(clone).not.toBe(obj);
+            expect(clone.b).not.toBe(obj.b);
+        });
+        it('should deeply clone an array', () => {
+            const arr = [{ a: 1 }, { b: 2 }];
+            const clone = arr.deepClone();
+            expect(clone).toEqual(arr);
+            expect(clone).not.toBe(arr);
+            expect(clone[0]).not.toBe(arr[0]);
+        });
+    });
+    describe('deepMerge()', () => {
+        it('should deeply merge two objects', () => {
+            const obj = { a: 1, b: { c: 2 } };
+            const source = { b: { d: 3 }, e: 4 };
+            const merged = obj.deepMerge(source);
+            expect(merged).toEqual({ a: 1, b: { c: 2, d: 3 }, e: 4 });
+            console.log(merged);
+        });
+        it('should overwrite primitive values', () => {
+            const obj = { a: 1, b: 2 };
+            const merged = obj.deepMerge({ b: 3 });
+            expect(merged).toEqual({ a: 1, b: 3 });
+            console.log(merged);
+        });
+        describe('error handling', () => {
+            it('should throw if source is not an object', () => {
+                expect(() => ({}).deepMerge(null)).toThrowError(TypeError);
+                expect(() => ({}).deepMerge(42)).toThrowError(TypeError);
+            });
+        });
+    });
+    describe('deepEquals()', () => {
+        describe('with objects', () => {
+            it('should return true for objects with same keys and values, regardless of key order', () => {
+                expect({ a: 2, b: 3 }.deepEquals({ b: 3, a: 2 })).toBe(true);
+                expect({ a: 2, b: { c: 4 } }.deepEquals({ b: { c: 4 }, a: 2 })).toBe(true);
+            });
+            it('should return false for objects with different values', () => {
+                expect({ a: 2, b: 3 }.deepEquals({ a: 2, b: 4 })).toBe(false);
+                expect({ a: 2, b: { c: 4 } }.deepEquals({ a: 2, b: { c: 5 } })).toBe(false);
+            });
+            it('should return false for objects with different keys', () => {
+                expect({ a: 2 }.deepEquals({ b: 2 })).toBe(false);
+            });
+            it('should return true for empty objects', () => {
+                expect({}.deepEquals({})).toBe(true);
+            });
+            it('should return false for objects with different key counts', () => {
+                expect({ a: 1 }.deepEquals({ a: 1, b: 2 })).toBe(false);
+            });
+        });
+        describe('with arrays', () => {
+            it('should return true for arrays with same elements in same order', () => {
+                expect([1, 2, 3].deepEquals([1, 2, 3])).toBe(true);
+                expect([1, [2, 3]].deepEquals([1, [2, 3]])).toBe(true);
+            });
+            it('should return false for arrays with different elements or order', () => {
+                expect([1, 2, 3].deepEquals([1, 3, 2])).toBe(false);
+                expect([1, [2, 3]].deepEquals([1, [3, 2]])).toBe(false);
+            });
+            it('should return true for empty arrays', () => {
+                expect([].deepEquals([])).toBe(true);
+            });
+            it('should return false for arrays with different lengths', () => {
+                expect([1].deepEquals([1, 2])).toBe(false);
+            });
+        });
+        describe('with special values', () => {
+            it('should return true for NaN deepEquals NaN', () => {
+                expect({ a: NaN }.deepEquals({ a: NaN })).toBe(true);
+                expect([NaN].deepEquals([NaN])).toBe(true);
+            });
+            it('should return false for +0 and -0', () => {
+                expect({ a: +0 }.deepEquals({ a: -0 })).toBe(false);
+                expect([+0].deepEquals([-0])).toBe(false);
+            });
+            it('should return false for objects with undefined vs missing keys', () => {
+                expect({ a: undefined }.deepEquals({})).toBe(false);
+                expect({}.deepEquals({ a: undefined })).toBe(false);
+            });
+            it('should return false for objects with functions, even if functions are equal', () => {
+                expect({ a: () => 1 }.deepEquals({ a: () => 1 })).toBe(false);
+            });
+        });
+        describe('with nested structures', () => {
+            it('should return true for nested structures deeply equal', () => {
+                expect({ a: [1, { b: 2 }] }.deepEquals({ a: [1, { b: 2 }] })).toBe(true);
+            });
+            it('should return false for nested structures not deeply equal', () => {
+                expect({ a: [1, { b: 2 }] }.deepEquals({ a: [1, { b: 3 }] })).toBe(false);
+            });
+        });
+        describe('type mismatches', () => {
+            it('should return false for array vs object', () => {
+                expect([].deepEquals({})).toBe(false);
+                expect({}.deepEquals([])).toBe(false);
+            });
+        });
+    });
+    describe('stableStringify()', () => {
+        it('should stringify plain objects with sorted keys', () => {
+            const obj = { b: 2, a: 1 };
+            expect(obj.stableStringify()).toBe('{"a":1,"b":2}');
+        });
+        it('should produce same string regardless of key order', () => {
+            const obj1 = { b: 2, a: 1, c: 3 };
+            const obj2 = { c: 3, a: 1, b: 2 };
+            expect(obj1.stableStringify()).toBe(obj2.stableStringify());
+        });
+        it('should stringify arrays with element order preserved', () => {
+            const arr = [1, 2, 3];
+            expect(arr.stableStringify()).toBe('[1,2,3]');
+        });
+        it('should handle nested objects', () => {
+            const obj = { b: { d: 4, c: 3 }, a: 1 };
+            expect(obj.stableStringify()).toBe('{"a":1,"b":{"c":3,"d":4}}');
+        });
+        it('should handle arrays within objects', () => {
+            const obj = { a: [1, 2], b: 2 };
+            expect(obj.stableStringify()).toBe('{"a":[1,2],"b":2}');
+        });
+        it('should handle empty objects and arrays', () => {
+            expect({}.stableStringify()).toBe('{}');
+            expect([].stableStringify()).toBe('[]');
+        });
+        it('should handle undefined values in objects', () => {
+            const obj = { a: undefined, b: 1 };
+            expect(obj.stableStringify()).toBe('{"a":undefined,"b":1}');
+        });
+    });
+    describe('stableHash()', () => {
+        it('should generate same hash for objects with different key order', () => {
+            const obj1 = { b: 2, a: 1 };
+            const obj2 = { a: 1, b: 2 };
+            expect(obj1.stableHash()).toBe(obj2.stableHash());
+        });
+        it('should generate different hashes for different objects', () => {
+            const obj1 = { a: 1, b: 2 };
+            const obj2 = { a: 1, b: 3 };
+            expect(obj1.stableHash()).not.toBe(obj2.stableHash());
+        });
+        it('should generate consistent hashes', () => {
+            const obj = { a: 1, b: 2 };
+            const hash1 = obj.stableHash();
+            const hash2 = obj.stableHash();
+            expect(hash1).toBe(hash2);
+        });
+        it('should generate hex string', () => {
+            const obj = { a: 1 };
+            const hash = obj.stableHash();
+            expect(/^[0-9a-f]+$/.test(hash)).toBe(true);
+        });
+        it('should handle arrays', () => {
+            const arr1 = [1, 2, 3];
+            const arr2 = [1, 2, 3];
+            expect(arr1.stableHash()).toBe(arr2.stableHash());
+        });
+        it('should handle different arrays', () => {
+            const arr1 = [1, 2, 3];
+            const arr2 = [3, 2, 1];
+            expect(arr1.stableHash()).not.toBe(arr2.stableHash());
+        });
+        it('should handle nested structures', () => {
+            const obj1 = { a: [1, { b: 2 }], c: 3 };
+            const obj2 = { c: 3, a: [1, { b: 2 }] };
+            expect(obj1.stableHash()).toBe(obj2.stableHash());
+        });
+        it('should handle empty objects', () => {
+            const obj1 = {};
+            const obj2 = {};
+            expect(obj1.stableHash()).toBe(obj2.stableHash());
+        });
+    });
+});