typeshi 1.7.18 → 2.0.0

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,5 +1,5 @@
-import { StringCaseOptions, StringPadOptions, StringStripOptions, CleanStringOptions } from "../regex";
-import { FileData, FileExtension } from "./types/Io";
+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 */
 export declare function isDirectory(value: any): value is string;
@@ -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.
@@ -124,8 +124,8 @@ export declare function handleFileArgument(arg1: string | FileData | Record<stri
  * - `if true`,  returned array elements are of form: `path.basename(file)`
  * - `if false`, returned array elements are of form: `path.join(dir, file)`
  * @param targetExtensions `string[] (optional)` - array of file extensions to filter files by.
- * - `If` not provided, all files in the directory will be returned.
- * - `If` provided, only files with extensions matching the array will be returned.
+ * - `if undefined`, all files in the directory will be returned.
+ * - `if defined`, only files with extensions matching the array will be returned.
  * @returns **`targetFiles`** `string[]` array of file paths
  */
 export declare function getDirectoryFiles(dir: string, basenameOnly: boolean, ...targetExtensions: string[]): string[];
@@ -133,21 +133,38 @@ export declare function getDirectoryFiles(dir: string, basenameOnly: boolean, ..
  * `sync`
  * @param dir `string` path to target directory
  * @param targetExtensions `string[] (optional)` - array of file extensions to filter files by.
- * - `If` not provided, all files in the directory will be returned.
- * - `If` provided, only files with extensions matching the array will be returned.
+ * - `if undefined`, all files in the directory will be returned.
+ * - `if defined`, only files with extensions matching the array will be returned.
  * @returns **`targetFiles`** `string[]` array of `full` file paths
  */
 export declare function getDirectoryFiles(dir: string, ...targetExtensions: string[]): string[];
+/**
+ * `sync`
+ * @param dir `string` path to target directory
+ * @param options {@link DirectoryFileOptions}
+ * = `{ basenameOnly?: boolean, recursive?: boolean, targetExtensions?: string[] }`
+ * @param options.basenameOnly `boolean (optional)` `default` = `false`
+ * - `if true`,  returned array elements are of form: `path.basename(file)`
+ * - `if false`, returned array elements are of form: `path.join(dir, file)`
+ * @param options.recursive `boolean (optional)` `default` = `false`
+ * - `true` - get files from `dir` and all of its subdirectories
+ * - `false` - only get files from `dir` (i.e. direct descendants of `dir`)
+ * @param options.targetExtensions `string[] (optional)` - array of file extensions to filter files by.
+ * - `if undefined`, all files in the directory will be returned.
+ * - `if defined`, only files with extensions matching the array will be returned.
+ * @returns **`targetFiles`** `string[]` array of file paths
+ */
+export declare function getDirectoryFiles(dir: string, options: DirectoryFileOptions): string[];
 /**
  * @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`
@@ -155,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}
@@ -176,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}`,
@@ -573,23 +573,29 @@ async function handleFileArgument(arg1, invocationSource, requiredHeaders = [],
 /**
  * `sync`
  * @param dir `string` path to target directory
- * @param arg2 `boolean (optional)` `default` = `false`
+ * @param arg2 `boolean (optional)` (`basenameOnly`) `default` = `false`
  * - `if true`,  returned array elements are of form: `path.basename(file)`
  * - `if false`, returned array elements are of form: `path.join(dir, file)`
  * @param targetExtensions `string[] (optional)` - array of file extensions to filter files by.
- * - `If` not provided, all files in the directory will be returned.
- * - `If` provided, only files with extensions matching the array will be returned.
+ * - `if undefined`, all files in the directory will be returned.
+ * - `if defined` provided, only files with extensions matching the array will be returned.
  * @returns **`targetFiles`** `string[]` array of file paths
  */
 function getDirectoryFiles(dir, arg2, ...targetExtensions) {
     const source = (0, logging_1.getSourceString)(__filename, getDirectoryFiles.name);
     let basenameOnly = false;
+    let recursive = false;
     if ((0, typeValidation_1.isBoolean)(arg2)) {
         basenameOnly = arg2;
     }
     else if ((0, typeValidation_1.isNonEmptyString)(arg2)) {
         targetExtensions = [arg2, ...targetExtensions];
     }
+    else if ((0, types_1.isDirectoryFileOptions)(arg2)) {
+        basenameOnly = arg2.basenameOnly ?? basenameOnly;
+        targetExtensions = arg2.targetExtensions ?? [];
+        recursive = arg2.recursive ?? false;
+    }
     const targetFiles = [];
     try {
         validate.existingDirectoryArgument(source, { dir });
@@ -601,11 +607,23 @@ function getDirectoryFiles(dir, arg2, ...targetExtensions) {
                 targetExtensions[i] = `.${ext}`;
             }
         }
-        targetFiles.push(...fs_1.default.readdirSync(dir)
+        const dirContent = fs_1.default.readdirSync(dir);
+        targetFiles.push(...dirContent
             .filter(f => (0, typeValidation_1.isNonEmptyArray)(targetExtensions)
             ? (0, regex_1.stringEndsWithAnyOf)(f, targetExtensions, regex_1.RegExpFlagsEnum.IGNORE_CASE)
             : fs_1.default.statSync(node_path_1.default.join(dir, f)).isFile() // get all files in dir, regardless of extension
         ).map(f => basenameOnly ? f : node_path_1.default.join(dir, f)));
+        if (recursive) {
+            const childDirs = dirContent
+                .filter(c => isDirectory(node_path_1.default.join(dir, c)))
+                .map(c => node_path_1.default.join(dir, c));
+            for (let childDir of childDirs) {
+                targetFiles.push(...getDirectoryFiles(childDir, {
+                    basenameOnly, recursive, targetExtensions
+                }));
+            }
+        }
+        return targetFiles;
     }
     catch (error) {
         config_1.typeshiLogger.error([`${source} Error retrieving directory files, returning empty array`,
@@ -616,14 +634,13 @@ function getDirectoryFiles(dir, arg2, ...targetExtensions) {
         ].join(config_1.INDENT_LOG_LINE));
         return [];
     }
-    return targetFiles;
 }
 /**
  * @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[]>>`
  */
@@ -631,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);
         }
@@ -656,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`
  */
@@ -672,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] = [];
             }
@@ -695,8 +712,8 @@ 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`
  */
@@ -719,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.d.ts

@@ -1,7 +1,7 @@
 /**
  * @file src/utils/io/types/typeGuards.ts
  */
-import { FileData, NodeLeaves, NodeStructure, RowDictionary, RowSourceMetaData, WriteJsonOptions } from "..";
+import { FileData, NodeLeaves, NodeStructure, DirectoryFileOptions, RowDictionary, RowSourceMetaData, WriteJsonOptions } from ".";
 /**
  * @param value `any`
  * @returns **`isRowSourceMetaData`** `boolean`
@@ -29,3 +29,4 @@ export declare function isWriteJsonOptions(value: any): value is WriteJsonOption
  * - **`false`** `otherwise`.
  */
 export declare function isFileData(value: any): value is FileData;
+export declare function isDirectoryFileOptions(value: unknown): value is DirectoryFileOptions;

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

@@ -9,6 +9,7 @@ exports.isNodeStructure = isNodeStructure;
 exports.isNodeLeaves = isNodeLeaves;
 exports.isWriteJsonOptions = isWriteJsonOptions;
 exports.isFileData = isFileData;
+exports.isDirectoryFileOptions = isDirectoryFileOptions;
 const typeValidation_1 = require("../../typeValidation");
 /**
  * @param value `any`
@@ -36,26 +37,21 @@ function isRowDictionary(value) {
             && typeof value[key] === 'object' && !Array.isArray(value[key])));
 }
 function isNodeStructure(value) {
-    return (value && typeof value === 'object'
-        && !Array.isArray(value)
-        && Object.keys(value).length > 0
-        && Object.entries(value).every(([key, value]) => typeof key === 'string'
-            && (isNodeStructure(value) || isNodeLeaves(value))));
+    const candidate = value;
+    return ((0, typeValidation_1.isObject)(candidate)
+        && Object.entries(candidate).every(([k, v]) => (0, typeValidation_1.isNonEmptyString)(k) && (isNodeLeaves(v) || isNodeStructure(v))));
 }
 function isNodeLeaves(value) {
     return ((Array.isArray(value) && value.every(v => typeof v === 'number'))
         || isRowDictionary(value));
 }
 function isWriteJsonOptions(value) {
-    return (value && typeof value === 'object'
-        && !Array.isArray(value)
-        && value.data !== undefined
-        && (typeof value.data === 'object' || typeof value.data === 'string')
-        && (0, typeValidation_1.isNonEmptyString)(value.filePath)
-        && (value.indent === undefined
-            || (typeof value.indent === 'number' && value.indent >= 0))
-        && (value.enableOverwrite === undefined
-            || typeof value.enableOverwrite === 'boolean'));
+    const candidate = value;
+    return ((0, typeValidation_1.isObject)(candidate)
+        && (typeof candidate.data === 'string' || (0, typeValidation_1.isObject)(candidate.data))
+        && (0, typeValidation_1.isNonEmptyString)(candidate.filePath)
+        && typeValidation_1.isUndefinedOr.positiveInteger(candidate.indent)
+        && typeValidation_1.isUndefinedOr.boolean(candidate.enableOverwrite));
 }
 /**
  * @consideration `FILE_NAME_WITH_EXTENSION_PATTERN = /^[^/\\:*?"<>|]+(\.[^/\\:*?"<>|]+)$/`
@@ -67,9 +63,15 @@ function isWriteJsonOptions(value) {
  * - **`false`** `otherwise`.
  */
 function isFileData(value) {
-    return (value && typeof value === 'object'
-        && (0, typeValidation_1.hasKeys)(value, ['fileName', 'fileContent'])
-        && (0, typeValidation_1.isNonEmptyString)(value.fileName)
-        // && fileNamePattern.test(value.fileName)
-        && (0, typeValidation_1.isNonEmptyString)(value.fileContent));
+    const candidate = value;
+    return ((0, typeValidation_1.isObject)(candidate)
+        && (0, typeValidation_1.isNonEmptyString)(candidate.fileName)
+        && (0, typeValidation_1.isNonEmptyString)(candidate.fileContent));
+}
+function isDirectoryFileOptions(value) {
+    const candidate = value;
+    return ((0, typeValidation_1.isObject)(candidate, false)
+        && typeValidation_1.isOptional.stringArray(candidate.targetExtensions)
+        && 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;
 };
@@ -51,3 +51,25 @@ export type ParseOneToManyOptions = {
  * common file extensions handled as input/output
  */
 export type FileExtension = '.csv' | '.tsv' | '.txt' | '.json' | '.xlsx' | '.xls' | '.xml' | '.yaml' | '.yml';
+/**
+ * @interface **`DirectoryFileOptions`** `getDirectoryFiles(parentDir: string, options: DirectoryFileOptions)`
+ */
+export interface DirectoryFileOptions {
+    /**
+     * - `true` - returned array elements are of form: `path.basename(file)`
+     * - `false` - returned array elements are of form: `path.join(dir, file)` (i.e. complete file paths)
+     * */
+    basenameOnly?: boolean;
+    /**
+     * `default` = `false`
+     * - `true` - get files in the `parentDir` and all of its subdirectories
+     * - `false` - only get files in the `parentDir`
+     * */
+    recursive?: boolean;
+    /**
+     * `(optional)` - array of file extensions to filter files by.
+     * - `If` not provided, all files in the directory will be returned.
+     * - `If` provided, only files with extensions matching those in the array will be returned.
+     * */
+    targetExtensions?: string[];
+}

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;
+}