typeshi 2.0.2 → 2.1.1

package/dist/utils/argumentValidation.d.ts

@@ -152,7 +152,7 @@ export declare function objectArgument(source: string,
 labeledArgs: ObjectArgumentOptions | {
     [label: string]: any | ((value: any) => boolean);
 }, allowEmpty?: boolean): void;
-type EnumObject = Record<string, string> | Record<string, number>;
+type EnumObject = Record<string, string> | Record<string, string | number>;
 /**
  * Object with 2 entries:
  * 1. `valueLabel` mapped to `valueToCheck`

package/dist/utils/argumentValidation.js

@@ -52,6 +52,7 @@ exports.enumArgument = enumArgument;
 exports.existingPathArgument = existingPathArgument;
 /**
  * @file src/utils/argumentValidation.ts
+ * @note these functions can be useful for sanity checks
  * @description moved the content of parameter type checks at the start of
  * functions to here. use these when you want your function to throw a fit when
  * it receives bad input.
@@ -61,8 +62,6 @@ exports.existingPathArgument = existingPathArgument;
  * - maybe add a configurable value that the validation functions should return if the validation test fails
  * - change the validation functions such that they return the validated value, if possible?
  * - or maybe have them return boolean type predicates ?
- * - -> maybe have to make a class
- * - research the thingy where a type is after the function name and before parens
  */
 const typeValidation_1 = require("./typeValidation");
 const setupLog_1 = require("../config/setupLog");
@@ -98,6 +97,9 @@ function stringArgument(source, arg2, value) {
         label = keys[0];
         value = arg2[label];
     }
+    else if ((0, typeValidation_1.isNonEmptyString)(arg2)) {
+        label = arg2;
+    }
     if (!(0, typeValidation_1.isNonEmptyString)(value)) {
         let msg = [`${source} Invalid argument: '${label}'`,
             `Expected '${label}' to be: non-empty string`,
@@ -229,6 +231,9 @@ function numberArgument(source, arg2, arg3, requireInteger = false) {
             requireInteger = arg3;
         }
     }
+    else if ((0, typeValidation_1.isNonEmptyString)(arg2)) {
+        label = arg2;
+    }
     if (typeof value !== 'number' || isNaN(value)) {
         let msg = [`${source} Invalid argument: '${label}'`,
             `Expected '${label}' to be: number`,
@@ -570,12 +575,20 @@ allowEmpty) {
     // reached end -> value is a valid object
     return;
 }
-function isEnumObject(value) {
+// @TODO be more rigorous and make check String(v) mapped to k 
+function isStringEnum(value) {
     return ((0, typeValidation_1.isObject)(value)
-        && Object.keys(value).length > 0
-        && (Object.values(value).every(v => typeof v === 'string')
-            ||
-                Object.values(value).every(v => typeof v === 'number')));
+        && Object.values(value).every(v => typeof v === 'string'));
+}
+// because enums also store String(v) mapped to k
+// @TODO be more rigorous and make check String(v) mapped to k 
+function isNumberEnum(value) {
+    return ((0, typeValidation_1.isObject)(value) && Object.keys(value).every(k => (0, typeValidation_1.isNumeric)(k, true, true)
+        ? (0, typeValidation_1.isNonEmptyString)(value[k])
+        : !Number.isNaN(value[k])));
+}
+function isEnumObject(value) {
+    return isStringEnum(value) || isNumberEnum(value);
 }
 function isEnumArgumentOptions(value) {
     if (!(0, typeValidation_1.isObject)(value)) {
@@ -654,7 +667,7 @@ function enumArgument(source, arg2, value, enumLabel, enumObject) {
         if (!enumLabel) {
             let msg = [`${source} -> ${vSource} Invalid parameter: arg2 as EnumArgumentOptions`,
                 `EnumArgumentOptions does not contain an entry with a value that is an EnumObject or isEnumFunction`,
-                `Expected arg2 to have single entry of format [label: string]: EnumObject | Function`
+                `Expected: arg2 to have single entry of format [label: string]: EnumObject | Function`
             ].join(setupLog_1.INDENT_LOG_LINE);
             setupLog_1.typeshiLogger.error(msg);
             throw new Error(msg);
@@ -663,25 +676,26 @@ function enumArgument(source, arg2, value, enumLabel, enumObject) {
     }
     else {
         let msg = [`${source} -> ${vSource} Invalid parameter 'arg2'`,
-            `Expected 'arg2' to be either label (string) | labeledArgs (EnumArgumentOptions)`,
-            `Received ${typeof arg2} = ${arg2}`
+            `Expected: 'arg2' to be either label (string) | labeledArgs (EnumArgumentOptions)`,
+            `Received: ${typeof arg2} = ${arg2}`
         ].join(setupLog_1.INDENT_LOG_LINE);
         setupLog_1.typeshiLogger.error(msg);
         throw new Error(msg);
     }
     if (!isEnumObject(enumObject)) {
         let msg = [`${source} -> ${vSource}.verbose: Invalid EnumObject for '${enumLabel}'`,
-            `Expected non-empty object Record<string, number> | Record<string, string>`,
+            `Expected: non-empty object Record<string, number> | Record<string, string>`,
+            `Received: ${typeof enumObject} = ${enumObject} = ${JSON.stringify(enumObject)}`
         ].join(setupLog_1.INDENT_LOG_LINE);
         setupLog_1.typeshiLogger.error(msg);
         throw new Error(msg);
     }
     const enumKeys = Object.keys(enumObject);
     const enumValues = Object.values(enumObject);
-    const isStringEnum = enumValues.every(val => typeof val === 'string');
-    const isNumberEnum = enumValues.every(val => typeof val === 'number');
+    const isStringEnumObject = isStringEnum(enumObject);
+    const isNumberEnumObject = isNumberEnum(enumObject);
     let matchedValue;
-    if (isStringEnum) {
+    if (isStringEnumObject) {
         // For string enums, check both keys and values with case-insensitive matching
         if (typeof valueToCheck === 'string') {
             const lowerValueToCheck = valueToCheck.toLowerCase();
@@ -703,7 +717,7 @@ function enumArgument(source, arg2, value, enumLabel, enumObject) {
             }
         }
     }
-    else if (isNumberEnum) {
+    else if (isNumberEnumObject) {
         // For number enums, check if value is a number or string key
         if (typeof valueToCheck === 'number' && enumValues.includes(valueToCheck)) {
             matchedValue = valueToCheck;
@@ -717,9 +731,10 @@ function enumArgument(source, arg2, value, enumLabel, enumObject) {
     }
     if (matchedValue === undefined) {
         let msg = [`${source} Invalid argument: '${valueLabel}'`,
-            `Expected '${valueLabel}' to be: valid ${enumLabel} enum ${isStringEnum
+            `Expected '${valueLabel}' to be: valid ${enumLabel} enum ${isStringEnumObject
                 ? 'key (string) or value (string)' : 'key (string) or value (number)'}`,
-            `Received '${valueLabel}' value: ${valueToCheck} (${typeof valueToCheck})`,
+            `Received '${valueLabel}' (${typeof valueToCheck}) = ${valueToCheck}`,
+            ``
         ].join(setupLog_1.INDENT_LOG_LINE);
         setupLog_1.typeshiLogger.error(msg);
         throw new Error(msg);

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
@@ -107,73 +107,90 @@ export declare function getCurrentPacificTime(): string;
  * @returns {string} The date string in Pacific Time
  */
 export declare function toPacificTime(initialDateString: string): string;
-export declare const Milliseconds: {
-    readonly from: {
+export declare class Milliseconds {
+    static readonly from: {
+        /**
+         * @param n `number`
+         * @param withLeapTime `boolean (optional)` `default = true`
+         * @returns `n * (1000 * 60 * 60 * 24) * (withLeapTime ? 365.25 : 365)`
+         */
+        years: (n: number, withLeapTime?: boolean) => number;
         /**
          * @param n `number`
          * @returns `n * (1000 * 60 * 60 * 24)` number of milliseconds in `n` days
          */
-        readonly days: (n: number) => number;
+        days: (n: number) => number;
         /**
          * @param n `number`
          * @returns `n * (1000 * 60 * 60)` number of milliseconds in `n` hours
          */
-        readonly hours: (n: number) => number;
+        hours: (n: number) => number;
         /**
          * @param n `number`
          * @returns `n * (1000 * 60)` number of milliseconds in `n` minutes
          */
-        readonly minutes: (n: number) => number;
+        minutes: (n: number) => number;
         /**
          * @param n `number`
          * @returns `n * (1000)` number of milliseconds in `n` seconds
          */
-        readonly seconds: (n: number) => number;
+        seconds: (n: number) => number;
         /**
          * @param d `Date` object
          * @returns `number` = `d.getTime()` = milliseconds since epoch
          */
-        readonly date: (d: Date) => number;
+        date: (d: Date) => number;
         /**
          * @param s `string` date string to pass into Date Constructor (e.g. ISO, UTC, Locale, etc.)
          * @returns `number` milliseconds since epoch or `null` if invalid (i.e. Date constructor can't parse it)
          */
-        readonly string: (s: string) => number | null;
+        string: (s: string) => number | null;
     };
-    readonly to: {
+    static readonly to: {
+        /**
+         * @param n `number`
+         * @param withLeapTime `boolean (optional)` `default = true`
+         * @returns `number` years in `n` milliseconds
+         * = `n / (1000 * 60 * 60 * 24 * (withLeapTime ? 365.25 : 365))`
+         */
+        years: (n: number, withLeapTime?: boolean) => number;
         /**
          * @param n `number`
          * @returns `number` days in `n` milliseconds
+         * = `n / (1000 * 60 * 60 * 24)`
          */
-        readonly days: (n: number) => number;
+        days: (n: number) => number;
         /**
          * @param n `number`
          * @returns `number` hours in `n` milliseconds
+         * = `n / (1000 * 60 * 60)`
          */
-        readonly hours: (n: number) => number;
+        hours: (n: number) => number;
         /**
          * @param n `number`
          * @returns `number` minutes in `n` milliseconds
+         * = `n / (1000 * 60)`
          */
-        readonly minutes: (n: number) => number;
+        minutes: (n: number) => number;
         /**
          * @param n `number`
          * @returns `number` seconds in `n` milliseconds
+         * = `n / (1000)`
          */
-        readonly seconds: (n: number) => number;
+        seconds: (n: number) => number;
         /**
          * interprets `n` as milliseconds since epoch
          * @param n `number` milliseconds
          * @returns `Date` object
          */
-        readonly date: (n: number) => Date;
+        date: (n: number) => Date;
         /**
          * @param n `number`
-         * @param format {@link DateFormatEnum} default = {@link DateFormatEnum.ISO}
-         * @param locale `string` default = `'en-US'` (only used if format = {@link DateFormatEnum.LOCALE})
-         * @param timeZone `string` default = `'America/Los_Angeles'` (only used if format = {@link DateFormatEnum.LOCALE})
+         * @param format {@link DateFormatEnum} `default` = {@link DateFormatEnum.ISO}
+         * @param locale `string` `default` = `'en-US'` (only used if `format` = `DateFormatEnum.LOCALE`)
+         * @param timeZone `string` `default` = `'America/Los_Angeles'` (only used if `format` = `DateFormatEnum.LOCALE`)
          * @returns `string` formatted date string or empty string if error
          */
-        readonly string: (n: number, format?: DateFormatEnum, locale?: string, timeZone?: string) => string;
+        string: (n: number, format?: DateFormatEnum, locale?: string, timeZone?: string) => string;
     };
-};
+}

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;
@@ -127,13 +127,13 @@ function calculateDifferenceOfDateStrings(ds1, ds2 = getCurrentPacificTime(), un
         case exports.TimeUnitEnum.MILLISECONDS:
             return diffInMs;
         case exports.TimeUnitEnum.SECONDS:
-            return exports.Milliseconds.from.seconds(diffInMs);
+            return Milliseconds.from.seconds(diffInMs);
         case exports.TimeUnitEnum.MINUTES:
-            return exports.Milliseconds.from.minutes(diffInMs);
+            return Milliseconds.from.minutes(diffInMs);
         case exports.TimeUnitEnum.HOURS:
-            return exports.Milliseconds.from.hours(diffInMs);
+            return Milliseconds.from.hours(diffInMs);
         case exports.TimeUnitEnum.DAYS:
-            return exports.Milliseconds.from.days(diffInMs);
+            return Milliseconds.from.days(diffInMs);
         default:
             console.error('Invalid time unit specified. Use TimeUnitEnum.MILLISECONDS, TimeUnitEnum.SECONDS, TimeUnitEnum.MINUTES, TimeUnitEnum.HOURS, or TimeUnitEnum.DAYS');
             return null;
@@ -208,122 +208,144 @@ function toPacificTime(initialDateString) {
     const pacificTime = initialDate.toLocaleString(exports.DEFAULT_LOCALE, { timeZone: exports.DEFAULT_TIMEZONE });
     return pacificTime;
 }
-exports.Milliseconds = {
-    from: {
-        /**
-         * @param n `number`
-         * @returns `n * (1000 * 60 * 60 * 24)` number of milliseconds in `n` days
-         */
-        days: (n) => {
-            return n * (1000 * 60 * 60 * 24);
-        },
-        /**
-         * @param n `number`
-         * @returns `n * (1000 * 60 * 60)` number of milliseconds in `n` hours
-         */
-        hours: (n) => {
-            return n * (1000 * 60 * 60);
-        },
-        /**
-         * @param n `number`
-         * @returns `n * (1000 * 60)` number of milliseconds in `n` minutes
-         */
-        minutes: (n) => {
-            return n * (1000 * 60);
-        },
-        /**
-         * @param n `number`
-         * @returns `n * (1000)` number of milliseconds in `n` seconds
-         */
-        seconds: (n) => {
-            return n * (1000);
-        },
-        /**
-         * @param d `Date` object
-         * @returns `number` = `d.getTime()` = milliseconds since epoch
-         */
-        date: (d) => {
-            return d.getTime();
-        },
-        /**
-         * @param s `string` date string to pass into Date Constructor (e.g. ISO, UTC, Locale, etc.)
-         * @returns `number` milliseconds since epoch or `null` if invalid (i.e. Date constructor can't parse it)
-         */
-        string: (s) => {
-            try {
-                const date = new Date(s);
-                if (isNaN(date.getTime())) {
-                    throw new Error(`Invalid date string: '${s}'`);
-                }
-                return date.getTime();
-            }
-            catch (error) {
-                console.error(`Failed to parse date string: '${s}'`, error);
-                return null;
-            }
-        },
+class Milliseconds {
+}
+exports.Milliseconds = Milliseconds;
+Milliseconds.from = {
+    /**
+     * @param n `number`
+     * @param withLeapTime `boolean (optional)` `default = true`
+     * @returns `n * (1000 * 60 * 60 * 24) * (withLeapTime ? 365.25 : 365)`
+     */
+    years: (n, withLeapTime = true) => {
+        return n * (1000 * 60 * 60 * 24) * (withLeapTime ? 365.25 : 365);
+    },
+    /**
+     * @param n `number`
+     * @returns `n * (1000 * 60 * 60 * 24)` number of milliseconds in `n` days
+     */
+    days: (n) => {
+        return n * (1000 * 60 * 60 * 24);
+    },
+    /**
+     * @param n `number`
+     * @returns `n * (1000 * 60 * 60)` number of milliseconds in `n` hours
+     */
+    hours: (n) => {
+        return n * (1000 * 60 * 60);
+    },
+    /**
+     * @param n `number`
+     * @returns `n * (1000 * 60)` number of milliseconds in `n` minutes
+     */
+    minutes: (n) => {
+        return n * (1000 * 60);
     },
-    to: {
-        /**
-         * @param n `number`
-         * @returns `number` days in `n` milliseconds
-         */
-        days: (n) => {
-            return n / (1000 * 60 * 60 * 24);
-        },
-        /**
-         * @param n `number`
-         * @returns `number` hours in `n` milliseconds
-         */
-        hours: (n) => {
-            return n / (1000 * 60 * 60);
-        },
-        /**
-         * @param n `number`
-         * @returns `number` minutes in `n` milliseconds
-         */
-        minutes: (n) => {
-            return n / (1000 * 60);
-        },
-        /**
-         * @param n `number`
-         * @returns `number` seconds in `n` milliseconds
-         */
-        seconds: (n) => {
-            return n / (1000);
-        },
-        /**
-         * interprets `n` as milliseconds since epoch
-         * @param n `number` milliseconds
-         * @returns `Date` object
-         */
-        date: (n) => {
-            return new Date(n);
-        },
-        /**
-         * @param n `number`
-         * @param format {@link DateFormatEnum} default = {@link DateFormatEnum.ISO}
-         * @param locale `string` default = `'en-US'` (only used if format = {@link DateFormatEnum.LOCALE})
-         * @param timeZone `string` default = `'America/Los_Angeles'` (only used if format = {@link DateFormatEnum.LOCALE})
-         * @returns `string` formatted date string or empty string if error
-         */
-        string: (n, format = exports.DateFormatEnum.ISO, locale = exports.DEFAULT_LOCALE, timeZone = exports.DEFAULT_TIMEZONE) => {
-            const date = new Date(n);
+    /**
+     * @param n `number`
+     * @returns `n * (1000)` number of milliseconds in `n` seconds
+     */
+    seconds: (n) => {
+        return n * (1000);
+    },
+    /**
+     * @param d `Date` object
+     * @returns `number` = `d.getTime()` = milliseconds since epoch
+     */
+    date: (d) => {
+        return d.getTime();
+    },
+    /**
+     * @param s `string` date string to pass into Date Constructor (e.g. ISO, UTC, Locale, etc.)
+     * @returns `number` milliseconds since epoch or `null` if invalid (i.e. Date constructor can't parse it)
+     */
+    string: (s) => {
+        try {
+            const date = new Date(s);
             if (isNaN(date.getTime())) {
-                console.error(`Invalid milliseconds value: '${n}'`);
-                return ``;
+                throw new Error(`Invalid date string: '${s}'`);
             }
-            switch (format) {
-                case exports.DateFormatEnum.ISO:
-                    return date.toISOString();
-                case exports.DateFormatEnum.UTC:
-                    return date.toUTCString();
-                case exports.DateFormatEnum.LOCALE:
-                    return date.toLocaleString(locale, { timeZone });
-                default:
-                    console.error(`Invalid date format specified: '${format}'.`, `Use DateFormatEnum.ISO, DateFormatEnum.UTC, or DateFormatEnum.LOCALE`);
-                    return ``;
-            }
-        },
+            return date.getTime();
+        }
+        catch (error) {
+            console.error(`[Milliseconds.from.string()] Failed to parse date string: '${s}'`, error);
+            return null;
+        }
+    },
+};
+Milliseconds.to = {
+    /**
+     * @param n `number`
+     * @param withLeapTime `boolean (optional)` `default = true`
+     * @returns `number` years in `n` milliseconds
+     * = `n / (1000 * 60 * 60 * 24 * (withLeapTime ? 365.25 : 365))`
+     */
+    years: (n, withLeapTime = true) => {
+        return n / (1000 * 60 * 60 * 24 * (withLeapTime ? 365.25 : 365));
+    },
+    /**
+     * @param n `number`
+     * @returns `number` days in `n` milliseconds
+     * = `n / (1000 * 60 * 60 * 24)`
+     */
+    days: (n) => {
+        return n / (1000 * 60 * 60 * 24);
+    },
+    /**
+     * @param n `number`
+     * @returns `number` hours in `n` milliseconds
+     * = `n / (1000 * 60 * 60)`
+     */
+    hours: (n) => {
+        return n / (1000 * 60 * 60);
+    },
+    /**
+     * @param n `number`
+     * @returns `number` minutes in `n` milliseconds
+     * = `n / (1000 * 60)`
+     */
+    minutes: (n) => {
+        return n / (1000 * 60);
+    },
+    /**
+     * @param n `number`
+     * @returns `number` seconds in `n` milliseconds
+     * = `n / (1000)`
+     */
+    seconds: (n) => {
+        return n / (1000);
+    },
+    /**
+     * interprets `n` as milliseconds since epoch
+     * @param n `number` milliseconds
+     * @returns `Date` object
+     */
+    date: (n) => {
+        return new Date(n);
+    },
+    /**
+     * @param n `number`
+     * @param format {@link DateFormatEnum} `default` = {@link DateFormatEnum.ISO}
+     * @param locale `string` `default` = `'en-US'` (only used if `format` = `DateFormatEnum.LOCALE`)
+     * @param timeZone `string` `default` = `'America/Los_Angeles'` (only used if `format` = `DateFormatEnum.LOCALE`)
+     * @returns `string` formatted date string or empty string if error
+     */
+    string: (n, format = exports.DateFormatEnum.ISO, locale = exports.DEFAULT_LOCALE, timeZone = exports.DEFAULT_TIMEZONE) => {
+        const date = new Date(n);
+        if (isNaN(date.getTime())) {
+            console.error(`[Milliseconds.to.string()] Invalid milliseconds value: '${n}'`);
+            return ``;
+        }
+        switch (format) {
+            case exports.DateFormatEnum.ISO:
+                return date.toISOString();
+            case exports.DateFormatEnum.UTC:
+                return date.toUTCString();
+            case exports.DateFormatEnum.LOCALE:
+                return date.toLocaleString(locale, { timeZone });
+            default:
+                console.error(`[Milliseconds.to.string()] Invalid date format specified: '${format}'.`, `Use DateFormatEnum.ISO, DateFormatEnum.UTC, or DateFormatEnum.LOCALE`);
+                return ``;
+        }
     },
 };

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