typeshi 1.7.19 → 2.0.1

package/dist/utils/argumentValidation.js

@@ -810,22 +810,3 @@ function getSourceString(fileName, func, funcInfo, startLine, endLine) {
     let funcName = typeof func === 'string' ? func : func.name;
     return `[${fileName}.${funcName}(${(0, typeValidation_1.isNonEmptyString)(funcInfo) ? ` ${funcInfo} ` : ''})${lineNumberText}]`;
 }
-// isEnumArgumentOptions,
-// isEnumObject,
-// isObjectArgumentOptions,
-// const validate = {
-//     stringArgument,
-//     multipleStringArguments,
-//     numericStringArgument,
-//     booleanArgument,
-//     numberArgument,
-//     arrayArgument,
-//     enumArgument,
-//     objectArgument,
-//     functionArgument,
-//     existingPathArgument,
-//     existingDirectoryArgument,
-//     existingFileArgument,
-//     multipleExistingFileArguments
-// }
-// export default validate;

package/dist/utils/io/logging.js

@@ -107,20 +107,20 @@ function autoFormatLogsOnExit(filePaths) {
  * @returns `void`
  */
 function formatDebugLogFile(inputPath, outputPath) {
-    validate.existingPathArgument(`logging.formatDebugLogFile`, { inputPath });
-    // Generate output path if not provided
-    if (!outputPath) {
-        const parsedPath = node_path_1.default.parse(inputPath);
-        outputPath = node_path_1.default.join(parsedPath.dir, `${parsedPath.name}.FORMATTED${parsedPath.ext}`);
-    }
+    const source = getSourceString(__filename, formatAllDebugLogs.name);
     try {
+        validate.existingPathArgument(source, { inputPath });
+        if (!outputPath) { // Generate output path if not provided
+            const parsedPath = node_path_1.default.parse(inputPath);
+            outputPath = node_path_1.default.join(parsedPath.dir, `${parsedPath.name}.FORMATTED${parsedPath.ext}`);
+        }
         const fileContent = fs.readFileSync(inputPath, 'utf-8');
         const formattedContent = formatLogContent(fileContent);
         fs.writeFileSync(outputPath, formattedContent, { encoding: 'utf-8' });
         // mlog.info(`[formatDebugLogFile()] Formatted log file saved to '${outputPath}'`);
     }
     catch (error) {
-        setupLog_1.typeshiLogger.error('[formatDebugLogFile()] Error formatting log file:', error);
+        setupLog_1.typeshiLogger.error(`${source} Error formatting log file:'`, error);
         throw error;
     }
 }
@@ -130,7 +130,7 @@ function formatDebugLogFile(inputPath, outputPath) {
  * @returns `string` - the formatted content
  */
 function formatLogContent(content) {
-    const lines = content.split('\n');
+    const lines = content.split('\n'); //.map(s=>applyStripOptions(s, {char: `"`}));
     const formattedLines = [];
     let currentJsonObject = '';
     let insideJsonObject = false;

package/dist/utils/io/reading.d.ts

@@ -1,4 +1,4 @@
-import { StringCaseOptions, StringPadOptions, StringStripOptions, CleanStringOptions } from "../regex";
+import { DEP_StringCaseOptions, DEP_StringStripOptions, DEP_CleanStringOptions, DEP_StringPadOptions } from "../regex";
 import { DirectoryFileOptions, FileData, FileExtension } from "./types/Io";
 import { DelimiterCharacterEnum } from "./types";
 /** checks if `pathString (value)` points to an existing directory */
@@ -95,7 +95,7 @@ export declare function getCsvRows(arg1: FileData | string): Promise<Record<stri
  * @param valueColumn `string` - the column name whose contents will be used as values in the dictionary.
  * @returns **`dict`** `Record<string, string>`
  */
-export declare function getOneToOneDictionary(arg1: string | Record<string, any>[] | FileData, keyColumn: string, valueColumn: string, keyOptions?: CleanStringOptions, valueOptions?: CleanStringOptions, requireIncludeAllRows?: boolean): Promise<Record<string, string>>;
+export declare function getOneToOneDictionary(arg1: string | Record<string, any>[] | FileData, keyColumn: string, valueColumn: string, keyOptions?: DEP_CleanStringOptions, valueOptions?: DEP_CleanStringOptions, requireIncludeAllRows?: boolean): Promise<Record<string, string>>;
 /**
  * @param arg1 `string | FileData | Record<string, any>[]` - the `filePath` to a CSV file or an array of rows.
  * @param columnName `string` - the column name whose values will be returned.
@@ -159,12 +159,12 @@ export declare function getDirectoryFiles(dir: string, options: DirectoryFileOpt
  * @param dataSource `string | FileData | Record<string, any>[]`
  * @param keyColumn `string`
  * @param valueColumn `string`
- * @param keyOptions {@link CleanStringOptions} `(optional)`
- * @param valueOptions {@link CleanStringOptions}`(optional)`
+ * @param keyOptions {@link DEP_CleanStringOptions} `(optional)`
+ * @param valueOptions {@link DEP_CleanStringOptions}`(optional)`
  * @param sheetName `string`
  * @returns **`dict`** `Promise<Record<string, string[]>>`
  */
-export declare function getOneToManyDictionary(dataSource: string | FileData | Record<string, any>[], keyColumn: string, valueColumn: string, keyOptions?: CleanStringOptions, valueOptions?: CleanStringOptions, sheetName?: string): Promise<Record<string, string[]>>;
+export declare function getOneToManyDictionary(dataSource: string | FileData | Record<string, any>[], keyColumn: string, valueColumn: string, keyOptions?: DEP_CleanStringOptions, valueOptions?: DEP_CleanStringOptions, sheetName?: string): Promise<Record<string, string[]>>;
 /**
  * @deprecated `use `{@link getOneToManyDictionary}
  * @param filePath `string`
@@ -172,19 +172,19 @@ export declare function getOneToManyDictionary(dataSource: string | FileData | R
  * @param keyColumn `string`
  * @param valueColumn `string`
  * @param options - {@link ParseOneToManyOptions}
- * = `{ keyStripOptions`?: {@link StringStripOptions}, `valueStripOptions`?: {@link StringStripOptions}, keyCaseOptions`?: {@link StringCaseOptions}, `valueCaseOptions`?: {@link StringCaseOptions}, `keyPadOptions`?: {@link StringPadOptions}, `valuePadOptions`?: {@link StringPadOptions} `}`
- * - {@link StringStripOptions} = `{ char`: `string`, `escape`?: `boolean`, `stripLeftCondition`?: `(s: string, ...args: any[]) => boolean`, `leftArgs`?: `any[]`, `stripRightCondition`?: `(s: string, ...args: any[]) => boolean`, `rightArgs`?: `any[] }`
- * - {@link StringCaseOptions} = `{ toUpper`?: `boolean`, `toLower`?: `boolean`, `toTitle`?: `boolean }`
+ * = `{ keyStripOptions`?: {@link DEP_StringStripOptions}, `valueStripOptions`?: {@link DEP_StringStripOptions}, keyCaseOptions`?: {@link StringCaseOptions}, `valueCaseOptions`?: {@link StringCaseOptions}, `keyPadOptions`?: {@link StringPadOptions}, `valuePadOptions`?: {@link StringPadOptions} `}`
+ * - {@link DEP_StringStripOptions} = `{ char`: `string`, `escape`?: `boolean`, `stripLeftCondition`?: `(s: string, ...args: any[]) => boolean`, `leftArgs`?: `any[]`, `stripRightCondition`?: `(s: string, ...args: any[]) => boolean`, `rightArgs`?: `any[] }`
+ * - {@link DEP_StringCaseOptions} = `{ toUpper`?: `boolean`, `toLower`?: `boolean`, `toTitle`?: `boolean }`
  * - {@link StringPadOptions} = `{ padLength`: `number`, `padChar`?: `string`, `padLeft`?: `boolean`, `padRight`?: `boolean }`
  * @returns **`dict`** `Record<string, Array<string>>` — key-value pairs where key is from `keyColumn` and value is an array of values from `valueColumn`
  */
 export declare function parseExcelForOneToMany(filePath: string, sheetName: string, keyColumn: string, valueColumn: string, options?: {
-    keyStripOptions?: StringStripOptions;
-    valueStripOptions?: StringStripOptions;
-    keyCaseOptions?: StringCaseOptions;
-    valueCaseOptions?: StringCaseOptions;
-    keyPadOptions?: StringPadOptions;
-    valuePadOptions?: StringPadOptions;
+    keyStripOptions?: DEP_StringStripOptions;
+    valueStripOptions?: DEP_StringStripOptions;
+    keyCaseOptions?: DEP_StringCaseOptions;
+    valueCaseOptions?: DEP_StringCaseOptions;
+    keyPadOptions?: DEP_StringPadOptions;
+    valuePadOptions?: DEP_StringPadOptions;
 }): Record<string, Array<string>>;
 /**
  * @deprecated -> use {@link getOneToManyDictionary}
@@ -193,18 +193,18 @@ export declare function parseExcelForOneToMany(filePath: string, sheetName: stri
  * @param valueColumn `string`
  * @param delimiter {@link DelimiterCharacters} | `string`
  * @param options {@link ParseOneToManyOptions}
- * = `{ keyCaseOptions`?: {@link StringCaseOptions}, `valueCaseOptions`?: {@link StringCaseOptions}, `keyPadOptions`?: {@link StringPadOptions}, `valuePadOptions`?: {@link StringPadOptions} `}`
- * - {@link StringCaseOptions} = `{ toUpper`?: `boolean`, `toLower`?: `boolean`, `toTitle`?: `boolean }`
+ * = `{ keyCaseOptions`?: {@link DEP_StringCaseOptions}, `valueCaseOptions`?: {@link DEP_StringCaseOptions}, `keyPadOptions`?: {@link StringPadOptions}, `valuePadOptions`?: {@link StringPadOptions} `}`
+ * - {@link DEP_StringCaseOptions} = `{ toUpper`?: `boolean`, `toLower`?: `boolean`, `toTitle`?: `boolean }`
  * - {@link StringPadOptions} = `{ padLength`: `number`, `padChar`?: `string`, `padLeft`?: `boolean`, `padRight`?: `boolean }`
  * @returns `Record<string, Array<string>>` - key-value pairs where key is from `keyColumn` and value is an array of values from `valueColumn`
  */
 export declare function parseCsvForOneToMany(filePath: string, keyColumn: string, valueColumn: string, delimiter?: DelimiterCharacterEnum | string, options?: {
-    keyStripOptions?: StringStripOptions;
-    valueStripOptions?: StringStripOptions;
-    keyCaseOptions?: StringCaseOptions;
-    valueCaseOptions?: StringCaseOptions;
-    keyPadOptions?: StringPadOptions;
-    valuePadOptions?: StringPadOptions;
+    keyStripOptions?: DEP_StringStripOptions;
+    valueStripOptions?: DEP_StringStripOptions;
+    keyCaseOptions?: DEP_StringCaseOptions;
+    valueCaseOptions?: DEP_StringCaseOptions;
+    keyPadOptions?: DEP_StringPadOptions;
+    valuePadOptions?: DEP_StringPadOptions;
 }): Record<string, Array<string>>;
 export interface CsvValidationOptions {
     allowEmptyRows?: boolean;

package/dist/utils/io/reading.js

@@ -446,8 +446,8 @@ async function getOneToOneDictionary(arg1, keyColumn, valueColumn, keyOptions, v
             config_1.typeshiLogger.warn(msg);
             continue;
         }
-        const key = (0, regex_1.clean)(String(row[keyColumn]), keyOptions);
-        const value = (0, regex_1.clean)(String(row[valueColumn]), valueOptions);
+        const key = (0, regex_1.DEP_clean)(String(row[keyColumn]), keyOptions);
+        const value = (0, regex_1.DEP_clean)(String(row[valueColumn]), valueOptions);
         if (!key || !value) {
             let msg = [`${source} Row @ index ${i} missing key or value.`,
                 `  keyColumn: '${keyColumn}' in row ? ${keyColumn in row}`,
@@ -639,8 +639,8 @@ function getDirectoryFiles(dir, arg2, ...targetExtensions) {
  * @param dataSource `string | FileData | Record<string, any>[]`
  * @param keyColumn `string`
  * @param valueColumn `string`
- * @param keyOptions {@link CleanStringOptions} `(optional)`
- * @param valueOptions {@link CleanStringOptions}`(optional)`
+ * @param keyOptions {@link DEP_CleanStringOptions} `(optional)`
+ * @param valueOptions {@link DEP_CleanStringOptions}`(optional)`
  * @param sheetName `string`
  * @returns **`dict`** `Promise<Record<string, string[]>>`
  */
@@ -648,18 +648,18 @@ async function getOneToManyDictionary(dataSource, keyColumn, valueColumn, keyOpt
     const source = (0, logging_1.getSourceString)(__filename, getOneToManyDictionary.name);
     validate.multipleStringArguments(source, { keyColumn, valueColumn });
     if (keyOptions)
-        validate.objectArgument(source, { keyOptions, isCleanStringOptions: regex_1.isCleanStringOptions });
+        validate.objectArgument(source, { keyOptions, DEP_isCleanStringOptions: regex_1.DEP_isCleanStringOptions });
     if (valueOptions)
-        validate.objectArgument(source, { valueOptions, isCleanStringOptions: regex_1.isCleanStringOptions });
+        validate.objectArgument(source, { valueOptions, DEP_isCleanStringOptions: regex_1.DEP_isCleanStringOptions });
     const rows = await handleFileArgument(dataSource, source, [keyColumn, valueColumn], sheetName);
     const dict = {};
     for (let i = 0; i < rows.length; i++) {
         let row = rows[i];
-        let key = (0, regex_1.clean)(row[keyColumn], keyOptions).trim().replace(/\.$/, '');
+        let key = (0, regex_1.DEP_clean)(row[keyColumn], keyOptions).trim().replace(/\.$/, '');
         if (!dict[key]) {
             dict[key] = [];
         }
-        let value = (0, regex_1.clean)(row[valueColumn], valueOptions).trim().replace(/\.$/, '');
+        let value = (0, regex_1.DEP_clean)(row[valueColumn], valueOptions).trim().replace(/\.$/, '');
         if (!dict[key].includes(value)) {
             dict[key].push(value);
         }
@@ -673,9 +673,9 @@ async function getOneToManyDictionary(dataSource, keyColumn, valueColumn, keyOpt
  * @param keyColumn `string`
  * @param valueColumn `string`
  * @param options - {@link ParseOneToManyOptions}
- * = `{ keyStripOptions`?: {@link StringStripOptions}, `valueStripOptions`?: {@link StringStripOptions}, keyCaseOptions`?: {@link StringCaseOptions}, `valueCaseOptions`?: {@link StringCaseOptions}, `keyPadOptions`?: {@link StringPadOptions}, `valuePadOptions`?: {@link StringPadOptions} `}`
- * - {@link StringStripOptions} = `{ char`: `string`, `escape`?: `boolean`, `stripLeftCondition`?: `(s: string, ...args: any[]) => boolean`, `leftArgs`?: `any[]`, `stripRightCondition`?: `(s: string, ...args: any[]) => boolean`, `rightArgs`?: `any[] }`
- * - {@link StringCaseOptions} = `{ toUpper`?: `boolean`, `toLower`?: `boolean`, `toTitle`?: `boolean }`
+ * = `{ keyStripOptions`?: {@link DEP_StringStripOptions}, `valueStripOptions`?: {@link DEP_StringStripOptions}, keyCaseOptions`?: {@link StringCaseOptions}, `valueCaseOptions`?: {@link StringCaseOptions}, `keyPadOptions`?: {@link StringPadOptions}, `valuePadOptions`?: {@link StringPadOptions} `}`
+ * - {@link DEP_StringStripOptions} = `{ char`: `string`, `escape`?: `boolean`, `stripLeftCondition`?: `(s: string, ...args: any[]) => boolean`, `leftArgs`?: `any[]`, `stripRightCondition`?: `(s: string, ...args: any[]) => boolean`, `rightArgs`?: `any[] }`
+ * - {@link DEP_StringCaseOptions} = `{ toUpper`?: `boolean`, `toLower`?: `boolean`, `toTitle`?: `boolean }`
  * - {@link StringPadOptions} = `{ padLength`: `number`, `padChar`?: `string`, `padLeft`?: `boolean`, `padRight`?: `boolean }`
  * @returns **`dict`** `Record<string, Array<string>>` — key-value pairs where key is from `keyColumn` and value is an array of values from `valueColumn`
  */
@@ -689,8 +689,8 @@ function parseExcelForOneToMany(filePath, sheetName, keyColumn, valueColumn, opt
         const jsonData = xlsx_1.default.utils.sheet_to_json(sheet);
         const dict = {};
         jsonData.forEach(row => {
-            let key = (0, regex_1.clean)(String(row[keyColumn]), keyStripOptions, keyCaseOptions, keyPadOptions).trim().replace(/\.$/, '');
-            let val = (0, regex_1.clean)(String(row[valueColumn]), valueStripOptions, valueCaseOptions, valuePadOptions).trim().replace(/\.$/, '');
+            let key = (0, regex_1.DEP_clean)(String(row[keyColumn]), keyStripOptions, keyCaseOptions, keyPadOptions).trim().replace(/\.$/, '');
+            let val = (0, regex_1.DEP_clean)(String(row[valueColumn]), valueStripOptions, valueCaseOptions, valuePadOptions).trim().replace(/\.$/, '');
             if (!dict[key]) {
                 dict[key] = [];
             }
@@ -712,17 +712,17 @@ function parseExcelForOneToMany(filePath, sheetName, keyColumn, valueColumn, opt
  * @param valueColumn `string`
  * @param delimiter {@link DelimiterCharacters} | `string`
  * @param options {@link ParseOneToManyOptions}
- * = `{ keyCaseOptions`?: {@link StringCaseOptions}, `valueCaseOptions`?: {@link StringCaseOptions}, `keyPadOptions`?: {@link StringPadOptions}, `valuePadOptions`?: {@link StringPadOptions} `}`
- * - {@link StringCaseOptions} = `{ toUpper`?: `boolean`, `toLower`?: `boolean`, `toTitle`?: `boolean }`
+ * = `{ keyCaseOptions`?: {@link DEP_StringCaseOptions}, `valueCaseOptions`?: {@link DEP_StringCaseOptions}, `keyPadOptions`?: {@link StringPadOptions}, `valuePadOptions`?: {@link StringPadOptions} `}`
+ * - {@link DEP_StringCaseOptions} = `{ toUpper`?: `boolean`, `toLower`?: `boolean`, `toTitle`?: `boolean }`
  * - {@link StringPadOptions} = `{ padLength`: `number`, `padChar`?: `string`, `padLeft`?: `boolean`, `padRight`?: `boolean }`
  * @returns `Record<string, Array<string>>` - key-value pairs where key is from `keyColumn` and value is an array of values from `valueColumn`
  */
 function parseCsvForOneToMany(filePath, keyColumn, valueColumn, delimiter = types_1.DelimiterCharacterEnum.COMMA, options = {}) {
     filePath = coerceFileExtension(filePath, (delimiter === types_1.DelimiterCharacterEnum.TAB) ? 'tsv' : 'csv');
     const source = `[reading.parseCsvForOneToMany()]`;
-    validate.existingFileArgument(source, ['.tsv', '.csv'], { filePath });
-    validate.multipleStringArguments(source, { keyColumn, valueColumn });
     try {
+        validate.existingFileArgument(source, ['.tsv', '.csv'], { filePath });
+        validate.multipleStringArguments(source, { keyColumn, valueColumn });
         const { keyStripOptions, valueStripOptions, keyCaseOptions, valueCaseOptions, keyPadOptions, valuePadOptions } = options;
         const data = fs_1.default.readFileSync(filePath, 'utf8');
         const lines = data.split('\n');
@@ -736,8 +736,8 @@ function parseCsvForOneToMany(filePath, keyColumn, valueColumn, delimiter = type
         for (let i = 1; i < lines.length; i++) {
             const line = lines[i].split(delimiter).map(col => col.trim());
             if (line.length > 1) {
-                let key = (0, regex_1.clean)(line[keyIndex], keyStripOptions, keyCaseOptions, keyPadOptions);
-                let val = (0, regex_1.clean)(line[valueIndex], valueStripOptions, valueCaseOptions, valuePadOptions);
+                let key = (0, regex_1.DEP_clean)(line[keyIndex], keyStripOptions, keyCaseOptions, keyPadOptions);
+                let val = (0, regex_1.DEP_clean)(line[valueIndex], valueStripOptions, valueCaseOptions, valuePadOptions);
                 if (!dict[key]) {
                     dict[key] = [];
                 }

package/dist/utils/io/types/Io.TypeGuards.js

@@ -71,7 +71,7 @@ function isFileData(value) {
 function isDirectoryFileOptions(value) {
     const candidate = value;
     return ((0, typeValidation_1.isObject)(candidate, false)
-        && typeValidation_1.isOptional.stringArray(candidate.targetExtensions)
+        && typeValidation_1.isOptional.stringArray(candidate.targetExtensions, false)
         && typeValidation_1.isOptional.boolean(candidate.basenameOnly)
         && typeValidation_1.isOptional.boolean(candidate.recursive));
 }

package/dist/utils/io/types/Io.d.ts

@@ -1,7 +1,7 @@
 /**
  * @file src/utils/io/Io.ts
  */
-import { StringCaseOptions, StringPadOptions, StringStripOptions } from "../../regex/index";
+import { DEP_StringCaseOptions, StringPadOptions, DEP_StringStripOptions } from "../../regex/index";
 export type WriteJsonOptions = {
     data: Record<string, any> | string;
     filePath: string;
@@ -26,7 +26,7 @@ export type RowDictionary = {
     [rowIndex: number]: Record<string, any>;
 };
 /**
- * @deprecated use `CleanStringOptions` instead
+ * @deprecated
  * @typedefn **`ParseOneToManyOptions`**
  * @property {StringStripOptions} keyStripOptions - options for stripping characters from the key
  * @property {StringStripOptions} valueStripOptions - options for stripping characters from the value
@@ -35,15 +35,15 @@ export type RowDictionary = {
  * @property {StringPadOptions} keyPadOptions - options for padding values read from the `keyColumn`
  * @property {StringPadOptions} valuePadOptions - options for padding values read from the `valueColumn`
  *
- * - {@link StringStripOptions} = `{ char: string, escape?: boolean, stripLeftCondition?: (s: string, ...args: any[]) => boolean, leftArgs?: any[], stripRightCondition?: (s: string, ...args: any[]) => boolean, rightArgs?: any[] }`
- * - {@link StringCaseOptions}  = `{ toUpper: boolean, toLower: boolean, toTitle: boolean }`
+ * - {@link DEP_StringStripOptions} = `{ char: string, escape?: boolean, stripLeftCondition?: (s: string, ...args: any[]) => boolean, leftArgs?: any[], stripRightCondition?: (s: string, ...args: any[]) => boolean, rightArgs?: any[] }`
+ * - {@link DEP_StringCaseOptions}  = `{ toUpper: boolean, toLower: boolean, toTitle: boolean }`
  * - {@link StringPadOptions} = `{ padLength: number, padChar: string, padLeft: boolean, padRight: boolean }`
  */
 export type ParseOneToManyOptions = {
-    keyStripOptions?: StringStripOptions;
-    valueStripOptions?: StringStripOptions;
-    keyCaseOptions?: StringCaseOptions;
-    valueCaseOptions?: StringCaseOptions;
+    keyStripOptions?: DEP_StringStripOptions;
+    valueStripOptions?: DEP_StringStripOptions;
+    keyCaseOptions?: DEP_StringCaseOptions;
+    valueCaseOptions?: DEP_StringCaseOptions;
     keyPadOptions?: StringPadOptions;
     valuePadOptions?: StringPadOptions;
 };

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

@@ -0,0 +1,79 @@
+/**
+ * @file src/utils/regex/Str.ts
+ */
+import { stringStartsWithAnyOf, stringEndsWithAnyOf, stringContainsAnyOf, equivalentAlphanumericStrings } from "./stringOperations";
+import { applyCaseOptions, applyReplaceParams, clean as cleanString, applyStripOptions, applyPadOptions } from "./cleaning";
+export declare class Str {
+    /**
+     * @param s `string`
+     * @param prefixes `string | string[] | RegExp` possible starting string(s).
+     * @param flags `RegExpFlagsEnum[] (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.
+     */
+    static startsWith: typeof stringStartsWithAnyOf;
+    /**
+     * Checks if a string ends with any of the specified suffixes.
+     * @param s `string`
+     * @param suffixes `string | string[] | RegExp` possible ending strings.
+     * @param flags `RegExpFlagsEnum[] (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.
+     */
+    static endsWith: typeof stringEndsWithAnyOf;
+    /**
+     * @param s `string`
+     * @param substrings `string | string[] | RegExp`
+     * @param flags `RegExpFlagsEnum[] (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.
+     */
+    static contains: typeof stringContainsAnyOf;
+    /**
+     * Ignores case by default:
+     * - 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`.
+     */
+    static equivalentAlphanumeric: typeof equivalentAlphanumericStrings;
+    /**
+     * @param s `string`
+     * @param options {@link StringCleanOptions} `(optional)`
+     * @param options.useDefault `boolean (optional)` `default` = `true`
+     * - `if true` - calls `s.trim()` and replaces `/\s{2,}/g` with single space, `/\.{2,}/g` with single period, and `/,{2,}/g` with single comma
+     * *before* proceeding with remaining operations
+     * @returns **`s`** `string` = the modified string after applying operations specified in `options`
+     */
+    static clean: typeof cleanString;
+    /**
+     * @param s `string`
+     * @param caseOptions {@link StringCaseEnum} = 'upper' | 'lower' | 'title'
+     * @returns **`s`** `string` with case option applied
+     */
+    static toCase: typeof applyCaseOptions;
+    /**
+     * @param s `string`
+     * @param options {@link StringPadOptions}
+     * @param options.side `'left' | 'right' | 'both'`
+     * - `left` -> use `s.padStart()`
+     * - `right` -> use `s.padEnd()`
+     * - `both` -> apply half padding to both sides
+     * @returns **`s`** `string` padded to length = `options.maxLength`
+     */
+    static pad: typeof applyPadOptions;
+    /**
+     * @param s `string`
+     * @param replaceParams `Array<`{@link StringReplaceParams}`>`
+     * @returns **`s`** `string` with replace options applied
+     */
+    static replace: typeof applyReplaceParams;
+    /**
+     * @param s `string`
+     * @param options {@link StringStripOptions} = `{ char?: string, left?: StringStripCondition, right?: StringStripCondition }`
+     * @returns **`s`**
+     */
+    static strip: typeof applyStripOptions;
+}

package/dist/utils/regex/Str.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * @file src/utils/regex/Str.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Str = void 0;
+const stringOperations_1 = require("./stringOperations");
+const cleaning_1 = require("./cleaning");
+class Str {
+}
+exports.Str = Str;
+/**
+ * @param s `string`
+ * @param prefixes `string | string[] | RegExp` possible starting string(s).
+ * @param flags `RegExpFlagsEnum[] (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.
+ */
+Str.startsWith = stringOperations_1.stringStartsWithAnyOf;
+/**
+ * Checks if a string ends with any of the specified suffixes.
+ * @param s `string`
+ * @param suffixes `string | string[] | RegExp` possible ending strings.
+ * @param flags `RegExpFlagsEnum[] (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.
+ */
+Str.endsWith = stringOperations_1.stringEndsWithAnyOf;
+/**
+ * @param s `string`
+ * @param substrings `string | string[] | RegExp`
+ * @param flags `RegExpFlagsEnum[] (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.
+ */
+Str.contains = stringOperations_1.stringContainsAnyOf;
+/**
+ * Ignores case by default:
+ * - 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`.
+ */
+Str.equivalentAlphanumeric = stringOperations_1.equivalentAlphanumericStrings;
+/**
+ * @param s `string`
+ * @param options {@link StringCleanOptions} `(optional)`
+ * @param options.useDefault `boolean (optional)` `default` = `true`
+ * - `if true` - calls `s.trim()` and replaces `/\s{2,}/g` with single space, `/\.{2,}/g` with single period, and `/,{2,}/g` with single comma
+ * *before* proceeding with remaining operations
+ * @returns **`s`** `string` = the modified string after applying operations specified in `options`
+ */
+Str.clean = cleaning_1.clean;
+/**
+ * @param s `string`
+ * @param caseOptions {@link StringCaseEnum} = 'upper' | 'lower' | 'title'
+ * @returns **`s`** `string` with case option applied
+ */
+Str.toCase = cleaning_1.applyCaseOptions;
+/**
+ * @param s `string`
+ * @param options {@link StringPadOptions}
+ * @param options.side `'left' | 'right' | 'both'`
+ * - `left` -> use `s.padStart()`
+ * - `right` -> use `s.padEnd()`
+ * - `both` -> apply half padding to both sides
+ * @returns **`s`** `string` padded to length = `options.maxLength`
+ */
+Str.pad = cleaning_1.applyPadOptions;
+/**
+ * @param s `string`
+ * @param replaceParams `Array<`{@link StringReplaceParams}`>`
+ * @returns **`s`** `string` with replace options applied
+ */
+Str.replace = cleaning_1.applyReplaceParams;
+/**
+ * @param s `string`
+ * @param options {@link StringStripOptions} = `{ char?: string, left?: StringStripCondition, right?: StringStripCondition }`
+ * @returns **`s`**
+ */
+Str.strip = cleaning_1.applyStripOptions;

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

@@ -1,48 +1,43 @@
-import { CleanStringOptions, StringCaseOptions, StringPadOptions, StringReplaceOptions, StringStripOptions } from "./";
-export declare function clean(s: string, options?: CleanStringOptions): string;
+import { DEP_CleanStringOptions, DEP_StringCaseOptions, DEP_StringPadOptions, StringCaseEnum, StringPadOptions, StringReplaceOptions, DEP_StringStripOptions, StringCleanOptions, StringReplaceParams, StringStripOptions } from "./types";
 /**
- * @description
- * - converts to string and trims, then:
- * - applies options in this order: `StringReplaceOptions`, `StringStripOptions`, `StringCaseOptions`, `StringPadOptions`
- * - Removes leading+trailing spaces, extra spaces, commas, and dots from a string (e.g. `'..'` becomes `'.'`)
- * - optionally applies 4 option params with: {@link string.replace}, {@link applyStripOptions}, {@link applyCaseOptions}, and {@link applyPadOptions}.
- * @param s `string` to clean
- * @param stripOptions {@link StringStripOptions}
- * - `optional` strip options to apply to the string
- * - = `{ char: string, escape?: boolean, stripLeftCondition?: (s: string, ...args: any[]) => boolean, leftArgs?: any[], stripRightCondition?: (s: string, ...args: any[]) => boolean, rightArgs?: any[] }`
- * @param caseOptions {@link StringCaseOptions}
- * - `optional` case options to apply to the string
- * - = `{ toUpper: boolean, toLower: boolean, toTitle: boolean }`
- * @param padOptions {@link StringPadOptions}
- * - `optional` padding options to apply to the string
- * - = `{ padLength: number, padChar: string, padLeft: boolean, padRight: boolean }`
- * @param replaceOptions {@link StringReplaceOptions}
- * - `optional` replace options to apply to the string
- * - = `Array<`{@link StringReplaceParams}`>` = `{ searchValue: string | RegExp, replaceValue: string }[]`
- * @returns **`s`** `string`
+ * @param s `string`
+ * @param options {@link StringCleanOptions} `(optional)`
+ * @param options.useDefault `boolean (optional)` `default` = `true`
+ * - `if true` - calls `s.trim()` and replaces `/\s{2,}/g` with single space, `/\.{2,}/g` with single period, and `/,{2,}/g` with single comma
+ * *before* proceeding with remaining operations
+ * @returns **`s`** `string` = the modified string after applying operations specified in `options`
  */
-export declare function clean(s: string, stripOptions?: StringStripOptions, caseOptions?: StringCaseOptions, padOptions?: StringPadOptions, replaceOptions?: StringReplaceOptions): string;
+export declare function clean(s: string, options?: StringCleanOptions): string;
 /**
- * @param s `string` - the string to convert to title case
- * @returns **`s`** `string` - the string in title case
- * (i.e. first letter of each word, determined by the `\b` boundary metacharacter, is capitalized)
+ * @param s `string`
+ * @param options {@link StringStripOptions} = `{ char?: string, left?: StringStripCondition, right?: StringStripCondition }`
+ * @returns **`s`**
  */
-export declare function toTitleCase(s: string): string;
+export declare function applyStripOptions(s: string, options: StringStripOptions): string;
 /**
  * @param s `string`
- * @param replaceOptions `Array<`{@link StringReplaceParams}`>`
+ * @param replaceParams `Array<`{@link StringReplaceParams}`>`
  * @returns **`s`** `string` with replace options applied
  */
-export declare function applyReplaceOptions(s: string, replaceOptions: StringReplaceOptions): string;
+export declare function applyReplaceParams(s: string, replaceParams: StringReplaceParams[]): string;
 /**
- * @param s `string` - the string to handle case options for
- * @param caseOptions — {@link StringCaseOptions} - `optional` case options to apply to the string
- * = `{ toUpper: boolean, toLower: boolean, toTitle: boolean }`
- * - applies the first case option that is `true` and ignores the rest
- * @returns **`s`** - the string with case options applied
+ * @param s `string`
+ * @param options {@link StringPadOptions}
+ * @param options.side `'left' | 'right' | 'both'`
+ * - `left` -> use `s.padStart()`
+ * - `right` -> use `s.padEnd()`
+ * - `both` -> apply half padding to both sides
+ * @returns **`s`** `string` padded to length = `options.maxLength`
+ */
+export declare function applyPadOptions(s: string, options: StringPadOptions): string;
+/**
+ * @param s `string`
+ * @param caseOptions {@link StringCaseEnum} = `'upper' | 'lower' | 'title'`
+ * @returns **`s`** `string` with case option applied
  */
-export declare function applyCaseOptions(s: string, caseOptions?: StringCaseOptions): string;
+export declare function applyCaseOptions(s: string, caseOptions: StringCaseEnum): string;
 /**
+ * @deprecated
  * @param s `string` - the string to handle padding options for
  * @param padOptions — {@link StringPadOptions} - `optional` padding options to apply to the string
  * = `{ padLength: number, padChar: string, padLeft: boolean, padRight: boolean }`
@@ -50,10 +45,10 @@ export declare function applyCaseOptions(s: string, caseOptions?: StringCaseOpti
  * @returns **`s`** - the string with padding options applied
  * @note `if` `s.length >= padLength`, no padding is applied
  */
-export declare function applyPadOptions(s: string, padOptions?: StringPadOptions): string;
+export declare function DEP_applyPadOptions(s: string, padOptions?: DEP_StringPadOptions): string;
 /**
  * @param s `string`
- * @param stripOptions — {@link StringStripOptions}
+ * @param stripOptions — {@link DEP_StringStripOptions}
  * = `{ char: string, escape?: boolean, stripLeftCondition?: (s: string, ...args: any[]) => boolean, leftArgs?: any[], stripRightCondition?: (s: string, ...args: any[]) => boolean, rightArgs?: any[] }`
  * - if `stripLeftCondition(s, leftArgs)` is `true` or `stripLeftCondition` is `undefined` (i.e. no conditions need to be met to strip left):
  * - - then the left side of the `s` is stripped of `char`
@@ -62,4 +57,42 @@ export declare function applyPadOptions(s: string, padOptions?: StringPadOptions
  * @param stripOptions.escape escape special regex characters in `char` with `char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')`
  * @returns `string` - the string with leading and trailing characters removed
  */
-export declare function applyStripOptions(s: string, stripOptions: StringStripOptions): string;
+export declare function DEP_applyStripOptions(s: string, stripOptions: DEP_StringStripOptions): string;
+/**
+ * @param s `string` - the string to convert to title case
+ * @returns **`s`** `string` - the string in title case
+ * (i.e. first letter of each word, determined by the `\b` boundary metacharacter, is capitalized)
+ */
+export declare function toTitleCase(s: string): string;
+/**
+ * @deprecated use {@link applyCaseOptions} with {@link StringCaseEnum} instead
+ * @param s `string` - the string to handle case options for
+ * @param caseOptions — {@link DEP_StringCaseOptions} - `optional` case options to apply to the string
+ * = `{ toUpper: boolean, toLower: boolean, toTitle: boolean }`
+ * - applies the first case option that is `true` and ignores the rest
+ * @returns **`s`** - the string with case options applied
+ */
+export declare function DEP_applyCaseOptions(s: string, caseOptions?: DEP_StringCaseOptions): string;
+export declare function DEP_clean(s: string, options?: DEP_CleanStringOptions): string;
+/**
+ * @description
+ * - converts to string and trims, then:
+ * - applies options in this order: `StringReplaceOptions`, `StringStripOptions`, `StringCaseOptions`, `StringPadOptions`
+ * - Removes leading+trailing spaces, extra spaces, commas, and dots from a string (e.g. `'..'` becomes `'.'`)
+ * - optionally applies 4 option params with: {@link string.replace}, {@link DEP_applyStripOptions}, {@link DEP_applyCaseOptions}, and {@link DEP_applyPadOptions}.
+ * @param s `string` to clean
+ * @param stripOptions {@link DEP_StringStripOptions}
+ * - `optional` strip options to apply to the string
+ * - = `{ char: string, escape?: boolean, stripLeftCondition?: (s: string, ...args: any[]) => boolean, leftArgs?: any[], stripRightCondition?: (s: string, ...args: any[]) => boolean, rightArgs?: any[] }`
+ * @param caseOptions {@link DEP_StringCaseOptions}
+ * - `optional` case options to apply to the string
+ * - = `{ toUpper: boolean, toLower: boolean, toTitle: boolean }`
+ * @param padOptions {@link StringPadOptions}
+ * - `optional` padding options to apply to the string
+ * - = `{ padLength: number, padChar: string, padLeft: boolean, padRight: boolean }`
+ * @param replaceOptions {@link StringReplaceOptions}
+ * - `optional` replace options to apply to the string
+ * - = `Array<`{@link StringReplaceParams}`>` = `{ searchValue: string | RegExp, replaceValue: string }[]`
+ * @returns **`s`** `string`
+ */
+export declare function DEP_clean(s: string, stripOptions?: DEP_StringStripOptions, caseOptions?: DEP_StringCaseOptions, padOptions?: DEP_StringPadOptions, replaceOptions?: StringReplaceOptions): string;