binhend 2.3.4 → 2.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "binhend",
-    "version": "2.3.4",
+    "version": "2.3.6",
     "description": "",
     "main": "index.js",
     "author": "Nguyen Duc Binh",

package/packages/validation/src/typeValidation.js

@@ -110,17 +110,131 @@ function Array(input, options = {}) {
  * Validate an input being an object (non-array)
  *
  * @template {Record<string, any>} [T={}]
- * @template {Record<string, any>} [O={}]
  * 
  * @param {T=} input - Input value needs to be validated.
- * @param {Options & { optional?: O }} options - Options for validation with extra option { optional } for listing optional properties.
- * @returns {T & O & Record<string, any>} - The validated input
+ * @param {Options} options - Options for validation.
+ * @returns {T & Record<string, any>} - The validated input
  * @throws {HttpError} - If validation fails
  */
 function Object(input, options = {}) {
     return Validator(input, types.isObject, { ...options, type: 'object' });
 }
 
+/**
+ * Return an object fragment from an object via a specific key
+ * only if the value is defined (accept null), and pass validation.
+ *
+ * @template {string} K
+ * @template V
+ * @param {K} key - A property name
+ * @param {*} object - Any target that may have properties (objects or primitives)
+ * @param {((value: any, options: Options) => V)} [validator] - An optional validation function
+ * @param {Options=} options - Options for validation.
+ * @returns {{ [P in K]?: V }} - An object fragment with a single key/value at most
+ * @throws {HttpError} - If validation fails
+ */
+function PropIf(key, object, validator, options) {
+    var value = object != null ? object[key] : undefined;
+
+    if (validator instanceof Function) {
+        value = validator(value, { ...options, name: key });
+    }
+
+    if (object == null || !Object.prototype.hasOwnProperty.call(object, key)) {
+        return /** @type {{ [P in K]: V }} */ ({});
+    }
+
+    return /** @type {{ [P in K]: V }} */ ({ [key]: value });
+}
+
+/**
+ * Return an object fragment from an object via a specific key
+ * even if the value is undefined, but must pass validation.
+ *
+ * @template {string} K
+ * @template V
+ * @param {K} key - A property name
+ * @param {*} object - Any target that may have properties (objects or primitives)
+ * @param {((value: any, options: Options) => V)} [validator] - An optional validation function
+ * @param {Options=} options - Options for validation.
+ * @returns {{ [P in K]: V }} - An object fragment with a single key/value at most
+ * @throws {HttpError} - If validation fails
+ */
+function Prop(key, object, validator, options) {
+    return /** @type {{ [P in K]: V }} */ ({ [key]: PropIf(key, object, validator, options)[key] });
+}
+
+/**
+ * Return an object fragment from a value with a specific key
+ * only if the value is defined (accept null), and pass validation.
+ *
+ * @template {string} K
+ * @template V
+ * @param {K} key - A property name
+ * @param {*} value - A value
+ * @param {((value: any, options: Options) => V)} [validator] - An optional validation function
+ * @param {Options=} options - Options for validation.
+ * @returns {{ [P in K]?: V }} - An object fragment with a single key/value at most
+ * @throws {HttpError} - If validation fails
+ */
+function AssignIf(key, value, validator, options) {
+    return PropIf(key, { [key]: value }, validator, options);
+}
+
+/**
+ * Return an object fragment from a value with a specific key
+ * even if the value is undefined, but must pass validation.
+ *
+ * @template {string} K
+ * @template V
+ * @param {K} key - A property name
+ * @param {*} value - A value
+ * @param {((value: any, options: Options) => V)} [validator] - An optional validation function
+ * @param {Options=} options - Options for validation.
+ * @returns {{ [P in K]: V }} - An object fragment with a single key/value at most
+ * @throws {HttpError} - If validation fails
+ */
+function Assign(key, value, validator, options) {
+    return /** @type {{ [P in K]: V }} */ ({ [key]: AssignIf(key, value, validator, options)[key] });
+}
+
+/**
+ * Return an object fragment with a specific key,
+ * only if the value is defined. (accept null, but not undefined)
+ * 
+ * @template {string} K
+ * @template V
+ * @param {K} key - A property name
+ * @param {V | undefined} value - A value
+ * @returns {{ [P in K]?: V }} - An object fragment with a single key/value at most
+ */
+function Value(key, value) {
+    if (value === undefined) {
+        return /** @type {{ [P in K]?: V }} */ ({});
+    }
+
+    return /** @type {{ [P in K]?: V }} */ ({ [key]: value });
+}
+
+/**
+ * Return a new plain object containing keys with defined values only. (accept null)
+ *
+ * @template {Record<string, any>} T
+ * @param {T=} object
+ * @returns {{ [K in keyof T]?: T[K] }}
+ */
+function Optional(object) {
+    var key, output = {};
+
+    for (key in object) {
+        if (object[key] !== undefined) {
+            output[key] = object[key];
+        }
+    }
+
+    return output;
+}
+
 /**
  * Return an object fragment with a specific key
  * only if the key exists AND validation is passed.
@@ -173,7 +287,7 @@ function AsyncFunction(input, options = {}) {
     return Validator(input, (input) => input instanceof AsyncFunctionConstructor, { ...options, type: 'async function' });
 }
 
-const AsyncFunctionConstructor = global.Object.getPrototypeOf(async function() {}).constructor;
+const AsyncFunctionConstructor = global.Object.getPrototypeOf(async function () { }).constructor;
 
 /**
  * Validate an input being a date
@@ -200,30 +314,49 @@ function DateLike(input, options = {}) {
 }
 
 /**
- * Validate an input being one of the specified enum values
+ * Validate an input being one of allowed values
  *
+ * @template {string | number | boolean | symbol | bigint} T
  * @param {*} input - Input value needs to be validated.
- * @param {Array|Object} enumValues - Array of allowed values or object whose keys are allowed values
- * @param {Options} options - Additional options for validation.
- * @returns {*} - The validated input
- * @throws {HttpError} - If validation fails
+ * @param {readonly T[]} enumValues - Array of allowed values.
+ * @param {Options} options - Options for validation.
+ * @returns {T} - The validated input.
+ * @throws {HttpError} - If validation fails.
  */
 function Enum(input, enumValues, options = {}) {
-    var validArray = types.isArray(enumValues),
-        validObject = types.isObject(enumValues);
-
-    if (!(validArray || validObject)) {
-        throwError('Enum validator requires an array or object of allowed values');
+    if (!types.isArray(enumValues)) {
+        throwError('Enum validator requires an array of allowed values');
     }
 
-    var method = validArray ? 'includes' : 'hasOwnProperty';
-
     return Validator(
-        input, (input) => enumValues[method](input),
-        { ...options, message: options.message || `${input} is not defined in enum` }
+        input, (input) => enumValues.includes(input),
+        { ...options, message: options.message || `Value {${input}} is not defined in enum` }
     );
 }
 
+/**
+ * Return all keys of an object.
+ * Returns an array of names of the enumerable properties and methods of an object.
+ *
+ * @template {{ [key: PropertyKey]: any }} T
+ * @param {T} object - An object with keys and values
+ * @returns {(keyof T)[]} - List of all keys
+ */
+function Keys(object) {
+    return global.Object.keys(object);
+}
+
+/**
+ * Returns an array of values owned by the enumerable properties of an object.
+ * 
+ * @template {{ [key: PropertyKey]: any }} T
+ * @param {T} object
+ * @returns {T[keyof T][]}
+ */
+function Values(object) {
+    return global.Object.values(object);
+}
+
 /**
  * Validate an input being defined (not undefined)
  *
@@ -304,12 +437,14 @@ module.exports = {
     Boolean,
     Array,
     Object,
-    Prop,
+    PropIf, Prop,
+    AssignIf, Assign,
+    Value, Optional,
     Function,
     AsyncFunction,
     Date,
     DateLike,
-    Enum,
+    Enum, Keys, Values,
     Defined,
     NotNull,
     NotNullish,