utilitish 0.0.2 → 0.0.4

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.
@@ -84,5 +90,43 @@ declare global {
          * @returns The array itself after swapping
          */
         swap(i: number, j: number): this;
+        /**
+         * Returns a new array with the elements shuffled in random order.
+         * Uses the Fisher-Yates shuffle algorithm.
+         * @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');
@@ -125,3 +96,59 @@ const utils_1 = require("../utils");
     }
     return this;
 });
+(0, utils_1.defineIfNotExists)(Array.prototype, 'shuffle', function () {
+    const arr = this.slice();
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    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(this: Map<K, V[]>, key: K): V[];
+    }
+}

package/dist/map/map-prototype.js

@@ -0,0 +1,34 @@
+"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 (!this.has(key)) {
+        this.set(key, []);
+    }
+    return this.get(key);
+});

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,5 @@
 export declare const defineIfNotExists: <T extends object>(prototype: 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.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,31 @@ const defineIfNotExists = (prototype, name, fn) => {
     }
 };
 exports.defineIfNotExists = defineIfNotExists;
+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.2",
+  "version": "0.0.4",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",