utilitish 0.0.5 → 0.0.6

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

@@ -53,26 +53,30 @@ declare global {
          *
          * @example
          * // 1D array with primitive values
-         * Array.create('x', 5);
-         * // => ['x', 'x', 'x', 'x', 'x']
+         * const arr1 = Array.create('x', 5);
+         * // type: string[]
+         * // value: ['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)
+         * 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)
-         * Array.create(0, 2, 3);
-         * // => [[0, 0, 0], [0, 0, 0]]
+         * const arr3 = Array.create(0, 2, 3);
+         * // type: number[][]
+         * // value: [[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}]
-         * //    ]
+         * 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 `[]`.
@@ -83,11 +87,13 @@ declare global {
          * @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`.
+         * @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>(valueOrFactory: T | (() => T), ...sizes: number[]): any[];
+        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/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/utils.d.ts

@@ -1,28 +1,103 @@
-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).
+ * 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];
+ * });
  *
- * - 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 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.
  *
- * @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
+ * - 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
- * // Define Array.range if possible
- * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) { ... });
+ * 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 force replacement, delete the property first or use Object.defineProperty directly.
- * - This function is meant to standardize the addition of static methods in utilitish.
+ * 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

@@ -4,6 +4,27 @@ 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) {
@@ -17,26 +38,25 @@ 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).
+ * 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
+ * - 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
- * // Define Array.range if possible
- * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) { ... });
+ * 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 force replacement, delete the property first or use Object.defineProperty directly.
- * - This function is meant to standardize the addition of static methods in utilitish.
+ * 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);
@@ -50,6 +70,34 @@ const defineStaticIfNotExists = (constructor, name, fn) => {
     }
 };
 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') {
@@ -69,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.5",
+  "version": "0.0.6",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",