typeshi 2.0.1 → 2.1.0

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

@@ -72,7 +72,7 @@ export declare const DEFAULT_TIMEZONE = "America/Los_Angeles";
  * @example "2025-04-16T00:00:00.000Z"
  * @note dateFormat === DateFormatEnum.LOCALE -> use {@link DEFAULT_LOCALE} and {@link DEFAULT_TIMEZONE}
  */
-export declare function getDateFromUnixTimestamp(unixTimestamp: number, dateFormat: DateFormatEnum): string | null;
+export declare function getDateStringFromUnixTimestamp(unixTimestamp: number, dateFormat: DateFormatEnum): string | null;
 /**
  * @param ds1 first date `string` `(required)` - must be in {@link DateFormatEnum.ISO} format or {@link DateFormatEnum.LOCALE} format. @TODO test other formats
  * @param ds2 second date `string` `(optional)` - defaults to current date and time in Pacific Time

package/dist/utils/io/dateTime.js

@@ -4,7 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Milliseconds = exports.DEFAULT_TIMEZONE = exports.DEFAULT_LOCALE = exports.LOCALE_PATTERN = exports.UTC_PATTERN = exports.ISO_PATTERN = exports.TimeUnitEnum = exports.DateFormatEnum = void 0;
-exports.getDateFromUnixTimestamp = getDateFromUnixTimestamp;
+exports.getDateStringFromUnixTimestamp = getDateStringFromUnixTimestamp;
 exports.calculateDifferenceOfDateStrings = calculateDifferenceOfDateStrings;
 exports.getUnixTimestampFromISO = getUnixTimestampFromISO;
 exports.localeStringToDate = localeStringToDate;
@@ -79,7 +79,7 @@ exports.DEFAULT_TIMEZONE = 'America/Los_Angeles';
  * @example "2025-04-16T00:00:00.000Z"
  * @note dateFormat === DateFormatEnum.LOCALE -> use {@link DEFAULT_LOCALE} and {@link DEFAULT_TIMEZONE}
  */
-function getDateFromUnixTimestamp(unixTimestamp, dateFormat) {
+function getDateStringFromUnixTimestamp(unixTimestamp, dateFormat) {
     if (!unixTimestamp) {
         console.error('No unixTimestamp provided');
         return null;

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

@@ -9,6 +9,7 @@ import { ILogObj, ILogObjMeta } from "tslog";
  */
 export declare function getSourceString(fileName: string, func: string | Function, funcInfo?: any, startLine?: number, endLine?: number): string;
 /**
+ * @deprecated
  * Auto-formats debug logs at the end of application execution.
  * Call this function when your main application is finishing.
  * @param filePaths `string[]` - optional, specific file paths to format.
@@ -17,6 +18,7 @@ export declare function getSourceString(fileName: string, func: string | Functio
  */
 export declare function autoFormatLogsOnExit(filePaths?: string[]): void;
 /**
+ * @deprecated
  * Formats a debug log file from JSON format to a more readable text format.
  * Removes the numeric keys and properly handles escape sequences.
  * @param inputPath `string` - path to the input log file (e.g., DEBUG.txt)
@@ -26,6 +28,7 @@ export declare function autoFormatLogsOnExit(filePaths?: string[]): void;
  */
 export declare function formatDebugLogFile(inputPath: string, outputPath?: string): void;
 /**
+ * @deprecated
  * Formats all debug log files in the log directory.
  * Looks for .txt files and creates .FORMATTED.txt versions.
  * @param logDirectory `string` - optional, path to the log directory.
@@ -34,6 +37,7 @@ export declare function formatDebugLogFile(inputPath: string, outputPath?: strin
  */
 export declare function formatAllDebugLogs(logDirectory: string): void;
 /**
+ * @deprecated
  * reduce metadata to two entries, then return stringified `logObj`
  * @param logObj {@link ILogObj}
  * @returns `string`

package/dist/utils/io/logging.js

@@ -71,6 +71,7 @@ function getSourceString(fileName, func, funcInfo, startLine, endLine) {
     return `[${fileName}.${funcName}(${(0, typeValidation_1.isNonEmptyString)(funcInfo) ? ` ${funcInfo} ` : ''})${lineNumberText}]`;
 }
 /**
+ * @deprecated
  * Auto-formats debug logs at the end of application execution.
  * Call this function when your main application is finishing.
  * @param filePaths `string[]` - optional, specific file paths to format.
@@ -99,6 +100,7 @@ function autoFormatLogsOnExit(filePaths) {
     }
 }
 /**
+ * @deprecated
  * Formats a debug log file from JSON format to a more readable text format.
  * Removes the numeric keys and properly handles escape sequences.
  * @param inputPath `string` - path to the input log file (e.g., DEBUG.txt)
@@ -125,6 +127,7 @@ function formatDebugLogFile(inputPath, outputPath) {
     }
 }
 /**
+ * @deprecated
  * Formats the content of a debug log file from JSON objects to readable text.
  * @param content `string` - the raw content of the log file
  * @returns `string` - the formatted content
@@ -179,6 +182,7 @@ function formatLogContent(content) {
     return formattedLines.join('\n');
 }
 /**
+ * @deprecated
  * Formats a single log entry object into readable text.
  * @param logObj `Record<string, any>` - the parsed log object
  * @returns `string` - the formatted log entry
@@ -209,20 +213,7 @@ function formatSingleLogEntry(logObj) {
     return lines.join(''); // lines.join('\n');
 }
 /**
- * Unescapes a string by replacing escape sequences with their actual characters.
- * @param s `string` - the string with escape sequences
- * @returns `string` - the unescaped string
- */
-function unescapeString(s) {
-    return String(s) // coerce passed value to string
-        .replace(/\\n/g, '\n') // Replace \n with actual newlines
-        .replace(/\\t/g, '\t') // Replace \t with actual tabs
-        .replace(/\\r/g, '\r') // Replace \r with carriage returns
-        .replace(/\\"/g, '"') // Replace \" with actual quotes
-        .replace(/\\\\/g, '\\') // Replace \\ with single backslash
-        .replace(/\\'/g, "'"); // Replace \' with actual single quotes
-}
-/**
+ * @deprecated
  * Formats all debug log files in the log directory.
  * Looks for .txt files and creates .FORMATTED.txt versions.
  * @param logDirectory `string` - optional, path to the log directory.
@@ -259,6 +250,7 @@ function formatAllDebugLogs(logDirectory) {
     }
 }
 /**
+ * @deprecated
  * reduce metadata to two entries, then return stringified `logObj`
  * @param logObj {@link ILogObj}
  * @returns `string`
@@ -279,3 +271,17 @@ function formatLogObj(logObj) {
     }
     return JSON.stringify(logObj, null, 4) + "\n";
 }
+/**
+ * Unescapes a string by replacing escape sequences with their actual characters.
+ * @param s `string` - the string with escape sequences
+ * @returns `string` - the unescaped string
+ */
+function unescapeString(s) {
+    return String(s) // coerce passed value to string
+        .replace(/\\n/g, '\n') // Replace \n with actual newlines
+        .replace(/\\t/g, '\t') // Replace \t with actual tabs
+        .replace(/\\r/g, '\r') // Replace \r with carriage returns
+        .replace(/\\"/g, '"') // Replace \" with actual quotes
+        .replace(/\\\\/g, '\\') // Replace \\ with single backslash
+        .replace(/\\'/g, "'"); // Replace \' with actual single quotes
+}

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

@@ -1,4 +1,4 @@
-import { DEP_StringCaseOptions, DEP_StringStripOptions, DEP_CleanStringOptions, DEP_StringPadOptions } from "../regex";
+import { StringCleanOptions } from "../regex";
 import { DirectoryFileOptions, FileData, FileExtension } from "./types/Io";
 import { DelimiterCharacterEnum } from "./types";
 /** checks if `pathString (value)` points to an existing directory */
@@ -47,7 +47,7 @@ export declare function readFileToArraySync(filePath: string, separator?: string
  * @param expectedExtension `string | `{@link FileExtension}
  * @returns **`validatedFilePath`** `string`
  */
-export declare function coerceFileExtension(filePath: string, expectedExtension: string | FileExtension): string;
+export declare function coerceFileExtension(filePath: string, expectedExtension: FileExtension): string;
 /**
  * - {@link getDirectoryFiles}
  * @param arg1 `Array<`{@link FileData}` | string> | 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?: DEP_CleanStringOptions, valueOptions?: DEP_CleanStringOptions, requireIncludeAllRows?: boolean): Promise<Record<string, string>>;
+export declare function getOneToOneDictionary(arg1: string | Record<string, any>[] | FileData, keyColumn: string, valueColumn: string, keyOptions?: StringCleanOptions, valueOptions?: StringCleanOptions, 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,129 +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 DEP_CleanStringOptions} `(optional)`
- * @param valueOptions {@link DEP_CleanStringOptions}`(optional)`
- * @param sheetName `string`
+ * @param keyOptions {@link StringCleanOptions} `(optional)`
+ * @param valueOptions {@link StringCleanOptions} `(optional)`
+ * @param sheetName `string` `(optional)`
  * @returns **`dict`** `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`
- * @param sheetName `string`
- * @param keyColumn `string`
- * @param valueColumn `string`
- * @param options - {@link ParseOneToManyOptions}
- * = `{ 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?: 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}
- * @param filePath `string`
- * @param keyColumn `string`
- * @param valueColumn `string`
- * @param delimiter {@link DelimiterCharacters} | `string`
- * @param options {@link ParseOneToManyOptions}
- * = `{ 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?: 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;
-    allowInconsistentColumns?: boolean;
-    maxRowsToCheck?: number;
-}
-/**
- * @notimplemented
- * @TODO
- * @param arg1
- * @param requiredHeaders
- * @param options
- * @returns
- */
-export declare function isValidCsv(arg1: string | FileData | Record<string, any>[], requiredHeaders?: string[], options?: CsvValidationOptions): Promise<boolean>;
-/**
- * @problem has trouble handling case where column value contains a single double quote;
- * e.g. when it's used as the inches unit after a number
- *
- * `sync`
- * @param filePath `string` - must be a string to an existing file, otherwise return `false`.
- * @param requiredHeaders `string[]` - `optional` array of headers that must be present in the CSV file.
- * - If provided, the function checks if all required headers are present in the CSV header row
- * @param options `object` - optional configuration
- * - `allowEmptyRows`: `boolean` - if true, allows rows with all empty fields (default: true)
- * - `allowInconsistentColumns`: `boolean` - if true, allows rows with different column counts (default: false)
- * - `maxRowsToCheck`: `number` - maximum number of rows to validate (default: all rows)
- * @returns **`isValidCsv`** `boolean`
- * - **`true`** `if` the CSV file at `filePath` is valid (proper structure and formatting),
- * - **`false`** `otherwise`.
- */
-export declare function isValidCsvSync(filePath: string, requiredHeaders?: string[], options?: CsvValidationOptions): boolean;
-/**
- * Analyzes a CSV file and returns detailed validation information
- * @param filePath `string` - path to the CSV file
- * @param options `object` - validation options
- * @returns **`analysis`** `object` - detailed analysis of the CSV file
- */
-export declare function analyzeCsv(filePath: string, options?: {
-    sampleSize?: number;
-    checkEncoding?: boolean;
-    detectDelimiter?: boolean;
-}): {
-    isValid: boolean;
-    issues: string[];
-    warnings: string[];
-    stats: {
-        totalRows: number;
-        headerCount: number;
-        maxRowLength: number;
-        minRowLength: number;
-        emptyRows: number;
-        encoding: string | null;
-        detectedDelimiter: string | null;
-    };
-    headers: string[];
-};
-/**
- * Attempts to repair common CSV formatting issues
- * @param filePath `string` - path to the CSV file to repair
- * @param outputPath `string` - path where the repaired CSV will be saved
- * @param options `object` - repair options
- * @returns **`repairResult`** `object` - result of the repair operation
- */
-export declare function repairCsv(filePath: string, outputPath: string, options?: {
-    fixQuoting?: boolean;
-    removeEmptyRows?: boolean;
-    standardizeLineEndings?: boolean;
-    fillMissingColumns?: boolean;
-    fillValue?: string;
-}): {
-    success: boolean;
-    repairsMade: string[];
-    errors: string[];
-};
-/** paths to folders or files */
-export declare function validatePath(...paths: string[]): Promise<void>;
+export declare function getOneToManyDictionary(dataSource: string | FileData | Record<string, any>[], keyColumn: string, valueColumn: string, keyOptions?: StringCleanOptions, valueOptions?: StringCleanOptions, sheetName?: string): Promise<Record<string, string[]>>;
 /**
  * @param rowSource `string | Record<string, any>[]`
  * @param targetColumn `string`