@carecard/validate 3.1.16 → 3.1.18

package/lib/validateWhitelistProperties.js

@@ -0,0 +1,285 @@
+'use strict';
+
+const {
+    error: { throwBadInputError },
+    caseConverter: { keysToSnakeCase },
+} = require('@carecard/common-util');
+
+const { validateProperties } = require('./validateProperties');
+
+/** Maximum supported nesting depth for dot-notation property paths. */
+const MAX_NESTING_DEPTH = 5;
+
+/**
+ * Maximum number of property paths (required + optional combined) that can
+ * be validated in a single call. Guards against pathologically large or
+ * adversarial inputs.
+ */
+const MAX_KEYS_PER_CALL = 5000;
+
+/**
+ * Returns true if the segment contains a mix of snake_case (underscore) and
+ * camelCase (uppercase letter), e.g. `my_mixName`. Such names are ambiguous
+ * and are not supported.
+ * @param {string} segment
+ * @returns {boolean}
+ */
+function isMixedCaseSegment(segment) {
+    return /_/.test(segment) && /[A-Z]/.test(segment);
+}
+
+/**
+ * Converts a snake_case identifier to camelCase. Leaves identifiers without
+ * underscores unchanged.
+ * @param {string} s
+ * @returns {string}
+ */
+function snakeToCamel(s) {
+    return s.replace(/_([a-zA-Z0-9])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Converts a camelCase identifier to snake_case. Leaves identifiers without
+ * uppercase letters unchanged.
+ * @param {string} s
+ * @returns {string}
+ */
+function camelToSnake(s) {
+    return s.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
+}
+
+/**
+ * Returns the alternate-case form of the segment:
+ *  - snake_case -> camelCase
+ *  - camelCase  -> snake_case
+ *  - otherwise (no `_` and no uppercase) the segment itself.
+ * @param {string} segment
+ * @returns {string}
+ */
+function alternateCase(segment) {
+    if (segment.indexOf('_') !== -1) return snakeToCamel(segment);
+    if (/[A-Z]/.test(segment)) return camelToSnake(segment);
+    return segment;
+}
+
+/**
+ * Splits a dot-notation property path into its segments and validates depth
+ * and per-segment casing (mixed snake/camel segments are rejected).
+ * @param {string} path
+ * @returns {string[]}
+ */
+function splitPath(path) {
+    const segments = String(path).split('.');
+    if (segments.length > MAX_NESTING_DEPTH) {
+        throwBadInputError({
+            userMessage: `Property path "${path}" exceeds maximum nesting depth of ${MAX_NESTING_DEPTH}`,
+        });
+    }
+    for (const seg of segments) {
+        if (isMixedCaseSegment(seg)) {
+            throwBadInputError({
+                userMessage: `Property path "${path}" has a segment "${seg}" mixing snake_case and camelCase`,
+            });
+        }
+    }
+    return segments;
+}
+
+/**
+ * Reads the leaf value at `path` from `obj`. Returns `{ found, value }`.
+ * `found` is true only if every intermediate node exists and the final
+ * `hasOwnProperty(leaf)` check passes.
+ *
+ * @param {*} obj
+ * @param {string[]} segments
+ * @returns {{ found: boolean, value: any }}
+ */
+function readLeaf(obj, segments) {
+    // Resolve a segment against the current node, trying its as-written form
+    // first and then its alternate snake/camel form. Returns the actual key
+    // present in the node, or undefined if neither form exists.
+    function resolveKey(node, seg) {
+        if (Object.prototype.hasOwnProperty.call(node, seg)) return seg;
+        const alt = alternateCase(seg);
+        if (alt !== seg && Object.prototype.hasOwnProperty.call(node, alt)) return alt;
+        return undefined;
+    }
+
+    let current = obj;
+    for (let i = 0; i < segments.length - 1; i++) {
+        if (current === null || typeof current !== 'object') return { found: false, value: undefined };
+        const key = resolveKey(current, segments[i]);
+        if (key === undefined) return { found: false, value: undefined };
+        current = current[key];
+    }
+    if (current === null || typeof current !== 'object') return { found: false, value: undefined };
+    const leafKey = resolveKey(current, segments[segments.length - 1]);
+    if (leafKey === undefined) return { found: false, value: undefined };
+    return { found: true, value: current[leafKey] };
+}
+
+/**
+ * Writes `value` into `target` at the nested location described by `segments`,
+ * creating intermediate plain-object nodes as needed.
+ *
+ * @param {Object} target
+ * @param {string[]} segments
+ * @param {*} value
+ */
+function writeLeaf(target, segments, value) {
+    let current = target;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const key = segments[i];
+        if (current[key] === null || typeof current[key] !== 'object') {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[segments[segments.length - 1]] = value;
+}
+
+/**
+ * Recursively flattens a nested plain object so every leaf becomes a top-level
+ * key. Keys are joined by `.`; the original nested shape is discarded.
+ *
+ * Example: `{ a: { b: { c: 1 } }, d: 2 }` => `{ 'a.b.c': 1, d: 2 }`.
+ *
+ * @param {Object} obj
+ * @param {string} [prefix]
+ * @param {Object} [out]
+ * @returns {Object}
+ */
+function flattenObject(obj, prefix = '', out = {}) {
+    for (const [key, value] of Object.entries(obj)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+            flattenObject(value, path, out);
+        } else {
+            out[path] = value;
+        }
+    }
+    return out;
+}
+
+/**
+ * Validates and transforms whitelisted properties from an input object.
+ *
+ * Supports nested objects via dot-notation paths (e.g. `'address.city'`),
+ * up to {@link MAX_NESTING_DEPTH} levels deep. For each whitelisted path the
+ * function checks that the leaf property exists, validates the leaf value
+ * using {@link validateProperties} (keyed by the leaf segment), and rebuilds
+ * the same nested shape in the returned object.
+ *
+ * Steps:
+ *  1. Extracts only the whitelisted (required + optional) leaf properties.
+ *  2. Validates leaf values using {@link validateProperties}.
+ *  3. Asserts every required leaf is present and valid; throws otherwise.
+ *  4. Asserts any provided optional leaf is valid; throws otherwise.
+ *
+ * Array values: a leaf value may be an array; in that case the per-leaf
+ * validator is applied to each element. The leaf is accepted only when every
+ * 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.
+ *
+ * @param {Object} inputObject - The input object (e.g., req.body / req.params).
+ * @param {Array<string>} [requiredProperties=[]] - Leaf paths that MUST be present and valid.
+ * @param {Object} [options]
+ * @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.
+ * @returns {Promise<Object>} Resolves with the validated (and possibly transformed) object.
+ */
+function validateWhitelistProperties(
+    inputObject,
+    requiredProperties = [],
+    options = { optionalProperties: [], convertToSnakeCase: false, flattenOutput: false },
+) {
+    const optionalProperties = (options && options.optionalProperties) || [];
+    const convertToSnakeCase = !!(options && options.convertToSnakeCase);
+    const flattenOutput = !!(options && options.flattenOutput);
+
+    // Cap the total number of paths to validate per call.
+    const totalKeys = (requiredProperties ? requiredProperties.length : 0) + optionalProperties.length;
+    if (totalKeys > MAX_KEYS_PER_CALL) {
+        throwBadInputError({
+            userMessage: `Too many properties to validate: ${totalKeys} (maximum ${MAX_KEYS_PER_CALL})`,
+        });
+    }
+
+    const requiredPaths = (requiredProperties || []).map(p => ({ raw: p, segments: splitPath(p) }));
+    const optionalPaths = optionalProperties.map(p => ({ raw: p, segments: splitPath(p) }));
+
+    let validatedObject = {};
+
+    // Helper: validate a single leaf value by feeding `{ [leafKey]: value }` to
+    // `validateProperties` and checking whether the leaf key survived.
+    //
+    // If `value` is an array, the same per-element validation is applied to
+    // every element; the result is an array of validated element values. The
+    // leaf is considered valid only when every element passes validation.
+    function validateLeafValue(leafKey, value) {
+        if (Array.isArray(value)) {
+            const validatedArray = [];
+            for (const element of value) {
+                const out = validateProperties({ [leafKey]: element });
+                if (!Object.prototype.hasOwnProperty.call(out, leafKey)) {
+                    return { valid: false, value: undefined };
+                }
+                validatedArray.push(out[leafKey]);
+            }
+            return { valid: true, value: validatedArray };
+        }
+        const out = validateProperties({ [leafKey]: value });
+        if (Object.prototype.hasOwnProperty.call(out, leafKey)) {
+            return { valid: true, value: out[leafKey] };
+        }
+        return { valid: false, value: undefined };
+    }
+
+    // 1 + 3. Required paths must exist and be valid.
+    requiredPaths.forEach(({ raw, segments }) => {
+        const { found, value } = readLeaf(inputObject, segments);
+        if (!found) {
+            throwBadInputError({ userMessage: `Missing or invalid property: ${raw}` });
+        }
+        const leafKey = segments[segments.length - 1];
+        const { valid, value: validatedValue } = validateLeafValue(leafKey, value);
+        if (!valid) {
+            throwBadInputError({ userMessage: `Missing or invalid property: ${raw}` });
+        }
+        writeLeaf(validatedObject, segments, validatedValue);
+    });
+
+    // 1 + 4. Optional paths: if provided, must be valid.
+    optionalPaths.forEach(({ raw, segments }) => {
+        const { found, value } = readLeaf(inputObject, segments);
+        if (!found) return;
+        const leafKey = segments[segments.length - 1];
+        const { valid, value: validatedValue } = validateLeafValue(leafKey, value);
+        if (!valid) {
+            throwBadInputError({ userMessage: `Invalid property value: ${raw}` });
+        }
+        writeLeaf(validatedObject, segments, validatedValue);
+    });
+
+    // 5. Optional case transformation (recursive, handles nested keys).
+    if (convertToSnakeCase) {
+        validatedObject = keysToSnakeCase(validatedObject);
+    }
+
+    // 6. Optional flattening: produce a flat object with dot-joined keys.
+    if (flattenOutput) {
+        validatedObject = flattenObject(validatedObject);
+    }
+
+    return Promise.resolve(validatedObject);
+}
+
+module.exports = validateWhitelistProperties;
+module.exports.validateWhitelistProperties = validateWhitelistProperties;
+module.exports.MAX_NESTING_DEPTH = MAX_NESTING_DEPTH;
+module.exports.MAX_KEYS_PER_CALL = MAX_KEYS_PER_CALL;

package/package.json

@@ -1,40 +1,43 @@
 {
-  "name": "@carecard/validate",
-  "version": "3.1.16",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
-  },
-  "description": "Validate data",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "scripts": {
-    "test": "mocha --recursive",
-    "test:types": "tsc --noEmit && mocha -r ts-node/register test/types.test.ts",
-    "test:coverage": "tsc --noEmit && export NODE_ENV=test && nyc mocha --recursive -r ts-node/register 'test/**/*.{js,ts}'",
-    "test:All": "npm run test && npm run test:types",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "prepare": "husky",
-    "lint:fix": "eslint --fix",
-    "lint": "eslint"
-  },
-  "keywords": [
-    "validate",
-    "data"
-  ],
-  "author": "CareCard team",
-  "license": "ISC",
-  "devDependencies": {
-    "@types/mocha": "10.0.10",
-    "@types/node": "25.6.2",
-    "eslint": "9.39.4",
-    "husky": "9.1.7",
-    "lint-staged": "17.0.3",
-    "mocha": "11.7.5",
-    "nyc": "18.0.0",
-    "prettier": "3.8.3",
-    "ts-node": "10.9.2",
-    "typescript": "5.9.3"
-  }
+    "name": "@carecard/validate",
+    "version": "3.1.18",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
+    },
+    "description": "Validate data",
+    "main": "index.js",
+    "types": "index.d.ts",
+    "scripts": {
+        "test": "mocha --recursive",
+        "test:types": "tsc --noEmit && echo \"\\n  ✔ Type tests passed: tsc --noEmit reported 0 errors across index.d.ts and test/**/*.ts\\n\"",
+        "test:coverage": "tsc --noEmit && export NODE_ENV=test && nyc mocha --recursive",
+        "test:All": "npm run test && npm run test:types",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "prepare": "husky",
+        "lint:fix": "eslint --fix",
+        "lint": "eslint"
+    },
+    "keywords": [
+        "validate",
+        "data"
+    ],
+    "author": "CareCard team",
+    "license": "ISC",
+    "devDependencies": {
+        "@types/mocha": "10.0.10",
+        "@types/node": "25.6.2",
+        "eslint": "9.39.4",
+        "husky": "9.1.7",
+        "lint-staged": "17.0.3",
+        "mocha": "11.7.5",
+        "nyc": "18.0.0",
+        "prettier": "3.8.3",
+        "ts-node": "10.9.2",
+        "typescript": "5.9.3"
+    },
+    "dependencies": {
+        "@carecard/common-util": "^3.1.13"
+    }
 }