@alextheman/utility 4.10.2 → 4.12.0

package/dist/index.cjs

@@ -27,11 +27,16 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let zod = require("zod");
 zod = __toESM(zod);
-let libsodium_wrappers = require("libsodium-wrappers");
-libsodium_wrappers = __toESM(libsodium_wrappers);
 let node_path = require("node:path");
 node_path = __toESM(node_path);
+let libsodium_wrappers = require("libsodium-wrappers");
+libsodium_wrappers = __toESM(libsodium_wrappers);
 
+//#region src/constants/FILE_PATH_REGEX.ts
+const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
+var FILE_PATH_REGEX_default = FILE_PATH_REGEX;
+
+//#endregion
 //#region src/constants/NAMESPACE_EXPORT_REGEX.ts
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 var NAMESPACE_EXPORT_REGEX_default = NAMESPACE_EXPORT_REGEX;
@@ -653,17 +658,17 @@ function createFormData(data, options = {
 			default: throw new TypeError("SLOPPY_PURE_JAVASCRIPT_USER_ERROR");
 		}
 	}
-	function resolveNullables(key, value, options$1) {
-		if (options$1.nullableResolution) {
-			resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.nullableResolution));
+	function resolveNullables(key, value, options) {
+		if (options.nullableResolution) {
+			resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options.nullableResolution));
 			return;
 		}
-		if (options$1.undefinedResolution || options$1.nullResolution) {
-			if (data[key] === void 0 && options$1.undefinedResolution) {
-				resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.undefinedResolution));
+		if (options.undefinedResolution || options.nullResolution) {
+			if (data[key] === void 0 && options.undefinedResolution) {
+				resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options.undefinedResolution));
 				return;
 			}
-			if (data[key] === null && options$1.nullResolution) resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.nullResolution));
+			if (data[key] === null && options.nullResolution) resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options.nullResolution));
 		}
 	}
 	const entries = Object.entries(data);
@@ -884,8 +889,8 @@ function _parseZodSchema(parsedResult, data, onError) {
 		}
 		throw new DataError_default(data, Object.entries(allErrorCodes).toSorted(([_, firstCount], [__, secondCount]) => {
 			return secondCount - firstCount;
-		}).map(([code, count], _, allErrorCodes$1) => {
-			return allErrorCodes$1.length === 1 && count === 1 ? code : `${code}×${count}`;
+		}).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;
@@ -945,6 +950,38 @@ function parseEnv(data) {
 }
 var parseEnv_default = parseEnv;
 
+//#endregion
+//#region src/functions/parsers/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_default));
+	if (!caughtGroups) {
+		if (!(filePath.includes("/") || filePath.includes("\\")) && filePath.includes(".")) return {
+			directory: "",
+			base: filePath,
+			fullPath: filePath
+		};
+		throw new DataError_default({ filePath }, "INVALID_FILE_PATH", "The file path you provided is not valid.");
+	}
+	if (!caughtGroups.groups) throw new DataError_default({ 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)
+	};
+}
+var parseFilePath_default = parseFilePath;
+
 //#endregion
 //#region src/functions/parsers/parseFormData.ts
 /**
@@ -1096,6 +1133,32 @@ async function encryptWithKey(publicKey, plaintextValue) {
 }
 var encryptWithKey_default = encryptWithKey;
 
+//#endregion
+//#region src/functions/security/getPublicAndPrivateKey.ts
+/**
+* Returns the public key and private key, properly narrowing down types depending on the provided `outputFormat`.
+*
+* @deprecated Please use `sodium.crypto_box_keypair` from `libsodium-wrappers` instead.
+*
+* This function was initially created to deal with a typing issue with the package introduced in v0.8.1 of said package, but this seems to have been fixed in v0.8.2
+*
+* @param outputFormat - The format of the resulting publicKey and privateKey you would like to use.
+*
+* @returns An object containing both the publicKey and privateKey, along with a keyType.
+*/
+function getPublicAndPrivateKey(outputFormat) {
+	const keys = libsodium_wrappers.default.crypto_box_keypair(outputFormat);
+	if (outputFormat === "uint8array" || outputFormat === void 0) {
+		if (!(keys?.publicKey instanceof Uint8Array && keys?.privateKey instanceof Uint8Array)) throw new DataError_default({
+			publicKey: `<redacted: ${keys?.publicKey?.constructor?.name ?? typeof keys?.publicKey}>`,
+			privateKey: `<redacted: ${keys?.privateKey?.constructor?.name ?? typeof keys?.privateKey}>`
+		}, "INVALID_KEY_TYPES", "Expected Uint8Array keypair from libsodium.");
+		return keys;
+	}
+	return keys;
+}
+var getPublicAndPrivateKey_default = getPublicAndPrivateKey;
+
 //#endregion
 //#region src/functions/stringHelpers/appendSemicolon.ts
 /**
@@ -1143,8 +1206,8 @@ function camelToKebab(string, options = { preserveConsecutiveCapitals: true }) {
 				result += sequenceOfCapitals.toLowerCase();
 			} else {
 				if (result) result += "-";
-				result += sequenceOfCapitals.split("").map((character$1) => {
-					return character$1.toLowerCase();
+				result += sequenceOfCapitals.split("").map((character) => {
+					return character.toLowerCase();
 				}).join("-");
 			}
 			outerIndex = innerIndex;
@@ -1399,9 +1462,9 @@ function reduceLines(lines, { preserveTabs = true }) {
 */
 function normaliseIndents(first, ...args) {
 	if (typeof first === "object" && first !== null && !Array.isArray(first)) {
-		const options$1 = first;
-		return (strings$1, ...interpolations) => {
-			return normaliseIndents(strings$1, ...interpolations, options$1);
+		const options = first;
+		return (strings, ...interpolations) => {
+			return normaliseIndents(strings, ...interpolations, options);
 		};
 	}
 	const strings = first;
@@ -1531,6 +1594,7 @@ var incrementVersion_default = incrementVersion;
 exports.APIError = APIError_default;
 exports.DataError = DataError_default;
 exports.Env = Env;
+exports.FILE_PATH_REGEX = FILE_PATH_REGEX_default;
 exports.NAMESPACE_EXPORT_REGEX = NAMESPACE_EXPORT_REGEX_default;
 exports.VERSION_NUMBER_REGEX = VERSION_NUMBER_REGEX_default;
 exports.VersionNumber = VersionNumber_default;
@@ -1549,6 +1613,7 @@ exports.fillArray = fillArray_default;
 exports.formatDateAndTime = formatDateAndTime_default;
 exports.getIndividualVersionNumbers = getIndividualVersionNumbers_default;
 exports.getInterpolations = getInterpolations_default;
+exports.getPublicAndPrivateKey = getPublicAndPrivateKey_default;
 exports.getRandomNumber = getRandomNumber_default;
 exports.getRecordKeys = getRecordKeys_default;
 exports.httpErrorCodeLookup = httpErrorCodeLookup;
@@ -1569,6 +1634,7 @@ exports.omitProperties = omitProperties_default;
 exports.paralleliseArrays = paralleliseArrays_default;
 exports.parseBoolean = parseBoolean_default;
 exports.parseEnv = parseEnv_default;
+exports.parseFilePath = parseFilePath_default;
 exports.parseFormData = parseFormData_default;
 exports.parseIntStrict = parseIntStrict_default;
 exports.parseVersion = parseVersion_default;

package/dist/index.d.cts

@@ -1,6 +1,10 @@
 import { DotenvParseOutput } from "dotenv";
 import { ZodError, ZodType, z } from "zod";
+import sodium from "libsodium-wrappers";
 
+//#region src/constants/FILE_PATH_REGEX.d.ts
+declare const FILE_PATH_REGEX: string;
+//#endregion
 //#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
 declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 //#endregion
@@ -341,6 +345,9 @@ declare class VersionNumber {
  */
 type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
 //#endregion
+//#region src/types/CallReturnType.d.ts
+type CallReturnType<Function, Arguments> = Function extends ((arg: Arguments) => infer Return) ? Return : never;
+//#endregion
 //#region src/types/RecordKey.d.ts
 /**
  * Represents the native Record's possible key type.
@@ -410,9 +417,9 @@ type FormDataArrayResolutionStrategy = "stringify" | "multiple";
  *
  * @template Key - The type of the key of the input record.
  */
-interface CreateFormDataOptionsBase<Key$1 extends RecordKey> {
+interface CreateFormDataOptionsBase<Key extends RecordKey> {
   /** How to resolve any arrays provided in the data (can either stringify them or add them multiple times). */
-  arrayResolution?: FormDataArrayResolutionStrategy | Partial<Record<Key$1, FormDataArrayResolutionStrategy>>;
+  arrayResolution?: FormDataArrayResolutionStrategy | Partial<Record<Key, FormDataArrayResolutionStrategy>>;
 }
 /**
  * Options for resolving form data when it may be undefined or null, but not both.
@@ -421,11 +428,11 @@ interface CreateFormDataOptionsBase<Key$1 extends RecordKey> {
  *
  * @template Key - The type of the key of the input record.
  */
-interface CreateFormDataOptionsUndefinedOrNullResolution<Key$1 extends RecordKey> extends CreateFormDataOptionsBase<Key$1> {
+interface CreateFormDataOptionsUndefinedOrNullResolution<Key extends RecordKey> extends CreateFormDataOptionsBase<Key> {
   /** How to resolve undefined data (May either stringify to 'undefined', resolve to an empty string, or omit entirely). */
-  undefinedResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key$1, FormDataNullableResolutionStrategy>>;
+  undefinedResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
   /** How to resolve null data (May either stringify to 'null', resolve to an empty string, or omit entirely). */
-  nullResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key$1, FormDataNullableResolutionStrategy>>;
+  nullResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
   /** @note This must not be provided at the same time as undefinedResolution and/or nullResolution. */
   nullableResolution?: never;
 }
@@ -436,13 +443,13 @@ interface CreateFormDataOptionsUndefinedOrNullResolution<Key$1 extends RecordKey
  *
  * @template Key - The type of the key of the input record.
  */
-interface CreateFormDataOptionsNullableResolution<Key$1 extends RecordKey> extends CreateFormDataOptionsBase<Key$1> {
+interface CreateFormDataOptionsNullableResolution<Key extends RecordKey> extends CreateFormDataOptionsBase<Key> {
   /** @note This must not be provided at the same time as nullableResolution. */
   undefinedResolution?: never;
   /** @note This must not be provided at the same time as nullableResolution. */
   nullResolution?: never;
   /** How to resolve nullable data (May either stringify to 'undefined | null', resolve to an empty string, or omit entirely). */
-  nullableResolution: FormDataNullableResolutionStrategy | Partial<Record<Key$1, FormDataNullableResolutionStrategy>>;
+  nullableResolution: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
 }
 /**
  * Options for resolving form data.
@@ -451,7 +458,7 @@ interface CreateFormDataOptionsNullableResolution<Key$1 extends RecordKey> exten
  *
  * @template Key - The type of the key of the input record.
  */
-type CreateFormDataOptions<Key$1 extends RecordKey> = CreateFormDataOptionsUndefinedOrNullResolution<Key$1> | CreateFormDataOptionsNullableResolution<Key$1>;
+type CreateFormDataOptions<Key extends RecordKey> = CreateFormDataOptionsUndefinedOrNullResolution<Key> | CreateFormDataOptionsNullableResolution<Key>;
 /**
  * Creates FormData from a given object, resolving non-string types as appropriate.
  *
@@ -628,6 +635,28 @@ type Env = CreateEnumType<typeof Env>;
  */
 declare function parseEnv(data: unknown): Env;
 //#endregion
+//#region src/functions/parsers/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/functions/parsers/parseFormData.d.ts
 /**
  * Returns a parsed object given FormData and a data parser function to call on the resulting object.
@@ -771,6 +800,56 @@ declare function deepFreeze<ObjectType extends object>(object: ObjectType): Read
  */
 declare function encryptWithKey(publicKey: string, plaintextValue: string): Promise<string>;
 //#endregion
+//#region src/functions/security/getPublicAndPrivateKey.d.ts
+interface PublicAndPrivateKey<KeyType extends Uint8Array | string> {
+  /** The generated public key from libsodium */
+  publicKey: KeyType;
+  /** The generated private key from libsodium */
+  privateKey: KeyType;
+  /** The key type from libsodium */
+  keyType: ReturnType<typeof sodium.crypto_box_keypair>["keyType"];
+}
+/**
+ * Returns the public key and private key, properly narrowing down types depending on the provided `outputFormat`.
+ *
+ * @deprecated Please use `sodium.crypto_box_keypair` from `libsodium-wrappers` instead.
+ *
+ * This function was initially created to deal with a typing issue with the package introduced in v0.8.1 of said package, but this seems to have been fixed in v0.8.2
+ *
+ * @returns An object containing both the publicKey and privateKey, along with a keyType.
+ *
+ * Because you have not provided an `outputFormat`, the keys will be typed as `Uint8Array`.
+ */
+declare function getPublicAndPrivateKey(): PublicAndPrivateKey<Uint8Array>;
+/**
+ * Returns the public key and private key, properly narrowing down types depending on the provided `outputFormat`.
+ *
+ * @deprecated Please use `sodium.crypto_box_keypair` from `libsodium-wrappers` instead.
+ *
+ * This function was initially created to deal with a typing issue with the package introduced in v0.8.1 of said package, but this seems to have been fixed in v0.8.2
+ *
+ * @param outputFormat - The format of the resulting publicKey and privateKey you would like to use.
+ *
+ * @returns An object containing both the publicKey and privateKey, along with a keyType.
+ *
+ * Because you provided an `outputFormat` of `uint8array`, the keys will be typed as `Uint8Array`.
+ */
+declare function getPublicAndPrivateKey(outputFormat: "uint8array"): PublicAndPrivateKey<Uint8Array>;
+/**
+ * Returns the public key and private key, properly narrowing down types depending on the provided `outputFormat`.
+ *
+ * @deprecated Please use `sodium.crypto_box_keypair` from `libsodium-wrappers` instead.
+ *
+ * This function was initially created to deal with a typing issue with the package introduced in v0.8.1 of said package, but this seems to have been fixed in v0.8.2
+ *
+ * @param outputFormat - The format of the resulting publicKey and privateKey you would like to use.
+ *
+ * @returns An object containing both the publicKey and privateKey, along with a keyType.
+ *
+ * Because you provided an `outputFormat` of either `text`, `hex` or `base64`, the keys will be typed as `string`.
+ */
+declare function getPublicAndPrivateKey(outputFormat: "text" | "hex" | "base64"): PublicAndPrivateKey<string>;
+//#endregion
 //#region src/functions/stringHelpers/appendSemicolon.d.ts
 /**
  * Appends a semicolon to the end of a string, trimming where necessary first.
@@ -1083,4 +1162,4 @@ interface ParseVersionOptions {
  */
 declare function parseVersion(input: string, options?: ParseVersionOptions): string;
 //#endregion
-export { APIError, ArrayElement, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParallelTuple, ParseVersionOptions, RecordKey, RemoveUndefined, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, encryptWithKey, fillArray, formatDateAndTime, getIndividualVersionNumbers, getInterpolations, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, stringListToArray, stringifyDotenv, truncate, wait };
+export { APIError, ArrayElement, CallReturnType, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FILE_PATH_REGEX, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParallelTuple, ParseVersionOptions, PublicAndPrivateKey, RecordKey, RemoveUndefined, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, encryptWithKey, fillArray, formatDateAndTime, getIndividualVersionNumbers, getInterpolations, getPublicAndPrivateKey, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFilePath, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, stringListToArray, stringifyDotenv, truncate, wait };

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 import { ZodError, ZodType, z as z$1 } from "zod";
+import sodium from "libsodium-wrappers";
 import { DotenvParseOutput } from "dotenv";
 
+//#region src/constants/FILE_PATH_REGEX.d.ts
+declare const FILE_PATH_REGEX: string;
+//#endregion
 //#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
 declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 //#endregion
@@ -341,6 +345,9 @@ declare class VersionNumber {
  */
 type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
 //#endregion
+//#region src/types/CallReturnType.d.ts
+type CallReturnType<Function, Arguments> = Function extends ((arg: Arguments) => infer Return) ? Return : never;
+//#endregion
 //#region src/types/RecordKey.d.ts
 /**
  * Represents the native Record's possible key type.
@@ -410,9 +417,9 @@ type FormDataArrayResolutionStrategy = "stringify" | "multiple";
  *
  * @template Key - The type of the key of the input record.
  */
-interface CreateFormDataOptionsBase<Key$1 extends RecordKey> {
+interface CreateFormDataOptionsBase<Key extends RecordKey> {
   /** How to resolve any arrays provided in the data (can either stringify them or add them multiple times). */
-  arrayResolution?: FormDataArrayResolutionStrategy | Partial<Record<Key$1, FormDataArrayResolutionStrategy>>;
+  arrayResolution?: FormDataArrayResolutionStrategy | Partial<Record<Key, FormDataArrayResolutionStrategy>>;
 }
 /**
  * Options for resolving form data when it may be undefined or null, but not both.
@@ -421,11 +428,11 @@ interface CreateFormDataOptionsBase<Key$1 extends RecordKey> {
  *
  * @template Key - The type of the key of the input record.
  */
-interface CreateFormDataOptionsUndefinedOrNullResolution<Key$1 extends RecordKey> extends CreateFormDataOptionsBase<Key$1> {
+interface CreateFormDataOptionsUndefinedOrNullResolution<Key extends RecordKey> extends CreateFormDataOptionsBase<Key> {
   /** How to resolve undefined data (May either stringify to 'undefined', resolve to an empty string, or omit entirely). */
-  undefinedResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key$1, FormDataNullableResolutionStrategy>>;
+  undefinedResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
   /** How to resolve null data (May either stringify to 'null', resolve to an empty string, or omit entirely). */
-  nullResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key$1, FormDataNullableResolutionStrategy>>;
+  nullResolution?: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
   /** @note This must not be provided at the same time as undefinedResolution and/or nullResolution. */
   nullableResolution?: never;
 }
@@ -436,13 +443,13 @@ interface CreateFormDataOptionsUndefinedOrNullResolution<Key$1 extends RecordKey
  *
  * @template Key - The type of the key of the input record.
  */
-interface CreateFormDataOptionsNullableResolution<Key$1 extends RecordKey> extends CreateFormDataOptionsBase<Key$1> {
+interface CreateFormDataOptionsNullableResolution<Key extends RecordKey> extends CreateFormDataOptionsBase<Key> {
   /** @note This must not be provided at the same time as nullableResolution. */
   undefinedResolution?: never;
   /** @note This must not be provided at the same time as nullableResolution. */
   nullResolution?: never;
   /** How to resolve nullable data (May either stringify to 'undefined | null', resolve to an empty string, or omit entirely). */
-  nullableResolution: FormDataNullableResolutionStrategy | Partial<Record<Key$1, FormDataNullableResolutionStrategy>>;
+  nullableResolution: FormDataNullableResolutionStrategy | Partial<Record<Key, FormDataNullableResolutionStrategy>>;
 }
 /**
  * Options for resolving form data.
@@ -451,7 +458,7 @@ interface CreateFormDataOptionsNullableResolution<Key$1 extends RecordKey> exten
  *
  * @template Key - The type of the key of the input record.
  */
-type CreateFormDataOptions<Key$1 extends RecordKey> = CreateFormDataOptionsUndefinedOrNullResolution<Key$1> | CreateFormDataOptionsNullableResolution<Key$1>;
+type CreateFormDataOptions<Key extends RecordKey> = CreateFormDataOptionsUndefinedOrNullResolution<Key> | CreateFormDataOptionsNullableResolution<Key>;
 /**
  * Creates FormData from a given object, resolving non-string types as appropriate.
  *
@@ -628,6 +635,28 @@ type Env = CreateEnumType<typeof Env>;
  */
 declare function parseEnv(data: unknown): Env;
 //#endregion
+//#region src/functions/parsers/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/functions/parsers/parseFormData.d.ts
 /**
  * Returns a parsed object given FormData and a data parser function to call on the resulting object.
@@ -771,6 +800,56 @@ declare function deepFreeze<ObjectType extends object>(object: ObjectType): Read
  */
 declare function encryptWithKey(publicKey: string, plaintextValue: string): Promise<string>;
 //#endregion
+//#region src/functions/security/getPublicAndPrivateKey.d.ts
+interface PublicAndPrivateKey<KeyType extends Uint8Array | string> {
+  /** The generated public key from libsodium */
+  publicKey: KeyType;
+  /** The generated private key from libsodium */
+  privateKey: KeyType;
+  /** The key type from libsodium */
+  keyType: ReturnType<typeof sodium.crypto_box_keypair>["keyType"];
+}
+/**
+ * Returns the public key and private key, properly narrowing down types depending on the provided `outputFormat`.
+ *
+ * @deprecated Please use `sodium.crypto_box_keypair` from `libsodium-wrappers` instead.
+ *
+ * This function was initially created to deal with a typing issue with the package introduced in v0.8.1 of said package, but this seems to have been fixed in v0.8.2
+ *
+ * @returns An object containing both the publicKey and privateKey, along with a keyType.
+ *
+ * Because you have not provided an `outputFormat`, the keys will be typed as `Uint8Array`.
+ */
+declare function getPublicAndPrivateKey(): PublicAndPrivateKey<Uint8Array>;
+/**
+ * Returns the public key and private key, properly narrowing down types depending on the provided `outputFormat`.
+ *
+ * @deprecated Please use `sodium.crypto_box_keypair` from `libsodium-wrappers` instead.
+ *
+ * This function was initially created to deal with a typing issue with the package introduced in v0.8.1 of said package, but this seems to have been fixed in v0.8.2
+ *
+ * @param outputFormat - The format of the resulting publicKey and privateKey you would like to use.
+ *
+ * @returns An object containing both the publicKey and privateKey, along with a keyType.
+ *
+ * Because you provided an `outputFormat` of `uint8array`, the keys will be typed as `Uint8Array`.
+ */
+declare function getPublicAndPrivateKey(outputFormat: "uint8array"): PublicAndPrivateKey<Uint8Array>;
+/**
+ * Returns the public key and private key, properly narrowing down types depending on the provided `outputFormat`.
+ *
+ * @deprecated Please use `sodium.crypto_box_keypair` from `libsodium-wrappers` instead.
+ *
+ * This function was initially created to deal with a typing issue with the package introduced in v0.8.1 of said package, but this seems to have been fixed in v0.8.2
+ *
+ * @param outputFormat - The format of the resulting publicKey and privateKey you would like to use.
+ *
+ * @returns An object containing both the publicKey and privateKey, along with a keyType.
+ *
+ * Because you provided an `outputFormat` of either `text`, `hex` or `base64`, the keys will be typed as `string`.
+ */
+declare function getPublicAndPrivateKey(outputFormat: "text" | "hex" | "base64"): PublicAndPrivateKey<string>;
+//#endregion
 //#region src/functions/stringHelpers/appendSemicolon.d.ts
 /**
  * Appends a semicolon to the end of a string, trimming where necessary first.
@@ -1083,4 +1162,4 @@ interface ParseVersionOptions {
  */
 declare function parseVersion(input: string, options?: ParseVersionOptions): string;
 //#endregion
-export { APIError, ArrayElement, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, type IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParallelTuple, type ParseVersionOptions, RecordKey, RemoveUndefined, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, encryptWithKey, fillArray, formatDateAndTime, getIndividualVersionNumbers, getInterpolations, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, stringListToArray, stringifyDotenv, truncate, wait };
+export { APIError, ArrayElement, CallReturnType, CamelToKebabOptions, CreateEnumType, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DisallowUndefined, Env, FILE_PATH_REGEX, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, type IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParallelTuple, type ParseVersionOptions, type PublicAndPrivateKey, RecordKey, RemoveUndefined, StringListToArrayOptions, VERSION_NUMBER_REGEX, VersionNumber, VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, encryptWithKey, fillArray, formatDateAndTime, getIndividualVersionNumbers, getInterpolations, getPublicAndPrivateKey, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFilePath, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, stringListToArray, stringifyDotenv, truncate, wait };

package/dist/index.js

@@ -1,7 +1,12 @@
 import z, { z as z$1 } from "zod";
-import sodium from "libsodium-wrappers";
 import path from "node:path";
+import sodium from "libsodium-wrappers";
 
+//#region src/constants/FILE_PATH_REGEX.ts
+const FILE_PATH_REGEX = String.raw`^(?<directory>.+)[\/\\](?<base>[^\/\\]+)$`;
+var FILE_PATH_REGEX_default = FILE_PATH_REGEX;
+
+//#endregion
 //#region src/constants/NAMESPACE_EXPORT_REGEX.ts
 const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
 var NAMESPACE_EXPORT_REGEX_default = NAMESPACE_EXPORT_REGEX;
@@ -623,17 +628,17 @@ function createFormData(data, options = {
 			default: throw new TypeError("SLOPPY_PURE_JAVASCRIPT_USER_ERROR");
 		}
 	}
-	function resolveNullables(key, value, options$1) {
-		if (options$1.nullableResolution) {
-			resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.nullableResolution));
+	function resolveNullables(key, value, options) {
+		if (options.nullableResolution) {
+			resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options.nullableResolution));
 			return;
 		}
-		if (options$1.undefinedResolution || options$1.nullResolution) {
-			if (data[key] === void 0 && options$1.undefinedResolution) {
-				resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.undefinedResolution));
+		if (options.undefinedResolution || options.nullResolution) {
+			if (data[key] === void 0 && options.undefinedResolution) {
+				resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options.undefinedResolution));
 				return;
 			}
-			if (data[key] === null && options$1.nullResolution) resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options$1.nullResolution));
+			if (data[key] === null && options.nullResolution) resolveNullablesByStrategy(key, value, getNullableResolutionStrategy(key, options.nullResolution));
 		}
 	}
 	const entries = Object.entries(data);
@@ -854,8 +859,8 @@ function _parseZodSchema(parsedResult, data, onError) {
 		}
 		throw new DataError_default(data, Object.entries(allErrorCodes).toSorted(([_, firstCount], [__, secondCount]) => {
 			return secondCount - firstCount;
-		}).map(([code, count], _, allErrorCodes$1) => {
-			return allErrorCodes$1.length === 1 && count === 1 ? code : `${code}×${count}`;
+		}).map(([code, count], _, allErrorCodes) => {
+			return allErrorCodes.length === 1 && count === 1 ? code : `${code}×${count}`;
 		}).join(","), `\n\n${z.prettifyError(parsedResult.error)}\n`);
 	}
 	return parsedResult.data;
@@ -915,6 +920,38 @@ function parseEnv(data) {
 }
 var parseEnv_default = parseEnv;
 
+//#endregion
+//#region src/functions/parsers/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_default));
+	if (!caughtGroups) {
+		if (!(filePath.includes("/") || filePath.includes("\\")) && filePath.includes(".")) return {
+			directory: "",
+			base: filePath,
+			fullPath: filePath
+		};
+		throw new DataError_default({ filePath }, "INVALID_FILE_PATH", "The file path you provided is not valid.");
+	}
+	if (!caughtGroups.groups) throw new DataError_default({ filePath }, "PARSING_ERROR", "An error occurred while trying to parse the data.");
+	return {
+		directory: caughtGroups.groups.directory,
+		base: caughtGroups.groups.base,
+		fullPath: path.join(caughtGroups.groups.directory.replaceAll("\\", "/"), caughtGroups.groups.base)
+	};
+}
+var parseFilePath_default = parseFilePath;
+
 //#endregion
 //#region src/functions/parsers/parseFormData.ts
 /**
@@ -1066,6 +1103,32 @@ async function encryptWithKey(publicKey, plaintextValue) {
 }
 var encryptWithKey_default = encryptWithKey;
 
+//#endregion
+//#region src/functions/security/getPublicAndPrivateKey.ts
+/**
+* Returns the public key and private key, properly narrowing down types depending on the provided `outputFormat`.
+*
+* @deprecated Please use `sodium.crypto_box_keypair` from `libsodium-wrappers` instead.
+*
+* This function was initially created to deal with a typing issue with the package introduced in v0.8.1 of said package, but this seems to have been fixed in v0.8.2
+*
+* @param outputFormat - The format of the resulting publicKey and privateKey you would like to use.
+*
+* @returns An object containing both the publicKey and privateKey, along with a keyType.
+*/
+function getPublicAndPrivateKey(outputFormat) {
+	const keys = sodium.crypto_box_keypair(outputFormat);
+	if (outputFormat === "uint8array" || outputFormat === void 0) {
+		if (!(keys?.publicKey instanceof Uint8Array && keys?.privateKey instanceof Uint8Array)) throw new DataError_default({
+			publicKey: `<redacted: ${keys?.publicKey?.constructor?.name ?? typeof keys?.publicKey}>`,
+			privateKey: `<redacted: ${keys?.privateKey?.constructor?.name ?? typeof keys?.privateKey}>`
+		}, "INVALID_KEY_TYPES", "Expected Uint8Array keypair from libsodium.");
+		return keys;
+	}
+	return keys;
+}
+var getPublicAndPrivateKey_default = getPublicAndPrivateKey;
+
 //#endregion
 //#region src/functions/stringHelpers/appendSemicolon.ts
 /**
@@ -1113,8 +1176,8 @@ function camelToKebab(string, options = { preserveConsecutiveCapitals: true }) {
 				result += sequenceOfCapitals.toLowerCase();
 			} else {
 				if (result) result += "-";
-				result += sequenceOfCapitals.split("").map((character$1) => {
-					return character$1.toLowerCase();
+				result += sequenceOfCapitals.split("").map((character) => {
+					return character.toLowerCase();
 				}).join("-");
 			}
 			outerIndex = innerIndex;
@@ -1369,9 +1432,9 @@ function reduceLines(lines, { preserveTabs = true }) {
 */
 function normaliseIndents(first, ...args) {
 	if (typeof first === "object" && first !== null && !Array.isArray(first)) {
-		const options$1 = first;
-		return (strings$1, ...interpolations) => {
-			return normaliseIndents(strings$1, ...interpolations, options$1);
+		const options = first;
+		return (strings, ...interpolations) => {
+			return normaliseIndents(strings, ...interpolations, options);
 		};
 	}
 	const strings = first;
@@ -1498,4 +1561,4 @@ function incrementVersion(version, incrementType, options) {
 var incrementVersion_default = incrementVersion;
 
 //#endregion
-export { APIError_default as APIError, DataError_default as DataError, Env, NAMESPACE_EXPORT_REGEX_default as NAMESPACE_EXPORT_REGEX, VERSION_NUMBER_REGEX_default as VERSION_NUMBER_REGEX, VersionNumber_default as VersionNumber, VersionType, addDaysToDate_default as addDaysToDate, appendSemicolon_default as appendSemicolon, camelToKebab_default as camelToKebab, convertFileToBase64_default as convertFileToBase64, createFormData_default as createFormData, createTemplateStringsArray_default as createTemplateStringsArray, deepCopy_default as deepCopy, deepFreeze_default as deepFreeze, determineVersionType_default as determineVersionType, encryptWithKey_default as encryptWithKey, fillArray_default as fillArray, formatDateAndTime_default as formatDateAndTime, getIndividualVersionNumbers_default as getIndividualVersionNumbers, getInterpolations_default as getInterpolations, getRandomNumber_default as getRandomNumber, getRecordKeys_default as getRecordKeys, httpErrorCodeLookup, incrementVersion_default as incrementVersion, interpolate_default as interpolate, interpolateObjects_default as interpolateObjects, isAnniversary_default as isAnniversary, isLeapYear_default as isLeapYear, isMonthlyMultiple_default as isMonthlyMultiple, isOrdered_default as isOrdered, isSameDate_default as isSameDate, kebabToCamel_default as kebabToCamel, normaliseImportPath, normaliseIndents_default as normaliseIndents, normalizeImportPath_default as normalizeImportPath, normalizeIndents, omitProperties_default as omitProperties, paralleliseArrays_default as paralleliseArrays, parseBoolean_default as parseBoolean, parseEnv_default as parseEnv, parseFormData_default as parseFormData, parseIntStrict_default as parseIntStrict, parseVersion_default as parseVersion, parseVersionType_default as parseVersionType, parseZodSchema_default as parseZodSchema, parseZodSchemaAsync_default as parseZodSchemaAsync, randomiseArray_default as randomiseArray, range_default as range, removeDuplicates_default as removeDuplicates, removeUndefinedFromObject_default as removeUndefinedFromObject, stringListToArray_default as stringListToArray, stringifyDotenv_default as stringifyDotenv, truncate_default as truncate, wait_default as wait };
+export { APIError_default as APIError, DataError_default as DataError, Env, FILE_PATH_REGEX_default as FILE_PATH_REGEX, NAMESPACE_EXPORT_REGEX_default as NAMESPACE_EXPORT_REGEX, VERSION_NUMBER_REGEX_default as VERSION_NUMBER_REGEX, VersionNumber_default as VersionNumber, VersionType, addDaysToDate_default as addDaysToDate, appendSemicolon_default as appendSemicolon, camelToKebab_default as camelToKebab, convertFileToBase64_default as convertFileToBase64, createFormData_default as createFormData, createTemplateStringsArray_default as createTemplateStringsArray, deepCopy_default as deepCopy, deepFreeze_default as deepFreeze, determineVersionType_default as determineVersionType, encryptWithKey_default as encryptWithKey, fillArray_default as fillArray, formatDateAndTime_default as formatDateAndTime, getIndividualVersionNumbers_default as getIndividualVersionNumbers, getInterpolations_default as getInterpolations, getPublicAndPrivateKey_default as getPublicAndPrivateKey, getRandomNumber_default as getRandomNumber, getRecordKeys_default as getRecordKeys, httpErrorCodeLookup, incrementVersion_default as incrementVersion, interpolate_default as interpolate, interpolateObjects_default as interpolateObjects, isAnniversary_default as isAnniversary, isLeapYear_default as isLeapYear, isMonthlyMultiple_default as isMonthlyMultiple, isOrdered_default as isOrdered, isSameDate_default as isSameDate, kebabToCamel_default as kebabToCamel, normaliseImportPath, normaliseIndents_default as normaliseIndents, normalizeImportPath_default as normalizeImportPath, normalizeIndents, omitProperties_default as omitProperties, paralleliseArrays_default as paralleliseArrays, parseBoolean_default as parseBoolean, parseEnv_default as parseEnv, parseFilePath_default as parseFilePath, parseFormData_default as parseFormData, parseIntStrict_default as parseIntStrict, parseVersion_default as parseVersion, parseVersionType_default as parseVersionType, parseZodSchema_default as parseZodSchema, parseZodSchemaAsync_default as parseZodSchemaAsync, randomiseArray_default as randomiseArray, range_default as range, removeDuplicates_default as removeDuplicates, removeUndefinedFromObject_default as removeUndefinedFromObject, stringListToArray_default as stringListToArray, stringifyDotenv_default as stringifyDotenv, truncate_default as truncate, wait_default as wait };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "4.10.2",
+  "version": "4.12.0",
   "description": "Helpful utility functions.",
   "repository": {
     "type": "git",
@@ -17,26 +17,25 @@
   ],
   "dependencies": {
     "dotenv": "^17.2.3",
-    "libsodium-wrappers": "^0.8.0",
-    "zod": "^4.3.5"
+    "libsodium-wrappers": "^0.8.2",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@alextheman/eslint-plugin": "^5.4.2",
-    "@types/libsodium-wrappers": "^0.7.14",
-    "@types/node": "^25.0.9",
-    "@typescript-eslint/types": "^8.53.0",
-    "alex-c-line": "^1.20.0",
+    "@alextheman/eslint-plugin": "^5.5.0",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/types": "^8.54.0",
+    "alex-c-line": "^1.21.2",
     "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.2",
-    "globals": "^17.0.0",
+    "globals": "^17.2.0",
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
-    "prettier": "^3.8.0",
-    "tsdown": "^0.19.0",
+    "prettier": "^3.8.1",
+    "tsdown": "^0.20.1",
     "typedoc": "^0.28.16",
     "typescript": "^5.9.3",
-    "vite-tsconfig-paths": "^6.0.4",
-    "vitest": "^4.0.17"
+    "vite-tsconfig-paths": "^6.0.5",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=22.0.0"