typeshi 2.2.2 → 2.2.3

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

@@ -1,22 +1,23 @@
 import { ILogObj, ILogObjMeta } from "tslog";
 /**
- * @param fileName `string` passed into `extractFileName()`
+ * @param base `string` - e.g. name of file or class
+ * - passed into `extractFileName()` if `/\\|\//.test(filename)`
  * @param func `Function` - to get Function.name
  * @param funcInfo `any` `(optional)` - context or params of func (converted to string)
  * @param startLine `number` `(optional)`
  * @param endLine `number` `(optional)`
  * @returns **`sourceString`** `string` to use in log statements or argumentValidation calls
  */
-export declare function getSourceString(fileName: string, func: string | Function, funcInfo?: any, startLine?: number, endLine?: number): string;
+export declare function getSourceString(base: 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.
+ * @param filepaths `string[]` - optional, specific file paths to format.
  * If not provided, will format all .txt files in the log directory.
  * @returns `void`
  */
-export declare function autoFormatLogsOnExit(filePaths?: string[]): void;
+export declare function autoFormatLogsOnExit(filepaths?: string[]): void;
 /**
  * @deprecated
  * Formats a debug log file from JSON format to a more readable text format.
@@ -31,11 +32,11 @@ export declare function formatDebugLogFile(inputPath: string, outputPath?: strin
  * @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.
+ * @param logDir `string` - optional, path to the log directory.
  * If not provided, uses LOCAL_LOG_DIR from setupLog.ts
  * @returns `void`
  */
-export declare function formatAllDebugLogs(logDirectory: string): void;
+export declare function formatAllDebugLogs(logDir: string): void;
 /**
  * @deprecated
  * reduce metadata to two entries, then return stringified `logObj`

package/dist/utils/io/logging.js

@@ -44,22 +44,24 @@ exports.formatLogObj = formatLogObj;
 /**
  * @file src/utils/io/logging.ts
  */
-const fs = __importStar(require("fs"));
+const node_fs_1 = __importDefault(require("node:fs"));
 const setupLog_1 = require("../../config/setupLog");
 const typeValidation_1 = require("../typeValidation");
 const regex_1 = require("../regex");
 const validate = __importStar(require("../argumentValidation"));
 const node_path_1 = __importDefault(require("node:path"));
 /**
- * @param fileName `string` passed into `extractFileName()`
+ * @param base `string` - e.g. name of file or class
+ * - passed into `extractFileName()` if `/\\|\//.test(filename)`
  * @param func `Function` - to get Function.name
  * @param funcInfo `any` `(optional)` - context or params of func (converted to string)
  * @param startLine `number` `(optional)`
  * @param endLine `number` `(optional)`
  * @returns **`sourceString`** `string` to use in log statements or argumentValidation calls
  */
-function getSourceString(fileName, func, funcInfo, startLine, endLine) {
-    fileName = (0, regex_1.extractFileName)(fileName);
+function getSourceString(base, func, funcInfo, startLine, endLine) {
+    if (/\\|\//.test(base))
+        base = (0, regex_1.extractFileName)(base);
     let lineNumberText = ((0, typeValidation_1.isInteger)(startLine)
         ? `:${startLine}`
         : '');
@@ -68,30 +70,23 @@ function getSourceString(fileName, func, funcInfo, startLine, endLine) {
         ? lineNumberText + `-${endLine}`
         : '');
     let funcName = typeof func === 'string' ? func : func.name;
-    return `[${fileName}.${funcName}(${(0, typeValidation_1.isNonEmptyString)(funcInfo) ? ` ${funcInfo} ` : ''})${lineNumberText}]`;
+    return `[${base}.${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.
+ * @param filepaths `string[]` - optional, specific file paths to format.
  * If not provided, will format all .txt files in the log directory.
  * @returns `void`
  */
-function autoFormatLogsOnExit(filePaths) {
-    const source = getSourceString(__filename, autoFormatLogsOnExit.name, `Array<string>(${(filePaths ?? []).length})`);
-    if (!(0, typeValidation_1.isStringArray)(filePaths)) {
-        setupLog_1.typeshiLogger.warn([`${source} Invalid param 'filePaths'`,
-            `Expected: string[] (array of filePaths)`,
-            `Received: ${typeof filePaths} = '${JSON.stringify(filePaths)}'`
-        ].join(setupLog_1.INDENT_LOG_LINE));
-        return;
-    }
+function autoFormatLogsOnExit(filepaths) {
+    const source = getSourceString(__filename, autoFormatLogsOnExit.name, `Array<string>(${(filepaths ?? []).length})`);
     try {
-        for (const filePath of filePaths) {
-            if (fs.existsSync(filePath)) {
+        validate.arrayArgument(source, { filepaths, isStringArray: typeValidation_1.isStringArray });
+        for (const filePath of filepaths ?? []) {
+            if (node_fs_1.default.existsSync(filePath))
                 formatDebugLogFile(filePath);
-            }
         }
     }
     catch (error) {
@@ -116,10 +111,10 @@ function formatDebugLogFile(inputPath, outputPath) {
             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 fileContent = node_fs_1.default.readFileSync(inputPath, 'utf-8');
         const formattedContent = formatLogContent(fileContent);
-        fs.writeFileSync(outputPath, formattedContent, { encoding: 'utf-8' });
-        // mlog.info(`[formatDebugLogFile()] Formatted log file saved to '${outputPath}'`);
+        node_fs_1.default.writeFileSync(outputPath, formattedContent, { encoding: 'utf-8' });
+        setupLog_1.typeshiHiddenLogger.info(`[formatDebugLogFile()] Formatted log file saved to '${outputPath}'`);
     }
     catch (error) {
         setupLog_1.typeshiLogger.error(`${source} Error formatting log file:'`, error);
@@ -216,18 +211,17 @@ function formatSingleLogEntry(logObj) {
  * @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.
+ * @param logDir `string` - optional, path to the log directory.
  * If not provided, uses LOCAL_LOG_DIR from setupLog.ts
  * @returns `void`
  */
-function formatAllDebugLogs(logDirectory) {
-    let logDir = logDirectory;
-    if (!fs.existsSync(logDir)) {
+function formatAllDebugLogs(logDir) {
+    if (!node_fs_1.default.existsSync(logDir)) {
         setupLog_1.typeshiLogger.warn(`[formatAllDebugLogs()] Log directory does not exist: ${logDir}`);
         return;
     }
     try {
-        const files = fs.readdirSync(logDir);
+        const files = node_fs_1.default.readdirSync(logDir);
         const txtFiles = files.filter(file => file.endsWith('.txt') && !file.includes('.FORMATTED.'));
         if (txtFiles.length === 0) {
             setupLog_1.typeshiLogger.warn(`[formatAllDebugLogs()] No .txt log files found in ${logDir}`);
@@ -237,7 +231,7 @@ function formatAllDebugLogs(logDirectory) {
             const inputPath = node_path_1.default.join(logDir, txtFile);
             try {
                 formatDebugLogFile(inputPath);
-                // mlog.info(`[formatAllDebugLogs()] Formatted: ${txtFile}`);
+                setupLog_1.typeshiHiddenLogger.info(`[formatAllDebugLogs()] Formatted: ${txtFile}`);
             }
             catch (error) {
                 setupLog_1.typeshiLogger.error(`[formatAllDebugLogs()] Failed to format ${txtFile}:`, error);

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

@@ -2,9 +2,9 @@ import { StringCleanOptions } 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;
+export declare function isDirectory(value: any): boolean;
 /** checks if `pathString (value)` points to an existing file */
-export declare function isFile(value: string): value is string;
+export declare function isFile(value: string): boolean;
 /**
  * Determines the proper delimiter based on file type or extension
  * @param filePath `string` Path to the file

package/dist/utils/io/reading.js

@@ -472,8 +472,8 @@ async function getOneToOneDictionary(arg1, keyColumn, valueColumn, keyOptions, v
  */
 async function getColumnValues(arg1, columnName, cleaner, allowDuplicates = false) {
     const source = (0, logging_1.getSourceString)(__filename, getColumnValues.name);
-    validate.stringArgument(source, { columnName });
-    validate.booleanArgument(source, { allowDuplicates });
+    // validate.stringArgument(source, {columnName});
+    // validate.booleanArgument(source, {allowDuplicates});
     if (cleaner)
         validate.functionArgument(source, { cleaner });
     let rows = await handleFileArgument(arg1, getColumnValues.name, [columnName]);
@@ -497,7 +497,7 @@ async function getColumnValues(arg1, columnName, cleaner, allowDuplicates = fals
  */
 async function getIndexedColumnValues(arg1, columnName, cleaner) {
     const source = `[reading.getIndexedColumnValues()]`;
-    validate.stringArgument(source, { columnName });
+    // validate.stringArgument(source, {columnName});
     if (cleaner)
         validate.functionArgument(source, { cleaner });
     let rows = await handleFileArgument(arg1, getIndexedColumnValues.name, [columnName]);

package/dist/utils/regex/email.js

@@ -8,6 +8,7 @@ exports.extractEmail = extractEmail;
  * @file src/utils/regex/email.ts
  */
 const Str_1 = require("./Str");
+// @TODO parameterize replacements in parsed displayName
 /**
  * @param s `string`
  * - e.g. `"{local}@{domain}"`, `"{displayName} <{local}@{domain}>"`

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

@@ -4,12 +4,12 @@
 /**
  * `extractFileNameFromPath`
  * essentially a wrapper for path.basename() for short-hand convenience
- * @param filePath `string` e.g. pass in the node module variable  `__filename`
+ * @param filepath `string` e.g. pass in the node module variable  `__filename`
  * @param removeExtension `boolean` `optional, default = true` - flag indicating
- * whether or not to remove the file extension from the fileName
- * @returns **`fileName`** `string`
+ * whether or not to remove the file extension from the filename
+ * @returns **`filename`** `string`
  */
-export declare function extractFileName(filePath: string, removeExtension?: boolean): string;
+export declare function extractFileName(filepath: string, removeExtension?: boolean): string;
 /**
  * = `= /^[^/\\:*?"<>|]+(\.[^/\\:*?"<>|]+)$/`
  */
@@ -33,3 +33,17 @@ export declare const KOREA_ADDRESS_LATIN_TEXT_PATTERN: RegExp;
  * @returns **`leaf`**: `string` - the extracted `leaf` or the original value if no extraction performed
  */
 export declare function extractLeaf(value: string, classDelimiter: string): string;
+/**
+ * @param keepParentheses `boolean (optional)` `default = false`
+ * @returns **new RegExp** with same flags as `re`
+ * - returns `re` if does not have `groupName`
+ * @example
+ * const re = /(?<name>)\s*abcdefg/;
+ * let groupName = 'name';
+ * let value = 'Bob';
+ * let result1 = replaceGroupWithLiteral(re, groupName, value, false);
+ * // result1.source === 'Bob\\s*abcdefg'
+ * let result2 = replaceGroupWithLiteral(re, groupName, value, true);
+ * // result2.source === '(Bob)\\s*abcdefg'
+ */
+export declare function replaceGroupWithLiteral(re: RegExp, groupName: string, value: string, keepParentheses?: boolean): RegExp;

package/dist/utils/regex/misc.js

@@ -9,25 +9,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KOREA_ADDRESS_LATIN_TEXT_PATTERN = exports.DATE_STRING_PATTERN = exports.FILE_NAME_WITH_EXTENSION_PATTERN = void 0;
 exports.extractFileName = extractFileName;
 exports.extractLeaf = extractLeaf;
+exports.replaceGroupWithLiteral = replaceGroupWithLiteral;
 const typeValidation_1 = require("../typeValidation");
 const node_path_1 = __importDefault(require("node:path"));
 /**
  * `extractFileNameFromPath`
  * essentially a wrapper for path.basename() for short-hand convenience
- * @param filePath `string` e.g. pass in the node module variable  `__filename`
+ * @param filepath `string` e.g. pass in the node module variable  `__filename`
  * @param removeExtension `boolean` `optional, default = true` - flag indicating
- * whether or not to remove the file extension from the fileName
- * @returns **`fileName`** `string`
+ * whether or not to remove the file extension from the filename
+ * @returns **`filename`** `string`
  */
-function extractFileName(filePath, removeExtension = true) {
-    if (!(0, typeValidation_1.isNonEmptyString)(filePath)) {
+function extractFileName(filepath, removeExtension = true) {
+    if (!(0, typeValidation_1.isNonEmptyString)(filepath)) {
         return 'undefined';
     }
-    let fileName = node_path_1.default.basename(filePath);
+    let filename = node_path_1.default.basename(filepath);
     if (removeExtension) {
-        fileName = fileName.replace(/(?<=.+)\.[a-z0-9]{1,}$/i, '');
+        filename = filename.replace(/(?<=.+)\.[a-z0-9]{1,}$/i, '');
     }
-    return fileName;
+    return filename;
 }
 /**
  * = `= /^[^/\\:*?"<>|]+(\.[^/\\:*?"<>|]+)$/`
@@ -59,3 +60,29 @@ function extractLeaf(value, classDelimiter) {
     }
     return result || value;
 }
+// @consideration rename keepParentheses to keepGroup or keepGrouping or keepGroupParentheses ?
+/**
+ * @param keepParentheses `boolean (optional)` `default = false`
+ * @returns **new RegExp** with same flags as `re`
+ * - returns `re` if does not have `groupName`
+ * @example
+ * const re = /(?<name>)\s*abcdefg/;
+ * let groupName = 'name';
+ * let value = 'Bob';
+ * let result1 = replaceGroupWithLiteral(re, groupName, value, false);
+ * // result1.source === 'Bob\\s*abcdefg'
+ * let result2 = replaceGroupWithLiteral(re, groupName, value, true);
+ * // result2.source === '(Bob)\\s*abcdefg'
+ */
+function replaceGroupWithLiteral(re, groupName, value, keepParentheses = false) {
+    let pat = (keepParentheses
+        ? `(?<=\\\()` + `\\\?<${groupName}>` + `(?=\\\))`
+        : `\\\(` + `\\\?<${groupName}>` + `\\\)`);
+    let groupPattern = new RegExp(pat);
+    if (!groupPattern.test(re.source)) { // re does not contain group
+        console.warn(`[regex.misc.replaceGroupWithLiteral()] re does not contain group '${groupName}'`);
+        return re;
+    }
+    let newSource = re.source.replace(groupPattern, value);
+    return new RegExp(newSource, re.flags);
+}

package/dist/utils/typeValidation.d.ts

@@ -81,7 +81,7 @@ export declare function isInteger(value: unknown, requireNonNegative?: boolean):
  * - `if` `false` then `value` is allowed to be an array
  * @returns **`isObject`** `boolean` `value is T`
  */
-export declare function isObject<T extends object = Record<string, any>>(value: unknown, requireNonEmpty?: boolean, requireNonArray?: boolean): value is T;
+export declare function isObject<T extends object = Record<keyof any, any>>(value: unknown, requireNonEmpty?: boolean, requireNonArray?: boolean): value is T;
 export declare function isPositveInteger(value: unknown): value is number;
 export declare const isType: <T>(value: any, guard: (v: any, ...args: any[]) => v is T, ...args: any[]) => value is T;
 /**
@@ -235,4 +235,4 @@ export declare function hasNonTrivialEntries<T extends object>(obj: T, requireAl
  * - **`true`** `if` `obj` is of type 'object' and has the required key(s),
  * - **`false`** `otherwise`
  */
-export declare function hasKeys<T extends object>(obj: T, keys: Array<keyof T> | string[] | string, requireAll?: boolean, restrictKeys?: boolean): boolean;
+export declare function hasKeys<T extends object = any>(obj: T, keys: Array<keyof T> | string[] | string, requireAll?: boolean, restrictKeys?: boolean): boolean;

package/dist/utils/typeValidation.js

@@ -110,7 +110,7 @@ function isNumeric(value, requireInteger = false, requireNonNegative = false) {
 function isNonEmptyString(value, requireNonSpace = false) {
     return (typeof value === 'string'
         && (requireNonSpace
-            ? value.trim() !== ''
+            ? value.trim() !== '' // Boolean(value.trim())
             : value.length > 0));
 }
 function isPrimitiveValue(value) {
@@ -376,7 +376,6 @@ function hasNonTrivialEntries(obj, requireAll = false) {
         ? Object.values(obj).every(v => !isEmpty(v))
         : Object.values(obj).some(v => !isEmpty(v)));
 }
-// @TODO add overload on param `keys` where keys = `{ required: string[], optional: string[] }`
 /**
  * @deprecated
  * @note uses `key in obj` for each element of param `keys`

package/dist/utils/utilityTypes.d.ts

@@ -1,39 +1,66 @@
 /**
  * @file src/utils/utilityTypes.ts
  */
-export type NumberKeys<T, Required extends boolean = false> = {
+/**
+ * @template Required - Whether the key is required
+ * (allows for `K` where `T[K]` can be `undefined` if `false`)
+ * - `default = false`
+ */
+export type NumberKeys<T, Required extends boolean = false> = Exclude<{
     [K in keyof T]: Required extends true ? (T[K] extends number ? K : never) : (T[K] extends number | undefined ? K : never);
-}[keyof T][];
-export type ArrayKeys<T, Required extends boolean = false> = {
+}[keyof T], undefined>[];
+/**
+ * @template Required - Whether the key is required
+ * (allows for `K` where `T[K]` can be `undefined` if `false`)
+ * - `default = false`
+ */
+export type ArrayKeys<T, Required extends boolean = false> = Exclude<{
     [K in keyof T]: Required extends true ? (T[K] extends Array<any> ? K : never) : (T[K] extends Array<any> | undefined ? K : never);
-}[keyof T][];
-export type ArrayOfTypeKeys<T, U, Required extends boolean = false> = {
+}[keyof T], undefined>[];
+/**
+ * @template Required - Whether the key is required
+ * (allows for `K` where `T[K]` can be `undefined` if `false`)
+ * - `default = false`
+ */
+export type ArrayOfTypeKeys<T, U, Required extends boolean = false> = Exclude<{
     [K in keyof T]: Required extends true ? (T[K] extends Array<U> ? K : never) : (T[K] extends Array<U> | undefined ? K : never);
-}[keyof T][];
-export type StringKeys<T, Required extends boolean = false> = {
+}[keyof T], undefined>[];
+/**
+ * @template Required - Whether the key is required
+ * (allows for `K` where `T[K]` can be `undefined` if `false`)
+ * - `default = false`
+ */
+export type StringKeys<T, Required extends boolean = false> = Exclude<{
     [K in keyof T]: Required extends true ? (T[K] extends string ? K : never) : (T[K] extends string | undefined ? K : never);
-}[keyof T][];
-export type PrimitiveKeys<T, Required extends boolean = false> = {
+}[keyof T], undefined>[];
+/**
+ * @template Required - Whether the key is required
+ * (allows for `K` where `T[K]` can be `undefined` if `false`)
+ * - `default = false`
+ */
+export type PrimitiveKeys<T, Required extends boolean = false> = Exclude<{
     [K in keyof T]: Required extends true ? (T[K] extends string | number | boolean | null ? K : never) : (T[K] extends string | number | boolean | null | undefined ? K : never);
-}[keyof T][];
+}[keyof T], undefined>[];
 export type Primitive = string | number | boolean | null | undefined;
 /** Get the union of all values of `T` (like `valueof T`) */
-export type ValueOf<T> = T[keyof T];
+export type ValueOf<T> = T extends object ? T[keyof T] : T;
 /**
  * Keys of `T` whose values extend a given type `U`
  * @template T - The object type
  * @template U - The type to check each `T[K]` against
- * @template Required - Whether the key is required (allows for `undefined` values if `false`) `default = false`
- */
-export type KeysOfType<T, U, Required extends boolean = false> = {
+ * @template Required - Whether the key is required
+ * (allows for `K` where `T[K]` can be `undefined` if `false`)
+ * - `default = false`
+ * */
+export type KeysOfType<T, U, Required extends boolean = false> = Exclude<{
     [K in keyof T]: Required extends true ? (T[K] extends U ? K : never) : (T[K] extends U | undefined ? K : never);
-}[keyof T][];
+}[keyof T], undefined>[];
 /**
  * use for non-strict autocomplete of enum/literal value types
  * @example
  * JobPlatformEnum = { GREENHOUSE: 'GREENHOUSE', WORKDAY: 'WORKDAY' } as const;
  * type JobPlatformEnum = (typeof JobPlatformEnum)[keyof typeof JobPlatformEnum]; // 'GREENHOUSE' | 'WORKDAY'
- * let key: NonStrict<JobPlatformEnum>; // `key` allows any string, but will have the enum values as suggested auto-complete values
+ * let key: NonStrict<JobPlatformEnum>; // allows any string, but will have the enum values as suggested auto-complete values
  * key = 'hello'; // ok
  * key = 9; // Error: Type '9' is not assignable to type 'NonStrict<JobPlatformEnum>'
  * */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "typeshi",
-    "version": "2.2.2",
+    "version": "2.2.3",
     "description": "TypeScript utility modules",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",