@alextheman/utility 4.16.2 → 5.0.0

package/dist/node/index.js

@@ -0,0 +1,562 @@
+import path from "node:path";
+import z from "zod";
+import "libsodium-wrappers";
+
+//#region src/node/functions/normalizeImportPath.ts
+/**
+* Normalizes an import path meant for use in an import statement in JavaScript.
+* When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used. If the path is a zero-length string, '.' is returned, representing the current working directory.
+*
+* If the path starts with ./, it is preserved (unlike what would happen with path.posix.normalize() normally).
+*
+* Helpful for custom linter rules that need to check (or fix) import paths.
+*
+* @category String Helpers
+*
+* @param importPath - The import path to normalize.
+*
+* @returns The import path normalized.
+*/
+function normalizeImportPath(importPath) {
+	const normalizedPath = path.posix.normalize(importPath);
+	if (importPath.startsWith("./") && !normalizedPath.startsWith("./")) return `./${normalizedPath}`;
+	return normalizedPath;
+}
+/**
+* Normalises an import path meant for use in an import statement in JavaScript.
+* When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used. If the path is a zero-length string, '.' is returned, representing the current working directory.
+*
+* If the path starts with ./, it is preserved (unlike what would happen with path.posix.normalize() normally).
+*
+* Helpful for custom linter rules that need to check (or fix) import paths.
+*
+* @category String Helpers
+*
+* @param importPath - The import path to normalise.
+*
+* @returns The import path normalised.
+*/
+const normaliseImportPath = normalizeImportPath;
+
+//#endregion
+//#region src/root/constants/FILE_PATH_REGEX.ts
+const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
+
+//#endregion
+//#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/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/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 = 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/functions/parsers/parseIntStrict.ts
+/**
+* Converts a string to an integer and throws an error if it cannot be converted.
+*
+* @category Parsers
+*
+* @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.
+*
+* @throws {DataError} If the provided string cannot safely be converted to an integer.
+*
+* @returns The integer parsed from the input string.
+*/
+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].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/taggedTemplate/interpolate.ts
+/**
+* Returns the result of interpolating a template string when given the strings and interpolations separately.
+*
+* You can pass a template string directly by doing:
+*
+* ```
+* interpolate`Template string here`;
+* ```
+*
+* In this case, it will be functionally the same as if you just wrote the template string by itself.
+*
+* @category Tagged Template
+*
+* @template InterpolationsType - The type of the interpolations.
+*
+* @param strings - The strings from the template to process.
+* @param interpolations - An array of all interpolations from the template.
+*
+* @returns A new string with the strings and interpolations from the template applied.
+*/
+function interpolate(strings, ...interpolations) {
+	let result = "";
+	for (const [string, interpolation = ""] of paralleliseArrays(strings, interpolations)) result += string + interpolation;
+	return result;
+}
+
+//#endregion
+//#region src/root/functions/taggedTemplate/normaliseIndents.ts
+function calculateTabSize(line, whitespaceLength) {
+	const potentialWhitespacePart = line.slice(0, whitespaceLength);
+	const trimmedString = line.trimStart();
+	if (potentialWhitespacePart.trim() !== "") return 0;
+	const tabSize = line.length - (trimmedString.length + whitespaceLength);
+	return tabSize < 0 ? 0 : tabSize;
+}
+function getWhitespaceLength(lines) {
+	const [firstNonEmptyLine] = lines.filter((line) => {
+		return line.trim() !== "";
+	});
+	return firstNonEmptyLine.length - firstNonEmptyLine.trimStart().length;
+}
+function reduceLines(lines, { preserveTabs = true }) {
+	const slicedLines = lines.slice(1);
+	const isFirstLineEmpty = lines[0].trim() === "";
+	const whitespaceLength = getWhitespaceLength(isFirstLineEmpty ? lines : slicedLines);
+	return (isFirstLineEmpty ? slicedLines : lines).map((line) => {
+		const tabSize = calculateTabSize(line, whitespaceLength);
+		return (preserveTabs ? fillArray(() => {
+			return " ";
+		}, tabSize).join("") : "") + line.trimStart();
+	}).join("\n");
+}
+/**
+* Applies any options if provided, then removes any extraneous indents from a multi-line template string.
+*
+* You can pass a template string directly by doing:
+*
+* ```typescript
+* normaliseIndents`Template string here
+*     with a new line
+*     and another new line`;
+* ```
+*
+* You may also pass the options first, then invoke the resulting function with a template string:
+*
+* ```typescript
+* normaliseIndents({ preserveTabs: false })`Template string here
+*     with a new line
+*     and another new line`;
+* ```
+*
+* @category Tagged Template
+*
+* @param first - The strings from the template to process, or the options to apply.
+* @param args - An array of all interpolations from the template.
+*
+* @returns An additional function to invoke, or a new string with the strings and interpolations from the template applied, and extraneous indents removed.
+*/
+function normaliseIndents(first, ...args) {
+	if (typeof first === "object" && first !== null && !Array.isArray(first)) {
+		const options = first;
+		return (strings, ...interpolations) => {
+			return normaliseIndents(strings, ...interpolations, options);
+		};
+	}
+	const strings = first;
+	const options = typeof args[args.length - 1] === "object" && !Array.isArray(args[args.length - 1]) ? args.pop() : {};
+	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/parseVersionType.ts
+/**
+* Represents the three common software version types.
+*
+* @category Types
+*/
+const VersionType = {
+	MAJOR: "major",
+	MINOR: "minor",
+	PATCH: "patch"
+};
+
+//#endregion
+//#region src/node/functions/sayHello.ts
+var sayHello_default = sayHello;
+
+//#endregion
+export { normaliseImportPath, normalizeImportPath, sayHello_default as sayHello };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "4.16.2",
+  "version": "5.0.0",
   "description": "Helpful utility functions.",
   "repository": {
     "type": "git",
@@ -14,6 +14,16 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./internal": {
+      "types": "./dist/internal/index.d.ts",
+      "import": "./dist/internal/index.js",
+      "require": "./dist/internal/index.cjs"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js",
+      "require": "./dist/node/index.cjs"
     }
   },
   "files": [
@@ -21,6 +31,7 @@
   ],
   "dependencies": {
     "dotenv": "^17.3.1",
+    "execa": "^9.6.1",
     "libsodium-wrappers": "^0.8.2",
     "zod": "^4.3.6"
   },
@@ -30,7 +41,6 @@
     "alex-c-line": "^1.26.2",
     "dotenv-cli": "^11.0.0",
     "eslint": "^10.0.0",
-    "execa": "^9.6.1",
     "globals": "^17.3.0",
     "husky": "^9.1.7",
     "jsdom": "^28.0.0",
@@ -68,7 +78,7 @@
     "prepare-live-eslint-plugin": "pnpm uninstall @alextheman/eslint-plugin && pnpm install --save-dev @alextheman/eslint-plugin",
     "prepare-local-eslint-plugin": "dotenv -e .env -- sh -c 'ESLINT_PLUGIN_PATH=${LOCAL_ESLINT_PLUGIN_PATH:-../eslint-plugin}; pnpm --prefix \"$ESLINT_PLUGIN_PATH\" run build && pnpm uninstall @alextheman/eslint-plugin && pnpm install --save-dev file:\"$ESLINT_PLUGIN_PATH\"'",
     "test": "vitest run",
-    "test-end-to-end": "RUN_END_TO_END=true vitest run tests/end-to-end",
+    "test-end-to-end": "RUN_END_TO_END=true vitest run tests/end-to-end --reporter verbose",
     "test-watch": "vitest",
     "update-dependencies": "pnpm update --latest && pnpm update",
     "use-live-eslint-plugin": "pnpm run prepare-live-eslint-plugin && pnpm run lint",