utilitish 0.0.6 → 0.0.8

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

@@ -1,27 +1,105 @@
-export {};
 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>;
     }
 }
+export {};

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';

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

@@ -1,62 +1,181 @@
-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.
          *
-         * @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.
+         * @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'
+         *
+         * @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;
     }
 }
+export {};

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';