@alextheman/utility 5.0.0 → 5.1.0

package/dist/internal/index.d.ts

@@ -1,16 +1,51 @@
+import { ExecaMethod } from "execa";
 import z from "zod";
 
-//#region src/internal/getExpectedTgzName.d.ts
-declare function getExpectedTgzName(packagePath: string, packageManager: string): Promise<string>;
-//#endregion
-//#region src/internal/getPackageJsonContents.d.ts
-declare function getPackageJsonContents(directory: string): Promise<Record<string, any> | null>;
+//#region src/root/types/RecordKey.d.ts
+/**
+ * Represents the native Record's possible key type.
+ *
+ * @category Types
+ */
+type RecordKey = string | number | symbol;
 //#endregion
-//#region src/internal/getPackageJsonPath.d.ts
-declare function getPackageJsonPath(directory: string): string;
+//#region src/root/types/DataError.d.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.
+ */
+declare class DataError<DataType extends Record<RecordKey, unknown> = Record<RecordKey, unknown>> extends Error {
+  code: string;
+  data: DataType;
+  /**
+   * @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: DataType, code?: string, message?: string, options?: ErrorOptions);
+  /**
+   * Checks whether the given input may have been caused by a DataError.
+   *
+   * @param input - The input to check.
+   *
+   * @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 Record<RecordKey, unknown> = Record<RecordKey, unknown>>(input: unknown): input is DataError<DataType>;
+}
 //#endregion
-//#region src/internal/parseJsonFromStdout.d.ts
-declare function parseJsonFromStdout(stdout: string): Record<string, unknown>;
+//#region src/root/types/CreateEnumType.d.ts
+/**
+ * Get the value types from a const object so the object can behave similarly to an enum.
+ *
+ * @category Types
+ *
+ * @template ObjectType - The type of the object to get the value types for.
+ */
+type CreateEnumType<ObjectType extends Record<RecordKey, unknown>> = ObjectType[keyof ObjectType];
 //#endregion
 //#region src/root/types/IsTypeArgumentString.d.ts
 type IsTypeArgumentString<Argument extends string> = Argument;
@@ -25,4 +60,49 @@ type IsTypeArgumentString<Argument extends string> = Argument;
  */
 declare function sayHello(): string;
 //#endregion
-export { type IsTypeArgumentString, getExpectedTgzName, getPackageJsonContents, getPackageJsonPath, parseJsonFromStdout, sayHello };
+//#region src/internal/DependencyGroup.d.ts
+declare const DependencyGroup: {
+  readonly DEPENDENCIES: "dependencies";
+  readonly DEV_DEPENDENCIES: "devDependencies";
+};
+type DependencyGroup = CreateEnumType<typeof DependencyGroup>;
+//#endregion
+//#region src/internal/getExpectedTgzName.d.ts
+declare function getExpectedTgzName(packagePath: string, packageManager: string): Promise<string>;
+//#endregion
+//#region src/internal/getPackageJsonContents.d.ts
+declare function getPackageJsonContents(directory: string): Promise<Record<string, any> | null>;
+//#endregion
+//#region src/internal/getPackageJsonPath.d.ts
+declare function getPackageJsonPath(directory: string): string;
+//#endregion
+//#region src/internal/ModuleType.d.ts
+declare const ModuleType: {
+  readonly COMMON_JS: "commonjs";
+  readonly ES_MODULES: "module";
+  readonly TYPESCRIPT: "typescript";
+};
+type ModuleType = CreateEnumType<typeof ModuleType>;
+//#endregion
+//#region src/internal/packageJsonNotFoundError.d.ts
+declare function packageJsonNotFoundError(packagePath: string): DataError;
+//#endregion
+//#region src/internal/PackageManager.d.ts
+declare const PackageManager: {
+  readonly NPM: "npm";
+  readonly PNPM: "pnpm";
+};
+type PackageManager = CreateEnumType<typeof PackageManager>;
+//#endregion
+//#region src/internal/parseJsonFromStdout.d.ts
+declare function parseJsonFromStdout(stdout: string): Record<string, unknown>;
+//#endregion
+//#region src/internal/setupPackageEndToEnd.d.ts
+interface SetupPackageEndToEndOptions {
+  dependencyGroup?: DependencyGroup;
+}
+declare function setupPackageEndToEnd(temporaryPath: string, packageManager: PackageManager, moduleType: ModuleType, options?: SetupPackageEndToEndOptions): Promise<ExecaMethod<{
+  cwd: string;
+}>>;
+//#endregion
+export { DependencyGroup, type IsTypeArgumentString, ModuleType, PackageManager, getExpectedTgzName, getPackageJsonContents, getPackageJsonPath, packageJsonNotFoundError, parseJsonFromStdout, sayHello, setupPackageEndToEnd };

package/dist/internal/index.js

@@ -1,9 +1,16 @@
 import { execa } from "execa";
 import z from "zod";
-import path from "node:path";
 import "libsodium-wrappers";
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 
+//#region src/internal/DependencyGroup.ts
+const DependencyGroup = {
+	DEPENDENCIES: "dependencies",
+	DEV_DEPENDENCIES: "devDependencies"
+};
+
+//#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
 * Creates a new array where each element is the result of the provided callback.
@@ -596,6 +603,27 @@ async function getPackageJsonContents(directory) {
 	}
 }
 
+//#endregion
+//#region src/internal/ModuleType.ts
+const ModuleType = {
+	COMMON_JS: "commonjs",
+	ES_MODULES: "module",
+	TYPESCRIPT: "typescript"
+};
+
+//#endregion
+//#region src/internal/packageJsonNotFoundError.ts
+function packageJsonNotFoundError(packagePath) {
+	return new DataError({ packagePath: getPackageJsonPath(packagePath) }, "PACKAGE_JSON_NOT_FOUND", "Could not find package.json in directory.");
+}
+
+//#endregion
+//#region src/internal/PackageManager.ts
+const PackageManager = {
+	NPM: "npm",
+	PNPM: "pnpm"
+};
+
 //#endregion
 //#region src/internal/parseJsonFromStdout.ts
 function parseJsonFromStdout(stdout) {
@@ -613,4 +641,21 @@ function parseJsonFromStdout(stdout) {
 var sayHello_default = sayHello;
 
 //#endregion
-export { getExpectedTgzName, getPackageJsonContents, getPackageJsonPath, parseJsonFromStdout, sayHello_default as sayHello };
+//#region src/internal/setupPackageEndToEnd.ts
+async function setupPackageEndToEnd(temporaryPath, packageManager, moduleType, options) {
+	const { dependencyGroup = "dependencies" } = options ?? {};
+	await execa({ cwd: process.cwd() })`${packageManager} pack --pack-destination ${temporaryPath}`;
+	const tgzFileName = await getExpectedTgzName(process.cwd(), packageManager);
+	const runCommandInTempDirectory = execa({ cwd: temporaryPath });
+	if (packageManager === PackageManager.NPM) await runCommandInTempDirectory`npm init -y`;
+	else await runCommandInTempDirectory`pnpm init`;
+	const packageInfo = await getPackageJsonContents(temporaryPath);
+	if (packageInfo === null) throw packageJsonNotFoundError(temporaryPath);
+	packageInfo.type = moduleType === ModuleType.TYPESCRIPT ? ModuleType.ES_MODULES : moduleType;
+	await writeFile(path.join(temporaryPath, "package.json"), JSON.stringify(packageInfo, null, 2));
+	await runCommandInTempDirectory`${packageManager} install ${dependencyGroup === "devDependencies" ? "--save-dev" : "--save-prod"} ${path.join(temporaryPath, tgzFileName)}`;
+	return runCommandInTempDirectory;
+}
+
+//#endregion
+export { DependencyGroup, ModuleType, PackageManager, getExpectedTgzName, getPackageJsonContents, getPackageJsonPath, packageJsonNotFoundError, parseJsonFromStdout, sayHello_default as sayHello, setupPackageEndToEnd };

package/dist/node/index.cjs

@@ -76,6 +76,47 @@ const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
 //#region src/root/constants/VERSION_NUMBER_REGEX.ts
 const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
 
+//#endregion
+//#region src/root/types/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 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) {
+		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 DataError.
+	*
+	* @param input - The input to check.
+	*
+	* @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(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;
+	}
+};
+
 //#endregion
 //#region src/root/functions/arrayHelpers/fillArray.ts
 /**
@@ -127,212 +168,6 @@ function paralleliseArrays(firstArray, secondArray) {
 	return outputArray;
 }
 
-//#endregion
-//#region src/root/types/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 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) {
-		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 DataError.
-	*
-	* @param input - The input to check.
-	*
-	* @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(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;
-	}
-};
-
-//#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 (!RegExp(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;
-		}
-	}
-	/**
-	* 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 = zod.default.union([
-	zod.default.string(),
-	zod.default.tuple([
-		zod.default.number(),
-		zod.default.number(),
-		zod.default.number()
-	]),
-	zod.default.instanceof(VersionNumber)
-]).transform((rawVersionNumber) => {
-	return new VersionNumber(rawVersionNumber);
-});
-
 //#endregion
 //#region src/root/functions/parsers/parseIntStrict.ts
 /**
@@ -584,6 +419,202 @@ const VersionType = {
 	PATCH: "patch"
 };
 
+//#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 (!RegExp(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;
+		}
+	}
+	/**
+	* 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 = zod.default.union([
+	zod.default.string(),
+	zod.default.tuple([
+		zod.default.number(),
+		zod.default.number(),
+		zod.default.number()
+	]),
+	zod.default.instanceof(VersionNumber)
+]).transform((rawVersionNumber) => {
+	return new VersionNumber(rawVersionNumber);
+});
+
+//#endregion
+//#region src/node/functions/parseFilePath.ts
+/**
+* Takes a file path string and parses it into the directory part, the base part, and the full path.
+*
+* @category Parsers
+*
+* @param filePath - The file path to parse.
+*
+* @throws {DataError} If the file path is invalid.
+*
+* @returns An object representing the different ways the file path can be represented.
+*/
+function parseFilePath(filePath) {
+	const caughtGroups = filePath.match(RegExp(FILE_PATH_REGEX));
+	if (!caughtGroups) {
+		if (!(filePath.includes("/") || filePath.includes("\\")) && filePath.includes(".")) return {
+			directory: "",
+			base: filePath,
+			fullPath: filePath
+		};
+		throw new DataError({ filePath }, "INVALID_FILE_PATH", "The file path you provided is not valid.");
+	}
+	if (!caughtGroups.groups) throw new DataError({ filePath }, "PARSING_ERROR", "An error occurred while trying to parse the data.");
+	return {
+		directory: caughtGroups.groups.directory,
+		base: caughtGroups.groups.base,
+		fullPath: node_path.default.join(caughtGroups.groups.directory.replaceAll("\\", "/"), caughtGroups.groups.base)
+	};
+}
+
 //#endregion
 //#region src/node/functions/sayHello.ts
 var sayHello_default = sayHello;
@@ -591,4 +622,5 @@ var sayHello_default = sayHello;
 //#endregion
 exports.normaliseImportPath = normaliseImportPath;
 exports.normalizeImportPath = normalizeImportPath;
+exports.parseFilePath = parseFilePath;
 exports.sayHello = sayHello_default;

package/dist/node/index.d.cts

@@ -30,6 +30,28 @@ declare function normalizeImportPath(importPath: string): string;
  */
 declare const normaliseImportPath: typeof normalizeImportPath;
 //#endregion
+//#region src/node/functions/parseFilePath.d.ts
+interface FilePathData {
+  /** The file path without the final part. */
+  directory: string;
+  /** The final part of the file path. */
+  base: string;
+  /** The full file path, normalised. */
+  fullPath: string;
+}
+/**
+ * Takes a file path string and parses it into the directory part, the base part, and the full path.
+ *
+ * @category Parsers
+ *
+ * @param filePath - The file path to parse.
+ *
+ * @throws {DataError} If the file path is invalid.
+ *
+ * @returns An object representing the different ways the file path can be represented.
+ */
+declare function parseFilePath(filePath: string): FilePathData;
+//#endregion
 //#region src/root/types/IsTypeArgumentString.d.ts
 type IsTypeArgumentString<Argument extends string> = Argument;
 //#endregion
@@ -43,4 +65,4 @@ type IsTypeArgumentString<Argument extends string> = Argument;
  */
 declare function sayHello(): string;
 //#endregion
-export { IsTypeArgumentString, normaliseImportPath, normalizeImportPath, sayHello };
+export { IsTypeArgumentString, normaliseImportPath, normalizeImportPath, parseFilePath, sayHello };