@planning-inspectorate/dynamic-forms 3.11.0 → 3.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planning-inspectorate/dynamic-forms",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "description": "This package is for building GDS forms using a configuration-based approach.",
   "main": "./src/index.js",
   "type": "module",

package/src/index.js

@@ -60,6 +60,7 @@ export * from './validator/base-validator.js';
 export * from './validator/conditional-required-validator.js';
 export * from './validator/confirmation-checkbox-validator.js';
 export * from './validator/coordinates-validator.js';
+export * from './validator/cross-question-validator.js';
 export * from './validator/date-period-validator.js';
 export * from './validator/date-time-validator.js';
 export * from './validator/date-validator.js';

package/src/validator/base-validator.js

@@ -13,6 +13,19 @@ export class BaseValidator {
 			throw new Error("Abstract classes can't be instantiated.");
 		}
 	}
+
+	/**
+	 * Validates response body against field validators.
+	 * Subclasses must override this method.
+	 * @abstract
+	 * @param {import('../questions/question-props.js').QuestionProps} questionObj - The question object containing the fieldName to validate.
+	 * @param {import('../journey/journey-response.js').JourneyResponse} [journeyResponse] - The current journey response (optional).
+	 * @returns {import('express-validator').ValidationChain | import('express-validator').ValidationChain[]}
+	 */
+	// eslint-disable-next-line no-unused-vars
+	validate(questionObj, journeyResponse) {
+		throw new Error('validate method must be implemented by subclass');
+	}
 }
 
 export default BaseValidator;

package/src/validator/cross-question-validator.js

@@ -0,0 +1,66 @@
+import BaseValidator from './base-validator.js';
+import { body } from 'express-validator';
+
+/**
+ * Validator for validating a question's answer against another question's answer using a custom validation function.
+ */
+export class CrossQuestionValidator extends BaseValidator {
+	/** @type {string} */
+	dependencyFieldName;
+	/** @type {((currentAnswer: unknown, dependencyAnswer: unknown) => boolean)} */
+	validationFunction;
+	/** @type {boolean} */
+	useBodyValues;
+
+	/**
+	 * @param {Object} params
+	 * @param {string} params.dependencyFieldName - The field name of the other question to compare against.
+	 * @param {((currentAnswer: unknown, dependencyAnswer: unknown) => boolean)| null} params.validationFunction - A function that takes the current question's answer and the other question's answer and returns true if valid, false otherwise.
+	 * @param {boolean} [params.useBodyValues=false] - Whether to use req.body values for validation (default: false). Usually CrossQuestionValidator will be for validating across saved session answers, but if used between multiple fields on one question, it will need to use the body.
+	 * @throws {Error} If validationFunction is not provided or is not a function.
+	 * @throws {Error} If dependencyFieldName is not provided
+	 */
+	constructor({ dependencyFieldName, validationFunction, useBodyValues = false } = {}) {
+		super();
+
+		if (!dependencyFieldName) {
+			throw new Error('CrossQuestionValidator requires dependencyFieldName');
+		}
+		if (!validationFunction || typeof validationFunction !== 'function') {
+			throw new Error('CrossQuestionValidator requires a validationFunction');
+		}
+
+		this.dependencyFieldName = dependencyFieldName;
+		this.validationFunction = validationFunction;
+		this.useBodyValues = useBodyValues;
+	}
+
+	/**
+	 * Validates response body against individual field validators.
+	 * @param {import('../questions/question-props.js').QuestionProps} questionObj - The question object containing the fieldName to validate.
+	 * @param {import('../journey/journey-response.js').JourneyResponse} [journeyResponse={}] - The current journey response, used to access saved answers for validation.
+	 * @returns {import('express-validator').ValidationChain[]}
+	 */
+	validate(questionObj, journeyResponse = {}) {
+		const fieldName = questionObj.fieldName;
+
+		return [
+			body(fieldName).custom((value, { req }) => {
+				const answers = journeyResponse?.answers || {};
+				const currentAnswer = this.useBodyValues ? value : answers[fieldName];
+				const dependencyAnswer = this.useBodyValues
+					? req.body[this.dependencyFieldName]
+					: answers[this.dependencyFieldName];
+				return (
+					this.validationFunction(currentAnswer, dependencyAnswer) ||
+					// Fallback if validation fails without throwing an error
+					Promise.reject(
+						new Error(`Cross-question validation failed between ${fieldName} and ${this.dependencyFieldName}`)
+					)
+				);
+			})
+		];
+	}
+}
+
+export default CrossQuestionValidator;

package/src/validator/cross-question-validator.test.js

@@ -0,0 +1,132 @@
+import { describe, test, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import CrossQuestionValidator from './cross-question-validator.js';
+
+function createMockRequest(answers) {
+	return {
+		res: {
+			locals: {
+				journeyResponse: {
+					answers: answers || {}
+				}
+			}
+		}
+	};
+}
+
+describe('CrossQuestionValidator', () => {
+	test('should throw an error if dependencyFieldName is missing', () => {
+		assert.throws(() => {
+			new CrossQuestionValidator({ validationFunction: () => true });
+		}, /requires dependencyFieldName/);
+	});
+
+	test('should throw an error if validationFunction is missing', () => {
+		assert.throws(() => {
+			new CrossQuestionValidator({ dependencyFieldName: 'other' });
+		}, /requires a validationFunction/);
+	});
+
+	test('should throw an error if validationFunction is not a function', () => {
+		assert.throws(() => {
+			new CrossQuestionValidator({ dependencyFieldName: 'other', validationFunction: 123 });
+		}, /requires a validationFunction/);
+	});
+
+	test('should return a validation chain that calls the validation function with correct answers', async () => {
+		const validationFn = mock.fn(() => true);
+		const validator = new CrossQuestionValidator({
+			dependencyFieldName: 'other',
+			validationFunction: validationFn
+		});
+		const questionObj = { fieldName: 'field' };
+		const req = createMockRequest({ field: 'foo', other: 'bar' });
+		const chain = validator.validate(questionObj, req.res.locals.journeyResponse);
+		await chain[0].run(req);
+		assert.deepEqual(validationFn.mock.calls[0].arguments, ['foo', 'bar']);
+	});
+
+	test('should fail validation if validation function returns false', async () => {
+		const validator = new CrossQuestionValidator({
+			dependencyFieldName: 'other',
+			validationFunction: () => false
+		});
+		const questionObj = { fieldName: 'field' };
+		const chain = validator.validate(questionObj);
+		const req = createMockRequest({ field: 'foo', other: 'bar' });
+		req.body = { field: 'foo' };
+		const result = await chain[0].run(req);
+		assert.strictEqual(result.isEmpty(), false);
+		assert.match(result.array()[0].msg, /Cross-question validation failed/);
+	});
+
+	test('should call validation function when journeyResponse is missing', async () => {
+		const validationFn = mock.fn(() => true);
+		const validator = new CrossQuestionValidator({
+			dependencyFieldName: 'other',
+			validationFunction: validationFn
+		});
+		const questionObj = { fieldName: 'field' };
+		const chain = validator.validate(questionObj);
+		const req = { res: { locals: {} } };
+		await chain[0].run(req);
+		assert.deepEqual(validationFn.mock.calls[0].arguments, [undefined, undefined]);
+	});
+
+	it('should use session answers instead of request body values when useBodyValues is false', async () => {
+		const validationFn = mock.fn(() => true);
+		const validator = new CrossQuestionValidator({
+			dependencyFieldName: 'other',
+			validationFunction: validationFn
+		});
+		const questionObj = { fieldName: 'field' };
+		const req = createMockRequest({ field: 'from-session', other: 'from-session-dependency' });
+		req.body = { field: 'from-body', other: 'from-body-dependency' };
+		const chain = validator.validate(questionObj, req.res.locals.journeyResponse);
+		await chain[0].run(req);
+		assert.deepEqual(validationFn.mock.calls[0].arguments, ['from-session', 'from-session-dependency']);
+	});
+
+	it('should use request body values when useBodyValues is true', async () => {
+		const validationFn = mock.fn(() => true);
+		const validator = new CrossQuestionValidator({
+			dependencyFieldName: 'other',
+			useBodyValues: true,
+			validationFunction: validationFn
+		});
+		const questionObj = { fieldName: 'field' };
+		const chain = validator.validate(questionObj);
+		const req = createMockRequest({ field: 'from-session', other: 'from-session-dependency' });
+		req.body = { field: 'from-body', other: 'from-body-dependency' };
+		await chain[0].run(req);
+		assert.deepEqual(validationFn.mock.calls[0].arguments, ['from-body', 'from-body-dependency']);
+	});
+
+	it('should fail validation with thrown error message when validation function throws', async () => {
+		const validator = new CrossQuestionValidator({
+			dependencyFieldName: 'other',
+			validationFunction: () => {
+				throw new Error('boom');
+			}
+		});
+		const questionObj = { fieldName: 'field' };
+		const chain = validator.validate(questionObj);
+		const req = createMockRequest({ field: 'foo', other: 'bar' });
+		const result = await chain[0].run(req);
+		assert.strictEqual(result.isEmpty(), false);
+		assert.strictEqual(result.array()[0].msg, 'boom');
+	});
+
+	it('should call validation function with undefined values when journeyResponse has no answers object', async () => {
+		const validationFn = mock.fn(() => true);
+		const validator = new CrossQuestionValidator({
+			dependencyFieldName: 'other',
+			validationFunction: validationFn
+		});
+		const questionObj = { fieldName: 'field' };
+		const chain = validator.validate(questionObj);
+		const req = { res: { locals: { journeyResponse: {} } } };
+		await chain[0].run(req);
+		assert.deepEqual(validationFn.mock.calls[0].arguments, [undefined, undefined]);
+	});
+});

package/types/src/index.d.ts

@@ -35,6 +35,7 @@ export * from "./validator/base-validator.js";
 export * from "./validator/conditional-required-validator.js";
 export * from "./validator/confirmation-checkbox-validator.js";
 export * from "./validator/coordinates-validator.js";
+export * from "./validator/cross-question-validator.js";
 export * from "./validator/date-period-validator.js";
 export * from "./validator/date-time-validator.js";
 export * from "./validator/date-validator.js";

package/types/src/validator/base-validator.d.ts

@@ -7,6 +7,15 @@ export class BaseValidator {
      * @type {string} error message to display to user
      */
     errorMessage: string;
+    /**
+     * Validates response body against field validators.
+     * Subclasses must override this method.
+     * @abstract
+     * @param {import('../questions/question-props.js').QuestionProps} questionObj - The question object containing the fieldName to validate.
+     * @param {import('../journey/journey-response.js').JourneyResponse} [journeyResponse] - The current journey response (optional).
+     * @returns {import('express-validator').ValidationChain | import('express-validator').ValidationChain[]}
+     */
+    validate(questionObj: import("../questions/question-props.js").QuestionProps, journeyResponse?: import("../journey/journey-response.js").JourneyResponse): import("express-validator").ValidationChain | import("express-validator").ValidationChain[];
 }
 export default BaseValidator;
 //# sourceMappingURL=base-validator.d.ts.map

package/types/src/validator/base-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-validator.d.ts","sourceRoot":"","sources":["../../../src/validator/base-validator.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IACC;;OAEG;IACH,cAFU,MAAM,CAEH;CAOb"}
+{"version":3,"file":"base-validator.d.ts","sourceRoot":"","sources":["../../../src/validator/base-validator.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IACC;;OAEG;IACH,cAFU,MAAM,CAEH;IAQb;;;;;;;OAOG;IAEH,sBALW,OAAO,gCAAgC,EAAE,aAAa,oBACtD,OAAO,gCAAgC,EAAE,eAAe,GACtD,OAAO,mBAAmB,EAAE,eAAe,GAAG,OAAO,mBAAmB,EAAE,eAAe,EAAE,CAKvG;CACD"}

package/types/src/validator/cross-question-validator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Validator for validating a question's answer against another question's answer using a custom validation function.
+ */
+export class CrossQuestionValidator extends BaseValidator {
+    /**
+     * @param {Object} params
+     * @param {string} params.dependencyFieldName - The field name of the other question to compare against.
+     * @param {((currentAnswer: unknown, dependencyAnswer: unknown) => boolean)| null} params.validationFunction - A function that takes the current question's answer and the other question's answer and returns true if valid, false otherwise.
+     * @param {boolean} [params.useBodyValues=false] - Whether to use req.body values for validation (default: false). Usually CrossQuestionValidator will be for validating across saved session answers, but if used between multiple fields on one question, it will need to use the body.
+     * @throws {Error} If validationFunction is not provided or is not a function.
+     * @throws {Error} If dependencyFieldName is not provided
+     */
+    constructor({ dependencyFieldName, validationFunction, useBodyValues }?: {
+        dependencyFieldName: string;
+        validationFunction: ((currentAnswer: unknown, dependencyAnswer: unknown) => boolean) | null;
+        useBodyValues?: boolean | undefined;
+    });
+    /** @type {string} */
+    dependencyFieldName: string;
+    /** @type {((currentAnswer: unknown, dependencyAnswer: unknown) => boolean)} */
+    validationFunction: ((currentAnswer: unknown, dependencyAnswer: unknown) => boolean);
+    /** @type {boolean} */
+    useBodyValues: boolean;
+    /**
+     * Validates response body against individual field validators.
+     * @param {import('../questions/question-props.js').QuestionProps} questionObj - The question object containing the fieldName to validate.
+     * @param {import('../journey/journey-response.js').JourneyResponse} [journeyResponse={}] - The current journey response, used to access saved answers for validation.
+     * @returns {import('express-validator').ValidationChain[]}
+     */
+    validate(questionObj: import("../questions/question-props.js").QuestionProps, journeyResponse?: import("../journey/journey-response.js").JourneyResponse): import("express-validator").ValidationChain[];
+}
+export default CrossQuestionValidator;
+import BaseValidator from './base-validator.js';
+//# sourceMappingURL=cross-question-validator.d.ts.map

package/types/src/validator/cross-question-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-question-validator.d.ts","sourceRoot":"","sources":["../../../src/validator/cross-question-validator.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IAQC;;;;;;;OAOG;IACH,yEANG;QAAuB,mBAAmB,EAAlC,MAAM;QACyE,kBAAkB,EAAjG,CAAC,CAAC,aAAa,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,KAAK,OAAO,CAAC,GAAE,IAAI;QACrD,aAAa;KACtC,EAgBF;IA5BD,qBAAqB;IACrB,qBADW,MAAM,CACG;IACpB,+EAA+E;IAC/E,oBADW,CAAC,CAAC,aAAa,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,KAAK,OAAO,CAAC,CACxD;IACnB,sBAAsB;IACtB,eADW,OAAO,CACJ;IAyBd;;;;;OAKG;IACH,sBAJW,OAAO,gCAAgC,EAAE,aAAa,oBACtD,OAAO,gCAAgC,EAAE,eAAe,GACtD,OAAO,mBAAmB,EAAE,eAAe,EAAE,CAqBzD;CACD;;0BA/DyB,qBAAqB"}