@carecard/validate 3.1.24 → 3.1.25

package/lib/validateWhitelistProperties.js

@@ -16,6 +16,8 @@ const MAX_NESTING_DEPTH = 5;
  * adversarial inputs.
  */
 const MAX_KEYS_PER_CALL = 5000;
+const DEFAULT_FLATTEN_KEY_STYLE = 'path';
+const VALID_FLATTEN_KEY_STYLES = new Set(['path', 'leaf']);
 
 /**
  * Returns true if the segment contains a mix of snake_case (underscore) and
@@ -161,6 +163,35 @@ function flattenObject(obj, prefix = '', out = {}) {
     return out;
 }
 
+/**
+ * Recursively flattens a nested plain object using only each leaf property
+ * name as the output key.
+ *
+ * Example: `{ a: { b: { c: 1, d: 2 } } }` => `{ c: 1, d: 2 }`.
+ * If duplicate leaf keys exist at different nesting levels, the higher-level
+ * leaf wins. If duplicate leaf keys exist at the same depth, the first
+ * traversal wins.
+ *
+ * @param {Object} obj
+ * @param {Object} [out]
+ * @param {Object} [depthByKey]
+ * @param {number} [depth]
+ * @returns {Object}
+ */
+function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+            flattenObjectByLeafKey(value, out, depthByKey, depth + 1);
+        } else {
+            if (!Object.prototype.hasOwnProperty.call(out, key) || depth < depthByKey[key]) {
+                out[key] = value;
+                depthByKey[key] = depth;
+            }
+        }
+    }
+    return out;
+}
+
 /**
  * Validates and transforms whitelisted properties from an input object.
  *
@@ -181,8 +212,11 @@ function flattenObject(obj, prefix = '', out = {}) {
  * element passes validation, and the returned value is an array of the
  * validated elements (in the same order).
  *  5. Optionally converts all keys (including nested) to snake_case.
- *  6. Optionally flattens the result so every leaf is a top-level key,
- *     joined by `.` (`flattenOutput`). Applied after snake_case conversion.
+ *  6. Optionally flattens the result (`flattenOutput`). Flattened keys use
+ *     full dot paths by default (`flattenKeyStyle: 'path'`) or direct leaf
+ *     names when requested (`flattenKeyStyle: 'leaf'`). For duplicate leaf
+ *     keys in leaf mode, the shallower value wins; ties keep the first value
+ *     encountered. Applied after snake_case conversion.
  *
  * @param {Object} inputObject - The input object (e.g., req.body / req.params).
  * @param {Array<string>} [requiredProperties=[]] - Leaf paths that MUST be present and valid.
@@ -190,17 +224,26 @@ function flattenObject(obj, prefix = '', out = {}) {
  * @param {Array<string>} [options.optionalProperties=[]] - Leaf paths allowed but not required.
  * @param {boolean} [options.convertToSnakeCase=false] - Whether to convert keys to snake_case.
  * @param {boolean} [options.flattenOutput=false] - Whether to flatten the result so that
- *   every leaf is a top-level key (joined by `.`), with no nested objects in the output.
+ *   every leaf is a top-level key, with no nested objects in the output.
+ * @param {'path'|'leaf'} [options.flattenKeyStyle='path'] - Flattened key naming strategy
+ *   when `flattenOutput` is true. `path` uses dot-joined paths; `leaf` uses leaf names.
  * @returns {Promise<Object>} Resolves with the validated (and possibly transformed) object.
  */
 function validateWhitelistProperties(
     inputObject,
     requiredProperties = [],
-    options = { optionalProperties: [], convertToSnakeCase: false, flattenOutput: false },
+    options = { optionalProperties: [], convertToSnakeCase: false, flattenOutput: false, flattenKeyStyle: DEFAULT_FLATTEN_KEY_STYLE },
 ) {
     const optionalProperties = (options && options.optionalProperties) || [];
     const convertToSnakeCase = !!(options && options.convertToSnakeCase);
     const flattenOutput = !!(options && options.flattenOutput);
+    const flattenKeyStyle = options && options.flattenKeyStyle !== undefined ? options.flattenKeyStyle : DEFAULT_FLATTEN_KEY_STYLE;
+
+    if (!VALID_FLATTEN_KEY_STYLES.has(flattenKeyStyle)) {
+        throwBadInputError({
+            userMessage: `Invalid flattenKeyStyle: ${String(flattenKeyStyle)}. Expected "path" or "leaf"`,
+        });
+    }
 
     // Cap the total number of paths to validate per call.
     const totalKeys = (requiredProperties ? requiredProperties.length : 0) + optionalProperties.length;
@@ -271,9 +314,9 @@ function validateWhitelistProperties(
         validatedObject = keysToSnakeCase(validatedObject);
     }
 
-    // 6. Optional flattening: produce a flat object with dot-joined keys.
+    // 6. Optional flattening.
     if (flattenOutput) {
-        validatedObject = flattenObject(validatedObject);
+        validatedObject = flattenKeyStyle === 'leaf' ? flattenObjectByLeafKey(validatedObject) : flattenObject(validatedObject);
     }
 
     return Promise.resolve(validatedObject);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@carecard/validate",
-    "version": "3.1.24",
+    "version": "3.1.25",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
@@ -27,18 +27,18 @@
     "license": "ISC",
     "devDependencies": {
         "@types/mocha": "10.0.10",
-        "@types/node": "25.6.2",
+        "@types/node": "25.9.1",
         "eslint": "9.39.4",
         "husky": "9.1.7",
-        "lint-staged": "17.0.3",
-        "mocha": "11.7.5",
+        "lint-staged": "17.0.5",
+        "mocha": "11.7.6",
         "nyc": "18.0.0",
         "prettier": "3.8.3",
         "ts-node": "10.9.2",
-        "typescript": "5.9.3"
+        "typescript": "6.0.3"
     },
     "dependencies": {
-        "@carecard/common-util": "^3.1.13"
+        "@carecard/common-util": "3.1.15"
     },
     "nyc": {
         "all": true,

package/readme.md

@@ -106,6 +106,7 @@ where the package supports both.
 | `isString6To16CharacterLong` and `isPasswordString`       | `strong_password`, `strongPassword`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `isEmailString`                                           | `email`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `isPhoneNumber`                                           | `phone_number`, `phoneNumber`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `isCountryCodeString`                                     | `country_code`, `countryCode`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `isUrlSafeString`                                         | `token`, `email_confirm_token`, `emailConfirmToken`, `verification_token`, `verificationToken`                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `isValidUuidString`                                       | `uuid`, `item_id`, `itemId`, `user_id`, `userId`, `address_id`, `addressId`, `image_id`, `imageId`, `order_id`, `orderId`, `category_id`, `categoryId`, `parent_id`, `parentId`, `college_id`, `collegeId`, `campus_id`, `campusId`, `program_id`, `programId`, `id`, `institution_id`, `institutionId`, `role_assignment_id`, `roleAssignmentId`, `user_role_id`, `userRoleId`, `phone_number_id`, `phoneNumberId`, `entity_id`, `entityId`, `changed_by`, `changedBy`, `request_id`, `requestId`                                          |
 | `isValidIntegerString`                                    | `offset_number`, `offsetNumber`, `number_of_orders`, `numberOfOrders`, `price`, `from`, `number`, `limit`, `offset`                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -363,3 +364,16 @@ npm run format:check
 
 CI runs on Node.js 25 and executes `npm run test:All`. Publishing to npm happens
 from `main` through the `Publish to npm` GitHub workflow.
+
+## Auth Boundary
+
+Validation protects request shape, not authorization. `ms-auth` owns its
+auth-table RLS contract: normal users are self-row only, JWT `roles: ["ad"]`
+is the auth super-admin signal, and public auth flows use narrow system
+contexts. Do not use validators as a replacement for service RLS or database
+context checks.
+
+Docs that mention `ms-auth` controller internals should use concise action
+names such as `loginUser`, `registerUser`, `getUserDetail`, and `renewJwt`.
+Access level is conveyed by route middleware and endpoint placement, not by
+`public`/`protected`/`admin`/`Handler` suffixes.