typeshi 2.1.8 → 2.2.1

package/dist/utils/argumentValidation.js

@@ -52,16 +52,8 @@ exports.enumArgument = enumArgument;
 exports.existingPathArgument = existingPathArgument;
 /**
  * @file src/utils/argumentValidation.ts
- * @note these functions can be useful for sanity checks
- * @description moved the content of parameter type checks at the start of
- * functions to here. use these when you want your function to throw a fit when
+ * @description functions useful for sanity checks. use if want function to throw a fit when
  * it receives bad input.
- * @example
- * import * as validate from "@typeshi/argumentValidation";
- * @TODO add boolean value configurable by a setter function that specifies if errors should be thrown or only logged
- * - maybe add a configurable value that the validation functions should return if the validation test fails
- * - change the validation functions such that they return the validated value, if possible?
- * - or maybe have them return boolean type predicates ?
  */
 const typeValidation_1 = require("./typeValidation");
 const setupLog_1 = require("../config/setupLog");

package/dist/utils/object.d.ts

@@ -32,10 +32,6 @@ export type TransformOptions<T extends object, K extends keyof T, S extends obje
  * @returns **`data`** `T` - new object with keys/values from generated from `schema` & `passThroughKeys`
  */
 export declare function sanitizeAndMap<T extends object, S extends object = any>(obj: S, schema: TransformationSchema<T, S>, passThroughKeys?: (keyof T & keyof S)[]): T;
-/**
- * @returns `Object.prototype.hasOwnProperty.call(obj, key) && obj[key] !== undefined;`
- */
-export declare function hasDefinedEntry<T extends object>(obj: any, key: keyof T | keyof any): boolean;
 /**
  * @returns `boolean`
  * - `true` if all keys in obj are also in validKeys
@@ -46,6 +42,23 @@ export declare function hasValidKeysOnly<T extends object>(obj: object, validKey
  * @returns a new object containing only the specified keys.
  */
 export declare function picked<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * @param arr `T[]`
+ * @param maxLength `number` an integer greater than or equal to `0`
+ * - the original array is returned if `maxLength < 0`
+ * - converts `float` to `int` with `Math.floor()`;
+ * @note **original array is returned if `arr.length <= Math.floor(maxLength)`**
+ * @param principle `'LIFO' | 'FIFO' (optional)` `default = 'LIFO'`
+ * `(if arr.length > maxLength)` indicate from which end of array to remove elements
+ * - `'LIFO'` - remove elements from end (`'Last-In-First-Out'`)
+ * - `'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 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`
+ */
+export declare function enforceMaxLength<T = unknown>(arr: T[], maxLength: number, principle?: 'LIFO' | 'FIFO', inPlace?: boolean): T[];
 export declare class Restrict {
     /**
      * `hasValidKeysOnly`
@@ -56,4 +69,34 @@ export declare class Restrict {
      * @returns a new object containing only the specified keys.
      */
     static toPicked: typeof picked;
+    /**
+     * @param arr `T[]`
+     * @param maxLength `number` an integer greater than or equal to `0`
+     * - the original array is returned if `maxLength < 0`
+     * - converts `float` to `int` with `Math.floor()`;
+     * @note **original array is returned if `arr.length <= Math.floor(maxLength)`**
+     * @param principle `'LIFO' | 'FIFO' (optional)` `default = 'LIFO'`
+     * `(if arr.length > maxLength)` indicate from which end of array to remove elements
+     * - `'LIFO'` - remove elements from end (`'Last-In-First-Out'`)
+     * - `'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`
+     * - `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`
+     */
+    static arrayLength: typeof enforceMaxLength;
 }
+/**
+ * @returns `Object.prototype.hasOwnProperty.call(obj, key) && obj[key] !== undefined;`
+ */
+export declare function hasDefinedEntry<T extends object>(obj: any, key: keyof T | keyof any): boolean;
+/**
+ * @returns **`containsKey`** `boolean = obj is { [K in keyof T]: T[K] }`
+ * - `true` if **`all`** `k` in `keys` return true for `Object.prototype.hasOwnProperty.call(obj, k)`
+ * - `false` otherwise
+ */
+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];
+};

package/dist/utils/object.js

@@ -6,9 +6,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Restrict = void 0;
 exports.sanitizeAndMap = sanitizeAndMap;
-exports.hasDefinedEntry = hasDefinedEntry;
 exports.hasValidKeysOnly = hasValidKeysOnly;
 exports.picked = picked;
+exports.enforceMaxLength = enforceMaxLength;
+exports.hasDefinedEntry = hasDefinedEntry;
+exports.containsKey = containsKey;
 const typeValidation_1 = require("./typeValidation");
 /**
  * @param obj `S` - source object (e.g., Request Body)
@@ -55,12 +57,6 @@ function sanitizeAndMap(obj, schema, passThroughKeys = []) {
     }
     return data;
 }
-/**
- * @returns `Object.prototype.hasOwnProperty.call(obj, key) && obj[key] !== undefined;`
- */
-function hasDefinedEntry(obj, key) {
-    return Object.prototype.hasOwnProperty.call(obj, key) && obj[key] !== undefined;
-}
 /**
  * @returns `boolean`
  * - `true` if all keys in obj are also in validKeys
@@ -80,6 +76,59 @@ function picked(obj, keys) {
     }
     return result;
 }
+// @TODO could try to generalize enforceMaxLength to handle objects operating on Object.keys()/Object.entries()
+// but I don't think hashed keys of dicts/objects retain consistent information on what order they were added to object...
+/**
+ * @param arr `T[]`
+ * @param maxLength `number` an integer greater than or equal to `0`
+ * - the original array is returned if `maxLength < 0`
+ * - converts `float` to `int` with `Math.floor()`;
+ * @note **original array is returned if `arr.length <= Math.floor(maxLength)`**
+ * @param principle `'LIFO' | 'FIFO' (optional)` `default = 'LIFO'`
+ * `(if arr.length > maxLength)` indicate from which end of array to remove elements
+ * - `'LIFO'` - remove elements from end (`'Last-In-First-Out'`)
+ * - `'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 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`
+ */
+function enforceMaxLength(arr, maxLength, principle = 'LIFO', inPlace = true) {
+    if (maxLength < 0)
+        return arr;
+    maxLength = Math.floor(maxLength);
+    if (maxLength === 0) {
+        if (inPlace) {
+            arr.length = 0;
+            return arr;
+        }
+        else {
+            return [];
+        }
+    }
+    const n = arr.length;
+    if (n <= maxLength)
+        return arr;
+    const excess = n - maxLength;
+    if (inPlace) {
+        if (principle === 'LIFO') {
+            arr.length = maxLength;
+        }
+        else { // 'FIFO'
+            arr.splice(0, excess);
+        }
+        return arr;
+    }
+    else {
+        if (principle === 'LIFO') {
+            return arr.slice(0, maxLength);
+        }
+        else { // 'FIFO'
+            return arr.slice(excess);
+        }
+    }
+}
 class Restrict {
 }
 exports.Restrict = Restrict;
@@ -92,3 +141,39 @@ Restrict.keys = hasValidKeysOnly;
  * @returns a new object containing only the specified keys.
  */
 Restrict.toPicked = picked;
+/**
+ * @param arr `T[]`
+ * @param maxLength `number` an integer greater than or equal to `0`
+ * - the original array is returned if `maxLength < 0`
+ * - converts `float` to `int` with `Math.floor()`;
+ * @note **original array is returned if `arr.length <= Math.floor(maxLength)`**
+ * @param principle `'LIFO' | 'FIFO' (optional)` `default = 'LIFO'`
+ * `(if arr.length > maxLength)` indicate from which end of array to remove elements
+ * - `'LIFO'` - remove elements from end (`'Last-In-First-Out'`)
+ * - `'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`
+ * - `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`
+ */
+Restrict.arrayLength = enforceMaxLength;
+/**
+ * @returns `Object.prototype.hasOwnProperty.call(obj, key) && obj[key] !== undefined;`
+ */
+function hasDefinedEntry(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key) && obj[key] !== undefined;
+}
+/**
+ * @returns **`containsKey`** `boolean = obj is { [K in keyof T]: T[K] }`
+ * - `true` if **`all`** `k` in `keys` return true for `Object.prototype.hasOwnProperty.call(obj, k)`
+ * - `false` otherwise
+ */
+function containsKey(obj, ...keys) {
+    for (let k of keys) {
+        if (!Object.prototype.hasOwnProperty.call(obj, k))
+            return false;
+    }
+    return true;
+}

package/dist/utils/typeValidation.d.ts

@@ -25,9 +25,9 @@ export declare function isEmptyArray<T>(value: any): value is Array<T> & {
  * @param requireNonEmpty `boolean` `default = true`
  * - `if` `true` then `value` must be array with at least 1 element
  * - `if` `false` then `value` can be empty array
- * @returns **`isIntegerArray`** `boolean` = `value is Array<number> & { length: number }`
+ * @returns **`isIntegerArray`** `boolean` = `value is number[] & { length: number }`
  */
-export declare function isIntegerArray(value: any, requireNonNegative?: boolean, requireNonEmpty?: boolean): value is Array<number> & {
+export declare function isIntegerArray(value: any, requireNonNegative?: boolean, requireNonEmpty?: boolean): value is number[] & {
     length: number;
 };
 /**
@@ -36,23 +36,23 @@ export declare function isIntegerArray(value: any, requireNonNegative?: boolean,
  * @param requireNonEmpty `boolean` `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 Array<string> & { length: number }`
+ * @returns **`isStringArray`** `boolean` = `value is string[] & { length: number }`
  */
 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 **`hasNonTrivialKeys`** `boolean`
+ * @returns **`hasNonTrivialEntries`** `boolean`
  * - **`true`** `if` the `obj` has non-empty keys,
  * - **`false`** `otherwise`
  */
-export declare function hasNonTrivialKeys(obj: any, requireAll?: boolean): obj is Record<string, any>;
+export declare function hasNonTrivialEntries<T extends object>(obj: T, requireAll?: boolean): obj is T;
 /**
- * @TODO add overload on param `keys` where keys = `{ required: string[], optional: string[] }`
  * @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
@@ -81,12 +81,12 @@ export declare function areEquivalentObjects(objA: Record<string, any>, objB: Re
  * @param requireNonNegative `boolean` `default = false`
  * @returns **`isNumeric`** `value is string | number`
  * - **`true`** `if` `value` is either a `number` or a `string` that can be casted to a `number`
- * while also meeting the boolean parameter requirements
+ * while also meeting the other params
  * - **`false`** `otherwise`
  */
-export declare function isNumeric(value: any, requireInteger?: boolean, requireNonNegative?: boolean): value is string | number;
+export declare function isNumeric<T extends string | number = string>(value: unknown, requireInteger?: boolean, requireNonNegative?: boolean): value is T;
 /**
- * @param value `any`
+ * @param value `unknown`
  * @param requireNonSpace `boolean (optional)` `default` = `false`
  * - `if true` then `value.trim()` must not result in empty string
  * - `if false` then allows for `value` to consist solely of whitespace characters
@@ -94,30 +94,30 @@ export declare function isNumeric(value: any, requireInteger?: boolean, requireN
  * - `true` `if` `value` is a non-empty string
  * - `false` `otherwise`.
  */
-export declare function isNonEmptyString(value: any, requireNonSpace?: boolean): value is string & {
+export declare function isNonEmptyString(value: unknown, requireNonSpace?: boolean): value is string & {
     length: number;
 };
-export declare function isPrimitiveValue(value: any): value is string | number | boolean | null | undefined;
+export declare function isPrimitiveValue(value: unknown): value is string | number | boolean | null | undefined;
 /**
- * @param value `any`
+ * @param value `unknown`
  * @param requireNonNegative `boolean`
  * - `if` `true` then require that `value` be an integer `>= 0`
  * - `if` `false` then the sign of the number doesn't matter
  * @returns **`isInteger`** `boolean`
  */
-export declare function isInteger(value: any, requireNonNegative?: boolean): value is number;
+export declare function isInteger(value: unknown, requireNonNegative?: boolean): value is number;
 /**
- * @param value `any`
+ * @param value `unknown`
  * @param requireNonEmpty `boolean` `default = true`
  * - `if` `true` then `value` must have at least 1 key
  * - `if` `false` then `value` is allowed to be an empty object
  * @param requireNonArray `boolean` `default = true`
  * - `if` `true` then `value` must not be an array
  * - `if` `false` then `value` is allowed to be an array
- * @returns **`isObject`** `boolean` `value is Record<string, any>`
+ * @returns **`isObject`** `boolean` `value is T`
  */
-export declare function isObject(value: any, requireNonEmpty?: boolean, requireNonArray?: boolean): value is Record<string, any>;
-export declare function isPositveInteger(value: any): value is number;
+export declare function isObject<T extends object = Record<string, 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;
 /**
  * - calls {@link isUndefinedOrNull}`(value)` which allows for value to be `undefined` or `null`
@@ -261,7 +261,12 @@ export type PrimitiveKeys<T, Required extends boolean = false> = {
 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;
+/**
+ * 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][];

package/dist/utils/typeValidation.js

@@ -8,7 +8,7 @@ exports.isNonEmptyArray = isNonEmptyArray;
 exports.isEmptyArray = isEmptyArray;
 exports.isIntegerArray = isIntegerArray;
 exports.isStringArray = isStringArray;
-exports.hasNonTrivialKeys = hasNonTrivialKeys;
+exports.hasNonTrivialEntries = hasNonTrivialEntries;
 exports.hasKeys = hasKeys;
 exports.areEquivalentObjects = areEquivalentObjects;
 exports.isNumeric = isNumeric;
@@ -48,7 +48,7 @@ function isEmptyArray(value) {
  * @param requireNonEmpty `boolean` `default = true`
  * - `if` `true` then `value` must be array with at least 1 element
  * - `if` `false` then `value` can be empty array
- * @returns **`isIntegerArray`** `boolean` = `value is Array<number> & { length: number }`
+ * @returns **`isIntegerArray`** `boolean` = `value is number[] & { length: number }`
  */
 function isIntegerArray(value, requireNonNegative = false, requireNonEmpty = true) {
     return (requireNonEmpty
@@ -61,23 +61,25 @@ function isIntegerArray(value, requireNonNegative = false, requireNonEmpty = tru
  * @param requireNonEmpty `boolean` `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 Array<string> & { length: number }`
+ * @returns **`isStringArray`** `boolean` = `value is string[] & { length: number }`
  */
 function isStringArray(value, requireNonEmpty = true) {
     return (requireNonEmpty
         ? 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 **`hasNonTrivialKeys`** `boolean`
+ * @returns **`hasNonTrivialEntries`** `boolean`
  * - **`true`** `if` the `obj` has non-empty keys,
  * - **`false`** `otherwise`
  */
-function hasNonTrivialKeys(obj, requireAll = false) {
+function hasNonTrivialEntries(obj, requireAll = false) {
     if (!isObject(obj)) {
         return false;
     }
@@ -85,8 +87,9 @@ function hasNonTrivialKeys(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[] }`
+// maybe deprecate this
 /**
- * @TODO add overload on param `keys` where keys = `{ required: string[], optional: string[] }`
  * @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
@@ -105,7 +108,7 @@ function hasKeys(obj, keys, requireAll = true, restrictKeys = false) {
         return false;
     }
     if (keys === null || keys === undefined) {
-        throw new Error('[hasKeys()] no keys provided: param `keys` must be defined');
+        return false;
     }
     if (!isNonEmptyArray(keys)) {
         keys = [keys]; // Convert string (assumed to be single key) to array of keys
@@ -168,7 +171,7 @@ function areEquivalentObjects(objA, objB) {
  * @param requireNonNegative `boolean` `default = false`
  * @returns **`isNumeric`** `value is string | number`
  * - **`true`** `if` `value` is either a `number` or a `string` that can be casted to a `number`
- * while also meeting the boolean parameter requirements
+ * while also meeting the other params
  * - **`false`** `otherwise`
  */
 function isNumeric(value, requireInteger = false, requireNonNegative = false) {
@@ -195,7 +198,7 @@ function isNumeric(value, requireInteger = false, requireNonNegative = false) {
     return true;
 }
 /**
- * @param value `any`
+ * @param value `unknown`
  * @param requireNonSpace `boolean (optional)` `default` = `false`
  * - `if true` then `value.trim()` must not result in empty string
  * - `if false` then allows for `value` to consist solely of whitespace characters
@@ -219,7 +222,7 @@ function isPrimitiveValue(value) {
     return false;
 }
 /**
- * @param value `any`
+ * @param value `unknown`
  * @param requireNonNegative `boolean`
  * - `if` `true` then require that `value` be an integer `>= 0`
  * - `if` `false` then the sign of the number doesn't matter
@@ -231,17 +234,17 @@ function isInteger(value, requireNonNegative = false) {
         && (requireNonNegative ? value >= 0 : true));
 }
 /**
- * @param value `any`
+ * @param value `unknown`
  * @param requireNonEmpty `boolean` `default = true`
  * - `if` `true` then `value` must have at least 1 key
  * - `if` `false` then `value` is allowed to be an empty object
  * @param requireNonArray `boolean` `default = true`
  * - `if` `true` then `value` must not be an array
  * - `if` `false` then `value` is allowed to be an array
- * @returns **`isObject`** `boolean` `value is Record<string, any>`
+ * @returns **`isObject`** `boolean` `value is T`
  */
 function isObject(value, requireNonEmpty = true, requireNonArray = true) {
-    return (value && typeof value === 'object'
+    return Boolean(value && typeof value === 'object'
         && (requireNonArray ? !Array.isArray(value) : true)
         && (requireNonEmpty ? Object.keys(value).length > 0 : true));
 }
@@ -255,6 +258,7 @@ const isType = (value, guard, ...args) => {
     return guard(value, ...args);
 };
 exports.isType = isType;
+//  * - rename to isNullable ?
 /**
  * - calls {@link isUndefinedOrNull}`(value)` which allows for value to be `undefined` or `null`
  * - use {@link isUndefinedOr} if you want `value is T | undefined`

package/package.json

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