typeshi 2.2.0 → 2.2.2

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

@@ -54,8 +54,7 @@ export declare function picked<T extends object, K extends keyof T>(obj: T, keys
  * - `'FIFO'` - remove elements from front (`'First-In-First-Out'`)
  * @note **assumes newest elements were pushed to end** i.e. `stack.push()` or `queue.enque()`
  * @param inPlace `boolean (optional)` `default = true`
- * - `true` - modify and return original array with: `arr.length = maxLength (LIFO)` or `arr.splice() (FIFO)`
- * - - if `'LIFO'`, can use JS trick by setting `arr.length = maxLength`
+ * - `true` - modify and return original array using: `arr.length = maxLength (LIFO)` or `arr.splice() (FIFO)`
  * - `false` - return new array with: `arr.slice()` `arr.slice(0, maxLength) (LIFO) or arr.slice(i, n) (FIFO)` where `n - i === maxLength`
  * @returns **`arr`** `T[]` where `arr.length <= maxLength`
  */
@@ -101,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.
@@ -90,8 +92,7 @@ function picked(obj, keys) {
  * - `'FIFO'` - remove elements from front (`'First-In-First-Out'`)
  * @note **assumes newest elements were pushed to end** i.e. `stack.push()` or `queue.enque()`
  * @param inPlace `boolean (optional)` `default = true`
- * - `true` - modify and return original array with: `arr.length = maxLength (LIFO)` or `arr.splice() (FIFO)`
- * - - if `'LIFO'`, can use JS trick by setting `arr.length = maxLength`
+ * - `true` - modify and return original array using: `arr.length = maxLength (LIFO)` or `arr.splice() (FIFO)`
  * - `false` - return new array with: `arr.slice()` `arr.slice(0, maxLength) (LIFO) or arr.slice(i, n) (FIFO)` where `n - i === maxLength`
  * @returns **`arr`** `T[]` where `arr.length <= maxLength`
  */
@@ -116,7 +117,7 @@ function enforceMaxLength(arr, maxLength, principle = 'LIFO', inPlace = true) {
         if (principle === 'LIFO') {
             arr.length = maxLength;
         }
-        else {
+        else { // 'FIFO'
             arr.splice(0, excess);
         }
         return arr;
@@ -125,7 +126,7 @@ function enforceMaxLength(arr, maxLength, principle = 'LIFO', inPlace = true) {
         if (principle === 'LIFO') {
             return arr.slice(0, maxLength);
         }
-        else {
+        else { // 'FIFO'
             return arr.slice(excess);
         }
     }
@@ -178,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,55 @@
 "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");
+/**
+ * @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/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`
@@ -243,25 +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` */
-export type KeysOfType<T, U> = {
-    [K in keyof T]: T[K] extends U ? K : never;
-}[keyof T][];
+/**
+ * @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 declare function hasKeys<T extends object>(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`
@@ -456,3 +357,70 @@ 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)));
+}
+// @TODO add overload on param `keys` where keys = `{ required: string[], optional: string[] }`
+/**
+ * @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,40 @@
+/**
+ * @file src/utils/utilityTypes.ts
+ */
+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`
+ */
+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][];
+/**
+ * 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
+ * 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.0",
+    "version": "2.2.2",
     "description": "TypeScript utility modules",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",