@alextheman/utility 5.11.3 → 5.13.0

package/dist/internal/index.cjs

@@ -82,34 +82,42 @@ function paralleliseArrays(firstArray, secondArray) {
 	return outputArray;
 }
 //#endregion
-//#region src/root/types/DataError.ts
+//#region src/v6/CodeError.ts
 /**
-* Represents errors you may get that may've been caused by a specific piece of data.
+* Represents errors that can be described using a standardised error code, and a human-readable error message.
 *
 * @category Types
 *
-* @template DataType - The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
 */
-var DataError = class DataError extends Error {
+var CodeError = class CodeError extends Error {
 	code;
-	data;
 	/**
-	* @param data - The data that caused the error.
 	* @param code - A standardised code (e.g. UNEXPECTED_DATA).
 	* @param message  - A human-readable error message (e.g. The data provided is invalid).
 	* @param options - Extra options to pass to super Error constructor.
 	*/
-	constructor(data, code = "INVALID_DATA", message = "The data provided is invalid", options) {
+	constructor(code, message = "Something went wrong.", options) {
 		super(message, options);
 		if (Error.captureStackTrace) Error.captureStackTrace(this, new.target);
 		this.name = new.target.name;
 		this.code = code;
-		this.data = data;
 		Object.defineProperty(this, "message", { enumerable: true });
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
+	/**
+	* Checks whether the given input may have been caused by a CodeError.
+	*
+	* @param input - The input to check.
+	*
+	* @returns `true` if the input is a CodeError, and `false` otherwise. The type of the input will also be narrowed down to CodeError if `true`.
+	*/
+	static check(input) {
+		if (input instanceof CodeError) return true;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string";
+	}
 	static checkCaughtError(error, options) {
-		if (DataError.check(error)) {
+		if (this.check(error)) {
 			if (options?.expectedCode && error.code !== options.expectedCode) throw new Error(normaliseIndents`The error code on the thrown error does not match the expected error code.
             
             Expected: ${options.expectedCode}
@@ -120,6 +128,71 @@ var DataError = class DataError extends Error {
 		throw error;
 	}
 	/**
+	* Gets the thrown `CodeError` from a given function if one was thrown, and re-throws any other errors, or throws a default `CodeError` if no error thrown.
+	*
+	* @param errorFunction - The function expected to throw the error.
+	* @param options - Extra options to apply.
+	*
+	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `CodeError`.
+	* @throws {Error} If no `CodeError` was thrown by the `errorFunction`
+	*
+	* @returns The `CodeError` that was thrown by the `errorFunction`
+	*/
+	static expectError(errorFunction, options) {
+		try {
+			errorFunction();
+		} catch (error) {
+			return this.checkCaughtError(error, options);
+		}
+		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
+	}
+	/**
+	* Gets the thrown `CodeError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `CodeError` if no error thrown.
+	*
+	* @param errorFunction - The function expected to throw the error.
+	* @param options - Extra options to apply.
+	*
+	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `CodeError`.
+	* @throws {Error} If no `CodeError` was thrown by the `errorFunction`
+	*
+	* @returns The `CodeError` that was thrown by the `errorFunction`
+	*/
+	static async expectErrorAsync(errorFunction, options) {
+		try {
+			await errorFunction();
+		} catch (error) {
+			return this.checkCaughtError(error, options);
+		}
+		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
+	}
+};
+//#endregion
+//#region src/v6/DataError.ts
+/**
+* Represents errors you may get that may've been caused by a specific piece of data.
+*
+* @category Types
+*
+* @template DataType - The type of the data that caused the error.
+*/
+var DataError = class DataError extends CodeError {
+	data;
+	/**
+	* @param data - The data that caused the error.
+	* @param code - A standardised code (e.g. UNEXPECTED_DATA).
+	* @param message  - A human-readable error message (e.g. The data provided is invalid).
+	* @param options - Extra options to pass to super Error constructor.
+	*/
+	constructor(data, code = "INVALID_DATA", message = "The data provided is invalid", options) {
+		super(code, message, options);
+		if (Error.captureStackTrace) Error.captureStackTrace(this, new.target);
+		this.name = new.target.name;
+		this.code = code;
+		this.data = data;
+		Object.defineProperty(this, "message", { enumerable: true });
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	/**
 	* Checks whether the given input may have been caused by a DataError.
 	*
 	* @param input - The input to check.
@@ -128,8 +201,7 @@ var DataError = class DataError extends Error {
 	*/
 	static check(input) {
 		if (input instanceof DataError) return true;
-		const data = input;
-		return typeof data === "object" && data !== null && typeof data.message === "string" && typeof data.code === "string" && "data" in data;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
 	}
 	/**
 	* Gets the thrown `DataError` from a given function if one was thrown, and re-throws any other errors, or throws a default `DataError` if no error thrown.
@@ -143,12 +215,7 @@ var DataError = class DataError extends Error {
 	* @returns The `DataError` that was thrown by the `errorFunction`
 	*/
 	static expectError(errorFunction, options) {
-		try {
-			errorFunction();
-		} catch (error) {
-			return DataError.checkCaughtError(error, options);
-		}
-		throw new Error("Expected a DataError to be thrown but none was thrown");
+		return super.expectError(errorFunction, options);
 	}
 	/**
 	* Gets the thrown `DataError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `DataError` if no error thrown.
@@ -162,15 +229,57 @@ var DataError = class DataError extends Error {
 	* @returns The `DataError` that was thrown by the `errorFunction`
 	*/
 	static async expectErrorAsync(errorFunction, options) {
-		try {
-			await errorFunction();
-		} catch (error) {
-			return DataError.checkCaughtError(error, options);
-		}
-		throw new Error("Expected a DataError to be thrown but none was thrown");
+		return await super.expectErrorAsync(errorFunction, options);
 	}
 };
 //#endregion
+//#region src/root/functions/parsers/zod/_parseZodSchema.ts
+function _parseZodSchema(parsedResult, input, onError) {
+	if (!parsedResult.success) {
+		if (onError) {
+			if (onError instanceof Error) throw onError;
+			else if (typeof onError === "function") {
+				const evaluatedError = onError(parsedResult.error);
+				if (evaluatedError instanceof Error) throw evaluatedError;
+			}
+		}
+		const allErrorCodes = {};
+		for (const issue of parsedResult.error.issues) {
+			const code = issue.code.toUpperCase();
+			allErrorCodes[code] = (allErrorCodes[code] ?? 0) + 1;
+		}
+		throw new DataError({ input }, Object.entries(allErrorCodes).toSorted(([_, firstCount], [__, secondCount]) => {
+			return secondCount - firstCount;
+		}).map(([code, count], _, allErrorCodes) => {
+			return allErrorCodes.length === 1 && count === 1 ? code : `${code}×${count}`;
+		}).join(","), `\n\n${zod.default.prettifyError(parsedResult.error)}\n`);
+	}
+	return parsedResult.data;
+}
+//#endregion
+//#region src/root/functions/parsers/zod/parseZodSchema.ts
+/**
+* An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
+*
+* NOTE: Use `parseZodSchemaAsync` if your schema includes an asynchronous function.
+*
+* @category Parsers
+*
+* @template SchemaType - The Zod schema type.
+* @template ErrorType - The type of error to throw on invalid data.
+*
+* @param schema - The Zod schema to use in parsing.
+* @param input - The data to parse.
+* @param onError - A custom error to throw on invalid data (defaults to `DataError`). May either be the error itself, or a function that returns the error or nothing. If nothing is returned, the default error is thrown instead.
+*
+* @throws {DataErrorCode} If the given data cannot be parsed according to the schema.
+*
+* @returns The parsed data from the Zod schema.
+*/
+function parseZodSchema(schema, input, onError) {
+	return _parseZodSchema(schema.safeParse(input), input, onError);
+}
+//#endregion
 //#region src/root/functions/taggedTemplate/interpolate.ts
 /**
 * Returns the result of interpolating a template string when given the strings and interpolations separately.
@@ -261,166 +370,6 @@ function normaliseIndents(first, ...args) {
 	return reduceLines(interpolate(strings, ...[...args]).split("\n"), options);
 }
 //#endregion
-//#region src/root/functions/miscellaneous/sayHello.ts
-/**
-* Returns a string representing the lyrics to the package's theme song, Commit To You
-*
-* [Pls listen!](https://www.youtube.com/watch?v=mH-Sg-8EnxM)
-*
-* @returns The lyrics string in markdown format.
-*/
-function sayHello() {
-	return normaliseIndents`
-    # Commit To You
-
-    ### Verse 1
-
-    I know you've been checking me out,  
-    Shall we take it to the next level now?  
-    'Cause I really wanna be there all for you,  
-    All for you!  
-    Come on now, let's make a fresh start!  
-    Pin my number, then you can take me out!  
-    Can't you see I really do care about you,  
-    About you!
-
-    ### Pre-chorus 1
-    Although our calendars are imperfect, at best,  
-    I'd like to organise time with you! (with you!).  
-    Just tell me when and I'll make it clear,  
-    All clear for you,  
-    All clear for you!  
-    (One, two, three, go!)
-
-    ### Chorus
-    I wanna be of utility, I'll help you on the run!  
-    I'll be the one here in the back, while you go have some fun!  
-    Looking out for you tonight, I'll be the one you can rely on!  
-    Watch you go and watch me pass by,  
-    I'll be here!  
-    I'll commit to you!
-
-    ### Verse 2
-    Though sometimes it won't be easy,  
-    You'll be here to bring out the best in me,  
-    And I'll hold myself to high standards for you!  
-    All for you!  
-    We'll grow as a pair, you and me,  
-    We'll build up a healthy dependency,  
-    You can build with me and I'll develop with you!  
-    I'm with you!
-
-    ### Pre-chorus 2
-    I'll be with you when you're up or you're down,  
-    We'll deal with all our problems together (together!)  
-    Just tell me what you want, I'll make it clear,  
-    All clear for you,  
-    All clear for you!  
-    (One, three, one, go!)
-
-    ### Chorus
-    I wanna be of utility, I'll help you on the run!  
-    (help you on the run!)  
-    I'll be the one here in the back, while you go have some fun!  
-    (you go have some fun!)  
-    Looking out for you tonight, I'll be the one you can rely on!  
-    Watch you go and watch me pass by,  
-    I'll be here!  
-    I'll commit to you!
-
-    ### Bridge
-    Looking into our stack!  
-    I'll commit to you!  
-    We've got a lot to unpack!  
-    I'll commit to you!  
-    The environment that we're in!  
-    I'll commit to you!  
-    Delicate as a string!  
-    I'll commit to you!
-
-    But I think you're my type!  
-    I'll commit to you!  
-    Oh, this feels all so right!  
-    I'll commit to you!  
-    Nothing stopping us now!  
-    I'll commit to you!  
-    Let's show them what we're about!  
-    Two, three, four, go!
-
-    ### Final Chorus
-    I wanna be of utility, I'll help you on the run!  
-    (help you on the run!)  
-    I'll be the one here in the back, while you go have some fun!  
-    (you go have some fun!)  
-    Looking out for you tonight, I'll be the one you can rely on!  
-    Watch you go and watch me pass by,  
-    I'll be here!  
-    I'll commit to you!
-
-    I wanna be of utility, I'll help you on the run!  
-    (I'll commit to you!)  
-    I'll be the one here in the back, while you go have some fun!  
-    (I'll commit to you!)  
-    Looking out for you tonight, I'll be the one you can rely on!  
-    (I'll commit to you!)  
-    Watch you go and watch me pass by,  
-    (I'll commit to you!)  
-    I'll be here!  
-
-    ### Outro
-    I'll commit to you!  
-    I'll commit to you!  
-    I'll commit to you!
-    `;
-}
-//#endregion
-//#region src/root/functions/parsers/zod/_parseZodSchema.ts
-function _parseZodSchema(parsedResult, input, onError) {
-	if (!parsedResult.success) {
-		if (onError) {
-			if (onError instanceof Error) throw onError;
-			else if (typeof onError === "function") {
-				const evaluatedError = onError(parsedResult.error);
-				if (evaluatedError instanceof Error) throw evaluatedError;
-			}
-		}
-		const allErrorCodes = {};
-		for (const issue of parsedResult.error.issues) {
-			const code = issue.code.toUpperCase();
-			allErrorCodes[code] = (allErrorCodes[code] ?? 0) + 1;
-		}
-		throw new DataError({ input }, Object.entries(allErrorCodes).toSorted(([_, firstCount], [__, secondCount]) => {
-			return secondCount - firstCount;
-		}).map(([code, count], _, allErrorCodes) => {
-			return allErrorCodes.length === 1 && count === 1 ? code : `${code}×${count}`;
-		}).join(","), `\n\n${zod.default.prettifyError(parsedResult.error)}\n`);
-	}
-	return parsedResult.data;
-}
-//#endregion
-//#region src/root/functions/parsers/zod/parseZodSchema.ts
-/**
-* An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
-*
-* NOTE: Use `parseZodSchemaAsync` if your schema includes an asynchronous function.
-*
-* @category Parsers
-*
-* @template SchemaType - The Zod schema type.
-* @template ErrorType - The type of error to throw on invalid data.
-*
-* @param schema - The Zod schema to use in parsing.
-* @param input - The data to parse.
-* @param onError - A custom error to throw on invalid data (defaults to `DataError`). May either be the error itself, or a function that returns the error or nothing. If nothing is returned, the default error is thrown instead.
-*
-* @throws {DataError} If the given data cannot be parsed according to the schema.
-*
-* @returns The parsed data from the Zod schema.
-*/
-function parseZodSchema(schema, input, onError) {
-	return _parseZodSchema(schema.safeParse(input), input, onError);
-}
-//#endregion
 //#region src/internal/getDependenciesFromGroup.ts
 /**
 * Get the dependencies from a given dependency group in `package.json`.
@@ -496,7 +445,117 @@ function parseJsonFromStdout(stdout) {
 }
 //#endregion
 //#region src/internal/sayHello.ts
-var sayHello_default = sayHello;
+/**
+* Returns a string representing the lyrics to the package's theme song, Commit To You
+*
+* [Pls listen!](https://www.youtube.com/watch?v=mH-Sg-8EnxM)
+*
+* @returns The lyrics string in markdown format.
+*/
+function sayHello() {
+	return `
+# Commit To You
+
+### Verse 1
+
+I know you've been checking me out,  
+Shall we take it to the next level now?  
+'Cause I really wanna be there all for you,  
+All for you!  
+Come on now, let's make a fresh start!  
+Pin my number, then you can take me out!  
+Can't you see I really do care about you,  
+About you!
+
+### Pre-chorus 1
+Although our calendars are imperfect, at best,  
+I'd like to organise time with you! (with you!).  
+Just tell me when and I'll make it clear,  
+All clear for you,  
+All clear for you!  
+(One, two, three, go!)
+
+### Chorus
+I wanna be of utility, I'll help you on the run!  
+I'll be the one here in the back, while you go have some fun!  
+Looking out for you tonight, I'll be the one you can rely on!  
+Watch you go and watch me pass by,  
+I'll be here!  
+I'll commit to you!
+
+### Verse 2
+Though sometimes it won't be easy,  
+You'll be here to bring out the best in me,  
+And I'll hold myself to high standards for you!  
+All for you!  
+We'll grow as a pair, you and me,  
+We'll build up a healthy dependency,  
+You can build with me and I'll develop with you!  
+I'm with you!
+
+### Pre-chorus 2
+I'll be with you when you're up or you're down,  
+We'll deal with all our problems together (together!)  
+Just tell me what you want, I'll make it clear,  
+All clear for you,  
+All clear for you!  
+(One, three, one, go!)
+
+### Chorus
+I wanna be of utility, I'll help you on the run!  
+(help you on the run!)  
+I'll be the one here in the back, while you go have some fun!  
+(you go have some fun!)  
+Looking out for you tonight, I'll be the one you can rely on!  
+Watch you go and watch me pass by,  
+I'll be here!  
+I'll commit to you!
+
+### Bridge
+Looking into our stack!  
+I'll commit to you!  
+We've got a lot to unpack!  
+I'll commit to you!  
+The environment that we're in!  
+I'll commit to you!  
+Delicate as a string!  
+I'll commit to you!
+
+But I think you're my type!  
+I'll commit to you!  
+Oh, this feels all so right!  
+I'll commit to you!  
+Nothing stopping us now!  
+I'll commit to you!  
+Let's show them what we're about!  
+Two, three, four, go!
+
+### Final Chorus
+I wanna be of utility, I'll help you on the run!  
+(help you on the run!)  
+I'll be the one here in the back, while you go have some fun!  
+(you go have some fun!)  
+Looking out for you tonight, I'll be the one you can rely on!  
+Watch you go and watch me pass by,  
+I'll be here!  
+I'll commit to you!
+
+I wanna be of utility, I'll help you on the run!  
+(I'll commit to you!)  
+I'll be the one here in the back, while you go have some fun!  
+(I'll commit to you!)  
+Looking out for you tonight, I'll be the one you can rely on!  
+(I'll commit to you!)  
+Watch you go and watch me pass by,  
+(I'll commit to you!)  
+I'll be here!  
+
+### Outro
+I'll commit to you!  
+I'll commit to you!  
+I'll commit to you!
+    `;
+}
 //#endregion
 //#region src/internal/setupPackageEndToEnd.ts
 async function setupPackageEndToEnd(temporaryPath, packageManager, moduleType, options) {
@@ -525,5 +584,5 @@ exports.getPackageJsonContents = getPackageJsonContents;
 exports.getPackageJsonPath = getPackageJsonPath;
 exports.packageJsonNotFoundError = packageJsonNotFoundError;
 exports.parseJsonFromStdout = parseJsonFromStdout;
-exports.sayHello = sayHello_default;
+exports.sayHello = sayHello;
 exports.setupPackageEndToEnd = setupPackageEndToEnd;