utilitish 0.0.4 → 0.0.6

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

@@ -2,25 +2,98 @@ 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
+         * const arr1 = Array.create('x', 5);
+         * // type: string[]
+         * // value: ['x', 'x', 'x', 'x', 'x']
+         *
+         * @example
+         * // 1D array with random numbers
+         * const arr2 = Array.create(() => Math.random(), 5);
+         * // type: number[]
+         * // value: [0.12, 0.87, 0.45, 0.76, 0.33] (values will differ)
+         *
+         * @example
+         * // 2D array (matrix)
+         * const arr3 = Array.create(0, 2, 3);
+         * // type: number[][]
+         * // value: [[0, 0, 0], [0, 0, 0]]
+         *
+         * @example
+         * // 2D array with distinct objects
+         * const arr4 = Array.create(() => ({ id: 0 }), 2, 3);
+         * // type: { id: number }[][]
+         * // value: [
+         * //   [{ 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 {Array} A multi-dimensional array of the specified depth filled with the given values.
+         *
+         * @remarks
+         * - This method is **static** and must be called on `Array`, not on an instance.
+         */
+        create<T, Dims extends number[]>(valueOrFactory: T | (() => T), ...sizes: Dims): MultiDimensionalArray<WidenLiterals<T>, Dims>;
     }
 }
+type MultiDimensionalArray<T, Dims extends number[]> = Dims extends [number, ...infer Rest extends number[]] ? MultiDimensionalArray<T[], Rest> : T;
+type WidenLiterals<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;

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/index.d.ts

@@ -1,4 +1,6 @@
 import './array/array-constructor';
 import './array/array-prototype';
+import './map/map-prototype';
 import './object/object-prototype';
+import './set/set-prototype';
 import './string/string-prototype';

package/dist/index.js

@@ -2,5 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 require("./array/array-constructor");
 require("./array/array-prototype");
+require("./map/map-prototype");
 require("./object/object-prototype");
+require("./set/set-prototype");
 require("./string/string-prototype");

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

@@ -20,6 +20,6 @@ declare global {
          * @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[];
+        ensureArray<L extends Array<any>>(this: Map<K, L>, key: K): L;
     }
 }

package/dist/map/map-prototype.js

@@ -27,8 +27,15 @@ const utils_1 = require("../utils");
     }
 });
 (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, []);
     }
-    return this.get(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/utils.d.ts

@@ -1,5 +1,103 @@
+/**
+ * Defines a **non-enumerable, non-writable, non-configurable** property on a prototype
+ * if it does not already exist, or if the existing property is writable or configurable.
+ *
+ * - Intended for instance prototype methods (e.g., `Array.prototype`, `String.prototype`).
+ * - Does **not** overwrite non-configurable and non-writable properties.
+ * - Ensures immutability and hides the property from enumeration.
+ *
+ * @example
+ * defineIfNotExists(Array.prototype, 'last', function() {
+ *   return this[this.length - 1];
+ * });
+ *
+ * @template T The prototype object type (e.g., `Array.prototype`).
+ * @param {T} prototype The prototype on which to define the method.
+ * @param {string} name The name of the method to define.
+ * @param {Function} fn The function to assign as the method.
+ *
+ * @remarks
+ * Use this function to safely add prototype methods without overwriting stable or built-in ones.
+ */
 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.
+ *
+ * - Only affects static properties on constructors (e.g., `Array`, `Map`).
+ * - The property is created as non-enumerable, immutable, and non-configurable.
+ * - Does **not** overwrite existing properties that are non-configurable and non-writable.
+ *
+ * @example
+ * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) {
+ *   // implementation
+ * });
+ *
+ * @template T The constructor type (e.g., `typeof Array`).
+ * @param {T} constructor The constructor object on which to define the static method.
+ * @param {string} name The name of the static method to define.
+ * @param {Function} fn The function to assign as the static method.
+ *
+ * @remarks
+ * To forcefully replace an existing property, delete it first or use `Object.defineProperty` directly.
+ */
+export declare const defineStaticIfNotExists: <T extends object>(constructor: T, name: string, fn: Function) => void;
+/**
+ * Resolves a selector parameter into a function that extracts a value from an item.
+ *
+ * The selector can be:
+ * - a key string of the object (returns the value at that key),
+ * - a function transforming the item to the desired value,
+ * - or undefined, in which case a fallback function must be provided.
+ *
+ * @example
+ * const sel1 = resolveSelector<{name: string}, string>('name');
+ * sel1({name: 'Alice'}); // 'Alice'
+ *
+ * const sel2 = resolveSelector<{value: number}, number>(item => item.value * 2);
+ * sel2({value: 5}); // 10
+ *
+ * const sel3 = resolveSelector(undefined, (item) => item.toString());
+ * sel3(42); // '42'
+ *
+ * @template T The type of the input items.
+ * @template R The type of the selected value.
+ * @param {keyof T | ((item: T) => R) | undefined} selector The selector key or function.
+ * @param {(item: T, index?: number) => R} [fallback] A fallback function if no selector is provided.
+ * @param {string} [name='selector'] Name used in error messages.
+ * @returns {(item: T, index?: number) => R} The resolved selector function.
+ *
+ * @throws {TypeError} If the selector is not a function or string key.
+ * @throws {TypeError} If no selector is provided and no fallback is given.
+ */
 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;
+/**
+ * Asserts that a selector parameter is valid, i.e., a function or a string.
+ *
+ * @template T The type of the input items.
+ * @template R The type of the selected value.
+ * @param {any} selector The selector to validate.
+ * @param {string} [name='selector'] The name to use in error messages.
+ *
+ * @throws {TypeError} If the selector is neither a function nor a string.
+ *
+ * @remarks
+ * Used internally by `resolveSelector` to provide clearer type safety and errors.
+ */
 export declare function assertValidSelector<T, R>(selector: any, name?: string): asserts selector is Selector<T, R>;
+/**
+ * Type guard to check if a value is a string or number.
+ *
+ * @example
+ * isNumberOrString('hello'); // true
+ * isNumberOrString(42);      // true
+ * isNumberOrString(true);    // false
+ *
+ * @param {unknown} value The value to test.
+ * @returns {value is string | number} True if the value is a string or number, else false.
+ */
 export declare function isNumberOrString(value: unknown): value is string | number;
+/**
+ * Type for a selector: either a key of T or a function from T to K.
+ */
 export type Selector<T, K> = keyof T | ((item: T) => K);

package/dist/utils.js

@@ -1,9 +1,30 @@
 "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;
+/**
+ * Defines a **non-enumerable, non-writable, non-configurable** property on a prototype
+ * if it does not already exist, or if the existing property is writable or configurable.
+ *
+ * - Intended for instance prototype methods (e.g., `Array.prototype`, `String.prototype`).
+ * - Does **not** overwrite non-configurable and non-writable properties.
+ * - Ensures immutability and hides the property from enumeration.
+ *
+ * @example
+ * defineIfNotExists(Array.prototype, 'last', function() {
+ *   return this[this.length - 1];
+ * });
+ *
+ * @template T The prototype object type (e.g., `Array.prototype`).
+ * @param {T} prototype The prototype on which to define the method.
+ * @param {string} name The name of the method to define.
+ * @param {Function} fn The function to assign as the method.
+ *
+ * @remarks
+ * Use this function to safely add prototype methods without overwriting stable or built-in ones.
+ */
 const defineIfNotExists = (prototype, name, fn) => {
     const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
     if (!descriptor || descriptor.writable || descriptor.configurable) {
@@ -16,6 +37,67 @@ 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.
+ *
+ * - Only affects static properties on constructors (e.g., `Array`, `Map`).
+ * - The property is created as non-enumerable, immutable, and non-configurable.
+ * - Does **not** overwrite existing properties that are non-configurable and non-writable.
+ *
+ * @example
+ * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) {
+ *   // implementation
+ * });
+ *
+ * @template T The constructor type (e.g., `typeof Array`).
+ * @param {T} constructor The constructor object on which to define the static method.
+ * @param {string} name The name of the static method to define.
+ * @param {Function} fn The function to assign as the static method.
+ *
+ * @remarks
+ * To forcefully replace an existing property, delete it first or use `Object.defineProperty` directly.
+ */
+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;
+/**
+ * Resolves a selector parameter into a function that extracts a value from an item.
+ *
+ * The selector can be:
+ * - a key string of the object (returns the value at that key),
+ * - a function transforming the item to the desired value,
+ * - or undefined, in which case a fallback function must be provided.
+ *
+ * @example
+ * const sel1 = resolveSelector<{name: string}, string>('name');
+ * sel1({name: 'Alice'}); // 'Alice'
+ *
+ * const sel2 = resolveSelector<{value: number}, number>(item => item.value * 2);
+ * sel2({value: 5}); // 10
+ *
+ * const sel3 = resolveSelector(undefined, (item) => item.toString());
+ * sel3(42); // '42'
+ *
+ * @template T The type of the input items.
+ * @template R The type of the selected value.
+ * @param {keyof T | ((item: T) => R) | undefined} selector The selector key or function.
+ * @param {(item: T, index?: number) => R} [fallback] A fallback function if no selector is provided.
+ * @param {string} [name='selector'] Name used in error messages.
+ * @returns {(item: T, index?: number) => R} The resolved selector function.
+ *
+ * @throws {TypeError} If the selector is not a function or string key.
+ * @throws {TypeError} If no selector is provided and no fallback is given.
+ */
 function resolveSelector(selector, fallback, name = 'selector') {
     assertValidSelector(selector);
     if (typeof selector === 'function') {
@@ -35,12 +117,36 @@ function resolveSelector(selector, fallback, name = 'selector') {
     }
     throw new TypeError(`fallback must be given if no selector`);
 }
+/**
+ * Asserts that a selector parameter is valid, i.e., a function or a string.
+ *
+ * @template T The type of the input items.
+ * @template R The type of the selected value.
+ * @param {any} selector The selector to validate.
+ * @param {string} [name='selector'] The name to use in error messages.
+ *
+ * @throws {TypeError} If the selector is neither a function nor a string.
+ *
+ * @remarks
+ * Used internally by `resolveSelector` to provide clearer type safety and errors.
+ */
 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`);
     }
 }
+/**
+ * Type guard to check if a value is a string or number.
+ *
+ * @example
+ * isNumberOrString('hello'); // true
+ * isNumberOrString(42);      // true
+ * isNumberOrString(true);    // false
+ *
+ * @param {unknown} value The value to test.
+ * @returns {value is string | number} True if the value is a string or number, else false.
+ */
 function isNumberOrString(value) {
     return typeof value === 'string' || typeof value === 'number';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utilitish",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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"
   }
 }