@alextheman/utility 5.17.1 → 5.18.1

package/dist/index.cjs

@@ -83,55 +83,6 @@ var APIError = class APIError extends Error {
 	}
 };
 //#endregion
-//#region src/root/functions/arrayHelpers/fillArray.ts
-/**
-* Creates a new array where each element is the result of the provided callback.
-*
-* 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.
-*
-* @category Array Helpers
-*
-* @template ItemType - The return type of the callback (awaited if any items are a Promise) that becomes the type of the array items.
-*
-* @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.
-*
-* @returns An array of the callback results, or a Promise resolving to one if the callback is async.
-*/
-function fillArray(callback, length = 1) {
-	const outputArray = new Array(length).fill(null).map((_, index) => {
-		return callback(index);
-	});
-	if (outputArray.some((item) => {
-		return item instanceof Promise;
-	})) return Promise.all(outputArray);
-	return outputArray;
-}
-//#endregion
-//#region src/root/functions/arrayHelpers/paralleliseArrays.ts
-/**
-* Creates a new array of tuples, each containing the item at the given index from both arrays.
-*
-* If `secondArray` is shorter than `firstArray`, the second position in the tuple
-* will be `undefined`. Iteration always uses the length of the first array.
-*
-* @category Array Helpers
-*
-* @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) {
-	const outputArray = [];
-	for (let i = 0; i < firstArray.length; i++) outputArray.push([firstArray[i], secondArray[i]]);
-	return outputArray;
-}
-//#endregion
 //#region src/v6/CodeError.ts
 /**
 * Represents errors that can be described using a standardised error code, and a human-readable error message.
@@ -335,6 +286,100 @@ var DataError$1 = class DataError$1 extends CodeError {
 	}
 };
 //#endregion
+//#region src/root/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.
+*
+* @category Array Helpers
+*
+* @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 {DataError} If `step` is `0`.
+* @throws {DataError} 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 DataError$1({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	else if (step > 0) {
+		if (start > stop) throw new DataError$1({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
+		for (let i = start; i < stop; i += step) numbers.push(i);
+	} else if (step < 0) {
+		if (start < stop) throw new DataError$1({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
+		for (let i = start; i > stop; i += step) numbers.push(i);
+	}
+	return numbers;
+}
+//#endregion
+//#region src/root/functions/arrayHelpers/fillArray.ts
+/**
+* Creates a new array where each element is the result of the provided callback.
+*
+* 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.
+*
+* @category Array Helpers
+*
+* @template ItemType - The return type of the callback (awaited if any items are a Promise) that becomes the type of the array items.
+*
+* @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 options - Extra options to apply if any item is asynchronous.
+*
+* @returns An array of the callback results, or a Promise resolving to one if the callback is async.
+*/
+function fillArray(callback, length = 1, options) {
+	if (options?.sequential) return (async () => {
+		const resolvedArray = [];
+		for (const index of range(0, length)) resolvedArray.push(await callback(index));
+		return resolvedArray;
+	})();
+	const outputArray = new Array(length).fill(null).map((_, index) => {
+		return callback(index);
+	});
+	if (outputArray.some((item) => {
+		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
+	})) return Promise.all(outputArray);
+	return outputArray;
+}
+//#endregion
+//#region src/root/functions/arrayHelpers/paralleliseArrays.ts
+/**
+* Creates a new array of tuples, each containing the item at the given index from both arrays.
+*
+* If `secondArray` is shorter than `firstArray`, the second position in the tuple
+* will be `undefined`. Iteration always uses the length of the first array.
+*
+* @category Array Helpers
+*
+* @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) {
+	const outputArray = [];
+	for (let i = 0; i < firstArray.length; i++) outputArray.push([firstArray[i], secondArray[i]]);
+	return outputArray;
+}
+//#endregion
 //#region src/root/functions/parsers/parseIntStrict.ts
 /**
 * Converts a string to an integer and throws an error if it cannot be converted.
@@ -405,45 +450,6 @@ function randomiseArray(array) {
 	return outputArray;
 }
 //#endregion
-//#region src/root/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.
-*
-* @category Array Helpers
-*
-* @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 {DataError} If `step` is `0`.
-* @throws {DataError} 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 DataError$1({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
-	else if (step > 0) {
-		if (start > stop) throw new DataError$1({
-			start,
-			stop,
-			step
-		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
-		for (let i = start; i < stop; i += step) numbers.push(i);
-	} else if (step < 0) {
-		if (start < stop) throw new DataError$1({
-			start,
-			stop,
-			step
-		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
-		for (let i = start; i > stop; i += step) numbers.push(i);
-	}
-	return numbers;
-}
-//#endregion
 //#region src/root/functions/arrayHelpers/removeDuplicates.ts
 /**
 * Removes duplicate values from an array.

package/dist/index.d.cts

@@ -113,6 +113,10 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
 type RecordKey = string | number | symbol;
 //#endregion
 //#region src/root/functions/arrayHelpers/fillArray.d.ts
+interface FillArrayAsyncOptions {
+  /** Resolve each array item sequentially rather than in parallel (defaults to parallel). */
+  sequential?: boolean;
+}
 /**
  * Creates a new array where each element is the resolved result of the provided asynchronous callback.
  *
@@ -123,10 +127,11 @@ type RecordKey = string | number | symbol;
  *
  * @param callback - An asynchronous function invoked with the current index.
  * @param length - The desired length of the resulting array.
+ * @param options - Extra options to apply.
  *
  * @returns A Promise resolving to an array of the callback results.
  */
-declare function fillArray<ItemType>(callback: (index: number) => Promise<ItemType>, length?: number): Promise<Array<ItemType>>;
+declare function fillArray<ItemType>(callback: (index: number) => Promise<ItemType>, length?: number, options?: FillArrayAsyncOptions): Promise<Array<ItemType>>;
 /**
  * Creates a new array where each element is the result of the provided synchronous callback.
  *
@@ -504,7 +509,7 @@ declare function getRecordKeys<InputRecordType extends Record<PropertyKey, unkno
  *
  * @returns An object with a new reference in memory, with the properties omitted.
  */
-declare function omitProperties<ObjectType extends Record<string, unknown> | Readonly<Record<string, unknown>>, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | ReadonlyArray<KeysToOmit>): Omit<ObjectType, KeysToOmit>;
+declare function omitProperties<ObjectType extends object, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | ReadonlyArray<KeysToOmit>): Omit<ObjectType, KeysToOmit>;
 //#endregion
 //#region src/root/functions/objectHelpers/removeUndefinedFromObject.d.ts
 type RemoveUndefined<RecordType extends Record<PropertyKey, unknown>> = { [Key in keyof RecordType]: Exclude<RecordType[Key], undefined> };

package/dist/index.d.ts

@@ -113,6 +113,10 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
 type RecordKey = string | number | symbol;
 //#endregion
 //#region src/root/functions/arrayHelpers/fillArray.d.ts
+interface FillArrayAsyncOptions {
+  /** Resolve each array item sequentially rather than in parallel (defaults to parallel). */
+  sequential?: boolean;
+}
 /**
  * Creates a new array where each element is the resolved result of the provided asynchronous callback.
  *
@@ -123,10 +127,11 @@ type RecordKey = string | number | symbol;
  *
  * @param callback - An asynchronous function invoked with the current index.
  * @param length - The desired length of the resulting array.
+ * @param options - Extra options to apply.
  *
  * @returns A Promise resolving to an array of the callback results.
  */
-declare function fillArray<ItemType>(callback: (index: number) => Promise<ItemType>, length?: number): Promise<Array<ItemType>>;
+declare function fillArray<ItemType>(callback: (index: number) => Promise<ItemType>, length?: number, options?: FillArrayAsyncOptions): Promise<Array<ItemType>>;
 /**
  * Creates a new array where each element is the result of the provided synchronous callback.
  *
@@ -504,7 +509,7 @@ declare function getRecordKeys<InputRecordType extends Record<PropertyKey, unkno
  *
  * @returns An object with a new reference in memory, with the properties omitted.
  */
-declare function omitProperties<ObjectType extends Record<string, unknown> | Readonly<Record<string, unknown>>, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | ReadonlyArray<KeysToOmit>): Omit<ObjectType, KeysToOmit>;
+declare function omitProperties<ObjectType extends object, KeysToOmit extends keyof ObjectType>(object: ObjectType, keysToOmit: KeysToOmit | ReadonlyArray<KeysToOmit>): Omit<ObjectType, KeysToOmit>;
 //#endregion
 //#region src/root/functions/objectHelpers/removeUndefinedFromObject.d.ts
 type RemoveUndefined<RecordType extends Record<PropertyKey, unknown>> = { [Key in keyof RecordType]: Exclude<RecordType[Key], undefined> };

package/dist/index.js

@@ -59,55 +59,6 @@ var APIError = class APIError extends Error {
 	}
 };
 //#endregion
-//#region src/root/functions/arrayHelpers/fillArray.ts
-/**
-* Creates a new array where each element is the result of the provided callback.
-*
-* 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.
-*
-* @category Array Helpers
-*
-* @template ItemType - The return type of the callback (awaited if any items are a Promise) that becomes the type of the array items.
-*
-* @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.
-*
-* @returns An array of the callback results, or a Promise resolving to one if the callback is async.
-*/
-function fillArray(callback, length = 1) {
-	const outputArray = new Array(length).fill(null).map((_, index) => {
-		return callback(index);
-	});
-	if (outputArray.some((item) => {
-		return item instanceof Promise;
-	})) return Promise.all(outputArray);
-	return outputArray;
-}
-//#endregion
-//#region src/root/functions/arrayHelpers/paralleliseArrays.ts
-/**
-* Creates a new array of tuples, each containing the item at the given index from both arrays.
-*
-* If `secondArray` is shorter than `firstArray`, the second position in the tuple
-* will be `undefined`. Iteration always uses the length of the first array.
-*
-* @category Array Helpers
-*
-* @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) {
-	const outputArray = [];
-	for (let i = 0; i < firstArray.length; i++) outputArray.push([firstArray[i], secondArray[i]]);
-	return outputArray;
-}
-//#endregion
 //#region src/v6/CodeError.ts
 /**
 * Represents errors that can be described using a standardised error code, and a human-readable error message.
@@ -311,6 +262,100 @@ var DataError$1 = class DataError$1 extends CodeError {
 	}
 };
 //#endregion
+//#region src/root/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.
+*
+* @category Array Helpers
+*
+* @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 {DataError} If `step` is `0`.
+* @throws {DataError} 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 DataError$1({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	else if (step > 0) {
+		if (start > stop) throw new DataError$1({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
+		for (let i = start; i < stop; i += step) numbers.push(i);
+	} else if (step < 0) {
+		if (start < stop) throw new DataError$1({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
+		for (let i = start; i > stop; i += step) numbers.push(i);
+	}
+	return numbers;
+}
+//#endregion
+//#region src/root/functions/arrayHelpers/fillArray.ts
+/**
+* Creates a new array where each element is the result of the provided callback.
+*
+* 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.
+*
+* @category Array Helpers
+*
+* @template ItemType - The return type of the callback (awaited if any items are a Promise) that becomes the type of the array items.
+*
+* @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 options - Extra options to apply if any item is asynchronous.
+*
+* @returns An array of the callback results, or a Promise resolving to one if the callback is async.
+*/
+function fillArray(callback, length = 1, options) {
+	if (options?.sequential) return (async () => {
+		const resolvedArray = [];
+		for (const index of range(0, length)) resolvedArray.push(await callback(index));
+		return resolvedArray;
+	})();
+	const outputArray = new Array(length).fill(null).map((_, index) => {
+		return callback(index);
+	});
+	if (outputArray.some((item) => {
+		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
+	})) return Promise.all(outputArray);
+	return outputArray;
+}
+//#endregion
+//#region src/root/functions/arrayHelpers/paralleliseArrays.ts
+/**
+* Creates a new array of tuples, each containing the item at the given index from both arrays.
+*
+* If `secondArray` is shorter than `firstArray`, the second position in the tuple
+* will be `undefined`. Iteration always uses the length of the first array.
+*
+* @category Array Helpers
+*
+* @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) {
+	const outputArray = [];
+	for (let i = 0; i < firstArray.length; i++) outputArray.push([firstArray[i], secondArray[i]]);
+	return outputArray;
+}
+//#endregion
 //#region src/root/functions/parsers/parseIntStrict.ts
 /**
 * Converts a string to an integer and throws an error if it cannot be converted.
@@ -381,45 +426,6 @@ function randomiseArray(array) {
 	return outputArray;
 }
 //#endregion
-//#region src/root/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.
-*
-* @category Array Helpers
-*
-* @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 {DataError} If `step` is `0`.
-* @throws {DataError} 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 DataError$1({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
-	else if (step > 0) {
-		if (start > stop) throw new DataError$1({
-			start,
-			stop,
-			step
-		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
-		for (let i = start; i < stop; i += step) numbers.push(i);
-	} else if (step < 0) {
-		if (start < stop) throw new DataError$1({
-			start,
-			stop,
-			step
-		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
-		for (let i = start; i > stop; i += step) numbers.push(i);
-	}
-	return numbers;
-}
-//#endregion
 //#region src/root/functions/arrayHelpers/removeDuplicates.ts
 /**
 * Removes duplicate values from an array.

package/dist/internal/index.cjs

@@ -37,55 +37,6 @@ const DependencyGroup = {
 const VERSION_NUMBER_PATTERN = String.raw`^(?:v)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`;
 const VERSION_NUMBER_REGEX = RegExp(`^${VERSION_NUMBER_PATTERN}$`);
 //#endregion
-//#region src/root/functions/arrayHelpers/fillArray.ts
-/**
-* Creates a new array where each element is the result of the provided callback.
-*
-* 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.
-*
-* @category Array Helpers
-*
-* @template ItemType - The return type of the callback (awaited if any items are a Promise) that becomes the type of the array items.
-*
-* @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.
-*
-* @returns An array of the callback results, or a Promise resolving to one if the callback is async.
-*/
-function fillArray(callback, length = 1) {
-	const outputArray = new Array(length).fill(null).map((_, index) => {
-		return callback(index);
-	});
-	if (outputArray.some((item) => {
-		return item instanceof Promise;
-	})) return Promise.all(outputArray);
-	return outputArray;
-}
-//#endregion
-//#region src/root/functions/arrayHelpers/paralleliseArrays.ts
-/**
-* Creates a new array of tuples, each containing the item at the given index from both arrays.
-*
-* If `secondArray` is shorter than `firstArray`, the second position in the tuple
-* will be `undefined`. Iteration always uses the length of the first array.
-*
-* @category Array Helpers
-*
-* @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) {
-	const outputArray = [];
-	for (let i = 0; i < firstArray.length; i++) outputArray.push([firstArray[i], secondArray[i]]);
-	return outputArray;
-}
-//#endregion
 //#region src/v6/CodeError.ts
 /**
 * Represents errors that can be described using a standardised error code, and a human-readable error message.
@@ -289,6 +240,100 @@ var DataError = class DataError extends CodeError {
 	}
 };
 //#endregion
+//#region src/root/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.
+*
+* @category Array Helpers
+*
+* @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 {DataError} If `step` is `0`.
+* @throws {DataError} 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 DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	else if (step > 0) {
+		if (start > stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
+		for (let i = start; i < stop; i += step) numbers.push(i);
+	} else if (step < 0) {
+		if (start < stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
+		for (let i = start; i > stop; i += step) numbers.push(i);
+	}
+	return numbers;
+}
+//#endregion
+//#region src/root/functions/arrayHelpers/fillArray.ts
+/**
+* Creates a new array where each element is the result of the provided callback.
+*
+* 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.
+*
+* @category Array Helpers
+*
+* @template ItemType - The return type of the callback (awaited if any items are a Promise) that becomes the type of the array items.
+*
+* @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 options - Extra options to apply if any item is asynchronous.
+*
+* @returns An array of the callback results, or a Promise resolving to one if the callback is async.
+*/
+function fillArray(callback, length = 1, options) {
+	if (options?.sequential) return (async () => {
+		const resolvedArray = [];
+		for (const index of range(0, length)) resolvedArray.push(await callback(index));
+		return resolvedArray;
+	})();
+	const outputArray = new Array(length).fill(null).map((_, index) => {
+		return callback(index);
+	});
+	if (outputArray.some((item) => {
+		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
+	})) return Promise.all(outputArray);
+	return outputArray;
+}
+//#endregion
+//#region src/root/functions/arrayHelpers/paralleliseArrays.ts
+/**
+* Creates a new array of tuples, each containing the item at the given index from both arrays.
+*
+* If `secondArray` is shorter than `firstArray`, the second position in the tuple
+* will be `undefined`. Iteration always uses the length of the first array.
+*
+* @category Array Helpers
+*
+* @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) {
+	const outputArray = [];
+	for (let i = 0; i < firstArray.length; i++) outputArray.push([firstArray[i], secondArray[i]]);
+	return outputArray;
+}
+//#endregion
 //#region src/root/functions/parsers/parseIntStrict.ts
 /**
 * Converts a string to an integer and throws an error if it cannot be converted.

package/dist/internal/index.js

@@ -12,55 +12,6 @@ const DependencyGroup = {
 const VERSION_NUMBER_PATTERN = String.raw`^(?:v)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`;
 const VERSION_NUMBER_REGEX = RegExp(`^${VERSION_NUMBER_PATTERN}$`);
 //#endregion
-//#region src/root/functions/arrayHelpers/fillArray.ts
-/**
-* Creates a new array where each element is the result of the provided callback.
-*
-* 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.
-*
-* @category Array Helpers
-*
-* @template ItemType - The return type of the callback (awaited if any items are a Promise) that becomes the type of the array items.
-*
-* @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.
-*
-* @returns An array of the callback results, or a Promise resolving to one if the callback is async.
-*/
-function fillArray(callback, length = 1) {
-	const outputArray = new Array(length).fill(null).map((_, index) => {
-		return callback(index);
-	});
-	if (outputArray.some((item) => {
-		return item instanceof Promise;
-	})) return Promise.all(outputArray);
-	return outputArray;
-}
-//#endregion
-//#region src/root/functions/arrayHelpers/paralleliseArrays.ts
-/**
-* Creates a new array of tuples, each containing the item at the given index from both arrays.
-*
-* If `secondArray` is shorter than `firstArray`, the second position in the tuple
-* will be `undefined`. Iteration always uses the length of the first array.
-*
-* @category Array Helpers
-*
-* @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) {
-	const outputArray = [];
-	for (let i = 0; i < firstArray.length; i++) outputArray.push([firstArray[i], secondArray[i]]);
-	return outputArray;
-}
-//#endregion
 //#region src/v6/CodeError.ts
 /**
 * Represents errors that can be described using a standardised error code, and a human-readable error message.
@@ -264,6 +215,100 @@ var DataError = class DataError extends CodeError {
 	}
 };
 //#endregion
+//#region src/root/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.
+*
+* @category Array Helpers
+*
+* @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 {DataError} If `step` is `0`.
+* @throws {DataError} 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 DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	else if (step > 0) {
+		if (start > stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
+		for (let i = start; i < stop; i += step) numbers.push(i);
+	} else if (step < 0) {
+		if (start < stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
+		for (let i = start; i > stop; i += step) numbers.push(i);
+	}
+	return numbers;
+}
+//#endregion
+//#region src/root/functions/arrayHelpers/fillArray.ts
+/**
+* Creates a new array where each element is the result of the provided callback.
+*
+* 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.
+*
+* @category Array Helpers
+*
+* @template ItemType - The return type of the callback (awaited if any items are a Promise) that becomes the type of the array items.
+*
+* @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 options - Extra options to apply if any item is asynchronous.
+*
+* @returns An array of the callback results, or a Promise resolving to one if the callback is async.
+*/
+function fillArray(callback, length = 1, options) {
+	if (options?.sequential) return (async () => {
+		const resolvedArray = [];
+		for (const index of range(0, length)) resolvedArray.push(await callback(index));
+		return resolvedArray;
+	})();
+	const outputArray = new Array(length).fill(null).map((_, index) => {
+		return callback(index);
+	});
+	if (outputArray.some((item) => {
+		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
+	})) return Promise.all(outputArray);
+	return outputArray;
+}
+//#endregion
+//#region src/root/functions/arrayHelpers/paralleliseArrays.ts
+/**
+* Creates a new array of tuples, each containing the item at the given index from both arrays.
+*
+* If `secondArray` is shorter than `firstArray`, the second position in the tuple
+* will be `undefined`. Iteration always uses the length of the first array.
+*
+* @category Array Helpers
+*
+* @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) {
+	const outputArray = [];
+	for (let i = 0; i < firstArray.length; i++) outputArray.push([firstArray[i], secondArray[i]]);
+	return outputArray;
+}
+//#endregion
 //#region src/root/functions/parsers/parseIntStrict.ts
 /**
 * Converts a string to an integer and throws an error if it cannot be converted.

package/dist/node/index.cjs

@@ -63,6 +63,45 @@ const normaliseImportPath = normalizeImportPath;
 const FILE_PATH_PATTERN = String.raw`(?<directory>.+)[\/\\](?<base>[^\/\\]+)`;
 const FILE_PATH_REGEX = RegExp(`^${FILE_PATH_PATTERN}$`);
 //#endregion
+//#region src/root/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.
+*
+* @category Array Helpers
+*
+* @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 {DataError} If `step` is `0`.
+* @throws {DataError} 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 DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	else if (step > 0) {
+		if (start > stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
+		for (let i = start; i < stop; i += step) numbers.push(i);
+	} else if (step < 0) {
+		if (start < stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
+		for (let i = start; i > stop; i += step) numbers.push(i);
+	}
+	return numbers;
+}
+//#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
 * Creates a new array where each element is the result of the provided callback.
@@ -76,15 +115,21 @@ const FILE_PATH_REGEX = RegExp(`^${FILE_PATH_PATTERN}$`);
 *
 * @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 options - Extra options to apply if any item is asynchronous.
 *
 * @returns An array of the callback results, or a Promise resolving to one if the callback is async.
 */
-function fillArray(callback, length = 1) {
+function fillArray(callback, length = 1, options) {
+	if (options?.sequential) return (async () => {
+		const resolvedArray = [];
+		for (const index of range(0, length)) resolvedArray.push(await callback(index));
+		return resolvedArray;
+	})();
 	const outputArray = new Array(length).fill(null).map((_, index) => {
 		return callback(index);
 	});
 	if (outputArray.some((item) => {
-		return item instanceof Promise;
+		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
 	})) return Promise.all(outputArray);
 	return outputArray;
 }

package/dist/node/index.js

@@ -39,6 +39,45 @@ const normaliseImportPath = normalizeImportPath;
 const FILE_PATH_PATTERN = String.raw`(?<directory>.+)[\/\\](?<base>[^\/\\]+)`;
 const FILE_PATH_REGEX = RegExp(`^${FILE_PATH_PATTERN}$`);
 //#endregion
+//#region src/root/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.
+*
+* @category Array Helpers
+*
+* @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 {DataError} If `step` is `0`.
+* @throws {DataError} 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 DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	else if (step > 0) {
+		if (start > stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
+		for (let i = start; i < stop; i += step) numbers.push(i);
+	} else if (step < 0) {
+		if (start < stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
+		for (let i = start; i > stop; i += step) numbers.push(i);
+	}
+	return numbers;
+}
+//#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
 * Creates a new array where each element is the result of the provided callback.
@@ -52,15 +91,21 @@ const FILE_PATH_REGEX = RegExp(`^${FILE_PATH_PATTERN}$`);
 *
 * @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 options - Extra options to apply if any item is asynchronous.
 *
 * @returns An array of the callback results, or a Promise resolving to one if the callback is async.
 */
-function fillArray(callback, length = 1) {
+function fillArray(callback, length = 1, options) {
+	if (options?.sequential) return (async () => {
+		const resolvedArray = [];
+		for (const index of range(0, length)) resolvedArray.push(await callback(index));
+		return resolvedArray;
+	})();
 	const outputArray = new Array(length).fill(null).map((_, index) => {
 		return callback(index);
 	});
 	if (outputArray.some((item) => {
-		return item instanceof Promise;
+		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
 	})) return Promise.all(outputArray);
 	return outputArray;
 }

package/dist/v6/index.cjs

@@ -1,4 +1,43 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/root/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.
+*
+* @category Array Helpers
+*
+* @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 {DataError} If `step` is `0`.
+* @throws {DataError} 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 DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	else if (step > 0) {
+		if (start > stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
+		for (let i = start; i < stop; i += step) numbers.push(i);
+	} else if (step < 0) {
+		if (start < stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
+		for (let i = start; i > stop; i += step) numbers.push(i);
+	}
+	return numbers;
+}
+//#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
 * Creates a new array where each element is the result of the provided callback.
@@ -12,15 +51,21 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 *
 * @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 options - Extra options to apply if any item is asynchronous.
 *
 * @returns An array of the callback results, or a Promise resolving to one if the callback is async.
 */
-function fillArray(callback, length = 1) {
+function fillArray(callback, length = 1, options) {
+	if (options?.sequential) return (async () => {
+		const resolvedArray = [];
+		for (const index of range(0, length)) resolvedArray.push(await callback(index));
+		return resolvedArray;
+	})();
 	const outputArray = new Array(length).fill(null).map((_, index) => {
 		return callback(index);
 	});
 	if (outputArray.some((item) => {
-		return item instanceof Promise;
+		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
 	})) return Promise.all(outputArray);
 	return outputArray;
 }

package/dist/v6/index.js

@@ -1,3 +1,42 @@
+//#region src/root/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.
+*
+* @category Array Helpers
+*
+* @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 {DataError} If `step` is `0`.
+* @throws {DataError} 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 DataError({ step }, "ZERO_STEP_SIZE", "Step size cannot be zero.");
+	else if (step > 0) {
+		if (start > stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The starting value cannot be bigger than the final value if step is positive");
+		for (let i = start; i < stop; i += step) numbers.push(i);
+	} else if (step < 0) {
+		if (start < stop) throw new DataError({
+			start,
+			stop,
+			step
+		}, "INVALID_BOUNDARIES", "The final value cannot be bigger than the starting value if step is negative");
+		for (let i = start; i > stop; i += step) numbers.push(i);
+	}
+	return numbers;
+}
+//#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
 * Creates a new array where each element is the result of the provided callback.
@@ -11,15 +50,21 @@
 *
 * @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 options - Extra options to apply if any item is asynchronous.
 *
 * @returns An array of the callback results, or a Promise resolving to one if the callback is async.
 */
-function fillArray(callback, length = 1) {
+function fillArray(callback, length = 1, options) {
+	if (options?.sequential) return (async () => {
+		const resolvedArray = [];
+		for (const index of range(0, length)) resolvedArray.push(await callback(index));
+		return resolvedArray;
+	})();
 	const outputArray = new Array(length).fill(null).map((_, index) => {
 		return callback(index);
 	});
 	if (outputArray.some((item) => {
-		return item instanceof Promise;
+		return item instanceof Promise || typeof item === "object" && item !== null && "then" in item && typeof item.then === "function";
 	})) return Promise.all(outputArray);
 	return outputArray;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "5.17.1",
+  "version": "5.18.1",
   "description": "Helpful utility functions.",
   "repository": {
     "type": "git",