typeshi 2.2.1 → 2.2.3

package/README.md

@@ -0,0 +1 @@
+Copy/paste into your project if you find something useful.

package/dist/utils/index.d.ts

@@ -5,4 +5,5 @@ export * from "./io";
 export * from "./regex";
 export * from "./argumentValidation";
 export * from "./typeValidation";
+export * from "./utilityTypes";
 export * from "./object";

package/dist/utils/index.js

@@ -21,4 +21,5 @@ __exportStar(require("./io"), exports);
 __exportStar(require("./regex"), exports);
 __exportStar(require("./argumentValidation"), exports);
 __exportStar(require("./typeValidation"), exports);
+__exportStar(require("./utilityTypes"), exports);
 __exportStar(require("./object"), exports);

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/object.d.ts

@@ -100,3 +100,12 @@ export declare function hasDefinedEntry<T extends object>(obj: any, key: keyof T
 export declare function containsKey<T extends object, K extends (keyof T | (keyof any & {})) = any>(obj: T, ...keys: K[]): obj is {
     [K in keyof T]: T[K];
 };
+/**
+ * @deprecated
+ * @param objA `Record<string, any>`
+ * @param objB `Record<string, any>`
+ * @returns **`areEquivalentObjects`** `boolean`
+ * - `true` `if` `objA` and `objB` are equivalent objects (same keys and values, including nested objects and arrays),
+ * - `false` `otherwise`.
+ */
+export declare function areEquivalentObjects(objA: Record<string, any>, objB: Record<string, any>): boolean;

package/dist/utils/object.js

@@ -11,7 +11,9 @@ exports.picked = picked;
 exports.enforceMaxLength = enforceMaxLength;
 exports.hasDefinedEntry = hasDefinedEntry;
 exports.containsKey = containsKey;
+exports.areEquivalentObjects = areEquivalentObjects;
 const typeValidation_1 = require("./typeValidation");
+const index_1 = require("./regex/index");
 /**
  * @param obj `S` - source object (e.g., Request Body)
  * @param schema {@link TransformationSchema}`<T, S>` - map of keys to transformation functions.
@@ -177,3 +179,33 @@ function containsKey(obj, ...keys) {
     }
     return true;
 }
+/**
+ * @deprecated
+ * @param objA `Record<string, any>`
+ * @param objB `Record<string, any>`
+ * @returns **`areEquivalentObjects`** `boolean`
+ * - `true` `if` `objA` and `objB` are equivalent objects (same keys and values, including nested objects and arrays),
+ * - `false` `otherwise`.
+ */
+function areEquivalentObjects(objA, objB) {
+    if (!(0, typeValidation_1.isObject)(objA) || !(0, typeValidation_1.isObject)(objB))
+        return false;
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every(key => {
+        if (!containsKey(objB, key))
+            return false; // key not in both objects
+        const valA = objA[key];
+        const valB = objB[key];
+        if (Array.isArray(valA) && Array.isArray(valB)) {
+            return valA.length === valB.length
+                && valA.every((item) => valB.includes(item));
+        }
+        else if (typeof valA === "object" && valA && typeof valB === "object" && valB) {
+            return areEquivalentObjects(valA, valB);
+        }
+        return (0, index_1.equivalentAlphanumericStrings)(valA, valB);
+    });
+}

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

@@ -1,6 +1,29 @@
-/** `re` = `/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/` */
+export interface ParsedEmailAddress {
+    /** the whole email address */
+    address: string;
+    /** `localPart` the part before the @ sign */
+    local: string;
+    /** the part after the @ sign */
+    domain: string;
+    /** sender's display name if present in source string */
+    displayName?: string;
+}
+/**
+ * @param s `string`
+ * - e.g. `"{local}@{domain}"`, `"{displayName} <{local}@{domain}>"`
+ * @returns **`result`** {@link ParsedEmailAddress}` | null`
+ * @note `ParsedEmail.displayName` will be `undefined` if not present in `s`
+ * - prefix `/^no(-)?reply\s*(?=\w)/i` is removed from `displayName`
+ */
+export declare function parseEmailAddress(s: string): ParsedEmailAddress | null;
+/** @deprecated
+ * `re` = `/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/` */
 export declare const EMAIL_REGEX: RegExp;
-/**return true if matches {@link EMAIL_REGEX} and does not include pattern/string specified in `excludeSubstrings`  */
-export declare function isValidEmail(email: string, excludeSubstrings?: string | RegExp | string[]): boolean;
-/** @returns **`email`**: `string` - the first email that matches {@link EMAIL_REGEX} or an empty string `''`*/
+/**
+ * @deprecated
+ * return true if matches {@link EMAIL_REGEX} and does not include pattern/string specified in `excludeSubstrings`  */
+export declare function isValidEmail(email: string, excludeSubstrings?: string | string[] | RegExp): boolean;
+/**
+ * @deprecated
+ * @returns `RegExpMatchArray` {@link EMAIL_REGEX} */
 export declare function extractEmail(email: string): RegExpMatchArray | null;

package/dist/utils/regex/email.js

@@ -1,24 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EMAIL_REGEX = void 0;
+exports.parseEmailAddress = parseEmailAddress;
 exports.isValidEmail = isValidEmail;
 exports.extractEmail = extractEmail;
 /**
  * @file src/utils/regex/email.ts
  */
-const stringOperations_1 = require("./stringOperations");
-const StringOptions_1 = require("./types/StringOptions");
-/** `re` = `/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/` */
-exports.EMAIL_REGEX = new RegExp(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/, StringOptions_1.RegExpFlagsEnum.GLOBAL);
-/**return true if matches {@link EMAIL_REGEX} and does not include pattern/string specified in `excludeSubstrings`  */
+const Str_1 = require("./Str");
+// @TODO parameterize replacements in parsed displayName
+/**
+ * @param s `string`
+ * - e.g. `"{local}@{domain}"`, `"{displayName} <{local}@{domain}>"`
+ * @returns **`result`** {@link ParsedEmailAddress}` | null`
+ * @note `ParsedEmail.displayName` will be `undefined` if not present in `s`
+ * - prefix `/^no(-)?reply\s*(?=\w)/i` is removed from `displayName`
+ */
+function parseEmailAddress(s) {
+    const emailRegex = /([a-zA-Z0-9._%+-]+)@([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/g;
+    const matchArrays = Array.from(s.matchAll(emailRegex));
+    if (matchArrays.length === 0)
+        return null;
+    const match = matchArrays[0];
+    const [address, local, domain] = match;
+    const displayName = (s
+        .slice(0, match.index ?? 0)
+        .trim()
+        .replace(/^no(-)?reply\s*(?=\w)/i, '')
+        .replace(/<$/, '')
+        .trim());
+    const result = { address, local, domain };
+    if (displayName)
+        result.displayName = displayName;
+    return result;
+}
+/** @deprecated
+ * `re` = `/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/` */
+exports.EMAIL_REGEX = new RegExp(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/);
+/**
+ * @deprecated
+ * return true if matches {@link EMAIL_REGEX} and does not include pattern/string specified in `excludeSubstrings`  */
 function isValidEmail(email, excludeSubstrings) {
     if (!email)
         return false;
     email = email.trim();
-    return exports.EMAIL_REGEX.test(email)
-        && (excludeSubstrings ? !(0, stringOperations_1.stringContainsAnyOf)(email, excludeSubstrings) : true);
+    return (excludeSubstrings
+        ? exports.EMAIL_REGEX.test(email) && !Str_1.Str.contains(email, excludeSubstrings)
+        : exports.EMAIL_REGEX.test(email));
 }
-/** @returns **`email`**: `string` - the first email that matches {@link EMAIL_REGEX} or an empty string `''`*/
+/**
+ * @deprecated
+ * @returns `RegExpMatchArray` {@link EMAIL_REGEX} */
 function extractEmail(email) {
     if (!email)
         return null;

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/regex/stringOperations.d.ts

@@ -40,6 +40,9 @@ export declare function stringContainsAnyOf(s: string, substrings: string | stri
  * - **`false`** `otherwise`.
  */
 export declare function equivalentAlphanumericStrings(s1: string, s2: string, tolerance?: number): boolean;
-/** for simple regular expressions...
- * so like not ones that have parentheses, pipes, or curly braced numbers */
+/**
+ * @deprecated
+ * for simple regular expressions...
+ * so like not ones that have parentheses, pipes, or curly braced numbers
+ * */
 export declare function extractSource(regex: RegExp): string;

package/dist/utils/regex/stringOperations.js

@@ -128,7 +128,7 @@ function stringContainsAnyOf(s, substrings, ...flags) {
         regex = new RegExp(substrings, flagString);
     }
     if (!regex) {
-        config_1.typeshiLogger.warn('containsAnyOf() Invalid substrings type. returning false.', config_1.INDENT_LOG_LINE + `Expected string, array of strings, or RegExp, but received: ${typeof substrings}, ${substrings}`);
+        config_1.typeshiLogger.warn('[containsAnyOf()] Invalid substrings type. returning false.', config_1.INDENT_LOG_LINE + `Expected string, array of strings, or RegExp, but received: ${typeof substrings}, ${substrings}`);
         return false; // Invalid substrings type
     }
     return regex.test(s);
@@ -178,8 +178,11 @@ function equivalentAlphanumericStrings(s1, s2, tolerance = 0.90) {
     }
     return false;
 }
-/** for simple regular expressions...
- * so like not ones that have parentheses, pipes, or curly braced numbers */
+/**
+ * @deprecated
+ * for simple regular expressions...
+ * so like not ones that have parentheses, pipes, or curly braced numbers
+ * */
 function extractSource(regex) {
     if (!regex)
         return '';

package/dist/utils/typeValidation.d.ts

@@ -7,7 +7,7 @@
  * - **`true`** if `value` is an array and has at least one element,
  * - **`false`** otherwise.
  */
-export declare function isNonEmptyArray<T>(value: any): value is Array<T> & {
+export declare function isNonEmptyArray<T>(value: unknown): value is Array<T> & {
     length: number;
 };
 /**
@@ -16,7 +16,7 @@ export declare function isNonEmptyArray<T>(value: any): value is Array<T> & {
  * - **`true`** if `value` is an array and has no elements,
  * - **`false`** `otherwise`
  */
-export declare function isEmptyArray<T>(value: any): value is Array<T> & {
+export declare function isEmptyArray<T>(value: unknown): value is Array<T> & {
     length: 0;
 };
 /**
@@ -27,13 +27,12 @@ export declare function isEmptyArray<T>(value: any): value is Array<T> & {
  * - `if` `false` then `value` can be empty array
  * @returns **`isIntegerArray`** `boolean` = `value is number[] & { length: number }`
  */
-export declare function isIntegerArray(value: any, requireNonNegative?: boolean, requireNonEmpty?: boolean): value is number[] & {
+export declare function isIntegerArray(value: unknown, requireNonNegative?: boolean, requireNonEmpty?: boolean): value is number[] & {
     length: number;
 };
 /**
- * @consideration add param to allow for empty strings?
  * @param value `any`
- * @param requireNonEmpty `boolean` `default = true`
+ * @param requireNonEmpty `boolean` `aka "requireNonEmptyArray"` `default = true`
  * - `if` `true` then `value` must be array with at least 1 element and every element `isNonEmptyString`
  * - `if` `false` then `value` can be empty array
  * @returns **`isStringArray`** `boolean` = `value is string[] & { length: number }`
@@ -41,40 +40,6 @@ export declare function isIntegerArray(value: any, requireNonNegative?: boolean,
 export declare function isStringArray(value: any, requireNonEmpty?: boolean): value is string[] & {
     length: number;
 };
-/**
- * `fka hasNonTrivialKeys`
- * @note **passing in an array will return `false`.**
- * @note a value is considered trivial if {@link isEmpty}`(value)` returns `true` and vice versa
- * @param obj `any` The object to check.
- * @param requireAll `boolean` - flag indicating whether all values must be nontrivial or not
- * @returns **`hasNonTrivialEntries`** `boolean`
- * - **`true`** `if` the `obj` has non-empty keys,
- * - **`false`** `otherwise`
- */
-export declare function hasNonTrivialEntries<T extends object>(obj: T, requireAll?: boolean): obj is T;
-/**
- * @note uses `key in obj` for each element of param `keys`
- * @param obj `T extends Object` the object to check
- * @param keys `Array<keyof T> | string[] | string` the list of keys that obj must have
- * @param requireAll `boolean` defaults to `true`
- * - `if` `true`, all keys must be present in the object;
- * - `if` `false`, at least one key must be present
- * @param restrictKeys `boolean` defaults to `false`
- * - `if` `true`, only the keys provided in the `keys` param are allowed in the object;
- * - `if` `false`, the object can keys not included in the `keys` param.
- * @returns **`hasKeys`** `boolean`
- * - **`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;
-/**
- * @param objA `Record<string, any>`
- * @param objB `Record<string, any>`
- * @returns **`areEquivalentObjects`** `boolean`
- * - `true` `if` `objA` and `objB` are equivalent objects (same keys and values, including nested objects and arrays),
- * - `false` `otherwise`.
- */
-export declare function areEquivalentObjects(objA: Record<string, any>, objB: Record<string, any>): boolean;
 /**
  * @param value `any`
  * @param requireInteger `boolean` `default = false`
@@ -116,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;
 /**
@@ -243,30 +208,31 @@ export declare function isNull(value: unknown): value is null;
  */
 export declare function isUndefined(value: any): value is undefined;
 export declare function isUndefinedOrNull(value: unknown): value is undefined | null;
-export type NumberKeys<T, Required extends boolean = false> = {
-    [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> = {
-    [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> = {
-    [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> = {
-    [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> = {
-    [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][];
-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];
 /**
- * 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`
+ * @deprecated
+ * `fka hasNonTrivialKeys`
+ * @note **passing in an array will return `false`.**
+ * @note a value is considered trivial if {@link isEmpty}`(value)` returns `true` and vice versa
+ * @param obj `any` The object to check.
+ * @param requireAll `boolean` - flag indicating whether all values must be nontrivial or not
+ * @returns **`hasNonTrivialEntries`** `boolean`
+ * - **`true`** `if` the `obj` has non-empty keys,
+ * - **`false`** `otherwise`
+ */
+export declare function hasNonTrivialEntries<T extends object>(obj: T, requireAll?: boolean): obj is T;
+/**
+ * @deprecated
+ * @note uses `key in obj` for each element of param `keys`
+ * @param obj `T extends Object` the object to check
+ * @param keys `Array<keyof T> | string[] | string` the list of keys that obj must have
+ * @param requireAll `boolean` defaults to `true`
+ * - `if` `true`, all keys must be present in the object;
+ * - `if` `false`, at least one key must be present
+ * @param restrictKeys `boolean` defaults to `false`
+ * - `if` `true`, only the keys provided in the `keys` param are allowed in the object;
+ * - `if` `false`, the object can keys not included in the `keys` param.
+ * @returns **`hasKeys`** `boolean`
+ * - **`true`** `if` `obj` is of type 'object' and has the required key(s),
+ * - **`false`** `otherwise`
  */
-export type KeysOfType<T, U, Required extends boolean = false> = {
-    [K in keyof T]: Required extends true ? (T[K] extends U ? K : never) : (T[K] extends U | undefined ? K : never);
-}[keyof T][];
+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

@@ -8,9 +8,6 @@ exports.isNonEmptyArray = isNonEmptyArray;
 exports.isEmptyArray = isEmptyArray;
 exports.isIntegerArray = isIntegerArray;
 exports.isStringArray = isStringArray;
-exports.hasNonTrivialEntries = hasNonTrivialEntries;
-exports.hasKeys = hasKeys;
-exports.areEquivalentObjects = areEquivalentObjects;
 exports.isNumeric = isNumeric;
 exports.isNonEmptyString = isNonEmptyString;
 exports.isPrimitiveValue = isPrimitiveValue;
@@ -23,7 +20,8 @@ exports.isFunction = isFunction;
 exports.isNull = isNull;
 exports.isUndefined = isUndefined;
 exports.isUndefinedOrNull = isUndefinedOrNull;
-const index_1 = require("./regex/index");
+exports.hasNonTrivialEntries = hasNonTrivialEntries;
+exports.hasKeys = hasKeys;
 /**
  * @param value
  * @returns **`isNonEmptyArray`** `boolean` = `value is Array<T> & { length: number }`
@@ -55,10 +53,10 @@ function isIntegerArray(value, requireNonNegative = false, requireNonEmpty = tru
         ? isNonEmptyArray(value) && value.every(el => isInteger(el, requireNonNegative))
         : isEmptyArray(value));
 }
+//  * @consideration add param to allow for empty strings?
 /**
- * @consideration add param to allow for empty strings?
  * @param value `any`
- * @param requireNonEmpty `boolean` `default = true`
+ * @param requireNonEmpty `boolean` `aka "requireNonEmptyArray"` `default = true`
  * - `if` `true` then `value` must be array with at least 1 element and every element `isNonEmptyString`
  * - `if` `false` then `value` can be empty array
  * @returns **`isStringArray`** `boolean` = `value is string[] & { length: number }`
@@ -68,103 +66,6 @@ function isStringArray(value, requireNonEmpty = true) {
         ? isNonEmptyArray(value) && value.every(el => isNonEmptyString(el))
         : isEmptyArray(value));
 }
-// maybe deprecate this
-/**
- * `fka hasNonTrivialKeys`
- * @note **passing in an array will return `false`.**
- * @note a value is considered trivial if {@link isEmpty}`(value)` returns `true` and vice versa
- * @param obj `any` The object to check.
- * @param requireAll `boolean` - flag indicating whether all values must be nontrivial or not
- * @returns **`hasNonTrivialEntries`** `boolean`
- * - **`true`** `if` the `obj` has non-empty keys,
- * - **`false`** `otherwise`
- */
-function hasNonTrivialEntries(obj, requireAll = false) {
-    if (!isObject(obj)) {
-        return false;
-    }
-    return (requireAll
-        ? 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[] }`
-// maybe deprecate this
-/**
- * @note uses `key in obj` for each element of param `keys`
- * @param obj `T extends Object` the object to check
- * @param keys `Array<keyof T> | string[] | string` the list of keys that obj must have
- * @param requireAll `boolean` defaults to `true`
- * - `if` `true`, all keys must be present in the object;
- * - `if` `false`, at least one key must be present
- * @param restrictKeys `boolean` defaults to `false`
- * - `if` `true`, only the keys provided in the `keys` param are allowed in the object;
- * - `if` `false`, the object can keys not included in the `keys` param.
- * @returns **`hasKeys`** `boolean`
- * - **`true`** `if` `obj` is of type 'object' and has the required key(s),
- * - **`false`** `otherwise`
- */
-function hasKeys(obj, keys, requireAll = true, restrictKeys = false) {
-    if (!obj || typeof obj !== 'object') {
-        return false;
-    }
-    if (keys === null || keys === undefined) {
-        return false;
-    }
-    if (!isNonEmptyArray(keys)) {
-        keys = [keys]; // Convert string (assumed to be single key) to array of keys
-    }
-    let numKeysFound = 0;
-    for (const key of keys) {
-        if (key in obj) {
-            numKeysFound++;
-            if (!requireAll && !restrictKeys) {
-                return true;
-            }
-        }
-        else if (requireAll) { // and a key is not found
-            return false;
-        }
-    }
-    if (restrictKeys) {
-        // If restrictKeys is true, check that no other keys are present in the object
-        const objKeys = Object.keys(obj);
-        const extraKeys = objKeys.filter(k => !keys.includes(k));
-        if (extraKeys.length > 0) {
-            return false; // Found keys not in the allowed list
-        }
-    }
-    return requireAll ? numKeysFound === keys.length : numKeysFound > 0;
-}
-/**
- * @param objA `Record<string, any>`
- * @param objB `Record<string, any>`
- * @returns **`areEquivalentObjects`** `boolean`
- * - `true` `if` `objA` and `objB` are equivalent objects (same keys and values, including nested objects and arrays),
- * - `false` `otherwise`.
- */
-function areEquivalentObjects(objA, objB) {
-    if (!objA || typeof objA !== 'object' || !objB || typeof objB !== 'object') {
-        return false;
-    }
-    const keysA = Object.keys(objA);
-    const keysB = Object.keys(objB);
-    if (keysA.length !== keysB.length)
-        return false;
-    return keysA.every(key => {
-        if (!hasKeys(objB, key))
-            return false; // key not in both objects
-        const valA = objA[key];
-        const valB = objB[key];
-        if (Array.isArray(valA) && Array.isArray(valB)) {
-            return valA.length === valB.length
-                && valA.every((item) => valB.includes(item));
-        }
-        else if (typeof valA === "object" && valA && typeof valB === "object" && valB) {
-            return areEquivalentObjects(valA, valB);
-        }
-        return (0, index_1.equivalentAlphanumericStrings)(valA, valB);
-    });
-}
 /**
  * @param value `any`
  * @param requireInteger `boolean` `default = false`
@@ -209,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) {
@@ -456,3 +357,69 @@ function isUndefined(value) {
 function isUndefinedOrNull(value) {
     return value === undefined || value === null;
 }
+/**
+ * @deprecated
+ * `fka hasNonTrivialKeys`
+ * @note **passing in an array will return `false`.**
+ * @note a value is considered trivial if {@link isEmpty}`(value)` returns `true` and vice versa
+ * @param obj `any` The object to check.
+ * @param requireAll `boolean` - flag indicating whether all values must be nontrivial or not
+ * @returns **`hasNonTrivialEntries`** `boolean`
+ * - **`true`** `if` the `obj` has non-empty keys,
+ * - **`false`** `otherwise`
+ */
+function hasNonTrivialEntries(obj, requireAll = false) {
+    if (!isObject(obj)) {
+        return false;
+    }
+    return (requireAll
+        ? Object.values(obj).every(v => !isEmpty(v))
+        : Object.values(obj).some(v => !isEmpty(v)));
+}
+/**
+ * @deprecated
+ * @note uses `key in obj` for each element of param `keys`
+ * @param obj `T extends Object` the object to check
+ * @param keys `Array<keyof T> | string[] | string` the list of keys that obj must have
+ * @param requireAll `boolean` defaults to `true`
+ * - `if` `true`, all keys must be present in the object;
+ * - `if` `false`, at least one key must be present
+ * @param restrictKeys `boolean` defaults to `false`
+ * - `if` `true`, only the keys provided in the `keys` param are allowed in the object;
+ * - `if` `false`, the object can keys not included in the `keys` param.
+ * @returns **`hasKeys`** `boolean`
+ * - **`true`** `if` `obj` is of type 'object' and has the required key(s),
+ * - **`false`** `otherwise`
+ */
+function hasKeys(obj, keys, requireAll = true, restrictKeys = false) {
+    if (!obj || typeof obj !== 'object') {
+        return false;
+    }
+    if (keys === null || keys === undefined) {
+        return false;
+    }
+    if (!isNonEmptyArray(keys)) {
+        keys = [keys]; // Convert string (assumed to be single key) to array of keys
+    }
+    let numKeysFound = 0;
+    for (const key of keys) {
+        if (key in obj) {
+            numKeysFound++;
+            if (!requireAll && !restrictKeys) {
+                return true;
+            }
+        }
+        else if (requireAll) { // and a key is not found
+            return false;
+        }
+    }
+    if (restrictKeys) {
+        // If restrictKeys is true, check that no other keys are present in the object
+        const objKeys = Object.keys(obj);
+        const extraKeys = objKeys.filter(k => !keys.includes(k));
+        if (extraKeys.length > 0) {
+            return false; // Found keys not in the allowed list
+        }
+    }
+    return requireAll ? numKeysFound === keys.length : numKeysFound > 0;
+}

package/dist/utils/utilityTypes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file src/utils/utilityTypes.ts
+ */
+/**
+ * @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], 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], 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], 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], 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], 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 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 `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], 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>; // 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>'
+ * */
+export type NonStrict<T extends string | number> = T | (T extends string ? (string & {}) : (number & {}));

package/dist/utils/utilityTypes.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * @file src/utils/utilityTypes.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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