utilitish 0.0.6 → 0.0.7

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

@@ -2,20 +2,73 @@ 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;
     }

package/dist/object/object-prototype.js

@@ -11,9 +11,15 @@ const defineIfNotExists = (name, fn) => {
         });
     }
 };
+/**
+ * @see Object.prototype.deepClone
+ */
 defineIfNotExists('deepClone', function () {
     return structuredClone(this);
 });
+/**
+ * @see Object.prototype.deepMerge
+ */
 defineIfNotExists('deepMerge', function (source) {
     if (typeof source !== 'object' || source === null) {
         throw new TypeError('Source must be a non-null object');
@@ -34,6 +40,9 @@ defineIfNotExists('deepMerge', function (source) {
     };
     return merge(this.deepClone(), source);
 });
+/**
+ * @see Object.prototype.deepEquals
+ */
 defineIfNotExists('deepEquals', function (other) {
     function eq(a, b) {
         // Functions: always false (even if code is the same)

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

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

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

@@ -0,0 +1,110 @@
+"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);
+            });
+        });
+    });
+});

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

@@ -3,24 +3,102 @@ declare global {
     interface Set<T> {
         /**
          * Converts the Set into an array, preserving insertion order.
-         * @returns An array of all values in the Set.
+         *
+         * @template T The type of elements in the Set
+         * @this {Set<T>} The Set to convert
+         * @returns {T[]} An array containing all values in the Set in insertion order
+         *
+         * @example
+         * const set = new Set([1, 2, 3]);
+         * const arr = set.toList(); // [1, 2, 3]
+         *
+         * @remarks
+         * - Returns a new array instance each time; modifying it does not affect the Set
+         * - Empty sets return an empty array
          */
         toList<T>(): T[];
         /**
-         * Returns true if at least one of the given items is present in the set.
+         * Returns true if at least one of the given items is present in the Set.
+         *
+         * @template T The type of elements in the Set
+         * @this {Set<T>} The Set to check
+         * @param {...T[]} items - Variable number of items to check
+         * @returns {boolean} True if any item is in the Set, false if no items or Set is empty
+         * @throws {TypeError} If arguments are not in array-like form
+         *
+         * @example
+         * const set = new Set(['a', 'b', 'c']);
+         * set.hasAny('d', 'a'); // true
+         * set.hasAny('d', 'e'); // false
+         *
+         * @remarks
+         * - Returns false if no items are provided (empty arguments)
+         * - Uses strict equality (===) to check for item presence
          */
         hasAny(...items: T[]): boolean;
         /**
-         * Returns true if all of the given items are present in the set.
+         * Returns true if all of the given items are present in the Set.
+         * Can accept items as separate arguments or as a single Set parameter.
+         *
+         * @template T The type of elements in the Set
+         * @this {Set<T>} The Set to check
+         * @param {...(T[] | Set<T>)} args - Items to check (varargs or single Set)
+         * @returns {boolean} True if all items are in the Set, false otherwise
+         * @throws {TypeError} If arguments are not in a valid format or not all Sets
+         *
+         * @example
+         * const set = new Set(['a', 'b', 'c']);
+         * set.includes('a', 'b'); // true
+         * set.includes('a', 'd'); // false
+         * set.includes(new Set(['a', 'b'])); // true
+         *
+         * @remarks
+         * - Returns true if no arguments are provided (like Array's every())
+         * - Can check against another Set by passing it as the single argument
+         * - Uses strict equality (===) for item comparison
          */
         includes(...items: T[]): boolean;
         includes(items: Set<T>): boolean;
         /**
-         * Returns a new Set that is the union of this set and all given sets.
+         * Returns a new Set that is the union (combination) of this Set and all given Sets.
+         *
+         * @template T The type of elements in the Sets
+         * @this {Set<T>} The Set to start with
+         * @param {...Set<T>[]} others - Sets to union with
+         * @returns {Set<T>} A new Set containing all unique elements from this Set and all given Sets
+         * @throws {TypeError} If any argument is not a Set instance
+         *
+         * @example
+         * const set1 = new Set([1, 2, 3]);
+         * const set2 = new Set([3, 4, 5]);
+         * const result = set1.union(set2); // Set(5) { 1, 2, 3, 4, 5 }
+         *
+         * @remarks
+         * - Does not modify the original Set
+         * - Duplicate values across sets are automatically deduplicated (Set behavior)
+         * - Returns a new Set instance each time
          */
         union(...others: Set<T>[]): Set<T>;
         /**
-         * Returns a new Set that is the intersection of this set and all given sets.
+         * Returns a new Set that is the intersection of this Set and all given Sets.
+         * Contains only elements that are present in all Sets (this + all given Sets).
+         *
+         * @template T The type of elements in the Sets
+         * @this {Set<T>} The Set to start with
+         * @param {...Set<T>[]} others - Sets to intersect with
+         * @returns {Set<T>} A new Set containing only elements that exist in all Sets
+         * @throws {TypeError} If any argument is not a Set instance
+         *
+         * @example
+         * const set1 = new Set([1, 2, 3, 4]);
+         * const set2 = new Set([2, 3, 5]);
+         * const set3 = new Set([3, 6]);
+         * const result = set1.intersection(set2, set3); // Set(1) { 3 }
+         *
+         * @remarks
+         * - Does not modify the original Set
+         * - Returns an empty Set if no elements are common to all Sets
+         * - Returns a new Set instance each time
          */
         intersection(...others: Set<T>[]): Set<T>;
     }

package/dist/set/set-prototype.js

@@ -1,18 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const utils_1 = require("../utils");
-(0, utils_1.defineIfNotExists)(Set.prototype, 'toList', function () {
+const core_utils_1 = require("../utils/core.utils");
+/**
+ * @see Set.prototype.toList
+ */
+(0, core_utils_1.defineIfNotExists)(Set.prototype, 'toList', function () {
     // Always returns a new array, even for empty sets
     return Array.from(this);
 });
-(0, utils_1.defineIfNotExists)(Set.prototype, 'hasAny', function (...items) {
+/**
+ * @see Set.prototype.hasAny
+ */
+(0, core_utils_1.defineIfNotExists)(Set.prototype, 'hasAny', function (...items) {
     if (!Array.isArray(items))
         throw new TypeError('Arguments must be an array');
     if (items.length === 0)
         return false;
     return items.some((item) => this.has(item));
 });
-(0, utils_1.defineIfNotExists)(Set.prototype, 'includes', function (...args) {
+/**
+ * @see Set.prototype.includes
+ */
+(0, core_utils_1.defineIfNotExists)(Set.prototype, 'includes', function (...args) {
     let values;
     if (args.length === 0)
         return true; // empty means "all included" (like [].every)
@@ -26,7 +35,10 @@ const utils_1 = require("../utils");
         throw new TypeError('Arguments must be an array or a Set');
     return values.every((item) => this.has(item));
 });
-(0, utils_1.defineIfNotExists)(Set.prototype, 'union', function (...others) {
+/**
+ * @see Set.prototype.union
+ */
+(0, core_utils_1.defineIfNotExists)(Set.prototype, 'union', function (...others) {
     const result = new Set(this);
     for (const other of others) {
         if (!(other instanceof Set))
@@ -37,7 +49,10 @@ const utils_1 = require("../utils");
     }
     return result;
 });
-(0, utils_1.defineIfNotExists)(Set.prototype, 'intersection', function (...others) {
+/**
+ * @see Set.prototype.intersection
+ */
+(0, core_utils_1.defineIfNotExists)(Set.prototype, 'intersection', function (...others) {
     if (others.some((s) => !(s instanceof Set)))
         throw new TypeError('Arguments must be Sets');
     const result = new Set();

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

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