utilitish 0.0.4 → 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/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,4 +1,27 @@
 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;

package/dist/utils.js

@@ -1,6 +1,6 @@
 "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;
@@ -16,6 +16,40 @@ 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') {

package/package.json

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