@alextheman/utility 3.5.7 → 3.5.9

package/dist/index.cjs

@@ -51,9 +51,12 @@ var appendSemicolon_default = appendSemicolon;
 *
 * If the callback returns at least one Promise, the entire result will be wrapped
 * in a `Promise` and resolved with `Promise.all`. Otherwise, a plain array is returned.
+*
 * @template ItemType
+*
 * @param callback - A function invoked with the current index. May return a value or a Promise.
-* @param [length] - The desired length of the resulting array.
+* @param length - The desired length of the resulting array.
+*
 * @returns An array of the callback results, or a Promise resolving to one if the callback is async.
 */
 function fillArray(callback, length = 1) {
@@ -74,10 +77,13 @@ var fillArray_default = fillArray;
 *
 * If `secondArray` is shorter than `firstArray`, the second position in the tuple
 * will be `undefined`. Iteration always uses the length of the first array.
+*
 * @template FirstArrayItem
 * @template SecondArrayItem
+*
 * @param firstArray - The first array. Each item in this will take up the first tuple spot.
 * @param secondArray - The second array. Each item in this will take up the second tuple spot.
+*
 * @returns An array of `[firstItem, secondItem]` tuples for each index in `firstArray`.
 */
 function paralleliseArrays(firstArray, secondArray) {
@@ -113,6 +119,15 @@ var getRandomNumber_default = getRandomNumber;
 
 //#endregion
 //#region src/functions/arrayHelpers/randomiseArray.ts
+/**
+* Randomises the order of a given array and returns the result in a new array without mutating the original.
+*
+* @template ItemType - The type of the array items.
+*
+* @param array - The array to randomise.
+*
+* @returns A new array with the items randomised.
+*/
 function randomiseArray(array) {
 	const mutableArray = [...array];
 	const outputArray = [];
@@ -126,6 +141,21 @@ var randomiseArray_default = randomiseArray;
 
 //#endregion
 //#region src/functions/arrayHelpers/range.ts
+/**
+* Creates an array of numbers within a given range.
+*
+* The range is inclusive of `start` and exclusive of `stop`.
+* The sign of `step` must match the direction of the range.
+*
+* @param start - The number to start at (inclusive).
+* @param stop - The number to stop at (exclusive).
+* @param step - The step size between numbers, defaulting to 1.
+*
+* @throws {Error} If `step` is `0`.
+* @throws {Error} If `step` direction does not match the order of `start` and `stop`.
+*
+* @returns An array of numbers satisfying the range provided.
+*/
 function range(start, stop, step = 1) {
 	const numbers = [];
 	if (step === 0) throw new Error("ZERO_STEP_SIZE_NOT_ALLOWED");

package/dist/index.d.cts

@@ -12,9 +12,12 @@ declare function appendSemicolon(stringToAppendTo: string): string;
  *
  * The callback will be invoked once for each index from `0` to `length - 1`.
  * If no length is provided, a single-element array will be produced.
+ *
  * @template ItemType
+ *
  * @param callback - An asynchronous function invoked with the current index.
- * @param [length] - The desired length of the resulting array.
+ * @param length - The desired length of the resulting array.
+ *
  * @returns A Promise resolving to an array of the callback results.
  */
 declare function fillArray<ItemType$1>(callback: (index: number) => Promise<ItemType$1>, length?: number): Promise<ItemType$1[]>;
@@ -23,9 +26,12 @@ declare function fillArray<ItemType$1>(callback: (index: number) => Promise<Item
  *
  * The callback will be invoked once for each index from `0` to `length - 1`.
  * If no length is provided, a single-element array will be produced.
+ *
  * @template ItemType
+ *
  * @param callback - A synchronous function invoked with the current index.
- * @param [length] - The desired length of the resulting array.
+ * @param length - The desired length of the resulting array.
+ *
  * @returns An array of the callback results.
  */
 declare function fillArray<ItemType$1>(callback: (index: number) => ItemType$1, length?: number): ItemType$1[];
@@ -37,18 +43,45 @@ type ParallelTuple<A, B> = [A, B | undefined];
  *
  * If `secondArray` is shorter than `firstArray`, the second position in the tuple
  * will be `undefined`. Iteration always uses the length of the first array.
+ *
  * @template FirstArrayItem
  * @template SecondArrayItem
+ *
  * @param firstArray - The first array. Each item in this will take up the first tuple spot.
  * @param secondArray - The second array. Each item in this will take up the second tuple spot.
+ *
  * @returns An array of `[firstItem, secondItem]` tuples for each index in `firstArray`.
  */
 declare function paralleliseArrays<FirstArrayItem, SecondArrayItem>(firstArray: readonly FirstArrayItem[], secondArray: readonly SecondArrayItem[]): ParallelTuple<FirstArrayItem, SecondArrayItem>[];
 //#endregion
 //#region src/functions/arrayHelpers/randomiseArray.d.ts
-declare function randomiseArray<T>(array: T[]): T[];
+/**
+ * Randomises the order of a given array and returns the result in a new array without mutating the original.
+ *
+ * @template ItemType - The type of the array items.
+ *
+ * @param array - The array to randomise.
+ *
+ * @returns A new array with the items randomised.
+ */
+declare function randomiseArray<ItemType$1>(array: ItemType$1[]): ItemType$1[];
 //#endregion
 //#region src/functions/arrayHelpers/range.d.ts
+/**
+ * Creates an array of numbers within a given range.
+ *
+ * The range is inclusive of `start` and exclusive of `stop`.
+ * The sign of `step` must match the direction of the range.
+ *
+ * @param start - The number to start at (inclusive).
+ * @param stop - The number to stop at (exclusive).
+ * @param step - The step size between numbers, defaulting to 1.
+ *
+ * @throws {Error} If `step` is `0`.
+ * @throws {Error} If `step` direction does not match the order of `start` and `stop`.
+ *
+ * @returns An array of numbers satisfying the range provided.
+ */
 declare function range(start: number, stop: number, step?: number): number[];
 //#endregion
 //#region src/functions/camelToKebab.d.ts

package/dist/index.d.ts

@@ -12,9 +12,12 @@ declare function appendSemicolon(stringToAppendTo: string): string;
  *
  * The callback will be invoked once for each index from `0` to `length - 1`.
  * If no length is provided, a single-element array will be produced.
+ *
  * @template ItemType
+ *
  * @param callback - An asynchronous function invoked with the current index.
- * @param [length] - The desired length of the resulting array.
+ * @param length - The desired length of the resulting array.
+ *
  * @returns A Promise resolving to an array of the callback results.
  */
 declare function fillArray<ItemType$1>(callback: (index: number) => Promise<ItemType$1>, length?: number): Promise<ItemType$1[]>;
@@ -23,9 +26,12 @@ declare function fillArray<ItemType$1>(callback: (index: number) => Promise<Item
  *
  * The callback will be invoked once for each index from `0` to `length - 1`.
  * If no length is provided, a single-element array will be produced.
+ *
  * @template ItemType
+ *
  * @param callback - A synchronous function invoked with the current index.
- * @param [length] - The desired length of the resulting array.
+ * @param length - The desired length of the resulting array.
+ *
  * @returns An array of the callback results.
  */
 declare function fillArray<ItemType$1>(callback: (index: number) => ItemType$1, length?: number): ItemType$1[];
@@ -37,18 +43,45 @@ type ParallelTuple<A, B> = [A, B | undefined];
  *
  * If `secondArray` is shorter than `firstArray`, the second position in the tuple
  * will be `undefined`. Iteration always uses the length of the first array.
+ *
  * @template FirstArrayItem
  * @template SecondArrayItem
+ *
  * @param firstArray - The first array. Each item in this will take up the first tuple spot.
  * @param secondArray - The second array. Each item in this will take up the second tuple spot.
+ *
  * @returns An array of `[firstItem, secondItem]` tuples for each index in `firstArray`.
  */
 declare function paralleliseArrays<FirstArrayItem, SecondArrayItem>(firstArray: readonly FirstArrayItem[], secondArray: readonly SecondArrayItem[]): ParallelTuple<FirstArrayItem, SecondArrayItem>[];
 //#endregion
 //#region src/functions/arrayHelpers/randomiseArray.d.ts
-declare function randomiseArray<T>(array: T[]): T[];
+/**
+ * Randomises the order of a given array and returns the result in a new array without mutating the original.
+ *
+ * @template ItemType - The type of the array items.
+ *
+ * @param array - The array to randomise.
+ *
+ * @returns A new array with the items randomised.
+ */
+declare function randomiseArray<ItemType$1>(array: ItemType$1[]): ItemType$1[];
 //#endregion
 //#region src/functions/arrayHelpers/range.d.ts
+/**
+ * Creates an array of numbers within a given range.
+ *
+ * The range is inclusive of `start` and exclusive of `stop`.
+ * The sign of `step` must match the direction of the range.
+ *
+ * @param start - The number to start at (inclusive).
+ * @param stop - The number to stop at (exclusive).
+ * @param step - The step size between numbers, defaulting to 1.
+ *
+ * @throws {Error} If `step` is `0`.
+ * @throws {Error} If `step` direction does not match the order of `start` and `stop`.
+ *
+ * @returns An array of numbers satisfying the range provided.
+ */
 declare function range(start: number, stop: number, step?: number): number[];
 //#endregion
 //#region src/functions/camelToKebab.d.ts

package/dist/index.js

@@ -22,9 +22,12 @@ var appendSemicolon_default = appendSemicolon;
 *
 * If the callback returns at least one Promise, the entire result will be wrapped
 * in a `Promise` and resolved with `Promise.all`. Otherwise, a plain array is returned.
+*
 * @template ItemType
+*
 * @param callback - A function invoked with the current index. May return a value or a Promise.
-* @param [length] - The desired length of the resulting array.
+* @param length - The desired length of the resulting array.
+*
 * @returns An array of the callback results, or a Promise resolving to one if the callback is async.
 */
 function fillArray(callback, length = 1) {
@@ -45,10 +48,13 @@ var fillArray_default = fillArray;
 *
 * If `secondArray` is shorter than `firstArray`, the second position in the tuple
 * will be `undefined`. Iteration always uses the length of the first array.
+*
 * @template FirstArrayItem
 * @template SecondArrayItem
+*
 * @param firstArray - The first array. Each item in this will take up the first tuple spot.
 * @param secondArray - The second array. Each item in this will take up the second tuple spot.
+*
 * @returns An array of `[firstItem, secondItem]` tuples for each index in `firstArray`.
 */
 function paralleliseArrays(firstArray, secondArray) {
@@ -84,6 +90,15 @@ var getRandomNumber_default = getRandomNumber;
 
 //#endregion
 //#region src/functions/arrayHelpers/randomiseArray.ts
+/**
+* Randomises the order of a given array and returns the result in a new array without mutating the original.
+*
+* @template ItemType - The type of the array items.
+*
+* @param array - The array to randomise.
+*
+* @returns A new array with the items randomised.
+*/
 function randomiseArray(array) {
 	const mutableArray = [...array];
 	const outputArray = [];
@@ -97,6 +112,21 @@ var randomiseArray_default = randomiseArray;
 
 //#endregion
 //#region src/functions/arrayHelpers/range.ts
+/**
+* Creates an array of numbers within a given range.
+*
+* The range is inclusive of `start` and exclusive of `stop`.
+* The sign of `step` must match the direction of the range.
+*
+* @param start - The number to start at (inclusive).
+* @param stop - The number to stop at (exclusive).
+* @param step - The step size between numbers, defaulting to 1.
+*
+* @throws {Error} If `step` is `0`.
+* @throws {Error} If `step` direction does not match the order of `start` and `stop`.
+*
+* @returns An array of numbers satisfying the range provided.
+*/
 function range(start, stop, step = 1) {
 	const numbers = [];
 	if (step === 0) throw new Error("ZERO_STEP_SIZE_NOT_ALLOWED");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "3.5.7",
+  "version": "3.5.9",
   "description": "Helpful utility functions",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
     "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@alextheman/eslint-plugin": "^4.5.1",
+    "@alextheman/eslint-plugin": "^4.8.0",
     "@types/node": "^25.0.1",
     "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.1",