@alextheman/utility 5.9.0 → 5.10.0

package/dist/index.cjs

@@ -1570,6 +1570,32 @@ function kebabToCamel(input, options) {
 	return outputString;
 }
 //#endregion
+//#region src/root/functions/stringHelpers/toTitleCase.ts
+/**
+* Converts a string to a human-readable Title Case string.
+*
+* Words are split on spaces, underscores, and hyphens. Every first letter of each word is capitalised except for words specified in `options.preserveWords`.
+*
+* The comparison for preserved words is case-insensitive, but the original casing provided in `preserveWords` is retained in the output.
+*
+* @param input - The string to convert.
+* @param options - Additional options to apply.
+*
+* @returns A new string, converted into Title Case.
+*/
+function toTitleCase(input, options) {
+	const preservedWords = removeDuplicates(options?.preserveWords?.map((word) => {
+		return {
+			normalised: word.toLowerCase(),
+			original: word
+		};
+	}) ?? []);
+	return input.split(/[_\s-]+/).filter(Boolean).map((word) => {
+		for (const preservedWord of preservedWords) if (preservedWord.normalised === word.toLowerCase()) return preservedWord.original;
+		return word[0].toUpperCase() + word.slice(1).toLowerCase();
+	}).join(" ");
+}
+//#endregion
 //#region src/root/functions/stringHelpers/truncate.ts
 /**
 * Truncates a string and appends `...` to the end of it
@@ -1641,6 +1667,7 @@ exports.removeUndefinedFromObject = removeUndefinedFromObject;
 exports.sayHello = sayHello;
 exports.stringListToArray = stringListToArray;
 exports.stringifyDotenv = stringifyDotenv;
+exports.toTitleCase = toTitleCase;
 exports.truncate = truncate;
 exports.wait = wait;
 exports.zodVersionNumber = zodVersionNumber;

package/dist/index.d.cts

@@ -933,6 +933,29 @@ interface KebabToCamelOptions {
  */
 declare function kebabToCamel(input: string, options?: KebabToCamelOptions): string;
 //#endregion
+//#region src/root/functions/stringHelpers/toTitleCase.d.ts
+interface ToTitleCaseOptions {
+  /**
+   * An array of words to keep as is in the title.
+   *
+   * Note that the comparison is case insensitive, and if a match is found it will use the casing as found in the options.
+   */
+  preserveWords?: Array<string>;
+}
+/**
+ * Converts a string to a human-readable Title Case string.
+ *
+ * Words are split on spaces, underscores, and hyphens. Every first letter of each word is capitalised except for words specified in `options.preserveWords`.
+ *
+ * The comparison for preserved words is case-insensitive, but the original casing provided in `preserveWords` is retained in the output.
+ *
+ * @param input - The string to convert.
+ * @param options - Additional options to apply.
+ *
+ * @returns A new string, converted into Title Case.
+ */
+declare function toTitleCase(input: string, options?: ToTitleCaseOptions): string;
+//#endregion
 //#region src/root/functions/stringHelpers/truncate.d.ts
 /**
  * Truncates a string and appends `...` to the end of it
@@ -1124,4 +1147,4 @@ declare const normalizeIndents: typeof normaliseIndents;
  */
 type RecordKey = string | number | symbol;
 //#endregion
-export { APIError, type ArrayElement, type CallReturnType, CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, KebabToCamelOptions, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, type StringListToArrayOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+export { APIError, type ArrayElement, type CallReturnType, CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, KebabToCamelOptions, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, type StringListToArrayOptions, ToTitleCaseOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };

package/dist/index.d.ts

@@ -933,6 +933,29 @@ interface KebabToCamelOptions {
  */
 declare function kebabToCamel(input: string, options?: KebabToCamelOptions): string;
 //#endregion
+//#region src/root/functions/stringHelpers/toTitleCase.d.ts
+interface ToTitleCaseOptions {
+  /**
+   * An array of words to keep as is in the title.
+   *
+   * Note that the comparison is case insensitive, and if a match is found it will use the casing as found in the options.
+   */
+  preserveWords?: Array<string>;
+}
+/**
+ * Converts a string to a human-readable Title Case string.
+ *
+ * Words are split on spaces, underscores, and hyphens. Every first letter of each word is capitalised except for words specified in `options.preserveWords`.
+ *
+ * The comparison for preserved words is case-insensitive, but the original casing provided in `preserveWords` is retained in the output.
+ *
+ * @param input - The string to convert.
+ * @param options - Additional options to apply.
+ *
+ * @returns A new string, converted into Title Case.
+ */
+declare function toTitleCase(input: string, options?: ToTitleCaseOptions): string;
+//#endregion
 //#region src/root/functions/stringHelpers/truncate.d.ts
 /**
  * Truncates a string and appends `...` to the end of it
@@ -1124,4 +1147,4 @@ declare const normalizeIndents: typeof normaliseIndents;
  */
 type RecordKey = string | number | symbol;
 //#endregion
-export { APIError, type ArrayElement, type CallReturnType, CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, KebabToCamelOptions, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, type StringListToArrayOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+export { APIError, type ArrayElement, type CallReturnType, CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, KebabToCamelOptions, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, type StringListToArrayOptions, ToTitleCaseOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };

package/dist/index.js

@@ -1546,6 +1546,32 @@ function kebabToCamel(input, options) {
 	return outputString;
 }
 //#endregion
+//#region src/root/functions/stringHelpers/toTitleCase.ts
+/**
+* Converts a string to a human-readable Title Case string.
+*
+* Words are split on spaces, underscores, and hyphens. Every first letter of each word is capitalised except for words specified in `options.preserveWords`.
+*
+* The comparison for preserved words is case-insensitive, but the original casing provided in `preserveWords` is retained in the output.
+*
+* @param input - The string to convert.
+* @param options - Additional options to apply.
+*
+* @returns A new string, converted into Title Case.
+*/
+function toTitleCase(input, options) {
+	const preservedWords = removeDuplicates(options?.preserveWords?.map((word) => {
+		return {
+			normalised: word.toLowerCase(),
+			original: word
+		};
+	}) ?? []);
+	return input.split(/[_\s-]+/).filter(Boolean).map((word) => {
+		for (const preservedWord of preservedWords) if (preservedWord.normalised === word.toLowerCase()) return preservedWord.original;
+		return word[0].toUpperCase() + word.slice(1).toLowerCase();
+	}).join(" ");
+}
+//#endregion
 //#region src/root/functions/stringHelpers/truncate.ts
 /**
 * Truncates a string and appends `...` to the end of it
@@ -1561,4 +1587,4 @@ function truncate(stringToTruncate, maxLength = 5) {
 	return stringToTruncate.length > maxLength ? `${stringToTruncate.slice(0, maxLength)}...` : stringToTruncate;
 }
 //#endregion
-export { APIError, DataError, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, ONE_DAY_IN_MILLISECONDS, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, truncate, wait, zodVersionNumber };
+export { APIError, DataError, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, ONE_DAY_IN_MILLISECONDS, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "5.9.0",
+  "version": "5.10.0",
   "description": "Helpful utility functions.",
   "repository": {
     "type": "git",
@@ -30,36 +30,37 @@
     "dist"
   ],
   "dependencies": {
-    "dotenv": "^17.3.1",
-    "execa": "^9.6.1",
-    "libsodium-wrappers": "^0.8.2",
-    "zod": "^4.3.6"
+    "dotenv": "17.4.0",
+    "execa": "9.6.1",
+    "libsodium-wrappers": "0.8.2",
+    "zod": "4.3.6"
   },
   "devDependencies": {
-    "@alextheman/eslint-plugin": "^5.10.4",
-    "@types/node": "^25.5.0",
-    "alex-c-line": "^2.4.0",
-    "cross-env": "^10.1.0",
-    "dotenv-cli": "^11.0.0",
-    "eslint": "^10.1.0",
-    "globals": "^17.4.0",
-    "husky": "^9.1.7",
-    "jsdom": "^29.0.1",
-    "prettier": "^3.8.1",
-    "tempy": "^3.2.0",
-    "tsdown": "^0.21.7",
-    "tsx": "^4.21.0",
-    "typedoc": "^0.28.18",
-    "typescript": "^6.0.2",
-    "typescript-eslint": "^8.58.0",
-    "vite-tsconfig-paths": "^6.1.1",
-    "vitest": "^4.1.2"
+    "@alextheman/eslint-plugin": "5.11.0",
+    "@types/node": "25.5.2",
+    "alex-c-line": "2.5.0",
+    "cross-env": "10.1.0",
+    "dotenv-cli": "11.0.0",
+    "eslint": "10.2.0",
+    "globals": "17.4.0",
+    "husky": "9.1.7",
+    "jsdom": "29.0.1",
+    "prettier": "3.8.1",
+    "tempy": "3.2.0",
+    "tsdown": "0.21.7",
+    "tsx": "4.21.0",
+    "typedoc": "0.28.18",
+    "typescript": "6.0.2",
+    "typescript-eslint": "8.58.0",
+    "vite-tsconfig-paths": "6.1.1",
+    "vitest": "4.1.2"
   },
   "engines": {
     "node": ">=22.3.0"
   },
   "scripts": {
     "build": "tsdown",
+    "build-configs": "tsdown --config tsdown.configs.config.ts",
     "create-feature-docs": "typedoc",
     "create-local-package": "pnpm run build && rm -f alextheman-utility-*.tgz && pnpm pack",
     "create-release-note": "bash -c 'git pull origin main && alex-c-line template release-note create $@' --",
@@ -77,7 +78,7 @@
     "lint-prettier-typescript": "prettier --check --parser typescript \"./**/*.ts\"",
     "lint-prettier-yml": "prettier --check \"./**/*.{yml,yaml}\"",
     "lint-tsc": "tsc --noEmit",
-    "pre-commit": "alex-c-line pre-commit",
+    "pre-commit": "pnpm run build-configs && alex-c-line pre-commit",
     "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",