@defra/forms-engine-plugin 1.4.1 → 2.0.0

package/.server/server/plugins/engine/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":["UploadStatus","FileStatus"],"sources":["../../../../src/server/plugins/engine/types.ts"],"sourcesContent":["import {\n  type ComponentDef,\n  type Event,\n  type FormDefinition,\n  type FormMetadata,\n  type Item,\n  type List,\n  type Page\n} from '@defra/forms-model'\nimport { type PluginProperties, type Request } from '@hapi/hapi'\nimport { type JoiExpression, type ValidationErrorItem } from 'joi'\n\nimport { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'\nimport { type Component } from '~/src/server/plugins/engine/components/helpers.js'\nimport {\n  type BackLink,\n  type ComponentText,\n  type ComponentViewModel\n} from '~/src/server/plugins/engine/components/types.js'\nimport { type FormModel } from '~/src/server/plugins/engine/models/index.js'\nimport { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'\nimport { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'\nimport { type ViewContext } from '~/src/server/plugins/nunjucks/types.js'\nimport {\n  type FormAction,\n  type FormParams,\n  type FormRequest,\n  type FormRequestPayload\n} from '~/src/server/routes/types.js'\nimport { type RequestOptions } from '~/src/server/services/httpService.js'\nimport { type Services } from '~/src/server/types.js'\n\ntype RequestType = Request | FormRequest | FormRequestPayload\n\n/**\n * Form submission state stores the following in Redis:\n * Props containing user's submitted values as `{ [inputId]: value }` or as `{ [sectionName]: { [inputName]: value } }`\n *   a) . e.g:\n * ```ts\n *     {\n *       _C9PRHmsgt: 'Ben',\n *       WfLk9McjzX: 'Music',\n *       IK7jkUFCBL: 'Royal Academy of Music'\n *     }\n * ```\n *\n *   b)\n * ```ts\n *   {\n *         checkBeforeYouStart: { ukPassport: true },\n *         applicantDetails: {\n *           numberOfApplicants: 1,\n *           phoneNumber: '77777777',\n *           emailAddress: 'aaa@aaa.com'\n *         },\n *         applicantOneDetails: {\n *           firstName: 'a',\n *           middleName: 'a',\n *           lastName: 'a',\n *           address: { addressLine1: 'a', addressLine2: 'a', town: 'a', postcode: 'a' }\n *         }\n *     }\n * ```\n */\n\n/**\n * Form submission state\n */\nexport type FormSubmissionState = {\n  upload?: Record<string, TempFileState>\n} & FormState\n\nexport interface FormSubmissionError\n  extends Pick<ValidationErrorItem, 'context' | 'path'> {\n  href: string // e.g: '#dateField__day'\n  name: string // e.g: 'dateField__day'\n  text: string // e.g: 'Date field must be a real date'\n}\n\nexport interface FormPayloadParams {\n  action?: FormAction\n  confirm?: true\n  crumb?: string\n  itemId?: string\n}\n\n/**\n * Form POST for question pages\n * (after Joi has converted value types)\n */\nexport type FormPayload = FormPayloadParams & Partial<Record<string, FormValue>>\n\nexport type FormValue =\n  | Item['value']\n  | Item['value'][]\n  | UploadState\n  | RepeatListState\n  | undefined\n\nexport type FormState = Partial<Record<string, FormStateValue>>\nexport type FormStateValue = Exclude<FormValue, undefined> | null\n\nexport interface FormValidationResult<\n  ValueType extends FormPayload | FormSubmissionState\n> {\n  value: ValueType\n  errors: FormSubmissionError[] | undefined\n}\n\nexport interface FormContext {\n  /**\n   * Evaluation form state only (filtered by visited paths),\n   * with values formatted for condition evaluation using\n   * {@link FormComponent.getContextValueFromState}\n   */\n  evaluationState: FormState\n\n  /**\n   * Relevant form state only (filtered by visited paths)\n   */\n  relevantState: FormState\n\n  /**\n   * Relevant pages only (filtered by visited paths)\n   */\n  relevantPages: PageControllerClass[]\n\n  /**\n   * Form submission payload (single page)\n   */\n  payload: FormPayload\n\n  /**\n   * Form submission state (entire form)\n   */\n  state: FormSubmissionState\n\n  /**\n   * Validation errors (entire form)\n   */\n  errors?: FormSubmissionError[]\n\n  /**\n   * Visited paths evaluated from form state\n   */\n  paths: string[]\n\n  /**\n   * Preview URL direct access is allowed\n   */\n  isForceAccess: boolean\n\n  /**\n   * Miscellaneous extra data from event responses\n   */\n  data: object\n\n  pageDefMap: Map<string, Page>\n  listDefMap: Map<string, List>\n  componentDefMap: Map<string, ComponentDef>\n  pageMap: Map<string, PageControllerClass>\n  componentMap: Map<string, Component>\n  referenceNumber: string\n}\n\nexport type FormContextRequest = (\n  | {\n      method: 'get'\n      payload?: undefined\n    }\n  | {\n      method: 'post'\n      payload: FormPayload\n    }\n  | {\n      method: FormRequest['method']\n      payload?: object | undefined\n    }\n) &\n  Pick<FormRequest, 'app' | 'method' | 'params' | 'path' | 'query' | 'url'>\n\nexport interface UploadInitiateResponse {\n  uploadId: string\n  uploadUrl: string\n  statusUrl: string\n}\n\nexport enum UploadStatus {\n  initiated = 'initiated',\n  pending = 'pending',\n  ready = 'ready'\n}\n\nexport enum FileStatus {\n  complete = 'complete',\n  rejected = 'rejected',\n  pending = 'pending'\n}\n\nexport type UploadState = FileState[]\n\nexport type FileUpload = {\n  fileId: string\n  filename: string\n  contentLength: number\n} & (\n  | {\n      fileStatus: FileStatus.complete | FileStatus.rejected | FileStatus.pending\n      errorMessage?: string\n    }\n  | {\n      fileStatus: FileStatus.complete\n      errorMessage?: undefined\n    }\n)\n\nexport interface FileUploadMetadata {\n  retrievalKey: string\n}\n\nexport type UploadStatusResponse =\n  | {\n      uploadStatus: UploadStatus.initiated\n      metadata: FileUploadMetadata\n      form: { file?: undefined }\n    }\n  | {\n      uploadStatus: UploadStatus.pending | UploadStatus.ready\n      metadata: FileUploadMetadata\n      form: { file: FileUpload }\n      numberOfRejectedFiles?: number\n    }\n  | {\n      uploadStatus: UploadStatus.ready\n      metadata: FileUploadMetadata\n      form: { file: FileUpload }\n      numberOfRejectedFiles: 0\n    }\n\nexport type UploadStatusFileResponse = Exclude<\n  UploadStatusResponse,\n  { uploadStatus: UploadStatus.initiated }\n>\n\nexport interface FileState {\n  uploadId: string\n  status: UploadStatusFileResponse\n}\n\nexport interface TempFileState {\n  upload?: UploadInitiateResponse\n  files: UploadState\n}\n\nexport interface RepeatItemState extends FormPayload {\n  itemId: string\n}\n\nexport type RepeatListState = RepeatItemState[]\n\nexport interface CheckAnswers {\n  title?: ComponentText\n  summaryList: SummaryList\n}\n\nexport interface SummaryList {\n  classes?: string\n  rows: SummaryListRow[]\n}\n\nexport interface SummaryListRow {\n  key: ComponentText\n  value: ComponentText\n  actions?: { items: SummaryListAction[] }\n}\n\nexport type SummaryListAction = ComponentText & {\n  href: string\n  visuallyHiddenText: string\n}\n\nexport interface PageViewModelBase extends Partial<ViewContext> {\n  page: PageController\n  name?: string\n  pageTitle: string\n  sectionTitle?: string\n  showTitle: boolean\n  isStartPage: boolean\n  backLink?: BackLink\n  feedbackLink?: string\n  serviceUrl: string\n  phaseTag?: string\n}\n\nexport interface ItemDeletePageViewModel extends PageViewModelBase {\n  context: FormContext\n  itemTitle: string\n  confirmation?: ComponentText\n  buttonConfirm: ComponentText\n  buttonCancel: ComponentText\n}\n\nexport interface FormPageViewModel extends PageViewModelBase {\n  components: ComponentViewModel[]\n  context: FormContext\n  errors?: FormSubmissionError[]\n  hasMissingNotificationEmail?: boolean\n  allowSaveAndReturn?: boolean\n}\n\nexport interface RepeaterSummaryPageViewModel extends PageViewModelBase {\n  context: FormContext\n  errors?: FormSubmissionError[]\n  checkAnswers: CheckAnswers[]\n  repeatTitle: string\n}\n\nexport interface FeaturedFormPageViewModel extends FormPageViewModel {\n  formAction?: string\n  formComponent: ComponentViewModel\n  componentsBefore: ComponentViewModel[]\n  uploadId: string | undefined\n  proxyUrl: string | null\n}\n\nexport type PageViewModel =\n  | PageViewModelBase\n  | ItemDeletePageViewModel\n  | FormPageViewModel\n  | RepeaterSummaryPageViewModel\n  | FeaturedFormPageViewModel\n\nexport type GlobalFunction = (value: unknown) => unknown\nexport type FilterFunction = (value: unknown) => unknown\nexport interface ErrorMessageTemplate {\n  type: string\n  template: JoiExpression\n}\n\nexport interface ErrorMessageTemplateList {\n  baseErrors: ErrorMessageTemplate[]\n  advancedSettingsErrors: ErrorMessageTemplate[]\n}\n\nexport type PreparePageEventRequestOptions = (\n  options: RequestOptions,\n  event: Event,\n  page: PageControllerClass,\n  context: FormContext\n) => void\n\nexport type OnRequestCallback = (\n  request: FormRequest | FormRequestPayload,\n  params: FormParams,\n  definition: FormDefinition,\n  metadata: FormMetadata\n) => void\n\nexport interface PluginOptions {\n  model?: FormModel\n  services?: Services\n  controllers?: Record<string, typeof PageController>\n  cacheName?: string\n  globals?: Record<string, GlobalFunction>\n  filters?: Record<string, FilterFunction>\n  keyGenerator?: (request: RequestType) => string\n  sessionHydrator?: (request: RequestType) => Promise<FormSubmissionState>\n  sessionPersister?: (\n    key: string,\n    state: FormSubmissionState,\n    request: RequestType\n  ) => Promise<void>\n  pluginPath?: string\n  nunjucks: {\n    baseLayoutPath: string\n    paths: string[]\n  }\n  viewContext: PluginProperties['forms-engine-plugin']['viewContext']\n  preparePageEventRequestOptions?: PreparePageEventRequestOptions\n  onRequest?: OnRequestCallback\n  baseUrl: string // base URL of the application, protocol and hostname e.g. \"https://myapp.com\"\n}\n"],"mappings":"AAkCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;;AAmBA;AACA;AACA;AACA;;AAkGA,WAAYA,YAAY,0BAAZA,YAAY;EAAZA,YAAY;EAAZA,YAAY;EAAZA,YAAY;EAAA,OAAZA,YAAY;AAAA;AAMxB,WAAYC,UAAU,0BAAVA,UAAU;EAAVA,UAAU;EAAVA,UAAU;EAAVA,UAAU;EAAA,OAAVA,UAAU;AAAA","ignoreList":[]}
+{"version":3,"file":"types.js","names":["UploadStatus","FileStatus"],"sources":["../../../../src/server/plugins/engine/types.ts"],"sourcesContent":["import {\n  type ComponentDef,\n  type Event,\n  type FormDefinition,\n  type FormMetadata,\n  type Item,\n  type List,\n  type Page\n} from '@defra/forms-model'\nimport { type PluginProperties, type Request } from '@hapi/hapi'\nimport { type JoiExpression, type ValidationErrorItem } from 'joi'\n\nimport { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'\nimport { type Component } from '~/src/server/plugins/engine/components/helpers.js'\nimport {\n  type BackLink,\n  type ComponentText,\n  type ComponentViewModel\n} from '~/src/server/plugins/engine/components/types.js'\nimport { type FormModel } from '~/src/server/plugins/engine/models/index.js'\nimport { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'\nimport { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'\nimport { type ViewContext } from '~/src/server/plugins/nunjucks/types.js'\nimport {\n  type FormAction,\n  type FormParams,\n  type FormRequest,\n  type FormRequestPayload\n} from '~/src/server/routes/types.js'\nimport { type RequestOptions } from '~/src/server/services/httpService.js'\nimport { type Services } from '~/src/server/types.js'\n\ntype RequestType = Request | FormRequest | FormRequestPayload\n\n/**\n * Form submission state stores the following in Redis:\n * Props containing user's submitted values as `{ [inputId]: value }` or as `{ [sectionName]: { [inputName]: value } }`\n *   a) . e.g:\n * ```ts\n *     {\n *       _C9PRHmsgt: 'Ben',\n *       WfLk9McjzX: 'Music',\n *       IK7jkUFCBL: 'Royal Academy of Music'\n *     }\n * ```\n *\n *   b)\n * ```ts\n *   {\n *         checkBeforeYouStart: { ukPassport: true },\n *         applicantDetails: {\n *           numberOfApplicants: 1,\n *           phoneNumber: '77777777',\n *           emailAddress: 'aaa@aaa.com'\n *         },\n *         applicantOneDetails: {\n *           firstName: 'a',\n *           middleName: 'a',\n *           lastName: 'a',\n *           address: { addressLine1: 'a', addressLine2: 'a', town: 'a', postcode: 'a' }\n *         }\n *     }\n * ```\n */\n\n/**\n * Form submission state\n */\nexport type FormSubmissionState = {\n  upload?: Record<string, TempFileState>\n} & FormState\n\nexport interface FormSubmissionError\n  extends Pick<ValidationErrorItem, 'context' | 'path'> {\n  href: string // e.g: '#dateField__day'\n  name: string // e.g: 'dateField__day'\n  text: string // e.g: 'Date field must be a real date'\n}\n\nexport interface FormPayloadParams {\n  action?: FormAction\n  confirm?: true\n  crumb?: string\n  itemId?: string\n}\n\n/**\n * Form POST for question pages\n * (after Joi has converted value types)\n */\nexport type FormPayload = FormPayloadParams & Partial<Record<string, FormValue>>\n\nexport type FormValue =\n  | Item['value']\n  | Item['value'][]\n  | UploadState\n  | RepeatListState\n  | undefined\n\nexport type FormState = Partial<Record<string, FormStateValue>>\nexport type FormStateValue = Exclude<FormValue, undefined> | null\n\nexport interface FormValidationResult<\n  ValueType extends FormPayload | FormSubmissionState\n> {\n  value: ValueType\n  errors: FormSubmissionError[] | undefined\n}\n\nexport interface FormContext {\n  /**\n   * Evaluation form state only (filtered by visited paths),\n   * with values formatted for condition evaluation using\n   * {@link FormComponent.getContextValueFromState}\n   */\n  evaluationState: FormState\n\n  /**\n   * Relevant form state only (filtered by visited paths)\n   */\n  relevantState: FormState\n\n  /**\n   * Relevant pages only (filtered by visited paths)\n   */\n  relevantPages: PageControllerClass[]\n\n  /**\n   * Form submission payload (single page)\n   */\n  payload: FormPayload\n\n  /**\n   * Form submission state (entire form)\n   */\n  state: FormSubmissionState\n\n  /**\n   * Validation errors (entire form)\n   */\n  errors?: FormSubmissionError[]\n\n  /**\n   * Visited paths evaluated from form state\n   */\n  paths: string[]\n\n  /**\n   * Preview URL direct access is allowed\n   */\n  isForceAccess: boolean\n\n  /**\n   * Miscellaneous extra data from event responses\n   */\n  data: object\n\n  pageDefMap: Map<string, Page>\n  listDefMap: Map<string, List>\n  componentDefMap: Map<string, ComponentDef>\n  pageMap: Map<string, PageControllerClass>\n  componentMap: Map<string, Component>\n  referenceNumber: string\n}\n\nexport type FormContextRequest = (\n  | {\n      method: 'get'\n      payload?: undefined\n    }\n  | {\n      method: 'post'\n      payload: FormPayload\n    }\n  | {\n      method: FormRequest['method']\n      payload?: object | undefined\n    }\n) &\n  Pick<\n    FormRequest,\n    'app' | 'method' | 'params' | 'path' | 'query' | 'url' | 'server'\n  >\n\nexport interface UploadInitiateResponse {\n  uploadId: string\n  uploadUrl: string\n  statusUrl: string\n}\n\nexport enum UploadStatus {\n  initiated = 'initiated',\n  pending = 'pending',\n  ready = 'ready'\n}\n\nexport enum FileStatus {\n  complete = 'complete',\n  rejected = 'rejected',\n  pending = 'pending'\n}\n\nexport type UploadState = FileState[]\n\nexport type FileUpload = {\n  fileId: string\n  filename: string\n  contentLength: number\n} & (\n  | {\n      fileStatus: FileStatus.complete | FileStatus.rejected | FileStatus.pending\n      errorMessage?: string\n    }\n  | {\n      fileStatus: FileStatus.complete\n      errorMessage?: undefined\n    }\n)\n\nexport interface FileUploadMetadata {\n  retrievalKey: string\n}\n\nexport type UploadStatusResponse =\n  | {\n      uploadStatus: UploadStatus.initiated\n      metadata: FileUploadMetadata\n      form: { file?: undefined }\n    }\n  | {\n      uploadStatus: UploadStatus.pending | UploadStatus.ready\n      metadata: FileUploadMetadata\n      form: { file: FileUpload }\n      numberOfRejectedFiles?: number\n    }\n  | {\n      uploadStatus: UploadStatus.ready\n      metadata: FileUploadMetadata\n      form: { file: FileUpload }\n      numberOfRejectedFiles: 0\n    }\n\nexport type UploadStatusFileResponse = Exclude<\n  UploadStatusResponse,\n  { uploadStatus: UploadStatus.initiated }\n>\n\nexport interface FileState {\n  uploadId: string\n  status: UploadStatusFileResponse\n}\n\nexport interface TempFileState {\n  upload?: UploadInitiateResponse\n  files: UploadState\n}\n\nexport interface RepeatItemState extends FormPayload {\n  itemId: string\n}\n\nexport type RepeatListState = RepeatItemState[]\n\nexport interface CheckAnswers {\n  title?: ComponentText\n  summaryList: SummaryList\n}\n\nexport interface SummaryList {\n  classes?: string\n  rows: SummaryListRow[]\n}\n\nexport interface SummaryListRow {\n  key: ComponentText\n  value: ComponentText\n  actions?: { items: SummaryListAction[] }\n}\n\nexport type SummaryListAction = ComponentText & {\n  href: string\n  visuallyHiddenText: string\n}\n\nexport interface PageViewModelBase extends Partial<ViewContext> {\n  page: PageController\n  name?: string\n  pageTitle: string\n  sectionTitle?: string\n  showTitle: boolean\n  isStartPage: boolean\n  backLink?: BackLink\n  feedbackLink?: string\n  serviceUrl: string\n  phaseTag?: string\n}\n\nexport interface ItemDeletePageViewModel extends PageViewModelBase {\n  context: FormContext\n  itemTitle: string\n  confirmation?: ComponentText\n  buttonConfirm: ComponentText\n  buttonCancel: ComponentText\n}\n\nexport interface FormPageViewModel extends PageViewModelBase {\n  components: ComponentViewModel[]\n  context: FormContext\n  errors?: FormSubmissionError[]\n  hasMissingNotificationEmail?: boolean\n  allowSaveAndReturn: boolean\n}\n\nexport interface RepeaterSummaryPageViewModel extends PageViewModelBase {\n  context: FormContext\n  errors?: FormSubmissionError[]\n  checkAnswers: CheckAnswers[]\n  repeatTitle: string\n}\n\nexport interface FeaturedFormPageViewModel extends FormPageViewModel {\n  formAction?: string\n  formComponent: ComponentViewModel\n  componentsBefore: ComponentViewModel[]\n  uploadId: string | undefined\n  proxyUrl: string | null\n}\n\nexport type PageViewModel =\n  | PageViewModelBase\n  | ItemDeletePageViewModel\n  | FormPageViewModel\n  | RepeaterSummaryPageViewModel\n  | FeaturedFormPageViewModel\n\nexport type GlobalFunction = (value: unknown) => unknown\nexport type FilterFunction = (value: unknown) => unknown\nexport interface ErrorMessageTemplate {\n  type: string\n  template: JoiExpression\n}\n\nexport interface ErrorMessageTemplateList {\n  baseErrors: ErrorMessageTemplate[]\n  advancedSettingsErrors: ErrorMessageTemplate[]\n}\n\nexport type PreparePageEventRequestOptions = (\n  options: RequestOptions,\n  event: Event,\n  page: PageControllerClass,\n  context: FormContext\n) => void\n\nexport type OnRequestCallback = (\n  request: FormRequest | FormRequestPayload,\n  params: FormParams,\n  definition: FormDefinition,\n  metadata: FormMetadata\n) => void\n\nexport interface PluginOptions {\n  model?: FormModel\n  services?: Services\n  controllers?: Record<string, typeof PageController>\n  cacheName?: string\n  globals?: Record<string, GlobalFunction>\n  filters?: Record<string, FilterFunction>\n  saveAndReturn?: {\n    keyGenerator: (request: RequestType) => string\n    sessionHydrator: (request: RequestType) => Promise<FormSubmissionState>\n    sessionPersister: (\n      key: string,\n      state: FormSubmissionState,\n      request: RequestType\n    ) => Promise<void>\n  }\n  pluginPath?: string\n  nunjucks: {\n    baseLayoutPath: string\n    paths: string[]\n  }\n  viewContext: PluginProperties['forms-engine-plugin']['viewContext']\n  preparePageEventRequestOptions?: PreparePageEventRequestOptions\n  onRequest?: OnRequestCallback\n  baseUrl: string // base URL of the application, protocol and hostname e.g. \"https://myapp.com\"\n}\n"],"mappings":"AAkCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;;AAmBA;AACA;AACA;AACA;;AAqGA,WAAYA,YAAY,0BAAZA,YAAY;EAAZA,YAAY;EAAZA,YAAY;EAAZA,YAAY;EAAA,OAAZA,YAAY;AAAA;AAMxB,WAAYC,UAAU,0BAAVA,UAAU;EAAVA,UAAU;EAAVA,UAAU;EAAVA,UAAU;EAAA,OAAVA,UAAU;AAAA","ignoreList":[]}

package/.server/server/types.d.ts

@@ -2,7 +2,7 @@ import { type FormDefinition, type FormMetadata, type SubmitPayload, type Submit
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js';
 import { type DetailItem } from '~/src/server/plugins/engine/models/types.js';
 import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js';
-import { type OnRequestCallback, type PreparePageEventRequestOptions } from '~/src/server/plugins/engine/types.js';
+import { type OnRequestCallback, type PluginOptions, type PreparePageEventRequestOptions } from '~/src/server/plugins/engine/types.js';
 import { type FormRequestPayload, type FormStatus } from '~/src/server/routes/types.js';
 export interface FormsService {
     getFormMetadata: (slug: string) => Promise<FormMetadata>;
@@ -28,6 +28,7 @@ export interface RouteConfig {
     controllers?: Record<string, typeof PageController>;
     preparePageEventRequestOptions?: PreparePageEventRequestOptions;
     onRequest?: OnRequestCallback;
+    saveAndReturn?: PluginOptions['saveAndReturn'];
 }
 export interface OutputService {
     submit: (request: FormRequestPayload, model: FormModel, emailAddress: string, items: DetailItem[], submitResponse: SubmitResponsePayload) => Promise<void>;

package/.server/server/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/server/types.ts"],"sourcesContent":["import {\n  type FormDefinition,\n  type FormMetadata,\n  type SubmitPayload,\n  type SubmitResponsePayload\n} from '@defra/forms-model'\n\nimport { type FormModel } from '~/src/server/plugins/engine/models/index.js'\nimport { type DetailItem } from '~/src/server/plugins/engine/models/types.js'\nimport { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'\nimport {\n  type OnRequestCallback,\n  type PreparePageEventRequestOptions\n} from '~/src/server/plugins/engine/types.js'\nimport {\n  type FormRequestPayload,\n  type FormStatus\n} from '~/src/server/routes/types.js'\n\nexport interface FormsService {\n  getFormMetadata: (slug: string) => Promise<FormMetadata>\n  getFormDefinition: (\n    id: string,\n    state: FormStatus\n  ) => Promise<FormDefinition | undefined>\n}\n\nexport interface FormSubmissionService {\n  persistFiles: (\n    files: { fileId: string; initiatedRetrievalKey: string }[],\n    persistedRetrievalKey: string\n  ) => Promise<object>\n  submit: (data: SubmitPayload) => Promise<SubmitResponsePayload | undefined>\n}\n\nexport interface Services {\n  formsService: FormsService\n  formSubmissionService: FormSubmissionService\n  outputService: OutputService\n}\n\nexport interface RouteConfig {\n  formFileName?: string\n  formFilePath?: string\n  enforceCsrf?: boolean\n  services?: Services\n  controllers?: Record<string, typeof PageController>\n  preparePageEventRequestOptions?: PreparePageEventRequestOptions\n  onRequest?: OnRequestCallback\n}\n\nexport interface OutputService {\n  submit: (\n    request: FormRequestPayload,\n    model: FormModel,\n    emailAddress: string,\n    items: DetailItem[],\n    submitResponse: SubmitResponsePayload\n  ) => Promise<void>\n}\n"],"mappings":"","ignoreList":[]}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/server/types.ts"],"sourcesContent":["import {\n  type FormDefinition,\n  type FormMetadata,\n  type SubmitPayload,\n  type SubmitResponsePayload\n} from '@defra/forms-model'\n\nimport { type FormModel } from '~/src/server/plugins/engine/models/index.js'\nimport { type DetailItem } from '~/src/server/plugins/engine/models/types.js'\nimport { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'\nimport {\n  type OnRequestCallback,\n  type PluginOptions,\n  type PreparePageEventRequestOptions\n} from '~/src/server/plugins/engine/types.js'\nimport {\n  type FormRequestPayload,\n  type FormStatus\n} from '~/src/server/routes/types.js'\n\nexport interface FormsService {\n  getFormMetadata: (slug: string) => Promise<FormMetadata>\n  getFormDefinition: (\n    id: string,\n    state: FormStatus\n  ) => Promise<FormDefinition | undefined>\n}\n\nexport interface FormSubmissionService {\n  persistFiles: (\n    files: { fileId: string; initiatedRetrievalKey: string }[],\n    persistedRetrievalKey: string\n  ) => Promise<object>\n  submit: (data: SubmitPayload) => Promise<SubmitResponsePayload | undefined>\n}\n\nexport interface Services {\n  formsService: FormsService\n  formSubmissionService: FormSubmissionService\n  outputService: OutputService\n}\n\nexport interface RouteConfig {\n  formFileName?: string\n  formFilePath?: string\n  enforceCsrf?: boolean\n  services?: Services\n  controllers?: Record<string, typeof PageController>\n  preparePageEventRequestOptions?: PreparePageEventRequestOptions\n  onRequest?: OnRequestCallback\n  saveAndReturn?: PluginOptions['saveAndReturn']\n}\n\nexport interface OutputService {\n  submit: (\n    request: FormRequestPayload,\n    model: FormModel,\n    emailAddress: string,\n    items: DetailItem[],\n    submitResponse: SubmitResponsePayload\n  ) => Promise<void>\n}\n"],"mappings":"","ignoreList":[]}

package/.server/typings/hapi/index.d.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.js","names":[],"sources":["../../../src/typings/hapi/index.d.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/unified-signatures */\n\nimport { type Plugin } from '@hapi/hapi'\nimport { type ServerYar, type Yar } from '@hapi/yar'\nimport { type Logger } from 'pino'\n\nimport { type FormModel } from '~/src/server/plugins/engine/models/index.js'\nimport {\n  type FormRequest,\n  type FormRequestPayload\n} from '~/src/server/routes/types.js'\nimport { type CacheService } from '~/src/server/services/index.js'\n\ndeclare module '@hapi/hapi' {\n  // Here we are decorating Hapi interface types with\n  // props from plugins which doesn't export @types\n  interface PluginProperties {\n    crumb: {\n      generate?: (request: Request | FormRequest | FormRequestPayload) => string\n    }\n    'forms-engine-plugin': {\n      baseLayoutPath: string\n      cacheService: CacheService\n      viewContext?: (\n        request: FormRequest | FormRequestPayload | null\n      ) => Record<string, unknown> | Promise<Record<string, unknown>>\n    }\n  }\n\n  interface Request {\n    logger: Logger\n    yar: Yar\n  }\n\n  interface RequestApplicationState {\n    model?: FormModel\n  }\n\n  interface Server {\n    logger: Logger\n    yar: ServerYar\n  }\n\n  interface ServerApplicationState {\n    model?: FormModel\n    models: Map<string, { model: FormModel; updatedAt: Date }>\n  }\n}\n\ndeclare module '@hapi/scooter' {\n  declare const hapiScooter: {\n    plugin: Plugin\n  }\n\n  export = hapiScooter\n}\n\ndeclare module 'blankie' {\n  declare const blankie: {\n    plugin: Plugin<Record<string, boolean | string | string[]>>\n  }\n\n  export = blankie\n}\n\ndeclare module 'blipp' {\n  declare const blipp: {\n    plugin: Plugin\n  }\n\n  export = blipp\n}\n\ndeclare module 'hapi-pulse' {\n  declare const hapiPulse: {\n    plugin: Plugin<{\n      timeout: number\n    }>\n  }\n\n  export = hapiPulse\n}\n"],"mappings":"","ignoreList":[]}
+{"version":3,"file":"index.d.js","names":[],"sources":["../../../src/typings/hapi/index.d.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/unified-signatures */\n\nimport { type Plugin } from '@hapi/hapi'\nimport { type ServerYar, type Yar } from '@hapi/yar'\nimport { type Logger } from 'pino'\n\nimport { type FormModel } from '~/src/server/plugins/engine/models/index.js'\nimport { type PluginOptions } from '~/src/server/plugins/engine/types.ts'\nimport {\n  type FormRequest,\n  type FormRequestPayload\n} from '~/src/server/routes/types.js'\nimport { type CacheService } from '~/src/server/services/index.js'\n\ndeclare module '@hapi/hapi' {\n  // Here we are decorating Hapi interface types with\n  // props from plugins which doesn't export @types\n  interface PluginProperties {\n    crumb: {\n      generate?: (request: Request | FormRequest | FormRequestPayload) => string\n    }\n    'forms-engine-plugin': {\n      baseLayoutPath: string\n      cacheService: CacheService\n      viewContext?: (\n        request: FormRequest | FormRequestPayload | null\n      ) => Record<string, unknown> | Promise<Record<string, unknown>>\n      saveAndReturn?: PluginOptions['saveAndReturn']\n    }\n  }\n\n  interface Request {\n    logger: Logger\n    yar: Yar\n  }\n\n  interface RequestApplicationState {\n    model?: FormModel\n  }\n\n  interface Server {\n    logger: Logger\n    yar: ServerYar\n  }\n\n  interface ServerApplicationState {\n    model?: FormModel\n    models: Map<string, { model: FormModel; updatedAt: Date }>\n  }\n}\n\ndeclare module '@hapi/scooter' {\n  declare const hapiScooter: {\n    plugin: Plugin\n  }\n\n  export = hapiScooter\n}\n\ndeclare module 'blankie' {\n  declare const blankie: {\n    plugin: Plugin<Record<string, boolean | string | string[]>>\n  }\n\n  export = blankie\n}\n\ndeclare module 'blipp' {\n  declare const blipp: {\n    plugin: Plugin\n  }\n\n  export = blipp\n}\n\ndeclare module 'hapi-pulse' {\n  declare const hapiPulse: {\n    plugin: Plugin<{\n      timeout: number\n    }>\n  }\n\n  export = hapiPulse\n}\n"],"mappings":"","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/forms-engine-plugin",
-  "version": "1.4.1",
+  "version": "2.0.0",
   "description": "Defra forms engine",
   "type": "module",
   "files": [

package/src/server/plugins/engine/README.md

@@ -86,53 +86,9 @@ There are a number of `LiquidJS` filters available to you from within the templa
 ]
 ```
 
-## Session Rehydration
+### Save and return
 
-To support Save and Return functionality, this application now supports session rehydration. This allows user session state to be recovered across browser sessions or devices — even after the in-memory Redis session has expired.
-
-### How it works
-
-To support session rehydration from a backend (e.g. for Save & Return), the consuming application must provide two functions when registering the DXT engine plugin:
-
-```
-export interface PluginOptions {
-  ...
-  keyGenerator?: (request) => string
-  sessionHydrator?: (request) => Promise<FormSubmissionState | null>
-  ...
-}
-
-```
-
-1. `keyGenerator(request)`
-
-This generates a stable and consistent cache key used to store and retrieve user state. It should return a string based on persistent identifiers such as userId, businessId, and grantId — i.e., something like:
-
-```
-const keyGenerator = request => {
-  const { userId, businessId, grantId } = request.app.userContext
-  return `${userId}:${businessId}:${grantId}`
-}
-```
-
-2. `sessionHydrator(request, key)`
-
-This function is called when no session state is found in Redis. It should fetch saved state (e.g., from an API) using the provided key and return it in the same structure expected by the form engine:
-
-```
-const sessionHydrator = async (request, key) => {
-  const response = await fetch(`https://backend.api/state/${key}`)
-  if (!response.ok) return null
-  return await response.json()  // Must match form engine state shape
-}
-```
-
-#### Session flow
-
-- When user resumes a journey and Redis session data is missing or expired, DXT will use `keyGenerator` and `sessionHydrator` to fetch the saved state from an external API (e.g. `/state` endpoint).
-- The fetched state is written back into Redis and used to continue the user journey.
-- The rehydrated state must include enough information to satisfy schema validation on the current or next page.
-- To properly resume a session, users should be redirected to the `/summary` page. This ensures the UI has all required answers preloaded and avoids invalid transitions from deep links.
+See [our save and return feature page](/docs/features/code-based/SAVE_AND_RETURN.md).
 
 ### Additional notes
 

package/src/server/plugins/engine/configureEnginePlugin.ts

@@ -18,7 +18,8 @@ export const configureEnginePlugin = async ({
   services,
   controllers,
   preparePageEventRequestOptions,
-  onRequest
+  onRequest,
+  saveAndReturn
 }: RouteConfig = {}): Promise<{
   plugin: typeof plugin
   options: PluginOptions
@@ -57,7 +58,8 @@ export const configureEnginePlugin = async ({
       viewContext: devtoolContext,
       preparePageEventRequestOptions,
       onRequest,
-      baseUrl: 'http://localhost:3009' // always runs locally
+      baseUrl: 'http://localhost:3009', // always runs locally
+      saveAndReturn
     }
   }
 }

package/src/server/plugins/engine/helpers.test.ts

@@ -18,6 +18,7 @@ import {
 } from '~/src/server/plugins/engine/helpers.js'
 import { handleLegacyRedirect } from '~/src/server/plugins/engine/helpers.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
 import {
   createPage,
   type PageControllerClass
@@ -56,7 +57,7 @@ describe('Helpers', () => {
     page = createPage(model, definition.pages[0])
     const pageUrl = new URL(page.href, 'http://example.com')
 
-    request = {
+    request = buildFormContextRequest({
       method: 'get',
       url: pageUrl,
       path: pageUrl.pathname,
@@ -66,7 +67,7 @@ describe('Helpers', () => {
       },
       query: {},
       app: { model }
-    }
+    })
 
     const response = {
       code: jest.fn().mockImplementation(() => response)

package/src/server/plugins/engine/helpers.ts

@@ -377,7 +377,15 @@ export function evaluateTemplate(
 }
 
 export function getCacheService(server: Server) {
-  return server.plugins['forms-engine-plugin'].cacheService
+  return getPluginOptions(server).cacheService
+}
+
+export function getSaveAndReturnHelpers(server: Server) {
+  return getPluginOptions(server).saveAndReturn
+}
+
+export function getPluginOptions(server: Server) {
+  return server.plugins['forms-engine-plugin']
 }
 
 /**

package/src/server/plugins/engine/models/FormModel.test.ts

@@ -6,6 +6,7 @@ import {
 
 import { todayAsDateOnly } from '~/src/server/plugins/engine/date-helper.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
 import { type FormContextRequest } from '~/src/server/plugins/engine/types.js'
 import { V2 as definitionV2 } from '~/test/form/definitions/conditions-basic.js'
 import definition from '~/test/form/definitions/conditions-escaping.js'
@@ -151,7 +152,7 @@ describe('FormModel', () => {
       }
       const pageUrl = new URL('http://example.com/components/fields-required')
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'post',
         payload: { crumb: 'dummyCrumb', action: 'validate' },
         query: {},
@@ -159,7 +160,7 @@ describe('FormModel', () => {
         params: { path: 'components', slug: 'fields-required' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       const context = formModel.getFormContext(request, state)
 
@@ -180,7 +181,7 @@ describe('FormModel', () => {
       }
       const pageUrl = new URL('http://example.com/components/fields-required')
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'post',
         payload: { crumb: 'dummyCrumb', action: 'validate' },
         query: {},
@@ -188,7 +189,7 @@ describe('FormModel', () => {
         params: { path: 'components', slug: 'fields-required' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       expect(() => formModel.getFormContext(request, state)).toThrow(
         'Reference number not found in form state'
@@ -206,7 +207,7 @@ describe('FormModel', () => {
       }
       const pageUrl = new URL('http://example.com/components/fields-required')
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'post',
         payload: { crumb: 'dummyCrumb', action: 'validate' },
         query: {},
@@ -214,7 +215,7 @@ describe('FormModel', () => {
         params: { path: 'components', slug: 'fields-required' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       expect(() => formModel.getFormContext(request, state)).toThrow(
         'Reference number not found in form state'
@@ -236,14 +237,14 @@ describe('FormModel', () => {
         'http://example.com/conditional-list-items/summary'
       )
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'get',
         query: {},
         path: pageUrl.pathname,
         params: { path: 'summary', slug: 'conditional-list-items' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       const context = formModel.getFormContext(request, state)
 
@@ -271,14 +272,14 @@ describe('FormModel', () => {
         'http://example.com/conditional-list-items/summary'
       )
 
-      const request: FormContextRequest = {
+      const request: FormContextRequest = buildFormContextRequest({
         method: 'get',
         query: {},
         path: pageUrl.pathname,
         params: { path: 'summary', slug: 'conditional-list-items' },
         url: pageUrl,
         app: { model: formModel }
-      }
+      })
 
       const context = formModel.getFormContext(request, state)
 

package/src/server/plugins/engine/models/SummaryViewModel.test.ts

@@ -4,6 +4,8 @@ import {
   SummaryViewModel
 } from '~/src/server/plugins/engine/models/index.js'
 import { SummaryPageController } from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import {
   createPage,
   type PageControllerClass
@@ -14,7 +16,6 @@ import {
   type FormState
 } from '~/src/server/plugins/engine/types.js'
 import definition from '~/test/form/definitions/repeat-mixed.js'
-
 const basePath = `${FORM_PREFIX}/test`
 
 describe('SummaryViewModel', () => {
@@ -36,7 +37,7 @@ describe('SummaryViewModel', () => {
     page = createPage(model, definition.pages[2])
     pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
 
-    request = {
+    request = buildFormContextRequest({
       method: 'get',
       url: pageUrl,
       path: pageUrl.pathname,
@@ -46,7 +47,7 @@ describe('SummaryViewModel', () => {
       },
       query: {},
       app: { model }
-    }
+    })
   })
 
   describe.each([
@@ -272,13 +273,14 @@ describe('SummaryPageController', () => {
         slug: 'repeat'
       },
       query: {},
-      app: { model }
+      app: { model },
+      server: serverWithSaveAndReturn
     }
   })
 
   describe('Save and Return functionality', () => {
     it('should show save and return button on summary page', () => {
-      expect(controller.shouldShowSaveAndReturn()).toBe(true)
+      expect(controller.shouldShowSaveAndReturn(request.server)).toBe(true)
     })
 
     it('should handle save and return from summary page', () => {

package/src/server/plugins/engine/models/SummaryViewModel.ts

@@ -51,7 +51,7 @@ export class SummaryViewModel {
   serviceUrl: string
   hasMissingNotificationEmail?: boolean
   components?: ComponentViewModel[]
-  allowSaveAndReturn?: boolean
+  allowSaveAndReturn = false
 
   constructor(
     request: FormContextRequest,

package/src/server/plugins/engine/options.js

@@ -20,9 +20,11 @@ const pluginRegistrationOptionsSchema = Joi.object({
   preparePageEventRequestOptions: Joi.function().optional(),
   onRequest: Joi.function().optional(),
   baseUrl: Joi.string().uri().required(),
-  keyGenerator: Joi.function().optional(),
-  sessionHydrator: Joi.function().optional(),
-  sessionPersister: Joi.function().optional()
+  saveAndReturn: Joi.object({
+    keyGenerator: Joi.function(),
+    sessionHydrator: Joi.function(),
+    sessionPersister: Joi.function()
+  }).optional()
 })
 
 /**

package/src/server/plugins/engine/options.test.js

@@ -2,6 +2,9 @@ import { validatePluginOptions } from '~/src/server/plugins/engine/options.js'
 
 describe('validatePluginOptions', () => {
   it('returns the validated value for valid options', () => {
+    /**
+     * @type {PluginOptions}
+     */
     const validOptions = {
       nunjucks: {
         baseLayoutPath: 'dxt-devtool-baselayout.html',
@@ -17,6 +20,9 @@ describe('validatePluginOptions', () => {
   })
 
   it('accepts optional properties keyGenerator, sessionHydrator, and sessionPersister', () => {
+    /**
+     * @type {PluginOptions}
+     */
     const validOptionsWithOptionals = {
       nunjucks: {
         baseLayoutPath: 'dxt-devtool-baselayout.html',
@@ -26,9 +32,11 @@ describe('validatePluginOptions', () => {
         return { hello: 'world' }
       },
       baseUrl: 'http://localhost:3009',
-      keyGenerator: () => 'test-key',
-      sessionHydrator: () => Promise.resolve({ someState: 'value' }),
-      sessionPersister: () => Promise.resolve(undefined)
+      saveAndReturn: {
+        keyGenerator: () => 'test-key',
+        sessionHydrator: () => Promise.resolve({ someState: 'value' }),
+        sessionPersister: () => Promise.resolve(undefined)
+      }
     }
 
     expect(validatePluginOptions(validOptionsWithOptionals)).toEqual(
@@ -40,17 +48,20 @@ describe('validatePluginOptions', () => {
    * tsc would usually check compliance with the type, but given a user might be using plain JS we still want a test
    */
   it('fails if a required attribute is missing', () => {
-    // viewContext is missing
-    const invalidOptions = {
-      nunjucks: {
-        baseLayoutPath: 'dxt-devtool-baselayout.html',
-        paths: ['src/server/devserver'] // custom layout to make it really clear this is not the same as the runner
-      }
-    }
+    const invalidOptions =
+      /** @type {PluginOptions} testing without viewContext */ ({
+        nunjucks: {
+          baseLayoutPath: 'dxt-devtool-baselayout.html',
+          paths: ['src/server/devserver'] // custom layout to make it really clear this is not the same as the runner
+        }
+      })
 
-    // @ts-expect-error -- add a test for JS users
     expect(() => validatePluginOptions(invalidOptions)).toThrow(
       'Invalid plugin options'
     )
   })
 })
+
+/**
+ * @import { PluginOptions } from '~/src/server/plugins/engine/types.js'
+ */

package/src/server/plugins/engine/outputFormatters/human/v1.test.ts

@@ -7,7 +7,7 @@ import {
   SummaryPageController,
   getFormSubmissionData
 } from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
-import { type FormContextRequest } from '~/src/server/plugins/engine/types.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
 import { FormStatus } from '~/src/server/routes/types.js'
 import definition from '~/test/form/definitions/repeat-mixed.js'
 
@@ -52,7 +52,7 @@ const pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
 
 const controller = new SummaryPageController(model, pageDef)
 
-const request = {
+const request = buildFormContextRequest({
   method: 'get',
   url: pageUrl,
   path: pageUrl.pathname,
@@ -62,7 +62,7 @@ const request = {
   },
   query: {},
   app: { model }
-} satisfies FormContextRequest
+})
 
 const context = model.getFormContext(request, state)
 const summaryViewModel = controller.getSummaryViewModel(request, context)

package/src/server/plugins/engine/pageControllers/FileUploadPageController.test.ts

@@ -14,6 +14,7 @@ import {
   prepareStatus
 } from '~/src/server/plugins/engine/pageControllers/FileUploadPageController.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import * as pageHelpers from '~/src/server/plugins/engine/pageControllers/helpers.js'
 import * as uploadService from '~/src/server/plugins/engine/services/uploadService.js'
 import {
@@ -31,6 +32,7 @@ import {
   type FormRequest,
   type FormRequestPayload
 } from '~/src/server/routes/types.js'
+import { type CacheService } from '~/src/server/services/index.js'
 import definition from '~/test/form/definitions/file-upload-basic.js'
 
 type TestableFileUploadPageController = FileUploadPageController & {
@@ -77,12 +79,13 @@ describe('FileUploadPageController', () => {
       server: {
         plugins: {
           'forms-engine-plugin': {
+            baseLayoutPath: '',
             cacheService: {
               setFlash: jest.fn(),
               setState: jest
                 .fn()
                 .mockImplementation((req, updated) => Promise.resolve(updated))
-            }
+            } as unknown as CacheService
           }
         }
       },
@@ -1115,4 +1118,12 @@ describe('FileUploadPageController', () => {
       )
     })
   })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return true when save and return is enabled', () => {
+      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        true
+      )
+    })
+  })
 })

package/src/server/plugins/engine/pageControllers/PageController.test.ts

@@ -3,6 +3,7 @@ import { type ResponseToolkit } from '@hapi/hapi'
 import { FORM_PREFIX } from '~/src/server/constants.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import { type FormRequest } from '~/src/server/routes/types.js'
 import definition from '~/test/form/definitions/basic.js'
 
@@ -230,4 +231,12 @@ describe('PageController', () => {
       )
     })
   })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return false (PageController does not allow save and return)', () => {
+      expect(controller1.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+        false
+      )
+    })
+  })
 })

package/src/server/plugins/engine/pageControllers/PageController.ts

@@ -9,12 +9,14 @@ import Boom from '@hapi/boom'
 import {
   type Lifecycle,
   type ResponseToolkit,
-  type RouteOptions
+  type RouteOptions,
+  type Server
 } from '@hapi/hapi'
 
 import { type ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import {
   encodeUrl,
+  getSaveAndReturnHelpers,
   getStartPath,
   normalisePath
 } from '~/src/server/plugins/engine/helpers.js'
@@ -45,6 +47,7 @@ export class PageController {
   events?: Events
   collection?: ComponentCollection
   viewName = 'index'
+  allowSaveAndReturn = false
 
   constructor(model: FormModel, pageDef: Page) {
     const { def } = model
@@ -183,4 +186,10 @@ export class PageController {
   ) => ReturnType<Lifecycle.Method<FormRequestPayloadRefs>> {
     throw Boom.badRequest('Unsupported POST route handler for this page')
   }
+
+  shouldShowSaveAndReturn(server: Server): boolean {
+    return (
+      getSaveAndReturnHelpers(server) !== undefined && this.allowSaveAndReturn
+    )
+  }
 }