@planning-inspectorate/dynamic-forms 2.2.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planning-inspectorate/dynamic-forms",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "This package is for building GDS forms using a configuration-based approach.",
   "main": "./src/index.js",
   "type": "module",
@@ -26,6 +26,7 @@
   },
   "imports": {
     "#question-types": "./src/questions/question-types.d.ts",
+    "#src/*": "./src/*",
     "#test/*": "./test/*"
   },
   "devDependencies": {

package/src/controller.js

@@ -66,6 +66,14 @@ function buildSectionRowViewModel(key, value, action) {
 	};
 }
 
+/**
+ * @param {object} [viewData]
+ * @returns {import('express').Handler}
+ */
+export function buildList(viewData = {}) {
+	return (req, res) => list(req, res, viewData.pageCaption, viewData);
+}
+
 /**
  * @param {import('express').Request} req
  * @param {import('express').Response} res
@@ -139,18 +147,19 @@ export async function list(req, res, pageCaption, viewData) {
  */
 export async function question(req, res) {
 	//render an individual question
-	const { section, question } = req.params;
 	const { journey } = res.locals;
 
-	const sectionObj = journey.getSection(section);
-	const questionObj = journey.getQuestionBySectionAndName(section, question);
+	const section = journey.getSection(req.params.section);
+	const question = journey.getQuestionByParams(req.params);
 
-	if (!questionObj || !sectionObj) {
+	if (!question || !section) {
 		return res.redirect(journey.taskListUrl);
 	}
 
-	const viewModel = questionObj.prepQuestionForRendering(sectionObj, journey);
-	return questionObj.renderAction(res, viewModel);
+	const viewModel = question.prepQuestionForRendering(section, journey, {
+		originalUrl: req.originalUrl
+	});
+	return question.renderAction(res, viewModel);
 }
 
 /**
@@ -173,28 +182,27 @@ export async function question(req, res) {
  */
 export function buildSave(saveData, redirectToTaskListOnSuccess) {
 	return async (req, res) => {
-		const { section, question } = req.params;
 		/** @type {import('./journey/journey.js').Journey} */
 		const journey = res.locals.journey;
 		/** @type {import('./journey/journey-response.js').JourneyResponse} */
 		const journeyResponse = res.locals.journeyResponse;
 
-		const sectionObj = journey.getSection(section);
-		const questionObj = journey.getQuestionBySectionAndName(section, question);
+		const section = journey.getSection(req.params.section);
+		const question = journey.getQuestionByParams(req.params);
 
-		if (!questionObj || !sectionObj) {
+		if (!question || !section) {
 			return res.redirect(journey.taskListUrl);
 		}
 
 		try {
 			// check for validation errors
-			const errorViewModel = questionObj.checkForValidationErrors(req, sectionObj, journey);
+			const errorViewModel = question.checkForValidationErrors(req, section, journey);
 			if (errorViewModel) {
-				return questionObj.renderAction(res, errorViewModel);
+				return question.renderAction(res, errorViewModel);
 			}
 
 			// save
-			const data = await questionObj.getDataToSave(req, journeyResponse);
+			const data = await question.getDataToSave(req, journeyResponse);
 
 			await saveData({
 				req,
@@ -205,20 +213,23 @@ export function buildSave(saveData, redirectToTaskListOnSuccess) {
 			});
 
 			// check for saving errors
-			const saveViewModel = questionObj.checkForSavingErrors(req, sectionObj, journey);
+			const saveViewModel = question.checkForSavingErrors(req, section, journey);
 			if (saveViewModel) {
-				return questionObj.renderAction(res, saveViewModel);
+				return question.renderAction(res, saveViewModel);
 			}
 			if (redirectToTaskListOnSuccess) {
 				return res.redirect(journey.taskListUrl);
 			}
 			// move to the next question
-			return questionObj.handleNextQuestion(res, journey, sectionObj.segment, questionObj.fieldName);
+			return journey.redirectToNextQuestion(res, {
+				section: section.segment,
+				question: question.fieldName
+			});
 		} catch (err) {
-			const viewModel = questionObj.prepQuestionForRendering(sectionObj, journey, {
+			const viewModel = question.prepQuestionForRendering(section, journey, {
 				errorSummary: err.errorSummary ?? [{ text: err.toString(), href: '#' }]
 			});
-			return questionObj.renderAction(res, viewModel);
+			return question.renderAction(res, viewModel);
 		}
 	};
 }

package/src/controller.test.js

@@ -180,8 +180,7 @@ const sampleQuestionObj = {
 	checkForSavingErrors: mock.fn(),
 	prepQuestionForRendering: mock.fn(),
 	formatAnswerForSummary: mock.fn(() => [mockAnswer]),
-	viewFolder: 'sampleType',
-	handleNextQuestion: mock.fn()
+	viewFolder: 'sampleType'
 };
 
 const mockSection = {
@@ -301,8 +300,8 @@ describe('dynamic-form/controller', () => {
 
 	describe('question', () => {
 		it('should redirect if question is not found', async () => {
-			mockJourney.getQuestionBySectionAndName = mock.fn();
-			mockJourney.getQuestionBySectionAndName.mock.mockImplementationOnce(() => null);
+			mockJourney.getQuestionByParams = mock.fn();
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => null);
 
 			await question(req, res);
 
@@ -314,8 +313,8 @@ describe('dynamic-form/controller', () => {
 			mockJourney.getSection.mock.mockImplementationOnce(() => {
 				return {};
 			});
-			mockJourney.getQuestionBySectionAndName = mock.fn(() => sampleQuestionObj);
-			mockJourney.getQuestionBySectionAndName.mock.mockImplementationOnce(() => sampleQuestionObj);
+			mockJourney.getQuestionByParams = mock.fn(() => sampleQuestionObj);
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => sampleQuestionObj);
 			sampleQuestionObj.renderAction = mock.fn();
 
 			await question(req, res);
@@ -326,6 +325,7 @@ describe('dynamic-form/controller', () => {
 
 		it('should render the question template', async () => {
 			sampleQuestionObj.renderAction.mock.resetCalls();
+			sampleQuestionObj.prepQuestionForRendering.mock.resetCalls();
 			req.params.referenceId = mockRef;
 			const mockAnswer = 'sampleAnswer';
 			const mockBackLink = 'back';
@@ -333,8 +333,8 @@ describe('dynamic-form/controller', () => {
 
 			sampleQuestionObj.prepQuestionForRendering.mock.mockImplementationOnce(() => mockQuestionRendering);
 
-			mockJourney.getQuestionBySectionAndName = mock.fn();
-			mockJourney.getQuestionBySectionAndName.mock.mockImplementationOnce(() => sampleQuestionObj);
+			mockJourney.getQuestionByParams = mock.fn();
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => sampleQuestionObj);
 			mockJourney.response.answers.sampleFieldName = mockAnswer;
 			mockJourney.getNextQuestionUrl = mock.fn(() => mockBackLink);
 			mockJourney.getSection = mock.fn(() => mockSection);
@@ -343,6 +343,13 @@ describe('dynamic-form/controller', () => {
 
 			assert.strictEqual(sampleQuestionObj.renderAction.mock.callCount(), 1);
 			assert.deepStrictEqual(sampleQuestionObj.renderAction.mock.calls[0].arguments, [res, mockQuestionRendering]);
+			assert.strictEqual(sampleQuestionObj.prepQuestionForRendering.mock.callCount(), 1);
+			assert.ok(sampleQuestionObj.prepQuestionForRendering.mock.calls[0].arguments[2]);
+			assert.ok(sampleQuestionObj.prepQuestionForRendering.mock.calls[0].arguments[2].originalUrl);
+			assert.strictEqual(
+				sampleQuestionObj.prepQuestionForRendering.mock.calls[0].arguments[2].originalUrl,
+				req.originalUrl
+			);
 		});
 	});
 
@@ -367,8 +374,8 @@ describe('dynamic-form/controller', () => {
 				notSampleFieldName: 'do not send this'
 			};
 
-			mockJourney.getQuestionBySectionAndName = mock.fn();
-			mockJourney.getQuestionBySectionAndName.mock.mockImplementationOnce(() => sampleQuestionObj);
+			mockJourney.getQuestionByParams = mock.fn();
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => sampleQuestionObj);
 
 			const saveData = mock.fn();
 			await buildSave(saveData)(req, res, journeyId);
@@ -418,8 +425,8 @@ describe('dynamic-form/controller', () => {
 				notSampleFieldName: 'do not send this'
 			};
 
-			mockJourney.getQuestionBySectionAndName = mock.fn();
-			mockJourney.getQuestionBySectionAndName.mock.mockImplementationOnce(() => sampleQuestionObjWithActions);
+			mockJourney.getQuestionByParams = mock.fn();
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => sampleQuestionObjWithActions);
 
 			const saveData = mock.fn(() => {
 				throw new Error('Expected error message');
@@ -465,8 +472,8 @@ describe('dynamic-form/controller', () => {
 				answers: {}
 			};
 
-			mockJourney.getQuestionBySectionAndName = mock.fn();
-			mockJourney.getQuestionBySectionAndName.mock.mockImplementationOnce(() => sampleQuestionObjWithActions);
+			mockJourney.getQuestionByParams = mock.fn();
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => sampleQuestionObjWithActions);
 
 			const saveData = mock.fn();
 			await buildSave(saveData)(req, res, journeyId);
@@ -480,10 +487,7 @@ describe('dynamic-form/controller', () => {
 			const journeyId = 'has-questionnaire';
 			const expectedUrl = 'redirect-url';
 			const sampleQuestionObjWithActions = {
-				...sampleQuestionObj,
-				handleNextQuestion: mock.fn((res, journey) => {
-					res.redirect(journey.getNextQuestionUrl());
-				})
+				...sampleQuestionObj
 			};
 
 			req.params = {
@@ -498,8 +502,8 @@ describe('dynamic-form/controller', () => {
 			};
 
 			mockJourney.getSection = mock.fn(() => ({}));
-			mockJourney.getQuestionBySectionAndName = mock.fn();
-			mockJourney.getQuestionBySectionAndName.mock.mockImplementationOnce(() => sampleQuestionObjWithActions);
+			mockJourney.getQuestionByParams = mock.fn();
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => sampleQuestionObjWithActions);
 			mockJourney.getNextQuestionUrl = mock.fn(() => expectedUrl);
 
 			const saveData = mock.fn();
@@ -515,10 +519,7 @@ describe('dynamic-form/controller', () => {
 			const journeyId = 'has-questionnaire';
 			const expectedUrl = 'redirect-url';
 			const sampleQuestionObjWithActions = {
-				...sampleQuestionObj,
-				handleNextQuestion: mock.fn((res, journey) => {
-					res.redirect(journey.getNextQuestionUrl());
-				})
+				...sampleQuestionObj
 			};
 
 			req.params = {
@@ -533,8 +534,8 @@ describe('dynamic-form/controller', () => {
 			};
 
 			mockJourney.getSection = mock.fn(() => ({}));
-			mockJourney.getQuestionBySectionAndName = mock.fn();
-			mockJourney.getQuestionBySectionAndName.mock.mockImplementationOnce(() => sampleQuestionObjWithActions);
+			mockJourney.getQuestionByParams = mock.fn();
+			mockJourney.getQuestionByParams.mock.mockImplementationOnce(() => sampleQuestionObjWithActions);
 			mockJourney.getNextQuestionUrl = mock.fn(() => expectedUrl);
 
 			const saveData = mock.fn();

package/src/journey/journey-types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Express route parameters used for journey routes
+ */
+export type RouteParams = {
+	section: string;
+	question: string;
+	[key: string]: string;
+};

package/src/journey/journey.js

@@ -3,6 +3,7 @@
  * (e.g. questionnaire). Specific journeys should be       *
  * instances of this class                                 *
  ***********************************************************/
+import { END_OF_SECTION } from '#src/section.js';
 
 /**
  * @typedef {import('./journey-response').JourneyResponse} JourneyResponse
@@ -135,12 +136,11 @@ export class Journey {
 
 	/**
 	 * utility function to build up a url to a question
-	 * @param {string} sectionSegment url param for a section
-	 * @param {string} questionSegment url param for a question
+	 * @param {import('./journey-types.d.ts').RouteParams} params
 	 * @returns {string} url for a question
 	 */
-	#buildQuestionUrl(sectionSegment, questionSegment) {
-		return this.#prependPathToUrl(this.baseUrl, `${sectionSegment}/${questionSegment}`);
+	#buildQuestionUrl(params) {
+		return this.#prependPathToUrl(this.baseUrl, `${params.section}/${params.question}`);
 	}
 
 	/**
@@ -168,18 +168,17 @@ export class Journey {
 
 	/**
 	 * gets a question from the object's sections based on a section + question names
-	 * @param {string} sectionSegment segment of the section to find the question in
-	 * @param {string} questionSegment fieldname of the question to lookup
+	 * @param {import('./journey-types.d.ts').RouteParams} params
 	 * @returns {Question | undefined} question found by lookup
 	 */
-	getQuestionBySectionAndName(sectionSegment, questionSegment) {
-		const section = this.getSection(sectionSegment);
+	getQuestionByParams(params) {
+		const section = this.getSection(params.section);
 
 		if (!section) {
 			return undefined;
 		}
 
-		return this.#getQuestion(section, questionSegment);
+		return this.#getQuestion(section, params.question);
 	}
 
 	/**
@@ -190,7 +189,7 @@ export class Journey {
 	 * @returns {string|null} url for the next question, or null if unmatched
 	 */
 	getBackLink(sectionSegment, questionSegment) {
-		const previousQuestion = this.getNextQuestionUrl(sectionSegment, questionSegment, true);
+		const previousQuestion = this.getNextQuestionUrl({ section: sectionSegment, question: questionSegment }, true);
 		if (!previousQuestion) {
 			return this.initialBackLink;
 		}
@@ -198,13 +197,26 @@ export class Journey {
 	}
 
 	/**
-	 * Get url for the next question in this section
-	 * @param {string} sectionSegment - section segment
-	 * @param {string} questionSegment - question segment
+	 * Handles redirect to the next question in the journey
+	 * Used after question post/saving
+	 *
+	 * @param {import('express').Response} res
+	 * @param {import('./journey-types.d.ts').RouteParams} params
+	 * @returns {void}
+	 */
+	redirectToNextQuestion(res, params) {
+		const next = this.getNextQuestionUrl(params) ?? this.taskListUrl;
+		return res.redirect(next);
+	}
+
+	/**
+	 * Get url for the next question in the journey
+	 *
+	 * @param {import('./journey-types.d.ts').RouteParams} params
 	 * @param {boolean} [reverse] - if passed in this will get the previous question
 	 * @returns {string|null} url for the next question, or null if unmatched
 	 */
-	getNextQuestionUrl(sectionSegment, questionSegment, reverse = false) {
+	getNextQuestionUrl(params, reverse = false) {
 		const numberOfSections = this.sections.length;
 		const sectionsStart = reverse ? numberOfSections - 1 : 0;
 
@@ -214,9 +226,8 @@ export class Journey {
 
 		for (let i = sectionsStart; reverse ? i >= 0 : i < numberOfSections; reverse ? i-- : i++) {
 			const currentSection = this.sections[i];
-			const numberOfQuestions = currentSection.questions.length;
 
-			if (currentSection.segment === sectionSegment) {
+			if (currentSection.segment === params.section) {
 				foundSection = true;
 				currentSectionIndex = i;
 			}
@@ -225,17 +236,21 @@ export class Journey {
 				if (this.returnToListing && i !== currentSectionIndex) {
 					return null;
 				}
-
-				const questionsStart = reverse ? numberOfQuestions - 1 : 0;
-				for (let j = questionsStart; reverse ? j >= 0 : j < numberOfQuestions; reverse ? j-- : j++) {
-					const question = currentSection.questions[j];
-					if (takeNextQuestion && question.shouldDisplay(this.response)) {
-						return this.#buildQuestionUrl(currentSection.segment, question.url ? question.url : question.fieldName);
-					}
-
-					if (question.fieldName === questionSegment) {
-						takeNextQuestion = true;
-					}
+				const question = currentSection.getNextQuestion({
+					questionFieldName: params.question,
+					response: this.response,
+					takeNextQuestion,
+					reverse
+				});
+				if (question === END_OF_SECTION) {
+					takeNextQuestion = true; // get the first question from the following section
+				} else if (question) {
+					const newParams = {
+						...params,
+						section: currentSection.segment,
+						question: question.url || question.fieldName
+					};
+					return this.#buildQuestionUrl(newParams);
 				}
 			}
 		}
@@ -264,10 +279,10 @@ export class Journey {
 			return unmatchedUrl;
 		}
 
-		return this.#buildQuestionUrl(
-			matchingSection.segment,
-			matchingQuestion.url ? matchingQuestion.url : matchingQuestion.fieldName
-		);
+		return this.#buildQuestionUrl({
+			section: matchingSection.segment,
+			question: matchingQuestion.url || matchingQuestion.fieldName
+		});
 	};
 
 	/**
@@ -303,7 +318,10 @@ export class Journey {
 
 		const questionUrl = matchingQuestion.url ?? matchingQuestion.fieldName;
 
-		return this.#buildQuestionUrl(matchingSection.segment, questionUrl + addition);
+		return this.#buildQuestionUrl({
+			section: matchingSection.segment,
+			question: questionUrl + addition
+		});
 	};
 
 	/**

package/src/journey/journey.test.js

@@ -1,8 +1,9 @@
 import { describe, it, mock, beforeEach } from 'node:test';
 import assert from 'node:assert';
 import { Journey } from './journey.js';
+import { Section } from '#src/section.js';
 
-const mockSections = [
+const mockSectionDetails = [
 	{
 		segment: 'section1',
 		questions: [
@@ -40,6 +41,11 @@ const mockSections = [
 		]
 	}
 ];
+const mockSections = mockSectionDetails.map((data, index) => {
+	const section = new Section(`section ${index}`, data.segment);
+	section.questions = data.questions;
+	return section;
+});
 
 describe('Journey class', () => {
 	let constructorArgs;
@@ -193,15 +199,15 @@ describe('Journey class', () => {
 		});
 	});
 
-	describe('getQuestionBySectionAndName', () => {
+	describe('getQuestionByParams', () => {
 		it('should return the correct question by section and name', () => {
 			const journey = new Journey(constructorArgs);
 			journey.sections = mockSections;
 
-			const question = journey.getQuestionBySectionAndName(
-				mockSections[0].segment,
-				mockSections[0].questions[1].fieldName
-			);
+			const question = journey.getQuestionByParams({
+				section: mockSections[0].segment,
+				question: mockSections[0].questions[1].fieldName
+			});
 
 			assert.strictEqual(question, mockSections[0].questions[1]);
 		});
@@ -210,7 +216,7 @@ describe('Journey class', () => {
 			const journey = new Journey(constructorArgs);
 			journey.sections = mockSections;
 
-			const question = journey.getQuestionBySectionAndName('a', 'b');
+			const question = journey.getQuestionByParams({ section: 'a', question: 'b' });
 
 			assert.strictEqual(question, undefined);
 		});
@@ -219,7 +225,7 @@ describe('Journey class', () => {
 			const journey = new Journey(constructorArgs);
 			journey.sections = mockSections;
 
-			const question = journey.getQuestionBySectionAndName(mockSections[0].segment, 'nope');
+			const question = journey.getQuestionByParams({ section: mockSections[0].segment, question: 'nope' });
 
 			assert.strictEqual(question, undefined);
 		});
@@ -294,7 +300,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = returnToListing;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section, name, false);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section, question: name }, false);
 
 				assert.strictEqual(nextQuestionUrl, null);
 			});
@@ -309,7 +315,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = returnToListing;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section, name, false);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section, question: name }, false);
 
 				assert.strictEqual(nextQuestionUrl, null);
 			});
@@ -325,7 +331,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = returnToListing;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, false);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, false);
 
 				assert.strictEqual(nextQuestionUrl, `${constructorArgs.makeBaseUrl()}/${section.segment}/${nextQuestionName}`);
 			});
@@ -350,7 +356,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = returnToListing;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, false);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, false);
 
 				assert.strictEqual(nextQuestionUrl, `${constructorArgs.makeBaseUrl()}/${section.segment}/${nextQuestionName}`);
 			});
@@ -366,7 +372,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = returnToListing;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, true);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, true);
 
 				assert.strictEqual(nextQuestionUrl, `${constructorArgs.makeBaseUrl()}/${section.segment}/${prevQuestionName}`);
 			});
@@ -381,7 +387,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = returnToListing;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, false);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, false);
 
 				assert.strictEqual(nextQuestionUrl, null);
 			});
@@ -398,7 +404,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = false;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, true);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, true);
 
 				assert.strictEqual(
 					nextQuestionUrl,
@@ -416,7 +422,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = returnToListing;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, true);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, true);
 
 				assert.strictEqual(nextQuestionUrl, null);
 			});
@@ -431,7 +437,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = true;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, false);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, false);
 				assert.strictEqual(nextQuestionUrl, null);
 			});
 		}
@@ -445,7 +451,7 @@ describe('Journey class', () => {
 				journey.sections = mockSections;
 				journey.returnToListing = true;
 
-				const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, true);
+				const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, true);
 
 				assert.strictEqual(nextQuestionUrl, null);
 			});
@@ -460,7 +466,7 @@ describe('Journey class', () => {
 			const journey = new Journey(constructorArgs);
 			journey.sections = mockSections;
 
-			const nextQuestionUrl = journey.getNextQuestionUrl(section.segment, name, false);
+			const nextQuestionUrl = journey.getNextQuestionUrl({ section: section.segment, question: name }, false);
 
 			assert.strictEqual(nextQuestionUrl, `base/${section.segment}/${nextQuestionName}?id=1`);
 		});

package/src/lib/uuid.js

@@ -0,0 +1,10 @@
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Wrapper class so it can be overridden by test mocks
+ */
+export class Uuid {
+	static randomUUID() {
+		return randomUUID();
+	}
+}

package/src/lib/uuid.test.js

@@ -0,0 +1,24 @@
+import { Uuid } from '#src/lib/uuid.js';
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+/**
+ *
+ * @param {import('node:test').TestContext} ctx
+ * @param {string} [uuid]
+ */
+export function mockRandomUUID(ctx, uuid = '00000000-0000-0000-0000-000000000000') {
+	const original = Uuid.randomUUID;
+	Uuid.randomUUID = ctx.mock.fn(() => uuid);
+	// restore after the tests
+	ctx.after(() => (Uuid.randomUUID = original));
+}
+
+describe('uuid', () => {
+	it('should return a valid v4 UUID', () => {
+		assert.match(
+			Uuid.randomUUID(),
+			/^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$/
+		);
+	});
+});

package/src/middleware/dynamic-req-files-to-req-body-files.js

@@ -16,10 +16,9 @@ export default () => (req, res, next) => {
 		return next();
 	}
 
-	const { section, question } = req.params;
 	const { journey } = res.locals;
 
-	const questionObj = journey.getQuestionBySectionAndName(section, question);
+	const questionObj = journey.getQuestionByParams(req.params);
 	const filesPropertyPath = questionObj.fieldName;
 
 	if (typeof req.files[filesPropertyPath] === 'undefined') {

package/src/middleware/dynamic-req-files-to-req-body-files.test.js

@@ -8,7 +8,7 @@ describe('dynamic-forms/middleware/dynamic-req-files-to-req-body-files', () => {
 	let mockRes;
 	let filesPropertyPath = `example-files-property-path-${counter}`;
 
-	const mockGetQuestionBySectionAndName = mock.fn(() => {
+	const mockgetQuestionByParams = mock.fn(() => {
 		return { fieldName: filesPropertyPath };
 	});
 
@@ -24,7 +24,7 @@ describe('dynamic-forms/middleware/dynamic-req-files-to-req-body-files', () => {
 			cookie: mock.fn(),
 			locals: {
 				journeyResponse: mock.fn(),
-				journey: { getQuestionBySectionAndName: mockGetQuestionBySectionAndName }
+				journey: { getQuestionByParams: mockgetQuestionByParams }
 			},
 			redirect: mock.fn(),
 			render: mock.fn(),

package/src/questions/question.js

@@ -279,19 +279,20 @@ export class Question {
 	}
 
 	/**
-	 * Handles redirect after saving
+	 * Handles redirect after saving. Kept around for backwards compatibility.
+	 *
 	 * @param {import('express').Response} res
 	 * @param {Journey} journey
 	 * @param {string} sectionSegment
 	 * @param {string} questionSegment
 	 * @returns {void}
+	 * @deprecated - use `journey.redirectToNextQuestion`
 	 */
 	handleNextQuestion(res, journey, sectionSegment, questionSegment) {
-		let next = journey.getNextQuestionUrl(sectionSegment, questionSegment);
-		if (next === null) {
-			next = journey.taskListUrl;
-		}
-		return res.redirect(next);
+		return journey.redirectToNextQuestion(res, {
+			section: sectionSegment,
+			question: questionSegment
+		});
 	}
 
 	/**

package/src/section.js

@@ -5,7 +5,13 @@
  */
 
 import RequiredValidator from './validator/required-validator.js';
-import MultiFieldInputQuestion from './components/multi-field-input/question.js';
+
+/**
+ * A value indicating the final question of a section has been reached
+ *
+ * @type {Symbol}
+ */
+export const END_OF_SECTION = Symbol('END_OF_SECTION');
 
 /**
  * Defines a section for a questionnaire, a set of Questions
@@ -184,6 +190,35 @@ export class Section {
 		return this;
 	}
 
+	/**
+	 * Get the next question in this section given a questionParam (question fieldName)
+	 * @param {Object} params
+	 * @param {string} params.questionFieldName
+	 * @param {import('#src/journey/journey-response.js').JourneyResponse} params.response
+	 * @param {boolean} [params.takeNextQuestion]
+	 * @param {boolean} [params.reverse]
+	 * @returns {Question|Symbol|null}
+	 */
+	getNextQuestion({ questionFieldName, response, takeNextQuestion = false, reverse = false }) {
+		const numberOfQuestions = this.questions.length;
+
+		const questionsStart = reverse ? numberOfQuestions - 1 : 0;
+		for (let i = questionsStart; reverse ? i >= 0 : i < numberOfQuestions; reverse ? i-- : i++) {
+			const question = this.questions[i];
+			if (takeNextQuestion && question.shouldDisplay(response)) {
+				return question;
+			}
+
+			if (question.fieldName === questionFieldName) {
+				takeNextQuestion = true;
+			}
+		}
+		if (takeNextQuestion) {
+			return END_OF_SECTION;
+		}
+		return null;
+	}
+
 	/**
 	 * checks answers on response to ensure that a answer is provided for each required question in the section
 	 * @param {JourneyResponse} journeyResponse
@@ -200,7 +235,7 @@ export class Section {
 				continue;
 			}
 			// if question is a multi field input question, check all fields
-			if (question instanceof MultiFieldInputQuestion) {
+			if (question.inputFields) {
 				for (const field of question.inputFields) {
 					if (question.fieldIsRequired(field.fieldName)) {
 						requiredQuestionCount++;

package/src/section.test.js

@@ -1,6 +1,6 @@
 import { describe, it, mock } from 'node:test';
 import assert from 'node:assert';
-import { Section, SECTION_STATUS } from './section.js';
+import { END_OF_SECTION, Section, SECTION_STATUS } from './section.js';
 import RequiredValidator from './validator/required-validator.js';
 
 const mockQuestion = {
@@ -17,6 +17,13 @@ const mockQuestion2 = {
 	isAnswered: () => false
 };
 
+const mockQuestion3 = {
+	fieldName: 'mockQuestion3',
+	isRequired: () => true,
+	shouldDisplay: () => true,
+	isAnswered: () => false
+};
+
 describe('./src/dynamic-forms/section.js', () => {
 	describe('constructor', () => {
 		it('should create', () => {
@@ -575,4 +582,83 @@ describe('./src/dynamic-forms/section.js', () => {
 			assert.throws(() => section.withRequiredCondition(false));
 		});
 	});
+
+	describe('getNextQuestion', () => {
+		const newSection = () => {
+			const q1 = { ...mockQuestion };
+			const q2 = { ...mockQuestion2 };
+			const q3 = { ...mockQuestion3 };
+			const section = new Section('s1', 'S').addQuestion(q1).addQuestion(q2).addQuestion(q3);
+			return { section, q1, q2, q3 };
+		};
+
+		it('should take the first question if takeNextQuestion is set', () => {
+			const { section, q1 } = newSection();
+			const next = section.getNextQuestion({
+				questionFieldName: '',
+				response: {},
+				takeNextQuestion: true,
+				reverse: false
+			});
+			assert.strictEqual(next, q1);
+		});
+		it('should take second question if first is matched', () => {
+			const { section, q1, q2 } = newSection();
+			const next = section.getNextQuestion({
+				questionFieldName: q1.fieldName,
+				response: {},
+				takeNextQuestion: false,
+				reverse: false
+			});
+			assert.strictEqual(next, q2);
+		});
+		it('should return END_OF_SECTION if last question matched', () => {
+			const { section, q3 } = newSection();
+			const next = section.getNextQuestion({
+				questionFieldName: q3.fieldName,
+				response: {},
+				takeNextQuestion: false,
+				reverse: false
+			});
+			assert.strictEqual(next, END_OF_SECTION);
+		});
+		it('should return null if no questions match', () => {
+			const { section } = newSection();
+			const next = section.getNextQuestion({
+				questionFieldName: 'random-field-name',
+				response: {},
+				takeNextQuestion: false,
+				reverse: false
+			});
+			assert.strictEqual(next, null);
+		});
+		it('should return question only if it "shouldDisplay"', () => {
+			const { section, q1, q2, q3 } = newSection();
+			// skip q2
+			q2.shouldDisplay = mock.fn(() => false);
+			const next = section.getNextQuestion({
+				questionFieldName: q1.fieldName,
+				response: {},
+				takeNextQuestion: false,
+				reverse: false
+			});
+			assert.strictEqual(q2.shouldDisplay.mock.callCount(), 1);
+			assert.strictEqual(next, q3);
+		});
+		it(`should return END_OF_SECTION if remaining questions shouldn't display`, () => {
+			const { section, q1, q2, q3 } = newSection();
+			// skip q2 & q3
+			q2.shouldDisplay = mock.fn(() => false);
+			q3.shouldDisplay = mock.fn(() => false);
+			const next = section.getNextQuestion({
+				questionFieldName: q1.fieldName,
+				response: {},
+				takeNextQuestion: false,
+				reverse: false
+			});
+			assert.strictEqual(q2.shouldDisplay.mock.callCount(), 1);
+			assert.strictEqual(q3.shouldDisplay.mock.callCount(), 1);
+			assert.strictEqual(next, END_OF_SECTION);
+		});
+	});
 });

package/src/validator/validator.js

@@ -2,11 +2,9 @@ import { validationResult } from 'express-validator';
 
 /** @type {import('express').Handler} */
 const validate = async (req, res, next) => {
-	const { section, question } = req.params;
-
 	const { journey, journeyResponse } = res.locals;
 
-	const questionObj = journey.getQuestionBySectionAndName(section, question);
+	const questionObj = journey.getQuestionByParams(req.params);
 	if (!questionObj) {
 		throw new Error('unknown question type');
 	}

package/src/validator/validator.test.js

@@ -12,7 +12,7 @@ describe('./src/dynamic-forms/validator/validator.js', () => {
 			locals: {
 				journeyResponse: {},
 				journey: {
-					getQuestionBySectionAndName: function () {
+					getQuestionByParams: function () {
 						return null;
 					}
 				}
@@ -50,7 +50,7 @@ describe('./src/dynamic-forms/validator/validator.js', () => {
 		};
 
 		mockRes.locals.journey = {
-			getQuestionBySectionAndName: function () {
+			getQuestionByParams: function () {
 				return {
 					validators: [new RequiredValidator()],
 					fieldName: 'field1'
@@ -78,7 +78,7 @@ describe('./src/dynamic-forms/validator/validator.js', () => {
 		};
 
 		mockRes.locals.journey = {
-			getQuestionBySectionAndName: function () {
+			getQuestionByParams: function () {
 				return {
 					validators: [new RequiredValidator()],
 					fieldName: 'field1'
@@ -106,7 +106,7 @@ describe('./src/dynamic-forms/validator/validator.js', () => {
 		};
 
 		mockRes.locals.journey = {
-			getQuestionBySectionAndName: function () {
+			getQuestionByParams: function () {
 				return {
 					validators: [new RequiredValidator()],
 					fieldName: 'field1'
@@ -133,7 +133,7 @@ describe('./src/dynamic-forms/validator/validator.js', () => {
 		};
 
 		mockRes.locals.journey = {
-			getQuestionBySectionAndName: function () {
+			getQuestionByParams: function () {
 				return {
 					validators: [new RequiredValidator(), new ValidOptionValidator()],
 					fieldName: 'field1',
@@ -174,7 +174,7 @@ describe('./src/dynamic-forms/validator/validator.js', () => {
 		};
 
 		mockRes.locals.journey = {
-			getQuestionBySectionAndName: function () {
+			getQuestionByParams: function () {
 				return {
 					validators: [new RequiredValidator(), new ValidOptionValidator()],
 					fieldName: 'field1',
@@ -217,7 +217,7 @@ describe('./src/dynamic-forms/validator/validator.js', () => {
 		};
 
 		mockRes.locals.journey = {
-			getQuestionBySectionAndName: function () {
+			getQuestionByParams: function () {
 				return {
 					validators: [new AddressValidator()],
 					fieldName: 'field1'

package/test/questions.test.js

@@ -42,18 +42,25 @@ export async function createAppWithQuestions(ctx) {
 
 	app.get('/check-your-answers', getJourneyResponse, getJourney, (req, res) => list(req, res, '', {}));
 
-	app.use((error, req, res, next) => {
-		if (error) {
-			console.error('Internal Server Error:', error);
-		}
-		next();
-	});
-
 	app.use((req, res) => {
 		res.status(404);
 	});
 
-	const server = new TestServer(app, { rememberCookies: true });
+	/**
+	 * @type {import('express').ErrorRequestHandler}
+	 */
+	function errorHandler(error, req, res, next) {
+		console.error('Internal Server Error:', error);
+		if (res.headersSent) {
+			return next(error);
+		}
+		res.status(500);
+		res.render('error', { error });
+	}
+
+	app.use(errorHandler);
+
+	const server = new TestServer(app, { rememberCookies: true, timeoutMs: 2000 });
 	await server.start();
 	ctx.after(async () => await server.stop());
 	return server;

package/test/utils/test-server.js

@@ -8,10 +8,12 @@ export class TestServer {
 	// Private cookie jar for storing cookies between requests
 	/** @type {Object<string, string>} */
 	#cookieJar = {};
+	#timeoutMs;
 
 	/**
 	 * @param {import('http').RequestListener} requestListener
 	 * @param {object} [options]
+	 * @param {number} [options.timeoutMs] - timeout to use for fetch requests
 	 * @param {boolean} [options.rememberCookies] - If true, cookies are stored and sent with each request
 	 */
 	constructor(requestListener, options = {}) {
@@ -19,6 +21,7 @@ export class TestServer {
 		this.server = null;
 		this.port = null;
 		this.rememberCookies = Boolean(options.rememberCookies);
+		this.#timeoutMs = options.timeoutMs || 5000;
 	}
 
 	/**
@@ -66,11 +69,7 @@ export class TestServer {
 		}
 		const fetchOptions = { headers: {}, ...DEFAULT_OPTIONS, ...options, method: 'GET' };
 		this.#addCookies(fetchOptions.headers);
-		const response = await fetch(`http://localhost:${this.port}${path}`, fetchOptions);
-		if (this.rememberCookies) {
-			this.#updateCookies(response);
-		}
-		return response;
+		return this.#fetch(path, fetchOptions);
 	}
 
 	/**
@@ -131,11 +130,34 @@ export class TestServer {
 			body: JSON.stringify(body)
 		};
 		this.#addCookies(fetchOptions.headers);
-		const response = await fetch(`http://localhost:${this.port}${path}`, fetchOptions);
-		if (this.rememberCookies) {
-			this.#updateCookies(response);
+		return this.#fetch(path, fetchOptions);
+	}
+
+	/**
+	 * Perform a fetch request with a timeout
+	 *
+	 * @param {string} path
+	 * @param {RequestInit} [options]
+	 */
+	async #fetch(path, options) {
+		// set up an abort controller to cancel requests after timeout
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.#timeoutMs);
+		options.signal = controller.signal;
+		try {
+			const response = await fetch(`http://localhost:${this.port}${path}`, options);
+			if (this.rememberCookies) {
+				this.#updateCookies(response);
+			}
+			return response;
+		} catch (error) {
+			if (error instanceof Error && error.name === 'AbortError') {
+				throw new Error(`Request to ${path} timed out after ${this.#timeoutMs}ms`);
+			}
+			throw error;
+		} finally {
+			clearTimeout(timeoutId);
 		}
-		return response;
 	}
 
 	#addCookies(headers) {

package/test/utils/utils.js

@@ -28,7 +28,8 @@ export function mockLogger() {
 export const mockReq = () => ({
 	log: mockLogger(),
 	params: {},
-	body: {}
+	body: {},
+	originalUrl: '/original-url'
 });
 export const mockRes = () => {
 	const res = {

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+	"include": ["**/*.ts", "**/*.js"],
+	"exclude": ["node_modules", "packages/database/src/client/**", "**/*.test.ts", "test/**"],
+	"compilerOptions": {
+		"allowImportingTsExtensions": true,
+		"allowJs": true,
+		"allowSyntheticDefaultImports": true,
+		"baseUrl": ".",
+		"checkJs": false,
+		"erasableSyntaxOnly": true,
+		"esModuleInterop": true,
+		"module": "NodeNext",
+		"moduleResolution": "nodenext",
+		"strict": true,
+		"target": "esnext",
+		"skipLibCheck": true,
+		"paths": {
+			"#question-types": ["./src/questions/question-types.d.ts"],
+			"#src/*": ["./src/*"],
+			"#test/*": ["./test/*"]
+		}
+	}
+}