utilitish 0.0.5 → 0.0.7

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/array/array-constructor.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const utils_1 = require("../utils");
+const core_utils_1 = require("../utils/core.utils");
 /**
  * @see Array.zip
  */
-(0, utils_1.defineStaticIfNotExists)(Array, 'zip', function (...arrays) {
+(0, core_utils_1.defineStaticIfNotExists)(Array, 'zip', function (...arrays) {
     if (arrays.length === 0)
         return [];
     const maxLen = Math.max(...arrays.map((arr) => arr.length));
@@ -13,7 +13,7 @@ const utils_1 = require("../utils");
 /**
  * @see Array.range
  */
-(0, utils_1.defineStaticIfNotExists)(Array, 'range', function (start, end, step = 1) {
+(0, core_utils_1.defineStaticIfNotExists)(Array, 'range', function (start, end, step = 1) {
     if (end === undefined) {
         end = start;
         start = 0;
@@ -30,7 +30,7 @@ const utils_1 = require("../utils");
 /**
  * @see Array.repeat
  */
-(0, utils_1.defineStaticIfNotExists)(Array, 'repeat', function (length, value) {
+(0, core_utils_1.defineStaticIfNotExists)(Array, 'repeat', function (length, value) {
     if (typeof length !== 'number' || !Number.isInteger(length) || length < 0) {
         throw new TypeError('Length must be a non-negative integer');
     }
@@ -39,7 +39,7 @@ const utils_1 = require("../utils");
 /**
  * @see Array.create
  */
-(0, utils_1.defineStaticIfNotExists)(Array, 'create', function (valueOrFactory, ...sizes) {
+(0, core_utils_1.defineStaticIfNotExists)(Array, 'create', function (valueOrFactory, ...sizes) {
     if (sizes.length === 0)
         return [];
     if (!sizes.every((s) => Number.isInteger(s) && s >= 0)) {

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

@@ -0,0 +1,2 @@
+import '../array/array-constructor';
+import './array-constructor';

package/dist/array/array-constructor.spec.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("../array/array-constructor");
+require("./array-constructor");
+describe('Array', () => {
+    describe('range()', () => {
+        it('should generate a range from 0 to n-1 if only start is given', () => {
+            expect(Array.range(5)).toEqual([0, 1, 2, 3, 4]);
+        });
+        it('should generate a range from start to end-1', () => {
+            expect(Array.range(2, 6)).toEqual([2, 3, 4, 5]);
+        });
+        it('should support negative steps', () => {
+            expect(Array.range(5, 1, -1)).toEqual([5, 4, 3, 2]);
+        });
+        it('should return an empty array if start equals end', () => {
+            expect(Array.range(3, 3)).toEqual([]);
+        });
+        it('should return an empty array if step does not reach end', () => {
+            expect(Array.range(0, 5, -1)).toEqual([]);
+            expect(Array.range(5, 0, 1)).toEqual([]);
+        });
+        describe('error handling', () => {
+            it('should throw if step is 0', () => {
+                expect(() => Array.range(0, 5, 0)).toThrowError('step must not be 0');
+            });
+        });
+    });
+    describe('repeat()', () => {
+        it('should fill an array with the same value', () => {
+            expect(Array.repeat(3, 'a')).toEqual(['a', 'a', 'a']);
+        });
+        it('should fill an array with values from a function', () => {
+            let n = 0;
+            expect(Array.repeat(4, () => ++n)).toEqual([1, 2, 3, 4]);
+        });
+        it('should return an empty array if length is 0', () => {
+            expect(Array.repeat(0, 'x')).toEqual([]);
+        });
+        describe('error handling', () => {
+            it('should throw if length is negative or not an integer', () => {
+                expect(() => Array.repeat(-1, 'a')).toThrowError();
+                expect(() => Array.repeat(1.5, 'a')).toThrowError();
+                expect(() => Array.repeat('a', 'a')).toThrowError();
+            });
+        });
+    });
+    describe('zip()', () => {
+        it('should zip two arrays of equal length', () => {
+            expect(Array.zip([1, 2, 3], ['a', 'b', 'c'])).toEqual([
+                [1, 'a'],
+                [2, 'b'],
+                [3, 'c'],
+            ]);
+        });
+        it('should zip arrays of different lengths (fill with undefined)', () => {
+            expect(Array.zip([1, 2], ['a', 'b', 'c'], [true, false, true])).toEqual([
+                [1, 'a', true],
+                [2, 'b', false],
+                [undefined, 'c', true],
+            ]);
+        });
+        it('should work with a single array', () => {
+            expect(Array.zip([1, 2, 3])).toEqual([[1], [2], [3]]);
+        });
+        it('should fill with undefined for missing elements', () => {
+            expect(Array.zip([1], [2, 3, 4])).toEqual([
+                [1, 2],
+                [undefined, 3],
+                [undefined, 4],
+            ]);
+        });
+        describe('edge cases', () => {
+            it('should return an empty array if no arrays are given', () => {
+                expect(Array.zip()).toEqual([]);
+            });
+            it('should return an array of undefined if all arrays are empty', () => {
+                expect(Array.zip([], [])).toEqual([]);
+            });
+        });
+    });
+    describe('create()', () => {
+        it('should create a 1D array', () => {
+            expect(Array.create('x', 3)).toEqual(['x', 'x', 'x']);
+        });
+        it('should create a 2D array', () => {
+            expect(Array.create(0, 2, 3)).toEqual([
+                [0, 0, 0],
+                [0, 0, 0],
+            ]);
+        });
+        it('should create a 3D array', () => {
+            expect(Array.create(true, 2, 2, 2)).toEqual([
+                [
+                    [true, true],
+                    [true, true],
+                ],
+                [
+                    [true, true],
+                    [true, true],
+                ],
+            ]);
+        });
+        describe('edge cases', () => {
+            it('should return [] if no sizes are given', () => {
+                expect(Array.create('x')).toEqual([]);
+            });
+            it('should return [] if any size is 0', () => {
+                expect(Array.create('x', 0)).toEqual([]);
+                expect(Array.create('x', 2, 0)).toEqual([[], []]);
+            });
+            it('should return arrays with the same object reference for objects', () => {
+                const obj = { a: 1 };
+                const arr = Array.create(obj, 2);
+                expect(arr[0]).toBe(obj);
+                expect(arr[1]).toBe(obj);
+            });
+        });
+        describe('error handling', () => {
+            it('should throw if a size is negative', () => {
+                expect(() => Array.create('x', -1)).toThrow(TypeError);
+                expect(() => Array.create('x', 2, -3)).toThrow(TypeError);
+            });
+            it('should throw if a size is not an integer', () => {
+                expect(() => Array.create('x', 2.5)).toThrow(TypeError);
+                expect(() => Array.create('x', 2, 1.1)).toThrow(TypeError);
+            });
+        });
+    });
+});