@alextheman/utility 5.13.1 → 5.15.0

package/dist/internal/index.d.ts

@@ -25,7 +25,7 @@ type IsTypeArgumentString<Argument extends string> = Argument;
 type NullableOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | null;
 //#endregion
 //#region src/v6/CodeError.d.ts
-interface ExpectErrorOptions$1<ErrorCode extends string = string> {
+interface ExpectErrorOptions<ErrorCode extends string = string> {
   expectedCode?: ErrorCode;
 }
 /**
@@ -50,8 +50,21 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
    *
    * @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: unknown): input is CodeError<string>;
-  protected static checkCaughtError<ErrorCode extends string = string>(this: typeof CodeError, error: unknown, options?: ExpectErrorOptions$1<ErrorCode>): CodeError;
+  static check<ErrorCode extends string = string>(input: unknown): input is CodeError<ErrorCode>;
+  protected static checkCaughtError<ErrorCode extends string = string>(this: typeof CodeError, error: unknown, options?: ExpectErrorOptions<ErrorCode>): CodeError<ErrorCode>;
+  /**
+   * Check a `CodeError` against its error code
+   *
+   * This will also automatically narrow down the type of the input to be `CodeError`, with its error code properly typed if this function returns true.
+   *
+   * @template ErrorCode The type of the error code
+   *
+   * @param input - The input to check.
+   * @param code - The expected code of the resulting error.
+   *
+   * @returns `true` if the error code matches the expected code, and `false` otherwise. The type of the input will also be narrowed down to CodeError, and its code will be narrowed to the expected code's type if the function returns `true`.
+   */
+  static checkWithCode<ErrorCode extends string = string>(input: unknown, code: ErrorCode): input is CodeError<ErrorCode>;
   /**
    * 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.
    *
@@ -63,7 +76,7 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
    *
    * @returns The `CodeError` that was thrown by the `errorFunction`
    */
-  static expectError<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => unknown, options?: ExpectErrorOptions$1<ErrorCode>): CodeError;
+  static expectError<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => unknown, options?: ExpectErrorOptions<ErrorCode>): CodeError<ErrorCode>;
   /**
    * 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.
    *
@@ -75,18 +88,10 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
    *
    * @returns The `CodeError` that was thrown by the `errorFunction`
    */
-  static expectErrorAsync<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions$1<ErrorCode>): Promise<CodeError>;
+  static expectErrorAsync<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<CodeError>;
 }
 //#endregion
 //#region src/v6/DataError.d.ts
-type DefaultDataErrorCode = "INVALID_DATA";
-interface ExpectErrorOptions<ErrorCode extends string = DefaultDataErrorCode> {
-  expectedCode?: ErrorCode | DefaultDataErrorCode;
-}
-declare const DataErrorCode: {
-  readonly INVALID_DATA: "INVALID_DATA";
-};
-type DataErrorCode = CreateEnumType<typeof DataErrorCode>;
 /**
  * Represents errors you may get that may've been caused by a specific piece of data.
  *
@@ -94,7 +99,7 @@ type DataErrorCode = CreateEnumType<typeof DataErrorCode>;
  *
  * @template DataType - The type of the data that caused the error.
  */
-declare class DataError<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode> extends CodeError<ErrorCode | DataErrorCode> {
+declare class DataError<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string> extends CodeError<ErrorCode> {
   data: DataType;
   /**
    * @param data - The data that caused the error.
@@ -102,7 +107,7 @@ declare class DataError<DataType extends object = Record<PropertyKey, unknown>,
    * @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: DataType, code?: ErrorCode | DefaultDataErrorCode, message?: string, options?: ErrorOptions);
+  constructor(data: DataType, code: ErrorCode, message?: string, options?: ErrorOptions);
   /**
    * Checks whether the given input may have been caused by a DataError.
    *
@@ -110,7 +115,20 @@ declare class DataError<DataType extends object = Record<PropertyKey, unknown>,
    *
    * @returns `true` if the input is a DataError, and `false` otherwise. The type of the input will also be narrowed down to DataError if `true`.
    */
-  static check<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode>(input: unknown): input is DataError<DataType, ErrorCode>;
+  static check<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string>(input: unknown): input is DataError<DataType, ErrorCode>;
+  /**
+   * Check a `DataError` against its error code
+   *
+   * This will also automatically narrow down the type of the input to be `DataError`, with its error code properly typed if this function returns true.
+   *
+   * @template ErrorCode The type of the error code
+   *
+   * @param input - The input to check.
+   * @param code - The expected code of the resulting error.
+   *
+   * @returns `true` if the error code matches the expected code, and `false` otherwise. The type of the input will also be narrowed down to `DataError`, and its code will be narrowed to the expected code's type if the function returns `true`.
+   */
+  static checkWithCode<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string>(input: unknown, code: ErrorCode): input is DataError<DataType, ErrorCode>;
   /**
    * 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.
    *
@@ -122,7 +140,7 @@ declare class DataError<DataType extends object = Record<PropertyKey, unknown>,
    *
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
-  static expectError<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => unknown, options?: ExpectErrorOptions<ErrorCode>): DataError<DataType, ErrorCode>;
+  static expectError<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = string>(errorFunction: () => unknown, options?: ExpectErrorOptions<ErrorCode>): DataError<DataType, ErrorCode>;
   /**
    * 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.
    *
@@ -134,7 +152,7 @@ declare class DataError<DataType extends object = Record<PropertyKey, unknown>,
    *
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
-  static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError<DataType, ErrorCode>>;
+  static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = string>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError<DataType, ErrorCode>>;
 }
 //#endregion
 //#region src/internal/DependencyGroup.d.ts

package/dist/internal/index.js

@@ -8,6 +8,10 @@ const DependencyGroup = {
 	DEV_DEPENDENCIES: "devDependencies"
 };
 //#endregion
+//#region src/root/constants/VERSION_NUMBER_REGEX.ts
+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.
@@ -103,6 +107,21 @@ var CodeError = class CodeError extends Error {
 		throw error;
 	}
 	/**
+	* Check a `CodeError` against its error code
+	*
+	* This will also automatically narrow down the type of the input to be `CodeError`, with its error code properly typed if this function returns true.
+	*
+	* @template ErrorCode The type of the error code
+	*
+	* @param input - The input to check.
+	* @param code - The expected code of the resulting error.
+	*
+	* @returns `true` if the error code matches the expected code, and `false` otherwise. The type of the input will also be narrowed down to CodeError, and its code will be narrowed to the expected code's type if the function returns `true`.
+	*/
+	static checkWithCode(input, code) {
+		return this.check(input) && input.code === code;
+	}
+	/**
 	* 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.
@@ -158,11 +177,10 @@ var DataError = class DataError extends CodeError {
 	* @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(data, code, 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);
@@ -179,6 +197,21 @@ var DataError = class DataError extends CodeError {
 		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
 	}
 	/**
+	* Check a `DataError` against its error code
+	*
+	* This will also automatically narrow down the type of the input to be `DataError`, with its error code properly typed if this function returns true.
+	*
+	* @template ErrorCode The type of the error code
+	*
+	* @param input - The input to check.
+	* @param code - The expected code of the resulting error.
+	*
+	* @returns `true` if the error code matches the expected code, and `false` otherwise. The type of the input will also be narrowed down to `DataError`, and its code will be narrowed to the expected code's type if the function returns `true`.
+	*/
+	static checkWithCode(input, code) {
+		return this.check(input) && input.code === code;
+	}
+	/**
 	* 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.
 	*
 	* @param errorFunction - The function expected to throw the error.
@@ -208,53 +241,49 @@ var DataError = class DataError extends CodeError {
 	}
 };
 //#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${z.prettifyError(parsedResult.error)}\n`);
-	}
-	return parsedResult.data;
-}
-//#endregion
-//#region src/root/functions/parsers/zod/parseZodSchema.ts
+//#region src/root/functions/parsers/parseIntStrict.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.
+* Converts a string to an integer and throws an error if it cannot be converted.
 *
 * @category Parsers
 *
-* @template SchemaType - The Zod schema type.
-* @template ErrorType - The type of error to throw on invalid data.
+* @param string - A string to convert into a number.
+* @param radix - A value between 2 and 36 that specifies the base of the number in string. If this argument is not supplied, strings with a prefix of '0x' are considered hexadecimal. All other strings are considered decimal.
 *
-* @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 provided string cannot safely be converted to an integer.
 *
-* @throws {DataErrorCode} If the given data cannot be parsed according to the schema.
-*
-* @returns The parsed data from the Zod schema.
+* @returns The integer parsed from the input string.
 */
-function parseZodSchema(schema, input, onError) {
-	return _parseZodSchema(schema.safeParse(input), input, onError);
+function parseIntStrict(string, radix) {
+	const trimmedString = string.trim();
+	const maxAllowedAlphabeticalCharacter = radix && radix > 10 && radix <= 36 ? String.fromCharCode(87 + radix - 1) : void 0;
+	if (!(radix && radix > 10 && radix <= 36 ? new RegExp(`^[+-]?[0-9a-${maxAllowedAlphabeticalCharacter}]+$`, "i") : /^[+-]?\d+$/).test(trimmedString)) throw new DataError(radix ? {
+		string,
+		radix
+	} : { string }, "INTEGER_PARSING_ERROR", `Only numeric values${radix && radix > 10 && radix <= 36 ? ` or character${radix !== 11 ? "s" : ""} A${radix !== 11 ? `-${maxAllowedAlphabeticalCharacter?.toUpperCase()} ` : " "}` : " "}are allowed.`);
+	if (radix && radix < 10 && [...trimmedString.replace(/^[+-]/, "")].some((character) => {
+		return parseInt(character) >= radix;
+	})) throw new DataError({
+		string,
+		radix
+	}, "INTEGER_PARSING_ERROR", "Value contains one or more digits outside of the range of the given radix.");
+	const parseIntResult = parseInt(trimmedString, radix);
+	if (isNaN(parseIntResult)) throw new DataError({ string }, "INTEGER_PARSING_ERROR", "Value is not a valid integer.");
+	return parseIntResult;
 }
 //#endregion
+//#region src/root/functions/parsers/parseVersionType.ts
+/**
+* Represents the three common software version types.
+*
+* @category Types
+*/
+const VersionType = {
+	MAJOR: "major",
+	MINOR: "minor",
+	PATCH: "patch"
+};
+//#endregion
 //#region src/root/functions/taggedTemplate/interpolate.ts
 /**
 * Returns the result of interpolating a template string when given the strings and interpolations separately.
@@ -345,6 +374,276 @@ function normaliseIndents(first, ...args) {
 	return reduceLines(interpolate(strings, ...[...args]).split("\n"), options);
 }
 //#endregion
+//#region src/root/types/VersionNumber.ts
+/**
+* Represents a software version number, considered to be made up of a major, minor, and patch part.
+*
+* @category Types
+*/
+var VersionNumber = class VersionNumber {
+	static NON_NEGATIVE_TUPLE_ERROR = "Input array must be a tuple of three non-negative integers.";
+	/** The major number. Increments when a feature is removed or changed in a way that is not backwards-compatible with the previous release. */
+	major = 0;
+	/** The minor number. Increments when a new feature is added/deprecated and is expected to be backwards-compatible with the previous release. */
+	minor = 0;
+	/** The patch number. Increments when the next release is fixing a bug or doing a small refactor that should not be noticeable in practice. */
+	patch = 0;
+	/**
+	* @param input - The input to create a new instance of `VersionNumber` from.
+	*/
+	constructor(input) {
+		if (input instanceof VersionNumber) {
+			this.major = input.major;
+			this.minor = input.minor;
+			this.patch = input.patch;
+		} else if (typeof input === "string") {
+			if (!VERSION_NUMBER_REGEX.test(input)) throw new DataError({ input }, "INVALID_VERSION", `"${input}" is not a valid version number. Version numbers must be of the format "X.Y.Z" or "vX.Y.Z", where X, Y, and Z are non-negative integers.`);
+			const [major, minor, patch] = VersionNumber.formatString(input, { omitPrefix: true }).split(".").map((number) => {
+				return parseIntStrict(number);
+			});
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+		} else if (Array.isArray(input)) {
+			if (input.length !== 3) throw new DataError({ input }, "INVALID_LENGTH", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
+			const [major, minor, patch] = input.map((number) => {
+				const parsedInteger = parseIntStrict(number?.toString());
+				if (parsedInteger < 0) throw new DataError({ input }, "NEGATIVE_INPUTS", VersionNumber.NON_NEGATIVE_TUPLE_ERROR);
+				return parsedInteger;
+			});
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+		} else throw new DataError({ input }, "INVALID_INPUT", normaliseIndents`
+        The provided input can not be parsed into a valid version number.
+        Expected either a string of format X.Y.Z or vX.Y.Z, a tuple of three numbers, or another \`VersionNumber\` instance.
+      `);
+	}
+	/**
+	* Gets the current version type of the current instance of `VersionNumber`.
+	*
+	* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
+	*/
+	get type() {
+		if (this.minor === 0 && this.patch === 0) return VersionType.MAJOR;
+		if (this.patch === 0) return VersionType.MINOR;
+		return VersionType.PATCH;
+	}
+	static formatString(input, options) {
+		if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
+		return input.startsWith("v") ? input : `v${input}`;
+	}
+	/**
+	* Checks if the provided version numbers have the exact same major, minor, and patch numbers.
+	*
+	* @param firstVersion - The first version number to compare.
+	* @param secondVersion - The second version number to compare.
+	*
+	* @returns `true` if the provided version numbers have exactly the same major, minor, and patch numbers, and returns `false` otherwise.
+	*/
+	static isEqual(firstVersion, secondVersion) {
+		return firstVersion.major === secondVersion.major && firstVersion.minor === secondVersion.minor && firstVersion.patch === secondVersion.patch;
+	}
+	/**
+	* Get a formatted string representation of the current version number
+	*
+	* @param options - Options to apply to the string formatting.
+	*
+	* @returns A formatted string representation of the current version number with the options applied.
+	*/
+	format(options) {
+		let baseOutput = `${this.major}`;
+		if (!options?.omitMinor) {
+			baseOutput += `.${this.minor}`;
+			if (!options?.omitPatch) baseOutput += `.${this.patch}`;
+		}
+		return VersionNumber.formatString(baseOutput, { omitPrefix: options?.omitPrefix });
+	}
+	/**
+	* Increments the current version number by the given increment type, returning the result as a new reference in memory.
+	*
+	* @param incrementType - The type of increment. Can be one of the following:
+	* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+	* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+	* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+	* @param incrementAmount - The amount to increment by (defaults to 1).
+	*
+	* @returns A new instance of `VersionNumber` with the increment applied.
+	*/
+	increment(incrementType, incrementAmount = 1) {
+		const incrementBy = parseIntStrict(String(incrementAmount));
+		const calculatedRawVersion = {
+			major: [
+				this.major + incrementBy,
+				0,
+				0
+			],
+			minor: [
+				this.major,
+				this.minor + incrementBy,
+				0
+			],
+			patch: [
+				this.major,
+				this.minor,
+				this.patch + incrementBy
+			]
+		}[incrementType];
+		try {
+			return new VersionNumber(calculatedRawVersion);
+		} catch (error) {
+			if (DataError.check(error) && error.code === "NEGATIVE_INPUTS") throw new DataError({
+				currentVersion: this.toString(),
+				calculatedRawVersion: `v${calculatedRawVersion.join(".")}`,
+				incrementAmount
+			}, "NEGATIVE_VERSION", "Cannot apply this increment amount as it would lead to a negative version number.");
+			else throw error;
+		}
+	}
+	/**
+	* Ensures that the VersionNumber behaves correctly when attempted to be coerced to a string.
+	*
+	* @param hint - Not used as of now, but generally used to help with numeric coercion, I think (which we most likely do not need for version numbers).
+	*
+	* @returns A stringified representation of the current version number, prefixed with `v`.
+	*/
+	[Symbol.toPrimitive](hint) {
+		if (hint === "number") throw new DataError({ thisVersion: this.toString() }, "INVALID_COERCION", "VersionNumber cannot be coerced to a number type.");
+		return this.toString();
+	}
+	/**
+	* Ensures that the VersionNumber behaves correctly when attempted to be converted to JSON.
+	*
+	* @returns A stringified representation of the current version number, prefixed with `v`.
+	*/
+	toJSON() {
+		return this.toString();
+	}
+	/**
+	* Get a string representation of the current version number.
+	*
+	* @returns A stringified representation of the current version number with the prefix.
+	*/
+	toString() {
+		const rawString = `${this.major}.${this.minor}.${this.patch}`;
+		return VersionNumber.formatString(rawString, { omitPrefix: false });
+	}
+};
+const zodVersionNumber = z.union([
+	z.string(),
+	z.tuple([
+		z.number(),
+		z.number(),
+		z.number()
+	]),
+	z.instanceof(VersionNumber)
+]).transform((rawVersionNumber) => {
+	return new VersionNumber(rawVersionNumber);
+});
+//#endregion
+//#region src/root/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${z.prettifyError(parsedResult.error)}\n`);
+	}
+	return parsedResult.data;
+}
+//#endregion
+//#region src/root/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
+*
+* @deprecated Please use `az.with(schema).parse(input)` instead.
+*
+* @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/zod/parseZodSchemaAsync.ts
+/**
+* An alternative function to zodSchema.parseAsync() that can be used to strictly parse asynchronous Zod schemas.
+*
+* @category Parsers
+*
+* @deprecated Please use `az.with(schema).parseAsync(input)` instead.
+*
+* @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.
+*/
+async function parseZodSchemaAsync(schema, input, onError) {
+	return _parseZodSchema(await schema.safeParseAsync(input), input, onError);
+}
+//#endregion
+//#region src/root/zod/zodFieldWrapper.ts
+function zodFieldWrapper(schema) {
+	return z.string().trim().transform((value) => {
+		return value === "" ? null : value;
+	}).pipe(schema);
+}
+//#endregion
+//#region src/root/zod/az.ts
+const az = {
+	field: zodFieldWrapper,
+	fieldNumber: () => {
+		return z.coerce.number();
+	},
+	versionNumber: () => {
+		return zodVersionNumber;
+	},
+	fieldDate: () => {
+		return z.coerce.date();
+	},
+	with: (schema) => {
+		return {
+			parse: (input, error) => {
+				return parseZodSchema(schema, input, error);
+			},
+			parseAsync: async (input, error) => {
+				return await parseZodSchemaAsync(schema, input, error);
+			}
+		};
+	}
+};
+//#endregion
 //#region src/internal/getDependenciesFromGroup.ts
 /**
 * Get the dependencies from a given dependency group in `package.json`.
@@ -358,8 +657,8 @@ function normaliseIndents(first, ...args) {
 */
 function getDependenciesFromGroup(packageInfo, dependencyGroup) {
 	return {
-		dependencies: parseZodSchema(z.record(z.string(), z.string()), packageInfo.dependencies ?? {}),
-		devDependencies: parseZodSchema(z.record(z.string(), z.string()), packageInfo.devDependencies ?? {})
+		dependencies: az.with(z.record(z.string(), z.string())).parse(packageInfo.dependencies ?? {}),
+		devDependencies: az.with(z.record(z.string(), z.string())).parse(packageInfo.devDependencies ?? {})
 	}[dependencyGroup];
 }
 //#endregion
@@ -367,7 +666,7 @@ function getDependenciesFromGroup(packageInfo, dependencyGroup) {
 async function getExpectedTgzName(packagePath, packageManager) {
 	const { stdout: rawPackedTgzData } = await execa({ cwd: packagePath })`${packageManager} pack --json --dry-run`;
 	const packedTgzData = parseJsonFromStdout(rawPackedTgzData);
-	const parsedPackedTgzData = parseZodSchema(packageManager === "pnpm" ? z.object({ filename: z.string() }) : z.array(z.object({ filename: z.string() })), packedTgzData, new DataError(packedTgzData, "AMBIGUOUS_EXPECTED_FILE_NAME", "Could not figure out the expected filename."));
+	const parsedPackedTgzData = az.with(packageManager === "pnpm" ? z.object({ filename: z.string() }) : z.array(z.object({ filename: z.string() }))).parse(packedTgzData, new DataError(packedTgzData, "AMBIGUOUS_EXPECTED_FILE_NAME", "Could not figure out the expected filename."));
 	const [normalisedTgzMetadata] = Array.isArray(parsedPackedTgzData) ? parsedPackedTgzData : [parsedPackedTgzData];
 	const { filename: expectedTgzFileName } = normalisedTgzMetadata;
 	return expectedTgzFileName;

package/dist/node/index.cjs

@@ -248,6 +248,21 @@ var CodeError = class CodeError extends Error {
 		throw error;
 	}
 	/**
+	* Check a `CodeError` against its error code
+	*
+	* This will also automatically narrow down the type of the input to be `CodeError`, with its error code properly typed if this function returns true.
+	*
+	* @template ErrorCode The type of the error code
+	*
+	* @param input - The input to check.
+	* @param code - The expected code of the resulting error.
+	*
+	* @returns `true` if the error code matches the expected code, and `false` otherwise. The type of the input will also be narrowed down to CodeError, and its code will be narrowed to the expected code's type if the function returns `true`.
+	*/
+	static checkWithCode(input, code) {
+		return this.check(input) && input.code === code;
+	}
+	/**
 	* 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.
@@ -303,11 +318,10 @@ var DataError = class DataError extends CodeError {
 	* @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(data, code, 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);
@@ -324,6 +338,21 @@ var DataError = class DataError extends CodeError {
 		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
 	}
 	/**
+	* Check a `DataError` against its error code
+	*
+	* This will also automatically narrow down the type of the input to be `DataError`, with its error code properly typed if this function returns true.
+	*
+	* @template ErrorCode The type of the error code
+	*
+	* @param input - The input to check.
+	* @param code - The expected code of the resulting error.
+	*
+	* @returns `true` if the error code matches the expected code, and `false` otherwise. The type of the input will also be narrowed down to `DataError`, and its code will be narrowed to the expected code's type if the function returns `true`.
+	*/
+	static checkWithCode(input, code) {
+		return this.check(input) && input.code === code;
+	}
+	/**
 	* 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.
 	*
 	* @param errorFunction - The function expected to throw the error.