@carecard/validate 3.1.20 → 3.1.21

package/index.d.ts

@@ -13,13 +13,18 @@ export interface ValidateWhitelistPropertiesOptions {
     convertToSnakeCase?: boolean;
     /**
      * When true, the returned object is flattened so that every validated leaf
-     * becomes a top-level key. Existing dot-path flattening is preserved, and
-     * multiple leaves from the same nested parent can flatten to direct leaf
-     * property names (e.g. `{ email: 'Jane' }`). If duplicate direct leaf keys
-     * exist at different nesting levels, the higher-level property wins. No
-     * nested objects remain in the output. Applied after snake_case conversion.
+     * becomes a top-level key. No nested objects remain in the output. Applied
+     * after snake_case conversion.
      */
     flattenOutput?: boolean;
+    /**
+     * Controls flattened key naming when `flattenOutput` is true.
+     * - `path` uses full dot-notation paths, e.g. `{ "user.email": "Jane" }`.
+     * - `leaf` uses only leaf names, e.g. `{ email: "Jane" }`.
+     *
+     * Defaults to `path`.
+     */
+    flattenKeyStyle?: 'path' | 'leaf';
 }
 
 /**

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
@@ -190,51 +192,6 @@ function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
     return out;
 }
 
-/**
- * Detects whether the flattened leaf-key output would contain duplicate keys
- * from different nesting depths.
- *
- * @param {Object} obj
- * @param {Object} [depthByKey]
- * @param {number} [depth]
- * @returns {boolean}
- */
-function hasDuplicateLeafKeyAtDifferentDepth(obj, depthByKey = {}, depth = 1) {
-    for (const [key, value] of Object.entries(obj)) {
-        if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
-            if (hasDuplicateLeafKeyAtDifferentDepth(value, depthByKey, depth + 1)) {
-                return true;
-            }
-        } else if (Object.prototype.hasOwnProperty.call(depthByKey, key)) {
-            if (depthByKey[key] !== depth) {
-                return true;
-            }
-        } else {
-            depthByKey[key] = depth;
-        }
-    }
-    return false;
-}
-
-/**
- * Uses leaf-key flattening only when multiple validated leaves came from the
- * same nested parent, or when duplicate leaf keys exist at different nesting
- * depths and require the higher-level key to win. This preserves the existing
- * dot-path flatten output for current callers while supporting the sibling-leaf
- * output shape.
- *
- * @param {Array<string[]>} validatedSegments
- * @param {Object} validatedObject
- * @returns {boolean}
- */
-function shouldFlattenByLeafKey(validatedSegments, validatedObject) {
-    if (hasDuplicateLeafKeyAtDifferentDepth(validatedObject)) return true;
-    if (validatedSegments.length < 2) return false;
-    const firstParent = validatedSegments[0].slice(0, -1).join('.');
-    if (!firstParent || validatedSegments[0].length <= 2) return false;
-    return validatedSegments.every(segments => segments.slice(0, -1).join('.') === firstParent);
-}
-
 /**
  * Validates and transforms whitelisted properties from an input object.
  *
@@ -255,11 +212,11 @@ function shouldFlattenByLeafKey(validatedSegments, validatedObject) {
  * 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 (`flattenOutput`). Existing dot-path
- *     flattening is preserved, while multiple leaves from the same nested
- *     parent, or duplicate leaf keys at different nesting depths, flatten to
- *     direct leaf keys. For duplicates at different depths, the higher-level
- *     property wins. 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.
@@ -268,16 +225,25 @@ function shouldFlattenByLeafKey(validatedSegments, validatedObject) {
  * @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, 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;
@@ -291,7 +257,6 @@ function validateWhitelistProperties(
     const optionalPaths = optionalProperties.map(p => ({ raw: p, segments: splitPath(p) }));
 
     let validatedObject = {};
-    const validatedSegments = [];
 
     // Helper: validate a single leaf value by feeding `{ [leafKey]: value }` to
     // `validateProperties` and checking whether the leaf key survived.
@@ -330,7 +295,6 @@ function validateWhitelistProperties(
             throwBadInputError({ userMessage: `Missing or invalid property: ${raw}` });
         }
         writeLeaf(validatedObject, segments, validatedValue);
-        validatedSegments.push(segments);
     });
 
     // 1 + 4. Optional paths: if provided, must be valid.
@@ -343,7 +307,6 @@ function validateWhitelistProperties(
             throwBadInputError({ userMessage: `Invalid property value: ${raw}` });
         }
         writeLeaf(validatedObject, segments, validatedValue);
-        validatedSegments.push(segments);
     });
 
     // 5. Optional case transformation (recursive, handles nested keys).
@@ -353,9 +316,7 @@ function validateWhitelistProperties(
 
     // 6. Optional flattening.
     if (flattenOutput) {
-        validatedObject = shouldFlattenByLeafKey(validatedSegments, validatedObject)
-            ? flattenObjectByLeafKey(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.20",
+    "version": "3.1.21",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/CareCard-ca/pkg-validate.git"

package/readme.md

@@ -139,13 +139,63 @@ const out = await validateWhitelistProperties(body, ['first_name', 'email'], {
 // }
 ```
 
+### Defaults
+
+When omitted, `requiredProperties` defaults to `[]` and `options` defaults to:
+
+```js
+{
+    optionalProperties: [],
+    convertToSnakeCase: false,
+    flattenOutput: false,
+    flattenKeyStyle: 'path',
+}
+```
+
+The default output preserves the nested shape described by whitelisted dot paths.
+`flattenKeyStyle` only changes output when `flattenOutput` is `true`.
+
+```js
+const input = {
+    user: {
+        first_name: 'Jane',
+        contact: { email: 'jane@example.com' },
+    },
+};
+
+await validateWhitelistProperties(input, ['user.first_name', 'user.contact.email']);
+// {
+//   user: {
+//     first_name: 'Jane',
+//     contact: { email: 'jane@example.com' }
+//   }
+// }
+```
+
 ### Options
 
-| Option               | Default | Behavior                                                                                                                                                                                                                                                                                       |
-| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `optionalProperties` | `[]`    | Additional property paths that may be present. If present, each value must be valid.                                                                                                                                                                                                           |
-| `convertToSnakeCase` | `false` | Converts returned keys, including nested keys, to snake_case using `@carecard/common-util`.                                                                                                                                                                                                    |
-| `flattenOutput`      | `false` | Flattens returned nested objects. Existing dot-path output is preserved, and sibling leaves from the same nested parent can flatten to direct leaf keys. If duplicate direct leaf keys occur at different nesting levels, the higher-level property wins. Applied after snake_case conversion. |
+| Option               | Default  | Behavior                                                                                                                                                                           |
+| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `optionalProperties` | `[]`     | Additional property paths that may be present. Absent optional paths are ignored. Present optional paths must be valid.                                                            |
+| `convertToSnakeCase` | `false`  | When `true`, converts returned keys, including nested keys, to snake_case using `@carecard/common-util`. Conversion happens before flattening.                                     |
+| `flattenOutput`      | `false`  | When `true`, removes nested objects from the returned value so every validated leaf becomes a top-level key.                                                                       |
+| `flattenKeyStyle`    | `'path'` | Controls flattened key naming when `flattenOutput` is `true`. Use `'path'` for full dot-notation keys or `'leaf'` for direct leaf names. Invalid values throw a `BAD_INPUT` error. |
+
+Example with only the default options:
+
+```js
+await validateWhitelistProperties({ first_name: 'Jane', email: 'jane@example.com', ignored: 'x' }, ['first_name']);
+// { first_name: 'Jane' }
+```
+
+Example with optional properties:
+
+```js
+await validateWhitelistProperties({ first_name: 'Jane', phone_number: '4165551234' }, ['first_name'], {
+    optionalProperties: ['phone_number'],
+});
+// { first_name: 'Jane', phone_number: '4165551234' }
+```
 
 ### Required And Optional Values
 
@@ -236,20 +286,31 @@ await validateWhitelistProperties(input, ['a.b.c.d.email']);
 // { a: { b: { c: { d: { email: 'jane@example.com' } } } } }
 ```
 
-With `flattenOutput: true`, sibling leaves from the same nested parent are
-returned as top-level leaf keys:
+With `flattenOutput: true`, keys are full dot paths by default:
+
+```js
+const input = { a: { b: { c: { d: { email: 'jane@example.com', name: 'Jane' } } } } };
+await validateWhitelistProperties(input, ['a.b.c.d.email', 'a.b.c.d.name'], {
+    flattenOutput: true,
+});
+// { 'a.b.c.d.email': 'jane@example.com', 'a.b.c.d.name': 'Jane' }
+```
+
+Use `flattenKeyStyle: 'leaf'` to return top-level leaf keys instead:
 
 ```js
 const input = { a: { b: { c: { d: { email: 'jane@example.com', name: 'Jane' } } } } };
 await validateWhitelistProperties(input, ['a.b.c.d.email', 'a.b.c.d.name'], {
     flattenOutput: true,
+    flattenKeyStyle: 'leaf',
 });
 // { email: 'jane@example.com', name: 'Jane' }
 ```
 
-If direct leaf-key flattening produces duplicate keys at different nesting
+When `flattenKeyStyle: 'leaf'` produces duplicate keys at different nesting
 levels, the higher-level value is kept and the lower-level duplicate is
-discarded:
+discarded. Duplicate leaf keys at the same nesting depth keep the first value
+encountered:
 
 ```js
 const input = {
@@ -259,6 +320,7 @@ const input = {
 
 await validateWhitelistProperties(input, ['name', 'user.name', 'user.email'], {
     flattenOutput: true,
+    flattenKeyStyle: 'leaf',
 });
 // { name: 'Top Level Name', email: 'jane@example.com' }
 ```