utilitish 0.0.3 → 0.0.5

package/dist/array/array-constructor.d.ts

@@ -2,25 +2,92 @@ export {};
 declare global {
     interface ArrayConstructor {
         /**
-         * Combines multiple arrays element-wise, like Python's itertools.zip_longest .
-         * @param arrays Arrays to zip together
-         * @returns An array of arrays, each containing the i-th elements of the input arrays, undefined for the shortest arrays
+         * Combines multiple arrays element-wise, similar to Python's `itertools.zip_longest`.
+         *
+         * @example
+         * Array.zip([1, 2], ['a', 'b', 'c']);
+         * // => [[1, 'a'], [2, 'b'], [undefined, 'c']]
+         *
+         * @template T Type of the array elements
+         * @param {...T[][]} arrays Arrays to zip together
+         * @returns {Array<(T | undefined)[]>} A new array where each element is an array containing the elements at the same index from each input array. Missing elements are `undefined`.
          */
         zip(...arrays: any[][]): any[][];
         /**
-         * Generates a sequence of numbers, similar to Python's range.
-         * @param start First number, or length if end is not defined
-         * @param end Last number (excluded)
-         * @param step Step of the sequence (positive or negative)
-         * @returns An array of numbers
+         * Generates a sequence of numbers, similar to Python's `range`.
+         *
+         * @example
+         * Array.range(5);
+         * // => [0, 1, 2, 3, 4]
+         *
+         * @example
+         * Array.range(2, 10, 2);
+         * // => [2, 4, 6, 8]
+         *
+         * @param {number} start First number, or the length if `end` is not provided
+         * @param {number} [end] Last number (excluded)
+         * @param {number} [step=1] Step between numbers (can be negative)
+         * @returns {number[]} An array containing the generated sequence
          */
         range(start: number, end?: number, step?: number): number[];
         /**
-         * Creates an array filled with the same value or a generated value.
-         * @param length Length of the array
-         * @param value Value or function generating a value
-         * @returns Filled array
+         * Creates an array filled with the same value or with values generated by a factory function.
+         *
+         * @example
+         * Array.repeat(3, 'x');
+         * // => ['x', 'x', 'x']
+         *
+         * @example
+         * Array.repeat(3, () => Math.random());
+         * // => [0.12, 0.45, 0.78] (values will differ)
+         *
+         * @template T Type of the array elements
+         * @param {number} length Length of the array (must be a non-negative integer)
+         * @param {T | (() => T)} value Value or function generating the value
+         * @returns {T[]} The filled array
          */
         repeat<T>(length: number, value: T | (() => T)): T[];
+        /**
+         * Creates an array filled with a given value or generated using a factory function.
+         * Supports creating multi-dimensional arrays by passing multiple sizes.
+         *
+         * @example
+         * // 1D array with primitive values
+         * Array.create('x', 5);
+         * // => ['x', 'x', 'x', 'x', 'x']
+         *
+         * @example
+         * // 1D array with random numbers
+         * Array.create(() => Math.random(), 5);
+         * // => [0.12, 0.87, 0.45, 0.76, 0.33] (values will differ)
+         *
+         * @example
+         * // 2D array (matrix)
+         * Array.create(0, 2, 3);
+         * // => [[0, 0, 0], [0, 0, 0]]
+         *
+         * @example
+         * // 2D array with distinct objects
+         * Array.create(() => ({ id: 0 }), 2, 3);
+         * // => [
+         * //      [{id:0}, {id:0}, {id:0}],
+         * //      [{id:0}, {id:0}, {id:0}]
+         * //    ]
+         *
+         * @notes
+         * - If `sizes.length === 0`, returns `[]`.
+         * - If `valueOrFactory` is a primitive, all cells contain the same value.
+         * - If `valueOrFactory` is a function, it is called for each cell to produce a fresh value.
+         * - `sizes` should be integers >= 0; negative or non-integer values are not supported.
+         *
+         * @template T
+         * @param {T | (() => T)} valueOrFactory The value to fill the array with, or a factory function producing values.
+         * @param {...number} sizes Sizes for each dimension (1D => one number, 2D => two numbers, etc.).
+         * @returns {any[]} A multi-dimensional array of depth `sizes.length` filled with values from `valueOrFactory`.
+         *
+         * @remarks
+         * - This method is **static** and must be called on `Array`, not on an instance.
+         */
+        create<T>(valueOrFactory: T | (() => T), ...sizes: number[]): any[];
     }
 }

package/dist/array/array-constructor.js

@@ -1,36 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-Array.zip = function (...arrays) {
+const utils_1 = require("../utils");
+/**
+ * @see Array.zip
+ */
+(0, utils_1.defineStaticIfNotExists)(Array, 'zip', function (...arrays) {
     if (arrays.length === 0)
         return [];
     const maxLen = Math.max(...arrays.map((arr) => arr.length));
-    const result = [];
-    for (let i = 0; i < maxLen; i++) {
-        result.push(arrays.map((arr) => arr[i]));
-    }
-    return result;
-};
-Array.range = function (start, end, step = 1) {
+    return Array.from({ length: maxLen }, (_, i) => arrays.map((arr) => arr[i]));
+});
+/**
+ * @see Array.range
+ */
+(0, utils_1.defineStaticIfNotExists)(Array, 'range', function (start, end, step = 1) {
     if (end === undefined) {
         end = start;
         start = 0;
     }
-    const result = [];
     if (step === 0)
         throw new Error('step must not be 0');
+    const result = [];
     const condition = step > 0 ? (i) => i < end : (i) => i > end;
     for (let i = start; condition(i); i += step) {
         result.push(i);
     }
     return result;
-};
-Array.repeat = function (length, value) {
+});
+/**
+ * @see Array.repeat
+ */
+(0, utils_1.defineStaticIfNotExists)(Array, 'repeat', function (length, value) {
     if (typeof length !== 'number' || !Number.isInteger(length) || length < 0) {
-        throw new TypeError('Indices must be integers');
+        throw new TypeError('Length must be a non-negative integer');
     }
-    const result = [];
-    for (let i = 0; i < length; i++) {
-        result.push(typeof value === 'function' ? value() : value);
+    return Array.from({ length }, () => (typeof value === 'function' ? value() : value));
+});
+/**
+ * @see Array.create
+ */
+(0, utils_1.defineStaticIfNotExists)(Array, 'create', function (valueOrFactory, ...sizes) {
+    if (sizes.length === 0)
+        return [];
+    if (!sizes.every((s) => Number.isInteger(s) && s >= 0)) {
+        throw new TypeError('All sizes must be non-negative integers');
     }
-    return result;
-};
+    const getValue = typeof valueOrFactory === 'function' ? valueOrFactory : () => valueOrFactory;
+    const createDimension = (dimIndex) => Array.from({ length: sizes[dimIndex] }, () => dimIndex === sizes.length - 1 ? getValue() : createDimension(dimIndex + 1));
+    return createDimension(0);
+});

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

@@ -19,6 +19,7 @@ declare global {
          * @returns The sum of the values.
          */
         sum(this: number[]): number;
+        sum<K extends keyof T>(this: T[], key: K): number;
         sum(this: T[], callback: (item: T) => number): number;
         /**
          * Returns a new array with only unique elements (based on strict equality).
@@ -39,13 +40,16 @@ declare global {
          * @returns The average of the values.
          */
         average(this: number[]): number;
+        average<K extends keyof T>(this: T[], key: K): number;
         average(this: T[], callback: (item: T) => number): number;
         /**
-         * Groups the array elements based on a key returned by the callback function.
-         * @param callback - Function that returns a key to group by.
-         * @returns An object where keys are the group names and values are arrays of grouped items.
+         * Groups the array elements based on a key returned by the selector.
+         * The selector can be a function or a string key.
+         * @param selector Function or string key to group by.
+         * @returns A Map where keys are group values and values are arrays of grouped items.
          */
-        groupBy(callback: (item: T) => string | number): Record<string | number, T[]>;
+        groupBy<K extends keyof T>(this: T[], key: K): Map<T[K], T[]>;
+        groupBy<K>(this: T[], selector: (item: T) => K): Map<K, T[]>;
         /**
          * Removes all falsy values (`false`, `null`, `0`, `""`, `undefined`, and `NaN`) from the array.
          * @returns A new array with all falsy values removed.
@@ -66,6 +70,7 @@ declare global {
          * @returns A new array sorted in ascending order.
          */
         sortAsc(this: number[] | string[]): T[];
+        sortAsc<K extends keyof T>(this: T[], key: K): T[];
         sortAsc(this: T[], callback: (item: T) => number | string): T[];
         /**
          * Returns a sorted copy of the array in descending order.
@@ -76,6 +81,7 @@ declare global {
          * @returns A new array sorted in descending order.
          */
         sortDesc(this: number[] | string[]): T[];
+        sortDesc<K extends keyof T>(this: T[], key: K): T[];
         sortDesc(this: T[], callback: (item: T) => number | string): T[];
         /**
          * Swaps the values at two indices in the array.
@@ -90,5 +96,37 @@ declare global {
          * @returns A new shuffled array.
          */
         shuffle(): T[];
+        /**
+         * Converts an array to a Map.
+         * - If the array is of pairs [K, V], returns Map<K, V>.
+         * - If a key is provided, returns Map<T[K], T>.
+         * - If keySelector and valueSelector are provided, returns Map<K, V>.
+         * @param keyOrKeySelector Key name or key selector function.
+         * @param valueSelector Value selector function.
+         */
+        toMap<K, V>(this: [K, V][]): Map<K, V>;
+        toMap<K extends keyof T>(this: T[], key: K): Map<T[K], T>;
+        toMap<K, V>(): Map<number, T>;
+        toMap<K, V>(this: T[], keyCallback: (item: T) => K): Map<K, T>;
+        toMap<K, V>(this: T[], keyCallback: (item: T) => K, valueCallback: (item: T) => V): Map<K, V>;
+        /**
+         * Returns a Set containing the unique elements of the array.
+         * If a selector is provided, it can be a function or a string key.
+         * - If a function, it is called for each element.
+         * - If a string, it is used as a property key of each element.
+         * @param selector Optional function or string key to select the value to store in the Set.
+         * @returns A Set of unique elements or selected values.
+         */
+        toSet(): Set<T>;
+        toSet<K extends keyof T>(this: T[], key: K): Set<T[K]>;
+        toSet<K>(this: T[], selector: (item: T) => K): Set<K>;
+        /**
+         * Returns a Map where the keys are the result of the selector (function or string key) and the values are the counts of each key.
+         * @param selector Function or string key to select the key for counting.
+         * @returns A Map with the count of each key.
+         */
+        countBy(): Map<T, number>;
+        countBy<K extends keyof T>(this: T[], key: K): Map<T[K], number>;
+        countBy<K>(this: T[], selector: (item: T) => K): Map<K, number>;
     }
 }

package/dist/array/array-prototype.js

@@ -7,14 +7,14 @@ const utils_1 = require("../utils");
 (0, utils_1.defineIfNotExists)(Array.prototype, 'last', function () {
     return this[this.length - 1];
 });
-(0, utils_1.defineIfNotExists)(Array.prototype, 'sum', function (callback) {
-    if (typeof callback === 'function') {
-        return this.reduce((acc, item) => acc + callback(item), 0);
-    }
-    if (this.every((item) => typeof item === 'number')) {
-        return this.reduce((acc, item) => acc + item, 0);
+(0, utils_1.defineIfNotExists)(Array.prototype, 'sum', function (selector) {
+    if (this.length === 0)
+        return 0;
+    const getValue = (0, utils_1.resolveSelector)(selector, (item) => item);
+    if (this.every((item) => typeof getValue(item) === 'number')) {
+        return this.reduce((acc, item) => getValue(item) + acc, 0);
     }
-    throw new Error('Array.prototype.sum() requires a callback unless array is number[]');
+    throw new TypeError('Array.prototype.sum() requires a callback who return a number unless array is number[]');
 });
 (0, utils_1.defineIfNotExists)(Array.prototype, 'unique', function () {
     return [...new Set(this)];
@@ -29,32 +29,26 @@ const utils_1 = require("../utils");
     }
     return result;
 });
-(0, utils_1.defineIfNotExists)(Array.prototype, 'average', function (callback) {
+(0, utils_1.defineIfNotExists)(Array.prototype, 'average', function (selector) {
     if (this.length === 0)
         return 0;
-    if (typeof callback === 'function') {
-        return this.reduce((acc, item) => acc + callback(item), 0) / this.length;
+    const getValue = (0, utils_1.resolveSelector)(selector, (item) => item);
+    if (this.every((item) => typeof getValue(item) === 'number')) {
+        return this.reduce((acc, item) => getValue(item) + acc, 0) / this.length;
     }
-    if (this.every((item) => typeof item === 'number')) {
-        return this.reduce((acc, item) => acc + item, 0) / this.length;
-    }
-    throw new Error('Array.prototype.average() requires a callback unless array is number[]');
+    throw new TypeError('Array.prototype.average() requires a callback who return a number unless array is number[]');
 });
-(0, utils_1.defineIfNotExists)(Array.prototype, 'groupBy', function (callback) {
-    if (typeof callback !== 'function') {
-        throw new TypeError('Callback must be a function');
-    }
-    const result = {};
-    this.forEach((item) => {
-        const key = callback(item);
-        if (typeof key !== 'string' && typeof key !== 'number') {
-            throw new TypeError('groupBy callback must return a string or number');
+(0, utils_1.defineIfNotExists)(Array.prototype, 'groupBy', function (selector) {
+    const getKey = (0, utils_1.resolveSelector)(selector, (item) => item);
+    const map = new Map();
+    for (const item of this) {
+        const key = getKey(item);
+        if (!map.has(key)) {
+            map.set(key, []);
         }
-        if (!result[key])
-            result[key] = [];
-        result[key].push(item);
-    });
-    return result;
+        map.get(key).push(item);
+    }
+    return map;
 });
 (0, utils_1.defineIfNotExists)(Array.prototype, 'compact', function () {
     return this.filter(Boolean);
@@ -62,55 +56,32 @@ const utils_1 = require("../utils");
 (0, utils_1.defineIfNotExists)(Array.prototype, 'enumerate', function () {
     return this.map((value, index) => [value, index]);
 });
-(0, utils_1.defineIfNotExists)(Array.prototype, 'sortAsc', function (callback) {
-    const arr = this.slice();
-    if (arr.length === 0)
-        return arr;
-    if (callback && typeof callback !== 'function') {
-        throw new TypeError('Callback must be a function');
-    }
-    // Si pas de callback, vérifier que tous les éléments sont number ou string
-    if (!callback && !arr.every((item) => typeof item === 'number' || typeof item === 'string')) {
-        throw new TypeError('Array elements must be number or string if no callback is provided');
-    }
-    return arr.sort((a, b) => {
-        const valA = callback ? callback(a) : a;
-        const valB = callback ? callback(b) : b;
-        if ((typeof valA !== 'number' && typeof valA !== 'string') ||
-            (typeof valB !== 'number' && typeof valB !== 'string')) {
-            throw new TypeError('Callback must return number or string');
-        }
-        if (valA < valB)
-            return -1;
-        if (valA > valB)
-            return 1;
-        return 0;
-    });
-});
-(0, utils_1.defineIfNotExists)(Array.prototype, 'sortDesc', function (callback) {
-    const arr = this.slice();
-    if (arr.length === 0)
-        return arr;
-    if (callback && typeof callback !== 'function') {
-        throw new TypeError('Callback must be a function');
-    }
-    if (!callback && !arr.every((item) => typeof item === 'number' || typeof item === 'string')) {
-        throw new TypeError('Array elements must be number or string if no callback is provided');
+(0, utils_1.defineIfNotExists)(Array.prototype, 'sortBy', function (direction, selector) {
+    if (this.length === 0)
+        return this.slice();
+    const getValue = (0, utils_1.resolveSelector)(selector, (item) => item);
+    if (!selector && !this.every((item) => (0, utils_1.isNumberOrString)(item))) {
+        throw new TypeError('Array elements must be number or string if no selector is provided');
     }
-    return arr.sort((a, b) => {
-        const valA = callback ? callback(a) : a;
-        const valB = callback ? callback(b) : b;
-        if ((typeof valA !== 'number' && typeof valA !== 'string') ||
-            (typeof valB !== 'number' && typeof valB !== 'string')) {
+    return this.slice().sort((a, b) => {
+        const valA = getValue(a);
+        const valB = getValue(b);
+        if (!(0, utils_1.isNumberOrString)(valA) || !(0, utils_1.isNumberOrString)(valB)) {
             throw new TypeError('Callback must return number or string');
         }
         if (valA > valB)
-            return -1;
+            return direction === 'asc' ? 1 : -1;
         if (valA < valB)
-            return 1;
+            return direction === 'asc' ? -1 : 1;
         return 0;
     });
 });
+(0, utils_1.defineIfNotExists)(Array.prototype, 'sortAsc', function (selector) {
+    return sortBy(this, 'asc', selector);
+});
+(0, utils_1.defineIfNotExists)(Array.prototype, 'sortDesc', function (selector) {
+    return sortBy(this, 'desc', selector);
+});
 (0, utils_1.defineIfNotExists)(Array.prototype, 'swap', function (i, j) {
     if (typeof i !== 'number' || typeof j !== 'number' || !Number.isInteger(i) || !Number.isInteger(j)) {
         throw new TypeError('Indices must be integers');
@@ -133,3 +104,51 @@ const utils_1 = require("../utils");
     }
     return arr;
 });
+(0, utils_1.defineIfNotExists)(Array.prototype, 'toMap', function (keySelector, valueSelector) {
+    if (!keySelector && this.length && this.every((item) => Array.isArray(item) && item.length === 2)) {
+        return new Map(this);
+    }
+    const map = new Map();
+    const getKey = (0, utils_1.resolveSelector)(keySelector, (_, index) => index);
+    const getValue = (0, utils_1.resolveSelector)(valueSelector, (item) => item);
+    for (let i = 0; i < this.length; i++) {
+        const item = this[i];
+        const key = getKey(item, i);
+        const value = getValue(item);
+        map.set(key, value);
+    }
+    return map;
+});
+(0, utils_1.defineIfNotExists)(Array.prototype, 'toSet', function (selector) {
+    const getValue = (0, utils_1.resolveSelector)(selector, (item) => item);
+    return new Set(this.map(getValue));
+});
+(0, utils_1.defineIfNotExists)(Array.prototype, 'countBy', function (selector) {
+    const getKey = (0, utils_1.resolveSelector)(selector, (item) => item);
+    const map = new Map();
+    for (const item of this) {
+        const key = getKey(item);
+        map.set(key, (map.get(key) ?? 0) + 1);
+    }
+    return map;
+});
+function sortBy(arr, direction, selector) {
+    if (arr.length === 0)
+        return arr.slice();
+    const getValue = (0, utils_1.resolveSelector)(selector, (item) => item);
+    if (!selector && !arr.every((item) => (0, 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, utils_1.isNumberOrString)(valA) || !(0, utils_1.isNumberOrString)(valB)) {
+            throw new TypeError('Callback must return number or string');
+        }
+        if (valA > valB)
+            return direction === 'asc' ? 1 : -1;
+        if (valA < valB)
+            return direction === 'asc' ? -1 : 1;
+        return 0;
+    });
+}

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

@@ -0,0 +1,25 @@
+export {};
+declare global {
+    interface Map<K, V> {
+        /**
+         * Converts the Map into a list or object, depending on the selected type.
+         * - `entries` (default): returns `[K, V][]`
+         * - `keys`: returns `K[]`
+         * - `values`: returns `V[]`
+         * - `object`: returns `{ [key: string]: V }`
+         */
+        toList(type: 'keys'): K[];
+        toList(type: 'values'): V[];
+        toList(type: 'object'): Record<string, V>;
+        toList(type: 'entries'): [K, V][];
+        toList(): [K, V][];
+        /**
+         * Ensures that the value for the given key is an array.
+         * If the key does not exist, it sets it to an empty array.
+         *
+         * @param key - The key to look up in the map.
+         * @returns The array associated with the key.
+         */
+        ensureArray<L extends Array<any>>(this: Map<K, L>, key: K): L;
+    }
+}

package/dist/map/map-prototype.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("../utils");
+(0, utils_1.defineIfNotExists)(Map.prototype, 'toList', function (type = 'entries') {
+    switch (type) {
+        case 'keys':
+            return Array.from(this.keys());
+        case 'values':
+            return Array.from(this.values());
+        case 'object': {
+            const obj = {};
+            for (const [key, value] of this) {
+                if (typeof key === 'string' || typeof key === 'number' || typeof key === 'symbol') {
+                    // For number keys, convert to string (object keys are always strings or symbols)
+                    obj[String(key)] = value;
+                }
+                else {
+                    throw new TypeError(`Map.prototype.toList('object') only supports string, number, or symbol keys. Got: ${typeof key}`);
+                }
+            }
+            return obj;
+        }
+        case 'entries':
+            return Array.from(this.entries());
+        default:
+            throw new TypeError(`Unknown type "${type}" for Map.prototype.toList`);
+    }
+});
+(0, utils_1.defineIfNotExists)(Map.prototype, 'ensureArray', function (key) {
+    if (key === null || key === undefined) {
+        throw new TypeError('Key cannot be null or undefined');
+    }
+    if (!this.has(key)) {
+        this.set(key, []);
+    }
+    const arr = this.get(key);
+    if (!Array.isArray(arr)) {
+        throw new TypeError('Value for the key is not an array');
+    }
+    return arr;
+});

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

@@ -0,0 +1,27 @@
+export {};
+declare global {
+    interface Set<T> {
+        /**
+         * Converts the Set into an array, preserving insertion order.
+         * @returns An array of all values in the Set.
+         */
+        toList<T>(): T[];
+        /**
+         * Returns true if at least one of the given items is present in the set.
+         */
+        hasAny(...items: T[]): boolean;
+        /**
+         * Returns true if all of the given items are present in the set.
+         */
+        includes(...items: T[]): boolean;
+        includes(items: Set<T>): boolean;
+        /**
+         * Returns a new Set that is the union of this set and all given sets.
+         */
+        union(...others: Set<T>[]): Set<T>;
+        /**
+         * Returns a new Set that is the intersection of this set and all given sets.
+         */
+        intersection(...others: Set<T>[]): Set<T>;
+    }
+}

package/dist/set/set-prototype.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("../utils");
+(0, 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) {
+    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) {
+    let values;
+    if (args.length === 0)
+        return true; // empty means "all included" (like [].every)
+    if (args.length === 1 && args[0] instanceof Set) {
+        values = Array.from(args[0]);
+    }
+    else {
+        values = args;
+    }
+    if (!Array.isArray(values))
+        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) {
+    const result = new Set(this);
+    for (const other of others) {
+        if (!(other instanceof Set))
+            throw new TypeError('Arguments must be Sets');
+        for (const item of other) {
+            result.add(item);
+        }
+    }
+    return result;
+});
+(0, 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();
+    for (const item of this) {
+        if (others.every((set) => set.has(item))) {
+            result.add(item);
+        }
+    }
+    return result;
+});

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

@@ -47,5 +47,16 @@ declare global {
          * @returns A slugified version of the string.
          */
         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.
+         *
+         * @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.
+         */
+        replaceRange(start: number, end: number, replaceString?: string): string;
     }
 }

package/dist/string/string-prototype.js

@@ -12,7 +12,7 @@ const utils_1 = require("../utils");
 (0, 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))
+        .map((word, i) => (i === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1)))
         .join('');
 });
 (0, utils_1.defineIfNotExists)(String.prototype, 'kebabCase', function () {
@@ -49,3 +49,17 @@ const utils_1 = require("../utils");
         return '';
     return this.charAt(0).toUpperCase() + this.slice(1);
 });
+(0, 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');
+    }
+    if (start < 0 || end < 0) {
+        throw new RangeError('start or end cannot be negative');
+    }
+    if (start > this.length || end > this.length) {
+        throw new RangeError('start or end is out of bounds');
+    }
+    if (start > end)
+        [start, end] = [end, start];
+    return this.slice(0, start) + (replaceString ?? '') + this.slice(end);
+});

package/dist/utils.d.ts

@@ -1 +1,28 @@
 export declare const defineIfNotExists: <T extends object>(prototype: T, name: string, fn: Function) => void;
+/**
+ * Defines a **static** property on a constructor if it does not already exist
+ * (or if the existing property is writable **or** configurable).
+ *
+ * - Does **not** affect instance prototypes (use `defineIfNotExists` for `Foo.prototype`).
+ * - The property is created with: { enumerable: false, configurable: false, writable: false }
+ *   making it non-enumerable and immutable after definition.
+ * - If an existing property is non-configurable AND non-writable, it will **not** be replaced.
+ *
+ * @template T
+ * @param {T} constructor The constructor object (e.g., `Array`, `String`, `Map`, ...)
+ * @param {string} name The name of the static method to define (e.g., `'create'`, `'range'`)
+ * @param {Function} fn The function to attach as a static property
+ *
+ * @example
+ * // Define Array.range if possible
+ * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) { ... });
+ *
+ * @remarks
+ * - To force replacement, delete the property first or use Object.defineProperty directly.
+ * - This function is meant to standardize the addition of static methods in utilitish.
+ */
+export declare const defineStaticIfNotExists: <T extends object>(constructor: T, name: string, fn: Function) => void;
+export declare function resolveSelector<T, R>(selector?: keyof T | ((item: T) => R), fallback?: (item: T, index?: number) => R, name?: string): (item: T, index?: number) => R;
+export declare function assertValidSelector<T, R>(selector: any, name?: string): asserts selector is Selector<T, R>;
+export declare function isNumberOrString(value: unknown): value is string | number;
+export type Selector<T, K> = keyof T | ((item: T) => K);

package/dist/utils.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineIfNotExists = void 0;
+exports.defineStaticIfNotExists = exports.defineIfNotExists = void 0;
+exports.resolveSelector = resolveSelector;
+exports.assertValidSelector = assertValidSelector;
+exports.isNumberOrString = isNumberOrString;
 const defineIfNotExists = (prototype, name, fn) => {
     const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
     if (!descriptor || descriptor.writable || descriptor.configurable) {
@@ -13,3 +16,65 @@ const defineIfNotExists = (prototype, name, fn) => {
     }
 };
 exports.defineIfNotExists = defineIfNotExists;
+/**
+ * Defines a **static** property on a constructor if it does not already exist
+ * (or if the existing property is writable **or** configurable).
+ *
+ * - Does **not** affect instance prototypes (use `defineIfNotExists` for `Foo.prototype`).
+ * - The property is created with: { enumerable: false, configurable: false, writable: false }
+ *   making it non-enumerable and immutable after definition.
+ * - If an existing property is non-configurable AND non-writable, it will **not** be replaced.
+ *
+ * @template T
+ * @param {T} constructor The constructor object (e.g., `Array`, `String`, `Map`, ...)
+ * @param {string} name The name of the static method to define (e.g., `'create'`, `'range'`)
+ * @param {Function} fn The function to attach as a static property
+ *
+ * @example
+ * // Define Array.range if possible
+ * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) { ... });
+ *
+ * @remarks
+ * - To force replacement, delete the property first or use Object.defineProperty directly.
+ * - This function is meant to standardize the addition of static methods in utilitish.
+ */
+const defineStaticIfNotExists = (constructor, name, fn) => {
+    const descriptor = Object.getOwnPropertyDescriptor(constructor, name);
+    if (!descriptor || descriptor.writable || descriptor.configurable) {
+        Object.defineProperty(constructor, name, {
+            value: fn,
+            enumerable: false,
+            configurable: false,
+            writable: false,
+        });
+    }
+};
+exports.defineStaticIfNotExists = defineStaticIfNotExists;
+function resolveSelector(selector, fallback, name = 'selector') {
+    assertValidSelector(selector);
+    if (typeof selector === 'function') {
+        return selector;
+    }
+    if (typeof selector === 'string') {
+        return (item) => item[selector];
+    }
+    if (selector) {
+        throw new TypeError(`${name} must be a function or a string key`);
+    }
+    if (fallback) {
+        if (typeof fallback === 'function') {
+            return fallback;
+        }
+        throw new TypeError(`fallback must be a function`);
+    }
+    throw new TypeError(`fallback must be given if no selector`);
+}
+function assertValidSelector(selector, name = 'selector') {
+    const isValid = typeof selector === 'function' || typeof selector === 'string';
+    if (selector !== undefined && !isValid) {
+        throw new TypeError(`${name} must be a function or a string key`);
+    }
+}
+function isNumberOrString(value) {
+    return typeof value === 'string' || typeof value === 'number';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utilitish",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,8 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "jest"
+    "test": "jest",
+    "docs": "typedoc"
   },
   "keywords": [
     "typescript",
@@ -22,6 +23,7 @@
     "@types/jest": "^29.5.14",
     "jest": "^29.7.0",
     "ts-jest": "^29.3.4",
+    "typedoc": "^0.28.10",
     "typescript": "^5.8.3"
   }
 }