@alextheman/utility 4.10.2 → 4.11.0

package/dist/index.cjs

@@ -1096,6 +1096,28 @@ 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`.
+*
+* @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
 /**
@@ -1549,6 +1571,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;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { DotenvParseOutput } from "dotenv";
 import { ZodError, ZodType, z } from "zod";
+import sodium from "libsodium-wrappers";
 
 //#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
 declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
@@ -341,6 +342,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.
@@ -771,6 +775,44 @@ 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`.
+ *
+ * @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`.
+ *
+ * @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`.
+ *
+ * @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 +1125,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, 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, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, stringListToArray, stringifyDotenv, truncate, wait };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ZodError, ZodType, z as z$1 } from "zod";
+import sodium from "libsodium-wrappers";
 import { DotenvParseOutput } from "dotenv";
 
 //#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
@@ -341,6 +342,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.
@@ -771,6 +775,44 @@ 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`.
+ *
+ * @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`.
+ *
+ * @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`.
+ *
+ * @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 +1125,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, 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, parseFormData, parseIntStrict, parseVersion, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, stringListToArray, stringifyDotenv, truncate, wait };

package/dist/index.js

@@ -1066,6 +1066,28 @@ 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`.
+*
+* @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
 /**
@@ -1498,4 +1520,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, 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, 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.11.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.1",
+    "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",
+    "@alextheman/eslint-plugin": "^5.4.3",
+    "@types/node": "^25.0.10",
+    "@typescript-eslint/types": "^8.53.1",
     "alex-c-line": "^1.20.0",
     "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.2",
-    "globals": "^17.0.0",
+    "globals": "^17.1.0",
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
-    "prettier": "^3.8.0",
+    "prettier": "^3.8.1",
     "tsdown": "^0.19.0",
     "typedoc": "^0.28.16",
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^6.0.4",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=22.0.0"