typeshi 1.0.1

package/dist/utils/regex/misc.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file src/utils/regex/misc.ts
+ */
+/**
+ * `extractFileNameFromPath`
+ * essentially a wrapper for path.basename() for short-hand convenience
+ * @param filePath `string` e.g. pass in the node module variable  `__filename`
+ * @param removeExtension `boolean` `optional, default = true` - flag indicating
+ * whether or not to remove the file extension from the fileName
+ * @returns **`fileName`** `string`
+ */
+export declare function extractFileName(filePath: string, removeExtension?: boolean): string;
+/**
+ * = `= /^[^/\\:*?"<>|]+(\.[^/\\:*?"<>|]+)$/`
+ */
+export declare const FILE_NAME_WITH_EXTENSION_PATTERN: RegExp;
+/**
+ * `re` = `/^\s*(\d{4}-\d{2}-\d{2}|\d{1,2}[\/-]\d{1,2}[\/-]\d{4})\s*$/`
+ * 1. matches `YYYY-MM-DD` (ISO) format.
+ * 2. matches `MM/DD/YYYY` format. assumes `MM/DD/YYYY` format if the first part is less than or equal to 12 I think.
+ */
+export declare const DATE_STRING_PATTERN: RegExp;
+/** e.g. `"Pangyo-ro, Bundag-Gu, Seongnam-si"` */
+export declare const KOREA_ADDRESS_LATIN_TEXT_PATTERN: RegExp;
+/**
+ * @consideration `removeClasses` is unnecessary, can assume true if a value for
+ * classDelimiter is provided -> have to remove default value for classDelimiter
+ * @param value `string` - the string value from which to extract `leaf`
+ * @param removeClasses `boolean` - remove string prefixes from result `leaf`
+ * - `Default` = `true`
+ * - e.g. `'CLASSA:SKU-1'` -> `sku` with classes removed = `'SKU-1'`
+ * @param classDelimiter `string` - the character used to delimit the item's classes
+ * - `Default` = `':'` (colon character)
+ * - e.g. `classDelimiter` of `'CLASSA:SKU-1'` = `':'`
+ * @returns **`leaf`**: `string` - the extracted `leaf` or the original value if no extraction performed
+ */
+export declare function extractLeaf(value: string, removeClasses?: boolean, classDelimiter?: string): string;

package/dist/utils/regex/misc.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * @file src/utils/regex/misc.ts
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KOREA_ADDRESS_LATIN_TEXT_PATTERN = exports.DATE_STRING_PATTERN = exports.FILE_NAME_WITH_EXTENSION_PATTERN = void 0;
+exports.extractFileName = extractFileName;
+exports.extractLeaf = extractLeaf;
+const typeValidation_1 = require("../typeValidation");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * `extractFileNameFromPath`
+ * essentially a wrapper for path.basename() for short-hand convenience
+ * @param filePath `string` e.g. pass in the node module variable  `__filename`
+ * @param removeExtension `boolean` `optional, default = true` - flag indicating
+ * whether or not to remove the file extension from the fileName
+ * @returns **`fileName`** `string`
+ */
+function extractFileName(filePath, removeExtension = true) {
+    if (!(0, typeValidation_1.isNonEmptyString)(filePath)) {
+        return 'undefined';
+    }
+    let fileName = node_path_1.default.basename(filePath);
+    if (removeExtension) {
+        fileName = fileName.replace(/(?<=.+)\.[a-z0-9]{1,}$/i, '');
+    }
+    return fileName;
+}
+/**
+ * = `= /^[^/\\:*?"<>|]+(\.[^/\\:*?"<>|]+)$/`
+ */
+exports.FILE_NAME_WITH_EXTENSION_PATTERN = /^[^/\\:*?"<>|]+(\.[^/\\:*?"<>|]+)$/;
+/**
+ * `re` = `/^\s*(\d{4}-\d{2}-\d{2}|\d{1,2}[\/-]\d{1,2}[\/-]\d{4})\s*$/`
+ * 1. matches `YYYY-MM-DD` (ISO) format.
+ * 2. matches `MM/DD/YYYY` format. assumes `MM/DD/YYYY` format if the first part is less than or equal to 12 I think.
+ */
+exports.DATE_STRING_PATTERN = new RegExp(/^\s*(\d{4}-\d{2}-\d{2}|\d{1,2}[\/-]\d{1,2}[\/-]\d{4})\s*$/);
+/** e.g. `"Pangyo-ro, Bundag-Gu, Seongnam-si"` */
+exports.KOREA_ADDRESS_LATIN_TEXT_PATTERN = new RegExp(/^\s*([a-zA-Z]{2,}-[a-zA-Z]{2,},\s*){1,}[a-zA-Z]{2,}-[a-zA-Z]{2,}\s*$/);
+/**
+ * @consideration `removeClasses` is unnecessary, can assume true if a value for
+ * classDelimiter is provided -> have to remove default value for classDelimiter
+ * @param value `string` - the string value from which to extract `leaf`
+ * @param removeClasses `boolean` - remove string prefixes from result `leaf`
+ * - `Default` = `true`
+ * - e.g. `'CLASSA:SKU-1'` -> `sku` with classes removed = `'SKU-1'`
+ * @param classDelimiter `string` - the character used to delimit the item's classes
+ * - `Default` = `':'` (colon character)
+ * - e.g. `classDelimiter` of `'CLASSA:SKU-1'` = `':'`
+ * @returns **`leaf`**: `string` - the extracted `leaf` or the original value if no extraction performed
+ */
+function extractLeaf(value, removeClasses = true, classDelimiter = ':') {
+    let result = value;
+    if (value.includes(' (')) { // remove description enclosed in parentheses
+        result = value.split(' (')[0];
+        // const match = skuValue.match(skuPattern);
+        // if (isNonEmptyArray(match)) {
+        //     return match[0].trim();
+        // } 
+    }
+    if (removeClasses && result.includes(classDelimiter)) {
+        let classifierSplit = result.split(classDelimiter);
+        result = classifierSplit[classifierSplit.length - 1];
+    }
+    // if (value.includes(':')) {mlog.debug([`[regex.misc.extractLeaf()]`,
+    //     `      initial value: '${value}'`,
+    //     `after removeClasses: '${result}'`,
+    //     ].join(TAB));
+    // STOP_RUNNING(0)}
+    return result || value;
+}

package/dist/utils/regex/phone.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @param phone - `string` - phone number to test
+ * @returns **`phone`** - formatted phone number or empty string if unable to format it
+ * @description test phone on regex in this order:
+ * 1. {@link KOREA_PHONE_REGEX} = `/(?:^|\D)(82)[-).\s]?(\d{1,2})?[-.\s]?(\d{3,4})[-.\s]?(\d{4})(?:\D|$)/`
+ * 2. {@link HONG_KONG_PHONE_REGEX} = `/(?:^|\D)(852)[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * 3. {@link CHINA_PHONE_REGEX} = `/(?:^|\D)(86)[-.\s]?(\d{2,3})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)`
+ * 4. {@link JAPAN_PHONE_REGEX} = `/(?:^|\D)(81)[-.\s]?(\d{1})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * 5. GENERIC_{@link PHONE_REGEX} = `/(?:^|\D)(\d{1,3}[-.\s]?)?\(?(\d{3})\)?[-.\s]?(\d{3})[-.\s]?(\d{4})[-.\s]?(?:ext|x|ex)?(?:[-:.\s]*)?(\d{1,4})?(?:\D|$)/i`
+ * 6. `else` return emtpy string
+ * @note Valid formats for NetSuite Phone Number fields are:
+ * 1. `999-999-9999`
+ * 2. `1-999-999-9999`
+ * 3. `(999) 999-9999`
+ * 4. `1(999) 999-9999`
+ * 5. `999-999-9999 ext 9999`
+ */
+export declare function extractPhone(phone: string, phoneRegexList?: {
+    re: RegExp;
+    groupFormat: string;
+}[]): string[] | RegExpMatchArray | null;
+/**
+ * @param phone `string` - the phone number to format
+ * @param re {@link RegExp} - the regex to use to extract the phone number
+ * @param groupFormat `string` - use to format the phone number
+ * - `optional` - if not provided, the phone number is returned as is
+ * @returns **`phone`** = `string` - the formatted phone number
+ */
+export declare function formatPhone(phone: string, re: RegExp, groupFormat?: string): string;
+/**
+ * @description
+ * `re` = `/(?:^|\D)(\d{1,3}[-.\s]?)?\(?(\d{3})\)?[-.\s]?(\d{3})[-.\s]?(\d{4})[-.\s]?(?:ext|x|ex)?(?:[-:.\s]*)?(\d{1,4})?(?:\D|$)/i`
+ * - There are 5 capturing groups in the regex:
+ * - **`$1`** - Country code (optional) - `(\d{1,3})`
+ * - **`$2`** - Area code - `(\d{3})`
+ * - **`$3`** - First three digits - `(\d{3})`
+ * - **`$4`** - Last four digits - `(\d{4})`
+ * - **`$5`** - Extension (optional) - `( ?ext ?(\d{3,4}))?`
+ * */
+export declare const PHONE_REGEX: RegExp;
+/**
+ * @description
+ * `re` = `/(?:^|\D)(852)[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * - There are 3 capturing groups in the regex:
+ * - **`$1`** - Country code - `(852)`
+ * - **`$2`** - First four digits - `(\d{4})`
+ * - **`$3`** - Last four digits - `(\d{4})`
+ */
+export declare const HONG_KONG_PHONE_REGEX: RegExp;
+/**
+ * @description
+ * `re` = `/(?:^|\D)(86)[-.\s]?(\d{2,3})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * - There are 4 capturing groups in the regex:
+ * - **`$1`** - Country code - `(86)`
+ * - **`$2`** - Area code - `(\d{2,3})`
+ * - **`$3`** - First four digits - `(\d{4})`
+ * - **`$4`** - Last four digits - `(\d{4})`
+ */
+export declare const CHINA_PHONE_REGEX: RegExp;
+/**
+ * @description
+ * `re` = `/(?:^|\D)(81)[-.\s]?(\d{1})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * - There are 4 capturing groups in the regex:
+ * - **`$1`** - Country code - `(81)`
+ * - **`$2`** - Area code - `(\d{1})`
+ * - **`$3`** - First four digits - `(\d{4})`
+ * - **`$4`** - Last four digits - `(\d{4})`
+ */
+export declare const JAPAN_PHONE_REGEX: RegExp;
+/**
+ * @description
+ * `re` = `/(?:^|\D)(82)[-).\s]?(\d{1,2})?[-.\s]?(\d{3,4})[-.\s]?(\d{4})(?:\D|$)/`
+ * - There are 4 capturing groups in the regex:
+ * - **`$1`** - Country code - `(82)`
+ * - **`$2`** - Area code - `(\d{2})`
+ * - **`$3`** - First three digits - `(\d{3})`
+ * - **`$4`** - Last four digits - `(\d{4})`
+ */
+export declare const KOREA_PHONE_REGEX: RegExp;
+export declare const PHONE_REGEX_LIST: {
+    re: RegExp;
+    groupFormat: string;
+}[];

package/dist/utils/regex/phone.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PHONE_REGEX_LIST = exports.KOREA_PHONE_REGEX = exports.JAPAN_PHONE_REGEX = exports.CHINA_PHONE_REGEX = exports.HONG_KONG_PHONE_REGEX = exports.PHONE_REGEX = void 0;
+exports.extractPhone = extractPhone;
+exports.formatPhone = formatPhone;
+const cleaning_1 = require("./cleaning");
+const StringOptions_1 = require("./types/StringOptions");
+/**
+ * @param phone - `string` - phone number to test
+ * @returns **`phone`** - formatted phone number or empty string if unable to format it
+ * @description test phone on regex in this order:
+ * 1. {@link KOREA_PHONE_REGEX} = `/(?:^|\D)(82)[-).\s]?(\d{1,2})?[-.\s]?(\d{3,4})[-.\s]?(\d{4})(?:\D|$)/`
+ * 2. {@link HONG_KONG_PHONE_REGEX} = `/(?:^|\D)(852)[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * 3. {@link CHINA_PHONE_REGEX} = `/(?:^|\D)(86)[-.\s]?(\d{2,3})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)`
+ * 4. {@link JAPAN_PHONE_REGEX} = `/(?:^|\D)(81)[-.\s]?(\d{1})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * 5. GENERIC_{@link PHONE_REGEX} = `/(?:^|\D)(\d{1,3}[-.\s]?)?\(?(\d{3})\)?[-.\s]?(\d{3})[-.\s]?(\d{4})[-.\s]?(?:ext|x|ex)?(?:[-:.\s]*)?(\d{1,4})?(?:\D|$)/i`
+ * 6. `else` return emtpy string
+ * @note Valid formats for NetSuite Phone Number fields are:
+ * 1. `999-999-9999`
+ * 2. `1-999-999-9999`
+ * 3. `(999) 999-9999`
+ * 4. `1(999) 999-9999`
+ * 5. `999-999-9999 ext 9999`
+ */
+function extractPhone(phone, phoneRegexList = exports.PHONE_REGEX_LIST) {
+    if (!phone) {
+        return null;
+    }
+    const originalPhone = String(phone);
+    // remove leading and trailing letters. remove commas, semicolons, colons, and slashes
+    phone = originalPhone.trim().replace(/^\s*[a-zA-Z]*|[a-zA-Z]\s*$|[,;:/]*/g, '');
+    for (let i = 0; i < phoneRegexList.length; i++) {
+        const { re, groupFormat } = phoneRegexList[i];
+        let matches = phone.match(re);
+        if (!matches) {
+            continue;
+        }
+        let formattedPhones = matches.map(p => formatPhone(p, re, groupFormat));
+        // DEBUG.push(
+        //     NL+`extractPhone("${originalPhone}") - "${phone}" matched phoneRegexList[${i}]!`,
+        //     TAB + `        matches: ${JSON.stringify(matches)}`,
+        //     TAB + `formattedPhones: ${JSON.stringify(formattedPhones)}`,
+        // )
+        return formattedPhones;
+    }
+    if (phone) { // phone is non-empty and did not match any regex
+        // DEBUG.push(NL+`extractPhone() - no match found for "${phone}", returning null.`)
+    }
+    ;
+    return null;
+}
+/**
+ * @param phone `string` - the phone number to format
+ * @param re {@link RegExp} - the regex to use to extract the phone number
+ * @param groupFormat `string` - use to format the phone number
+ * - `optional` - if not provided, the phone number is returned as is
+ * @returns **`phone`** = `string` - the formatted phone number
+ */
+function formatPhone(phone, re, groupFormat) {
+    if (!phone)
+        return '';
+    let result = '';
+    const match = phone.match(re);
+    if (!match) {
+        return '';
+    }
+    result = match[0];
+    if (groupFormat) {
+        result = result.replace(re, groupFormat);
+    }
+    return (0, cleaning_1.clean)(result, { char: '-', escape: false })
+        .replace(/([a-zA-Z]+\s*$)/, '').trim();
+}
+// https://en.wikipedia.org/wiki/List_of_telephone_country_codes
+/**
+ * @description
+ * `re` = `/(?:^|\D)(\d{1,3}[-.\s]?)?\(?(\d{3})\)?[-.\s]?(\d{3})[-.\s]?(\d{4})[-.\s]?(?:ext|x|ex)?(?:[-:.\s]*)?(\d{1,4})?(?:\D|$)/i`
+ * - There are 5 capturing groups in the regex:
+ * - **`$1`** - Country code (optional) - `(\d{1,3})`
+ * - **`$2`** - Area code - `(\d{3})`
+ * - **`$3`** - First three digits - `(\d{3})`
+ * - **`$4`** - Last four digits - `(\d{4})`
+ * - **`$5`** - Extension (optional) - `( ?ext ?(\d{3,4}))?`
+ * */
+exports.PHONE_REGEX = new RegExp(/(?:^|\D)(\d{1,3}[-.\s]?)?\(?(\d{3})\)?[-.\s]?(\d{3})[-.\s]?(\d{4})[-.\s]?(?:ext|x|ex)?(?:[-:.\s]*)?(\d{1,4})?(?:\D|$)/, StringOptions_1.RegExpFlagsEnum.IGNORE_CASE + StringOptions_1.RegExpFlagsEnum.GLOBAL);
+// /(?:^\D*(\d{1,3})[-.\s]?)?\(?(\d{3})\)?[-.\s]?(\d{3})[-.\s]?(\d{4})[-.\s]?(?:ext|x|ex)?(?:[-:.\s]*)?(\d{1,4})?(?:\D*$)/i; 
+/**
+ * @description
+ * `re` = `/(?:^|\D)(852)[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * - There are 3 capturing groups in the regex:
+ * - **`$1`** - Country code - `(852)`
+ * - **`$2`** - First four digits - `(\d{4})`
+ * - **`$3`** - Last four digits - `(\d{4})`
+ */
+exports.HONG_KONG_PHONE_REGEX = new RegExp(/(?:^|\D)(852)[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/, StringOptions_1.RegExpFlagsEnum.GLOBAL);
+/**
+ * @description
+ * `re` = `/(?:^|\D)(86)[-.\s]?(\d{2,3})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * - There are 4 capturing groups in the regex:
+ * - **`$1`** - Country code - `(86)`
+ * - **`$2`** - Area code - `(\d{2,3})`
+ * - **`$3`** - First four digits - `(\d{4})`
+ * - **`$4`** - Last four digits - `(\d{4})`
+ */
+exports.CHINA_PHONE_REGEX = new RegExp(/(?:^|\D)(86)[-.\s]?(\d{2,3})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/, StringOptions_1.RegExpFlagsEnum.GLOBAL);
+/**
+ * @description
+ * `re` = `/(?:^|\D)(81)[-.\s]?(\d{1})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/`
+ * - There are 4 capturing groups in the regex:
+ * - **`$1`** - Country code - `(81)`
+ * - **`$2`** - Area code - `(\d{1})`
+ * - **`$3`** - First four digits - `(\d{4})`
+ * - **`$4`** - Last four digits - `(\d{4})`
+ */
+exports.JAPAN_PHONE_REGEX = new RegExp(/(?:^|\D)(81)[-.\s]?(\d{1})[-.\s]?(\d{4})[-.\s]?(\d{4})(?:\D|$)/, StringOptions_1.RegExpFlagsEnum.GLOBAL);
+/**
+ * @description
+ * `re` = `/(?:^|\D)(82)[-).\s]?(\d{1,2})?[-.\s]?(\d{3,4})[-.\s]?(\d{4})(?:\D|$)/`
+ * - There are 4 capturing groups in the regex:
+ * - **`$1`** - Country code - `(82)`
+ * - **`$2`** - Area code - `(\d{2})`
+ * - **`$3`** - First three digits - `(\d{3})`
+ * - **`$4`** - Last four digits - `(\d{4})`
+ */
+exports.KOREA_PHONE_REGEX = new RegExp(/(?:^|\D)(82)[-).\s]?(\d{1,2})?[-.\s]?(\d{3,4})[-.\s]?(\d{4})(?:\D|$)/, StringOptions_1.RegExpFlagsEnum.GLOBAL);
+exports.PHONE_REGEX_LIST = [
+    { re: exports.CHINA_PHONE_REGEX, groupFormat: '$1-$2-$3-$4' },
+    { re: exports.HONG_KONG_PHONE_REGEX, groupFormat: '$1-$2-$3' },
+    { re: exports.KOREA_PHONE_REGEX, groupFormat: '$1-$2-$3-$4' },
+    { re: exports.JAPAN_PHONE_REGEX, groupFormat: '$1-$2-$3-$4' },
+    { re: exports.PHONE_REGEX, groupFormat: '$1-$2-$3-$4 ext $5' },
+];

package/dist/utils/regex/stringOperations.d.ts

@@ -0,0 +1,45 @@
+import { RegExpFlagsEnum } from "./types/StringOptions";
+/**
+ * Checks if a string ends with any of the specified suffixes.
+ * @param s The `string` to check.
+ * @param suffixes An array of possible ending strings.
+ * @param flags `Optional` regex flags to use when creating the {@link RegExp} object. see {@link RegExpFlagsEnum}
+ * @returns **`true`** if the string ends with any of the suffixes, **`false`** otherwise.
+ * @example
+ * const myString = "hello world";
+ * const possibleEndings = ["world", "universe", "planet"];
+ * console.log(endsWithAny(myString, possibleEndings)); // Output: true
+ * const anotherString = "goodbye moon";
+ * console.log(endsWithAny(anotherString, possibleEndings)); // Output: false
+ */
+export declare function stringEndsWithAnyOf(s: string, suffixes: string | string[] | RegExp, ...flags: RegExpFlagsEnum[]): boolean;
+/**
+ * @param str The `string` to check.
+ * @param prefixes possible starting string(s).
+ * @param flags `Optional` regex flags to use when creating the {@link RegExp} object. see {@link RegExpFlagsEnum}
+ * @returns **`true`** if the string starts with any of the prefixes, **`false`** otherwise.
+ */
+export declare function stringStartsWithAnyOf(str: string, prefixes: string | string[] | RegExp, ...flags: RegExpFlagsEnum[]): boolean;
+/**
+ * @param str The `string` to check.
+ * @param substrings possible substring(s).
+ * @param flags `Optional` regex flags to use when creating the {@link RegExp} object. see {@link RegExpFlagsEnum}
+ * @returns **`true`** if the string contains any of the substrings, **`false`** otherwise.
+ */
+export declare function stringContainsAnyOf(str: string, substrings: string | string[] | RegExp, ...flags: RegExpFlagsEnum[]): boolean;
+/**
+ * @consideration add parameter to ignore case. currently:
+ * - converts `s1` & `s2` to lowercase and removes all non-alphanumeric characters from both strings,
+ * - sorts the characters in both strings,
+ * - then compares the two strings for equivalence.
+ * @param s1 `string`
+ * @param s2 `string`
+ * @param tolerance `number` - a number between 0 and 1, default is `0.90`
+ * @returns **`boolean`**
+ * - **`true`** `if` the two alphanumeric strings are equivalent,
+ * - **`false`** `otherwise`.
+ */
+export declare function equivalentAlphanumericStrings(s1: string, s2: string, tolerance?: number): boolean;
+/** for simple regular expressions...
+ * so like not ones that have parentheses, pipes, or curly braced numbers */
+export declare function extractSource(regex: RegExp): string;

package/dist/utils/regex/stringOperations.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringEndsWithAnyOf = stringEndsWithAnyOf;
+exports.stringStartsWithAnyOf = stringStartsWithAnyOf;
+exports.stringContainsAnyOf = stringContainsAnyOf;
+exports.equivalentAlphanumericStrings = equivalentAlphanumericStrings;
+exports.extractSource = extractSource;
+/**
+ * @file src/utils/regex/stringOperations.ts
+ */
+const config_1 = require("../../config");
+const cleaning_1 = require("./cleaning");
+const fastest_levenshtein_1 = require("fastest-levenshtein");
+const typeValidation_1 = require("../typeValidation");
+/**
+ * Checks if a string ends with any of the specified suffixes.
+ * @param s The `string` to check.
+ * @param suffixes An array of possible ending strings.
+ * @param flags `Optional` regex flags to use when creating the {@link RegExp} object. see {@link RegExpFlagsEnum}
+ * @returns **`true`** if the string ends with any of the suffixes, **`false`** otherwise.
+ * @example
+ * const myString = "hello world";
+ * const possibleEndings = ["world", "universe", "planet"];
+ * console.log(endsWithAny(myString, possibleEndings)); // Output: true
+ * const anotherString = "goodbye moon";
+ * console.log(endsWithAny(anotherString, possibleEndings)); // Output: false
+ */
+function stringEndsWithAnyOf(s, suffixes, ...flags) {
+    if (!s || !suffixes) {
+        return false;
+    }
+    let regex = undefined;
+    if (typeof suffixes === 'string') {
+        suffixes = [suffixes];
+    }
+    let flagString = ((0, typeValidation_1.isNonEmptyArray)(flags)
+        ? flags.join('')
+        : suffixes instanceof RegExp && (0, typeValidation_1.isNonEmptyString)(suffixes.flags)
+            ? suffixes.flags
+            : undefined);
+    if ((0, typeValidation_1.isStringArray)(suffixes)) {
+        /** Escape special regex characters in suffixes and join them with '|' (OR) */
+        const escapedSuffixes = suffixes.map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        const pattern = `(${escapedSuffixes.join('|')})\\s*$`;
+        regex = new RegExp(pattern, flagString);
+    }
+    else if (suffixes instanceof RegExp) {
+        regex = (suffixes.source.endsWith('$')
+            ? new RegExp(suffixes, flagString)
+            : new RegExp(suffixes.source + '\\s*$', flagString));
+    }
+    if (!regex) {
+        config_1.typeshiLogger.error('endsWithAnyOf() Invalid suffixes type. returning false.', 'Expected string, array of strings, or RegExp but received:', typeof suffixes, suffixes);
+        return false; // Invalid suffixes type
+    }
+    return regex.test(s);
+}
+/**
+ * @param str The `string` to check.
+ * @param prefixes possible starting string(s).
+ * @param flags `Optional` regex flags to use when creating the {@link RegExp} object. see {@link RegExpFlagsEnum}
+ * @returns **`true`** if the string starts with any of the prefixes, **`false`** otherwise.
+ */
+function stringStartsWithAnyOf(str, prefixes, ...flags) {
+    if (!str || !prefixes) {
+        return false;
+    }
+    let regex = undefined;
+    if (typeof prefixes === 'string') {
+        prefixes = [prefixes];
+    }
+    let flagString = ((0, typeValidation_1.isNonEmptyArray)(flags)
+        ? flags.join('')
+        : prefixes instanceof RegExp && prefixes.flags
+            ? prefixes.flags
+            : undefined);
+    if (Array.isArray(prefixes)) {
+        /** Escape special regex characters in suffixes and join them with '|' (OR) */
+        const escapedPrefixes = prefixes.map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        const pattern = `^\\s*(${escapedPrefixes.join('|')})`;
+        regex = new RegExp(pattern, flagString);
+    }
+    else if (prefixes instanceof RegExp) {
+        regex = (prefixes.source.startsWith('^')
+            ? new RegExp(prefixes, flagString)
+            : new RegExp('^\\s*' + prefixes.source, flagString));
+    }
+    if (!regex) {
+        config_1.typeshiLogger.warn('startsWithAnyOf() Invalid prefixes type. returning false.', config_1.INDENT_LOG_LINE + 'Expected string, array of strings, or RegExp, but received:', typeof prefixes, config_1.INDENT_LOG_LINE + 'prefixes', prefixes);
+        return false; // Invalid prefixes type
+    }
+    return regex.test(str);
+}
+/**
+ * @param str The `string` to check.
+ * @param substrings possible substring(s).
+ * @param flags `Optional` regex flags to use when creating the {@link RegExp} object. see {@link RegExpFlagsEnum}
+ * @returns **`true`** if the string contains any of the substrings, **`false`** otherwise.
+ */
+function stringContainsAnyOf(str, substrings, ...flags) {
+    if (!str || !substrings) {
+        return false;
+    }
+    let regex = undefined;
+    if (typeof substrings === 'string') {
+        substrings = [substrings];
+    }
+    let flagString = ((0, typeValidation_1.isNonEmptyArray)(flags)
+        ? flags.join('')
+        : substrings instanceof RegExp && substrings.flags
+            ? substrings.flags
+            : undefined);
+    if (Array.isArray(substrings)) {
+        /** Escape special regex characters in suffixes and join them with '|' (OR) */
+        const escapedSubstrings = substrings.map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        const pattern = `(${escapedSubstrings.join('|')})`;
+        regex = new RegExp(pattern, flagString);
+    }
+    else if (substrings instanceof RegExp) {
+        regex = new RegExp(substrings, flagString);
+    }
+    if (!regex) {
+        config_1.typeshiLogger.warn('containsAnyOf() Invalid substrings type. returning false.', config_1.INDENT_LOG_LINE + `Expected string, array of strings, or RegExp, but received: ${typeof substrings}, ${substrings}`);
+        return false; // Invalid substrings type
+    }
+    return regex.test(str);
+}
+/**
+ * @consideration add parameter to ignore case. currently:
+ * - converts `s1` & `s2` to lowercase and removes all non-alphanumeric characters from both strings,
+ * - sorts the characters in both strings,
+ * - then compares the two strings for equivalence.
+ * @param s1 `string`
+ * @param s2 `string`
+ * @param tolerance `number` - a number between 0 and 1, default is `0.90`
+ * @returns **`boolean`**
+ * - **`true`** `if` the two alphanumeric strings are equivalent,
+ * - **`false`** `otherwise`.
+ */
+function equivalentAlphanumericStrings(s1, s2, tolerance = 0.90) {
+    if (!s1 || !s2)
+        return false;
+    const cleanOptions = {
+        case: { toLower: true },
+        replace: [
+            { searchValue: /[^A-Za-z0-9]/g, replaceValue: '' }
+        ]
+    };
+    let s1Alphabetical = (0, cleaning_1.clean)(s1, cleanOptions).split('').sort().join('');
+    let s2Alphabetical = (0, cleaning_1.clean)(s2, cleanOptions).split('').sort().join('');
+    if (s1Alphabetical.length === 0 || s2Alphabetical.length === 0) {
+        return false;
+    }
+    if (s1Alphabetical === s2Alphabetical) { // exact match
+        return true;
+    }
+    const maxLevenshteinDistance = Math.max(Math.floor(s1Alphabetical.length * (1 - tolerance)), Math.floor(s2Alphabetical.length * (1 - tolerance)));
+    if ((0, fastest_levenshtein_1.distance)(s1, s2) <= maxLevenshteinDistance
+        || (0, fastest_levenshtein_1.distance)(s1Alphabetical, s2Alphabetical) <= maxLevenshteinDistance) {
+        return true;
+    }
+    const s1IncludesTolerableS2 = (s2.length > 0 && s2Alphabetical.length > 0
+        && s1Alphabetical.length >= s2Alphabetical.length
+        && s2Alphabetical.length / s1Alphabetical.length >= tolerance
+        && s1Alphabetical.includes(s2Alphabetical));
+    const s2IncludesTolerableS1 = (s1.length > 0 && s1Alphabetical.length > 0
+        && s2Alphabetical.length >= s1Alphabetical.length
+        && s1Alphabetical.length / s2Alphabetical.length >= tolerance
+        && s2Alphabetical.includes(s1Alphabetical));
+    if (s1IncludesTolerableS2 || s2IncludesTolerableS1) {
+        return true;
+    }
+    return false;
+}
+/** for simple regular expressions...
+ * so like not ones that have parentheses, pipes, or curly braced numbers */
+function extractSource(regex) {
+    if (!regex)
+        return '';
+    const REMOVE_ENDPOINT_CHARS = {
+        searchValue: /(^(\^|\\b)|(\$|\\b)$)/g, replaceValue: ''
+    };
+    const REPLACE_ESCAPED_DOT = {
+        searchValue: /\\\./g, replaceValue: '.'
+    };
+    const REPLACE_ESCAPED_WHITESPACE = {
+        searchValue: /\\\s(\*|\+)?/g, replaceValue: ' '
+    };
+    const REMOVE_UNESCAPED_QUESTION_MARK = {
+        searchValue: /(?<!\\)\?/g, replaceValue: ''
+    };
+    let source = (0, cleaning_1.clean)(regex.source, {
+        replace: [
+            REMOVE_ENDPOINT_CHARS,
+            REPLACE_ESCAPED_DOT,
+            REPLACE_ESCAPED_WHITESPACE,
+            REMOVE_UNESCAPED_QUESTION_MARK
+        ]
+    });
+    return source.trim();
+}

package/dist/utils/regex/types/StringOptions.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @file src/utils/regex/types/StringOptions.ts
+ */
+/**
+ * @reference {@link https://javascript.info/regexp-introduction}
+ * @enum {string} **`RegExpFlagsEnum`**
+ * @property {string} IGNORE_CASE - `i` - case insensitive "the search is case-insensitive: no difference between `A` and `a`"
+ * @property {string} MULTI_LINE - `m` - multi-line "Multiline mode" see {@link https://javascript.info/regexp-multiline-mode}
+ * @property {string} GLOBAL - `g` - global search "With this flag the search looks for all matches, without it – only the first match is returned."
+ * @property {string} DOT_MATCHES_NEWLINE - `s` - dot matches newline "By default, a dot doesn’t match the newline character `n`."
+ * @property {string} UNICODE - `u` - unicode "Enables full Unicode support. The flag enables correct processing of surrogate pairs." see {@link https://javascript.info/regexp-unicode}
+ * @property {string} STICKY - `y` - sticky search "searching at the exact position in the text." see {@link https://javascript.info/regexp-sticky}
+ */
+export declare enum RegExpFlagsEnum {
+    IGNORE_CASE = "i",
+    MULTI_LINE = "m",
+    GLOBAL = "g",
+    DOT_MATCHES_NEWLINE = "s",
+    UNICODE = "u",
+    STICKY = "y"
+}
+/**
+ * @typedefn **`CleanStringOptions`**
+ */
+export type CleanStringOptions = {
+    strip?: StringStripOptions;
+    case?: StringCaseOptions;
+    pad?: StringPadOptions;
+    replace?: StringReplaceOptions;
+};
+/**
+ * @typedefn **`StringCaseOptions`**
+ * @property {boolean} [toUpper] - `true` if the string should be converted to upper case
+ * @property {boolean} [toLower] - `true` if the string should be converted to lower case
+ * @property {boolean} [toTitle] - `true` if the string should be converted to title case, see {@link toTitleCase}
+ */
+export type StringCaseOptions = {
+    toUpper?: boolean;
+    toLower?: boolean;
+    toTitle?: boolean;
+};
+/**
+ * @typedefn **`StringPadOptions`**
+ * @property {number} padLength - the length of the string after padding
+ * @property {string} [padChar] - the character to use for padding, defaults to ' '
+ * @property {boolean} [padLeft] - `true` if the padding should be added to the left side of the string
+ * @property {boolean} [padRight] - `true` if the padding should be added to the right side of the string
+ */
+export type StringPadOptions = {
+    padLength: number;
+    padChar?: string;
+    padLeft?: boolean;
+    padRight?: boolean;
+};
+/**
+ * @typedefn **`StringStripOptions`**
+ * @property {string} char - the character to strip from the string with {@link applyStripOptions}
+ * @property {boolean} [escape] - `true` if the character should be escaped
+ * @property {function} [stripLeftCondition] - a function that takes a string and returns `true` if the character should be stripped from the left side of the string
+ * @property {any[]} [leftArgs] - arguments to pass to the `stripLeftCondition` function
+ * - if `stripLeftCondition(s, leftArgs)` is `true` or `stripLeftCondition` is `undefined` (i.e. no conditions need to be met to strip left), the left side of `s` is stripped of `char`
+ * @property {function} [stripRightCondition] - a function that takes a string and returns `true` if the character should be stripped from the right side of the string
+ * @property {any[]} [rightArgs] - arguments to pass to the `stripRightCondition` function
+ * - if `stripRightCondition(s, rightArgs)` is `true` or `stripRightCondition` is `undefined` (i.e. no conditions need to be met to strip right), the right side of `s` is stripped of `char`
+ */
+export type StringStripOptions = {
+    char: string;
+    escape?: boolean;
+    stripLeftCondition?: (s: string, ...args: any[]) => boolean;
+    leftArgs?: any[];
+    stripRightCondition?: (s: string, ...args: any[]) => boolean;
+    rightArgs?: any[];
+};
+/**
+ * @typedefn **`StringReplaceOptions`**
+ * @property {StringReplaceParams[]} replacements - an array of objects containing `searchValue` and `replaceValue` properties
+ */
+export type StringReplaceOptions = StringReplaceParams[];
+/**
+ * @typedefn **`StringReplaceParams`**
+ * @property {string | RegExp} searchValue - the string or regular expression to search for in the string
+ * @property {string} replaceValue - the string to replace the `searchValue` with
+ */
+export type StringReplaceParams = {
+    searchValue: string | RegExp;
+    replaceValue: string;
+};