utilitish 0.0.6 → 0.0.7

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

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("../set/set-prototype");
+describe('Set.prototype', () => {
+    describe('toList()', () => {
+        it('should return array with all values in insertion order', () => {
+            const set = new Set([3, 1, 2]);
+            expect(set.toList()).toEqual([3, 1, 2]);
+        });
+        it('should return empty array when set is empty', () => {
+            const set = new Set();
+            expect(set.toList()).toEqual([]);
+        });
+        it('should return a new array instance (not same reference)', () => {
+            const set = new Set([1, 2, 3]);
+            const arr = set.toList();
+            expect(Array.isArray(arr)).toBe(true);
+            expect(arr).not.toBe(set);
+        });
+    });
+    describe('hasAny()', () => {
+        describe('with multiple items', () => {
+            it('should return true when at least one item is present', () => {
+                const set = new Set([1, 2, 3]);
+                expect(set.hasAny(0, 2)).toBe(true);
+            });
+            it('should return false when no items are present', () => {
+                const set = new Set([1, 2, 3]);
+                expect(set.hasAny(4, 5)).toBe(false);
+            });
+        });
+        describe('with edge cases', () => {
+            it('should return false when called with no arguments', () => {
+                const set = new Set([1, 2, 3]);
+                expect(set.hasAny()).toBe(false);
+            });
+        });
+    });
+    describe('includes()', () => {
+        describe('with multiple items as arguments', () => {
+            it('should return true when all items are present', () => {
+                const set = new Set([1, 2, 3]);
+                expect(set.includes(1, 2)).toBe(true);
+            });
+            it('should return false when at least one item is missing', () => {
+                const set = new Set([1, 2, 3]);
+                expect(set.includes(1, 4)).toBe(false);
+            });
+        });
+        describe('with Set as argument', () => {
+            it('should return true when all items from Set are present', () => {
+                const set = new Set([1, 2, 3]);
+                expect(set.includes(new Set([1, 2]))).toBe(true);
+            });
+            it('should return false when some items from Set are missing', () => {
+                const set = new Set([1, 2, 3]);
+                expect(set.includes(new Set([1, 4]))).toBe(false);
+            });
+        });
+        describe('with edge cases', () => {
+            it('should return true when called with no arguments', () => {
+                const set = new Set([1, 2, 3]);
+                expect(set.includes()).toBe(true);
+            });
+        });
+    });
+    describe('union()', () => {
+        describe('with multiple Sets', () => {
+            it('should return a new Set with all unique values', () => {
+                const a = new Set([1, 2]);
+                const b = new Set([2, 3]);
+                expect(a.union(b)).toEqual(new Set([1, 2, 3]));
+            });
+        });
+        describe('with no arguments', () => {
+            it('should return a copy of the Set when no arguments provided', () => {
+                const a = new Set([1, 2]);
+                expect(a.union()).toEqual(new Set([1, 2]));
+            });
+        });
+        describe('error handling', () => {
+            it('should throw TypeError when argument is not a Set', () => {
+                const a = new Set([1, 2]);
+                // @ts-expect-error
+                expect(() => a.union([3, 4])).toThrow(TypeError);
+            });
+        });
+    });
+    describe('intersection()', () => {
+        describe('with multiple Sets', () => {
+            it('should return a new Set with only common values', () => {
+                const a = new Set([1, 2, 3]);
+                const b = new Set([2, 3, 4]);
+                expect(a.intersection(b)).toEqual(new Set([2, 3]));
+            });
+            it('should return empty Set when no common values exist', () => {
+                const a = new Set([1, 2]);
+                const b = new Set([3, 4]);
+                expect(a.intersection(b)).toEqual(new Set());
+            });
+            it('should work with multiple Sets at once', () => {
+                const a = new Set([1, 2, 3, 4]);
+                const b = new Set([2, 3, 5]);
+                const c = new Set([3, 6]);
+                expect(a.intersection(b, c)).toEqual(new Set([3]));
+            });
+        });
+        describe('with no arguments', () => {
+            it('should return a copy of the Set when no arguments provided', () => {
+                const a = new Set([1, 2]);
+                expect(a.intersection()).toEqual(new Set([1, 2]));
+            });
+        });
+        describe('error handling', () => {
+            it('should throw TypeError when argument is not a Set', () => {
+                const a = new Set([1, 2]);
+                // @ts-expect-error
+                expect(() => a.intersection([2])).toThrow(TypeError);
+            });
+        });
+    });
+});

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

@@ -2,60 +2,179 @@ export {};
 declare global {
     interface String {
         /**
-         * Capitalizes the first character of the string.
-         * @returns A new string with the first character in uppercase.
+         * Capitalizes the first character of the string (uppercase) and keeps the rest unchanged.
+         *
+         * @this {string} The string to capitalize
+         * @returns {string} A new string with the first character in uppercase
+         *
+         * @example
+         * 'hello world'.capitalize(); // 'Hello world'
+         * 'HELLO'.capitalize(); // 'HELLO'
+         *
+         * @remarks
+         * - Only affects the first character
+         * - Returns an empty string for empty input
+         * - Does not normalize the rest of the string
          */
         capitalize(): string;
         /**
-         * Splits the string into an array of words, detecting camelCase, kebab-case, snake_case, and spaces.
-         * @returns An array of words extracted from the string.
+         * Splits the string into an array of words by detecting camelCase, kebab-case, snake_case, and spaces.
+         * Useful as a foundation for case conversion methods.
+         *
+         * @this {string} The string to split
+         * @returns {string[]} An array of individual words extracted from the string
+         *
+         * @example
+         * 'helloWorld'.splitWords(); // ['hello', 'World']
+         * 'hello-world'.splitWords(); // ['hello', 'world']
+         * 'hello_world'.splitWords(); // ['hello', 'world']
+         * 'HelloWorld'.splitWords(); // ['Hello', 'World']
+         *
+         * @remarks
+         * - Handles transitions from lowercase to uppercase (camelCase)
+         * - Handles consecutive uppercase letters (HTMLParser → HTML Parser)
+         * - Treats spaces, hyphens, and underscores as word separators
+         * - Filters out empty strings
          */
         splitWords(): string[];
         /**
-         * Converts the string to camelCase.
-         * @returns A camelCased version of the string.
+         * Converts the string to camelCase format.
+         *
+         * @this {string} The string to convert
+         * @returns {string} The camelCased version of the string
+         *
+         * @example
+         * 'hello-world'.camelCase(); // 'helloWorld'
+         * 'hello_world'.camelCase(); // 'helloWorld'
+         * 'HelloWorld'.camelCase(); // 'helloWorld'
+         *
+         * @remarks
+         * - First word is lowercase, subsequent words have uppercase first letter
+         * - Uses `splitWords()` internally to handle various naming conventions
          */
         camelCase(): string;
         /**
-         * Converts the string to kebab-case.
-         * @returns A kebab-cased version of the string.
+         * Converts the string to kebab-case format.
+         *
+         * @this {string} The string to convert
+         * @returns {string} The kebab-cased version of the string
+         *
+         * @example
+         * 'helloWorld'.kebabCase(); // 'hello-world'
+         * 'hello_world'.kebabCase(); // 'hello-world'
+         * 'HelloWorld'.kebabCase(); // 'hello-world'
+         *
+         * @remarks
+         * - All letters are lowercase
+         * - Words are separated by hyphens
+         * - Uses `splitWords()` internally
          */
         kebabCase(): string;
         /**
-         * Converts the string to snake_case.
-         * @returns A snake_cased version of the string.
+         * Converts the string to snake_case format.
+         *
+         * @this {string} The string to convert
+         * @returns {string} The snake_cased version of the string
+         *
+         * @example
+         * 'helloWorld'.snakeCase(); // 'hello_world'
+         * 'hello-world'.snakeCase(); // 'hello_world'
+         * 'HelloWorld'.snakeCase(); // 'hello_world'
+         *
+         * @remarks
+         * - All letters are lowercase
+         * - Words are separated by underscores
+         * - Uses `splitWords()` internally
          */
         snakeCase(): string;
         /**
          * Truncates the string to a maximum number of characters, appending '...' if truncated.
-         * @param n - Maximum length of the string.
-         * @returns A truncated string.
+         *
+         * @this {string} The string to truncate
+         * @param {number} n - Maximum length of the result (not including the '...')
+         * @returns {string} The truncated string with '...' appended if truncated, otherwise the original string
+         * @throws {TypeError} If n is not a non-negative integer
+         *
+         * @example
+         * 'hello world'.truncate(5); // 'hello...'
+         * 'hello'.truncate(10); // 'hello'
+         *
+         * @remarks
+         * - The '...' is added after the truncated portion, so total length is n + 3
+         * - Negative or non-integer values throw an error
          */
         truncate(n: number): string;
         /**
-         * Reverses the characters in the string.
-         * @returns The reversed string.
+         * Reverses the characters in the string, properly handling Unicode surrogate pairs.
+         *
+         * @this {string} The string to reverse
+         * @returns {string} The reversed string
+         *
+         * @example
+         * 'hello'.reverse(); // 'olleh'
+         * '👋world'.reverse(); // 'dlrow👋'
+         *
+         * @remarks
+         * - Uses spread operator to properly handle Unicode characters
+         * - Works correctly with emoji and other multi-byte characters
          */
         reverse(): string;
         /**
-         * Checks if the string is empty or contains only whitespace.
-         * @returns `true` if the string is empty or whitespace only, `false` otherwise.
+         * Checks if the string is empty or contains only whitespace characters.
+         *
+         * @this {string} The string to check
+         * @returns {boolean} True if the string is empty or whitespace-only, false otherwise
+         *
+         * @example
+         * ''.isEmpty(); // true
+         * '   '.isEmpty(); // true
+         * 'hello'.isEmpty(); // false
+         * ' hello '.isEmpty(); // false
+         *
+         * @remarks
+         * - Uses `trim()` internally, so handles all whitespace characters
          */
         isEmpty(): boolean;
         /**
-         * Converts the string into a slug usable in URLs.
-         * @returns A slugified version of the string.
+         * Converts the string into a URL-friendly slug format.
+         * Combines normalization, lowercasing, whitespace handling, and special character removal.
+         *
+         * @this {string} The string to slugify
+         * @returns {string} A URL-safe slug version of the string
+         *
+         * @example
+         * 'Hello World'.slugify(); // 'hello-world'
+         * 'Héllo Wørld'.slugify(); // 'hello-world'
+         * 'Hello  World!!!'.slugify(); // 'hello-world'
+         *
+         * @remarks
+         * - Normalizes Unicode characters (NFD decomposition)
+         * - Removes accents and diacritical marks
+         * - Converts to lowercase
+         * - Replaces spaces and special characters with hyphens
+         * - Removes leading/trailing hyphens
+         * - Collapses multiple consecutive hyphens into one
          */
         slugify(): string;
         /**
          * Replaces a substring between `start` and `end` indices with a given string.
-         * If `end` is not provided, only the character at `start` is replaced.
-         * If `replaceString` is not provided, the range is simply removed.
+         * Provides precise control over which portion of the string to replace.
+         *
+         * @this {string} The string to modify
+         * @param {number} start - Start index of the replacement range (inclusive)
+         * @param {number} [end] - End index of the replacement range (exclusive); defaults to start + 1
+         * @param {string} [replaceString=''] - The string to insert in place of the removed portion
+         * @returns {string} A new string with the range replaced
+         *
+         * @example
+         * 'hello world'.replaceRange(0, 5, 'goodbye'); // 'goodbye world'
+         * 'hello'.replaceRange(2, 2, 'XX'); // 'heXXllo'
+         * 'hello'.replaceRange(1, 4); // 'ho'
          *
-         * @param start - Start index of the replacement (inclusive).
-         * @param end - End index of the replacement (exclusive). Defaults to `start`.
-         * @param replaceString - The string to insert in place. Defaults to `''`.
-         * @returns A new string with the specified range replaced.
+         * @remarks
+         * - If end is not provided, defaults to replacing only the character at start
+         * - If replaceString is not provided, the range is simply removed
+         * - Uses slice() internally for safe index handling
          */
         replaceRange(start: number, end: number, replaceString?: string): string;
     }

package/dist/string/string-prototype.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const utils_1 = require("../utils");
-(0, utils_1.defineIfNotExists)(String.prototype, 'splitWords', function () {
+const core_utils_1 = require("../utils/core.utils");
+/**
+ * @see String.prototype.splitWords
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'splitWords', function () {
     return this.replace(/([a-z0-9])([A-Z])/g, '$1 $2') // helloWorld → hello World
         .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2') // HTMLParser → HTML Parser
         .replace(/[^a-zA-Z0-9]+/g, ' ')
@@ -9,47 +12,74 @@ const utils_1 = require("../utils");
         .split(/\s+/)
         .filter(Boolean);
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'camelCase', function () {
+/**
+ * @see String.prototype.camelCase
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'camelCase', function () {
     const words = this.splitWords().map((w) => w.toLowerCase());
     return words
         .map((word, i) => (i === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1)))
         .join('');
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'kebabCase', function () {
+/**
+ * @see String.prototype.kebabCase
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'kebabCase', function () {
     return this.splitWords()
         .map((w) => w.toLowerCase())
         .join('-');
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'snakeCase', function () {
+/**
+ * @see String.prototype.snakeCase
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'snakeCase', function () {
     return this.splitWords()
         .map((w) => w.toLowerCase())
         .join('_');
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'truncate', function (n) {
+/**
+ * @see String.prototype.truncate
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'truncate', function (n) {
     if (typeof n !== 'number' || !Number.isInteger(n) || n < 0) {
         throw new TypeError('Truncate length must be a non-negative integer');
     }
     return this.length > n ? this.slice(0, n) + '...' : this.toString();
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'reverse', function () {
+/**
+ * @see String.prototype.reverse
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'reverse', function () {
     return [...this].reverse().join('');
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'isEmpty', function () {
+/**
+ * @see String.prototype.isEmpty
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'isEmpty', function () {
     return this.trim().length === 0;
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'slugify', function () {
+/**
+ * @see String.prototype.slugify
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'slugify', function () {
     return this.normalize('NFD')
         .replace(/[̀-ͯ]/g, '')
         .replace(/[^a-zA-Z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '')
         .toLowerCase();
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'capitalize', function () {
+/**
+ * @see String.prototype.capitalize
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'capitalize', function () {
     if (this.length === 0)
         return '';
     return this.charAt(0).toUpperCase() + this.slice(1);
 });
-(0, utils_1.defineIfNotExists)(String.prototype, 'replaceRange', function (start, end, replaceString = '') {
+/**
+ * @see String.prototype.replaceRange
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'replaceRange', function (start, end, replaceString = '') {
     if (!Number.isInteger(start) || !Number.isInteger(end)) {
         throw new TypeError('start and end must be integers');
     }

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

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

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

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("../string/string-prototype");
+describe('String.prototype', () => {
+    describe('capitalize()', () => {
+        it('should capitalize the first character', () => {
+            expect('hello'.capitalize()).toBe('Hello');
+            expect('Hello'.capitalize()).toBe('Hello');
+            expect(''.capitalize()).toBe('');
+        });
+    });
+    describe('splitWords()', () => {
+        it('should split camelCase, kebab-case, snake_case, and spaces', () => {
+            expect('helloWorld'.splitWords()).toEqual(['hello', 'World']);
+            expect('hello-world'.splitWords()).toEqual(['hello', 'world']);
+            expect('hello_world'.splitWords()).toEqual(['hello', 'world']);
+            expect('hello world'.splitWords()).toEqual(['hello', 'world']);
+            expect('HTMLParser'.splitWords()).toEqual(['HTML', 'Parser']);
+        });
+    });
+    describe('camelCase()', () => {
+        it('should convert to camelCase', () => {
+            expect('hello world'.camelCase()).toBe('helloWorld');
+            expect('Hello_world-test'.camelCase()).toBe('helloWorldTest');
+            expect('helloWorldTest'.camelCase()).toBe('helloWorldTest');
+        });
+    });
+    describe('kebabCase()', () => {
+        it('should convert to kebab-case', () => {
+            expect('hello world'.kebabCase()).toBe('hello-world');
+            expect('Hello_worldTest'.kebabCase()).toBe('hello-world-test');
+            expect('hello-world-test'.kebabCase()).toBe('hello-world-test');
+        });
+    });
+    describe('snakeCase()', () => {
+        it('should convert to snake_case', () => {
+            expect('hello world'.snakeCase()).toBe('hello_world');
+            expect('Hello-worldTest'.snakeCase()).toBe('hello_world_test');
+            expect('hello_world_test'.snakeCase()).toBe('hello_world_test');
+        });
+    });
+    describe('truncate()', () => {
+        it('should truncate and add ... if needed', () => {
+            expect('hello world'.truncate(5)).toBe('hello...');
+            expect('hello'.truncate(10)).toBe('hello');
+        });
+        it('should throw if n is not a non-negative integer', () => {
+            expect(() => 'abc'.truncate(-1)).toThrowError(TypeError);
+            expect(() => 'abc'.truncate(1.5)).toThrowError(TypeError);
+            expect(() => 'abc'.truncate('a')).toThrowError(TypeError);
+        });
+    });
+    describe('reverse()', () => {
+        it('should reverse the string', () => {
+            expect('abc'.reverse()).toBe('cba');
+            expect('été'.reverse()).toBe('été');
+        });
+    });
+    describe('isEmpty()', () => {
+        it('should return true for empty or whitespace strings', () => {
+            expect(''.isEmpty()).toBe(true);
+            expect('   '.isEmpty()).toBe(true);
+        });
+        it('should return false for non-empty strings', () => {
+            expect('abc'.isEmpty()).toBe(false);
+            expect(' a '.isEmpty()).toBe(false);
+        });
+    });
+    describe('slugify()', () => {
+        it('should slugify a string', () => {
+            expect('Hello World!'.slugify()).toBe('hello-world');
+            expect("Éléphant à l'été".slugify()).toBe('elephant-a-l-ete');
+            expect('  --Hello__World--  '.slugify()).toBe('hello-world');
+        });
+    });
+    describe('replaceRange()', () => {
+        it('should replace a single character at the given index', () => {
+            expect('hello'.replaceRange(1, 2, 'a')).toBe('hallo');
+        });
+        it('should replace a range of characters', () => {
+            expect('abcdef'.replaceRange(2, 5, 'Z')).toBe('abZf');
+        });
+        it('should remove a range if replaceString is omitted', () => {
+            expect('abcdef'.replaceRange(1, 4)).toBe('aef');
+        });
+        it('should work when start > end (swaps automatically)', () => {
+            expect('abcdef'.replaceRange(5, 2, 'X')).toBe('abXf');
+        });
+        it('should insert at the end if start and end are equal to length', () => {
+            expect('abc'.replaceRange(3, 3, 'Z')).toBe('abcZ');
+        });
+        describe('error handling', () => {
+            it('should throw if start or end is negative', () => {
+                expect(() => 'abc'.replaceRange(-1, 2)).toThrow(RangeError);
+                expect(() => 'abc'.replaceRange(1, -2)).toThrow(RangeError);
+            });
+            it('should throw if start or end is out of bounds', () => {
+                expect(() => 'abc'.replaceRange(0, 4)).toThrow(RangeError);
+                expect(() => 'abc'.replaceRange(5, 1)).toThrow(RangeError);
+            });
+            it('should throw if start or end is not an integer', () => {
+                expect(() => 'abc'.replaceRange(1.5, 2)).toThrow(TypeError);
+                expect(() => 'abc'.replaceRange(1, 2.2)).toThrow(TypeError);
+            });
+        });
+        describe('edge cases', () => {
+            it('should default replaceString to empty string', () => {
+                expect('hello'.replaceRange(1, 4)).toBe('ho');
+            });
+            it('should support empty string', () => {
+                expect(''.replaceRange(0, 0, 'x')).toBe('x');
+            });
+        });
+    });
+});

package/dist/utils/logic.utils.d.ts

@@ -0,0 +1,3 @@
+import { Selector } from './core.utils';
+export declare function mapToObject<K extends PropertyKey, V>(map: Map<K, V>): Record<K, V>;
+export declare function sortBy<T>(arr: T[], direction: 'asc' | 'desc', selector?: Selector<T, number | string>): T[];

package/dist/utils/logic.utils.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapToObject = mapToObject;
+exports.sortBy = sortBy;
+const core_utils_1 = require("./core.utils");
+function mapToObject(map) {
+    const obj = {};
+    for (const [key, value] of map) {
+        // Validate that key is not null or undefined
+        if (key === null || key === undefined) {
+            throw new TypeError(`Invalid key: key cannot be null or undefined. Key received: ${String(key)}`);
+        }
+        const keyType = typeof key;
+        // Only allow string, number, or symbol
+        if (keyType !== 'string' && keyType !== 'number' && keyType !== 'symbol') {
+            throw new TypeError(`Invalid key type: keys must be string, number, or symbol, received ${keyType}. Key value: ${String(key)}`);
+        }
+        obj[key] = value;
+    }
+    return obj;
+}
+function sortBy(arr, direction, selector) {
+    if (arr.length === 0)
+        return arr.slice();
+    const getValue = (0, core_utils_1.resolveSelector)(selector, (item) => item);
+    if (!selector && !arr.every((item) => (0, core_utils_1.isNumberOrString)(item))) {
+        throw new TypeError('Array elements must be number or string if no selector is provided');
+    }
+    return arr.slice().sort((a, b) => {
+        const valA = getValue(a);
+        const valB = getValue(b);
+        if (!(0, core_utils_1.isNumberOrString)(valA) || !(0, core_utils_1.isNumberOrString)(valB)) {
+            throw new TypeError('Selector must return number or string');
+        }
+        if (valA > valB)
+            return direction === 'asc' ? 1 : -1;
+        if (valA < valB)
+            return direction === 'asc' ? -1 : 1;
+        return 0;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utilitish",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",