@dwtechs/antity 0.9.2 → 0.11.0

package/README.md

@@ -120,6 +120,8 @@ const entity = new Entity("consumers", [
 
 // add a consumer. Used when loggin in from user service
 router.post("/", entity.normalize, entity.validate, ...);
+// or use check method to both normalize and validate at once
+router.put("/", entity.check, ...);
 
 ```
 
@@ -143,6 +145,7 @@ type Type =
   "array" |
   "jwt" |
   "symbol" |
+  "password" |
   "email" |
   "regex" |
   "json" |
@@ -162,8 +165,8 @@ type Method = "GET" | "PATCH" | "PUT" | "POST" | "DELETE";
 class Property {
   key: string;
   type: Type;
-  min: number | Date;
-  max: number | Date;
+  min: number | Date | null;
+  max: number | Date | null;
   required: boolean;
   safe: boolean;
   typeCheck: boolean;
@@ -184,34 +187,143 @@ class Entity {
   set name(name: string);
   
   /**
-   * Retrieves a property from the `properties` array that matches the specified key.
+   * Returns a single property object matching the given key.
    *
-   * @param {string} key - The key of the property to retrieve.
-   * @returns {Property | undefined} - The property object if found, otherwise `undefined`.
+   * - Searches the entity's properties for a property with the specified key
+   * - Useful for dynamic validation, normalization, or documentation
+   *
+   * @param {string} key - The property key to look up
+   * @returns {Property | undefined} The Property object if found, otherwise undefined
+   *
+   * **Input Properties Required:**
+   * - `key` (string) - Property key to look up
+   *
+   * **Output Properties:**
+   * - Property object matching the key, or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * const prop = entity.getProp('firstName');
+   * // prop contains the Property object for 'firstName' or undefined
+   * ```
    */
   getProp(key: string): Property | undefined;
 
   /**
-   * Retrieves a list of properties associated with a specific method.
+   * Returns all properties configured for a given REST method.
+   *
+   * - Filters the entity's properties by the specified method (e.g., 'POST', 'GET')
+   * - Useful for dynamic validation, normalization, or documentation
    *
-   * @param {Method} method - The method to filter properties by.
-   * @returns {Property[]} An array of properties that are associated with the specified method.
+   * @param {Method} method - The REST method to filter properties by (e.g., 'POST', 'GET')
+   * @returns {Property[]} Array of Property objects associated with the method
+   *
+   * **Input Properties Required:**
+   * - `method` (string) - REST method to filter by
+   *
+   * **Output Properties:**
+   * - Array of Property objects matching the method
+   *
+   * @example
+   * ```typescript
+   * const postProps = entity.getPropsByMethod('POST');
+   * // postProps contains all properties relevant for POST requests
+   * ```
    */
   getPropsByMethod(method: Method): Property[];
   
   /**
-   * Normalizes an array of records by applying sanitization and normalization
-   * rules defined in the `properties` of the class.
+   * Normalizes each row in req.body.rows according to property config and HTTP method.
+   *
+   * - Applies sanitization if `sanitize: true` and method matches
+   * - Applies normalization if `normalize: true` and method matches
+   * - Mutates req.body.rows with sanitized/normalized values
+   * - Calls next(error) on failure, next() on success
+   *
+   * @param {Request} req - Express request object containing rows
+   * @param {Response} _res - Express response object (not used)
+   * @param {NextFunction} next - Express next function
+   *
+   * @returns {void}
+   *
+   * **Input Properties Required:**
+   * - `req.body.rows` (array) - Array of objects to normalize
+   * - Each property config can specify sanitize, normalize, etc.
+   *
+   * **Output Properties:**
+   * - Mutates `req.body.rows` with sanitized/normalized values
+   * - Calls next(error) if any row fails normalization, next() if all pass
+   *
+   * @example
+   * ```typescript
+   * router.post('/entity', entity.normalize, (req, res) => {
+   *   // req.body.rows are now sanitized and normalized
+   *   res.json({ success: true });
+   * });
+   * ```
    */
-  normalize(req: Request, _res: Response, next: NextFunction): void;
+  normalize: (req: Request, _res: Response, next: NextFunction) => void;
   
   /**
-   * Validates a set of rows against the defined properties and operation/method.
+   * Validates each row in req.body.rows according to property config and HTTP method.
+   *
+   * - Checks required properties and validates values
+   * - Calls next(error) on failure, next() on success
+   *
+   * @param {Request} req - Express request object containing rows
+   * @param {Response} _res - Express response object (not used)
+   * @param {NextFunction} next - Express next function
+   *
+   * @returns {void}
+   *
+   * **Input Properties Required:**
+   * - `req.body.rows` (array) - Array of objects to validate
+   * - Each property config can specify validate, required, etc.
+   *
+   * **Output Properties:**
+   * - Calls next(error) if any row fails validation, next() if all pass
+   *
+   * @example
+   * ```typescript
+   * router.post('/entity', entity.validate, (req, res) => {
+   *   // req.body.rows are now validated
+   *   res.json({ success: true });
+   * });
+   * ```
+   */
+  validate: (req: Request, _res: Response, next: NextFunction) => void;
+
+  /**
+   * Checks, sanitizes, normalizes, and validates each row in req.body.rows according to property config and HTTP method.
+   *
+   * - Applies sanitization if `sanitize: true` and method matches
+   * - Applies normalization if `normalize: true` and method matches
+   * - Checks required properties and validates values
+   * - Calls next(error) on failure, next() on success
+   *
+   * @param {Request} req - Express request object containing rows
+   * @param {Response} _res - Express response object (not used)
+   * @param {NextFunction} next - Express next function
    *
-   * If a property is required and missing, or if it fails the control checks, the function returns an error message.
-   * Otherwise, it returns `null` indicating successful validation.
+   * @returns {void}
+   *
+   * **Input Properties Required:**
+   * - `req.body.rows` (array) - Array of objects to check
+   * - Each property config can specify sanitize, normalize, validate, required, etc.
+   *
+   * **Output Properties:**
+   * - Mutates `req.body.rows` with sanitized/normalized values
+   * - Calls next(error) if any row fails checks, next() if all pass
+   *
+   * @example
+   * ```typescript
+   * router.post('/entity', entity.check, (req, res) => {
+   *   // req.body.rows are now sanitized, normalized, and validated
+   *   res.json({ success: true });
+   * });
+   * ```
    */
-  validate(req: Request, _res: Response, next: NextFunction): void;
+  check: (req: Request, _res: Response, next: NextFunction) => void;
 }
 
 ```
@@ -219,6 +331,35 @@ normalize() and validate() methods are made to be used as Express.js middlewares
 Each method will look for data to work on in the **req.body.rows** parameter.
 
 
+### Password validation
+
+Password validation will have the following options by default : 
+
+```javascript
+const PWD_MIN_LENGTH = 9;
+const PWD_MAX_LENGTH = 20;
+const PWD_NUMBERS = true; // password must contain a number
+const PWD_UPPERCASE = true; // password must contain an uppercase letter
+const PWD_LOWERCASE = true; // password must contain a lowercase letter
+const PWD_SYMBOLS = true; //  password must contain at least one of the following symbol character : !@#%*_-+=:?><./()
+```
+
+#### Environment variables
+
+You can update password default validator by setting the following environment variables :
+
+```javascript
+  PWD_MIN_LENGTH_POLICY,
+  PWD_MAX_LENGTH_POLICY,
+  PWD_NUMBERS_POLICY,
+  PWD_UPPERCASE_POLICY,
+  PWD_LOWERCASE_POLICY,
+  PWD_SYMBOLS_POLICY
+```
+
+Properties **min** and **max** of the password properties will override default and environement variable if set.
+
+
 ### Available options for a property
 
 Any of these can be passed into the options object for each function.

package/dist/antity.d.ts

@@ -42,6 +42,7 @@ type Type =
   "array" |
   "jwt" |
   "symbol" |
+  "password" |
   "email" |
   "regex" |
   "json" |
@@ -69,13 +70,14 @@ declare class Entity {
   getPropsByMethod(method: Method): Property[];
   normalize: (req: Request, _res: Response, next: NextFunction) => void;
   validate: (req: Request, _res: Response, next: NextFunction) => void;
+  check: (req: Request, _res: Response, next: NextFunction) => void;
 }
 
 declare class Property {
   key: string;
   type: Type;
-  min: number | Date;
-  max: number | Date;
+  min: number | Date | null;
+  max: number | Date | null;
   required: boolean;
   safe: boolean;
   typeCheck: boolean;
@@ -89,8 +91,8 @@ declare class Property {
   constructor(
     key: string,
     type: Type,
-    min: number | Date,
-    max: number | Date,
+    min: number | Date | null,
+    max: number | Date | null,
     required: boolean,
     safe: boolean,
     typeCheck: boolean,

package/dist/antity.js

@@ -24,11 +24,18 @@ SOFTWARE.
 https://github.com/DWTechs/Antity.js
 */
 
-import { isBoolean, isStringOfLength, isValidNumber, isValidInteger, isValidFloat, isEven, isOdd, isPositive, isNegative, isPowerOfTwo, isAscii, isArrayOfLength, isEmail, isRegex, isJson, isJWT, isSymbol, isIpAddress, isSlug, isHexadecimal, isValidDate, isValidTimestamp, isFunction, isHtmlElement, isHtmlEventAttribute, isNode, isObject, isString, isProperty, isArray, isIn, isDate, isNumber, isInteger, isNil } from '@dwtechs/checkard';
+import { isBoolean, isStringOfLength, isValidNumber, isValidInteger, isValidFloat, isEven, isOdd, isPositive, isNegative, isPowerOfTwo, isAscii, isArrayOfLength, isValidPassword, isEmail, isRegex, isJson, isJWT, isSymbol, isIpAddress, isSlug, isHexadecimal, isValidDate, isValidTimestamp, isFunction, isHtmlElement, isHtmlEventAttribute, isNode, isObject, isString, isProperty, isArray, isIn, isDate, isNumber, isInteger, isNil } from '@dwtechs/checkard';
 import { log } from '@dwtechs/winstan';
 
 const Methods = ["GET", "PATCH", "PUT", "POST", "DELETE"];
 
+const { PWD_MIN_LENGTH_POLICY, PWD_MAX_LENGTH_POLICY, PWD_NUMBERS_POLICY, PWD_UPPERCASE_POLICY, PWD_LOWERCASE_POLICY, PWD_SYMBOLS_POLICY } = process.env;
+const PWD_MIN_LENGTH = PWD_MIN_LENGTH_POLICY ? +PWD_MIN_LENGTH_POLICY : 9;
+const PWD_MAX_LENGTH = PWD_MAX_LENGTH_POLICY ? +PWD_MAX_LENGTH_POLICY : 20;
+const PWD_NUMBERS = PWD_NUMBERS_POLICY ? true : false;
+const PWD_UPPERCASE = PWD_UPPERCASE_POLICY ? true : false;
+const PWD_LOWERCASE = PWD_LOWERCASE_POLICY ? true : false;
+const PWD_SYMBOLS = PWD_SYMBOLS_POLICY ? true : false;
 const Types = {
     boolean: {
         validate: (v, _min, _max, _typeCheck) => isBoolean(v)
@@ -66,6 +73,19 @@ const Types = {
     array: {
         validate: (v, min, max, _typeCheck) => isArrayOfLength(v, min || undefined, max || undefined)
     },
+    password: {
+        validate: (v, min, max, _typeCheck) => {
+            const o = {
+                minLength: min || PWD_MIN_LENGTH,
+                maxLength: max || PWD_MAX_LENGTH,
+                lowerCase: PWD_LOWERCASE,
+                upperCase: PWD_UPPERCASE,
+                number: PWD_NUMBERS,
+                specialCharacter: PWD_SYMBOLS,
+            };
+            return isValidPassword(v, o);
+        }
+    },
     email: {
         validate: (v, _min, _max, _typeCheck) => isEmail(v)
     },
@@ -185,12 +205,12 @@ function control(v, key, type, min, max, typeCheck, cb) {
         c += ` and >= ${min}`;
     if (!isNil(max))
         c += ` and <= ${max}`;
-    return val ? null : { status: 400, msg: `Invalid ${key}, must be of type ${type}${c}` };
+    return val ? null : { statusCode: 400, message: `Invalid ${key}, must be of type ${type}${c}` };
 }
 
 function require(v, key, type) {
     log.debug(`require ${key}: ${type} = ${v}`);
-    return isNil(v) ? { status: 400, msg: `Missing ${key} of type ${type}` } : null;
+    return isNil(v) ? { statusCode: 400, message: `Missing ${key} of type ${type}` } : null;
 }
 
 class Entity {
@@ -199,7 +219,7 @@ class Entity {
             var _a;
             const rows = (_a = req.body) === null || _a === void 0 ? void 0 : _a.rows;
             if (!isArray(rows, "!0"))
-                return next({ status: 400, msg: "Normalize: no rows found in request body" });
+                return next({ statusCode: 400, message: "Normalize: no rows found in request body" });
             for (const r of rows) {
                 for (const { key, type, sanitize: sanitize$1, normalize, sanitizer, normalizer, } of this._properties) {
                     let v = r[key];
@@ -223,11 +243,11 @@ class Entity {
             const rows = (_a = req.body) === null || _a === void 0 ? void 0 : _a.rows;
             const method = req.method;
             if (!isArray(rows, "!0"))
-                return next({ status: 400, msg: "Sanitize: no rows found in request body" });
+                return next({ statusCode: 400, message: "Validate: no rows found in request body" });
             if (!isIn(Methods, method))
                 return next({
-                    status: 400,
-                    msg: `Invalid REST method. Received: ${method}. Must be one of: ${Methods.toString()}`
+                    statusCode: 400,
+                    message: `Invalid REST method. Received: ${method}. Must be one of: ${Methods.toString()}`
                 });
             for (const r of rows) {
                 for (const { key, type, min, max, required, typeCheck, methods, validate, validator } of this._properties) {
@@ -248,6 +268,47 @@ class Entity {
             }
             next();
         };
+        this.check = (req, _res, next) => {
+            var _a;
+            const rows = (_a = req.body) === null || _a === void 0 ? void 0 : _a.rows;
+            const method = req.method;
+            if (!isArray(rows, "!0"))
+                return next({ statusCode: 400, message: "Check: no rows found in request body" });
+            if (!isIn(Methods, method))
+                return next({
+                    statusCode: 400,
+                    message: `Invalid REST method. Received: ${method}. Must be one of: ${Methods.toString()}`
+                });
+            for (const r of rows) {
+                for (const { key, type, min, max, required, typeCheck, methods, validate, sanitize: sanitize$1, normalize, sanitizer, normalizer, validator } of this._properties) {
+                    let v = r[key];
+                    if (isIn(methods, method)) {
+                        if (v) {
+                            if (sanitize$1) {
+                                log.debug(`sanitize ${key}: ${type} = ${v}`);
+                                v = sanitize(v, sanitizer);
+                            }
+                            if (normalize && isFunction(normalizer)) {
+                                log.debug(`normalize ${key}: ${type} = ${v}`);
+                                v = normalizer(v);
+                            }
+                            r[key] = v;
+                            if (validate) {
+                                const ct = control(v, key, type, min, max, typeCheck, validator);
+                                if (ct)
+                                    return next(ct);
+                            }
+                        }
+                        if (required) {
+                            const rq = require(v, key, type);
+                            if (rq)
+                                return next(rq);
+                        }
+                    }
+                }
+            }
+            next();
+        };
         this._name = name;
         this._properties = [];
         this._unsafeProps = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dwtechs/antity",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Open source library for easy entity management",
   "keywords": [
     "entities"