@defra/forms-engine-plugin 2.1.10 → 3.0.0

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

@@ -23,6 +23,7 @@ import {
 import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
 import {
+  type AnyFormRequest,
   type FormContext,
   type FormContextRequest,
   type FormSubmissionError
@@ -32,8 +33,7 @@ import {
   FormStatus,
   type FormParams,
   type FormQuery,
-  type FormRequest,
-  type FormRequestPayload
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 
 const logger = createLogger()
@@ -117,7 +117,7 @@ engine.registerFilter('answer', function (name: string) {
 
 export function proceed(
   request: Pick<FormContextRequest, 'method' | 'payload' | 'query'>,
-  h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+  h: FormResponseToolkit,
   nextUrl: string
 ) {
   const { method, payload, query } = request
@@ -327,7 +327,7 @@ export function getError(detail: ValidationErrorItem): FormSubmissionError {
  * is not disabled on the current route, and that cookies/state are present.
  */
 export function safeGenerateCrumb(
-  request: FormRequest | FormRequestPayload | null
+  request: AnyFormRequest | null
 ): string | undefined {
   // no request or no .state
   if (!request?.state) {
@@ -380,8 +380,8 @@ export function getCacheService(server: Server) {
   return getPluginOptions(server).cacheService
 }
 
-export function getSaveAndReturnHelpers(server: Server) {
-  return getPluginOptions(server).saveAndReturn
+export function getSaveAndExitHelpers(server: Server) {
+  return getPluginOptions(server).saveAndExit
 }
 
 export function getPluginOptions(server: Server) {

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

@@ -185,7 +185,7 @@ describe('FormModel', () => {
   })
 
   describe('getFormContext', () => {
-    it.each([FormAction.Validate, FormAction.SaveAndReturn, undefined])(
+    it.each([FormAction.Validate, FormAction.SaveAndExit, undefined])(
       'returns a form context with the correct payload and state when action is %s',
       (action) => {
         const formModel = new FormModel(fieldsRequiredDefinition, {
@@ -219,7 +219,7 @@ describe('FormModel', () => {
       }
     )
 
-    it('returns without updating the state when the action is not validate or saveAndReturn', () => {
+    it('returns without updating the state when the action is not validate or saveAndExit', () => {
       const formModel = new FormModel(fieldsRequiredDefinition, {
         basePath: '/components'
       })

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

@@ -543,8 +543,7 @@ function validateFormPayload(
   // Skip validation GET requests or other actions
   if (
     !request.payload ||
-    (action &&
-      ![FormAction.Validate, FormAction.SaveAndReturn].includes(action))
+    (action && ![FormAction.Validate, FormAction.SaveAndExit].includes(action))
   ) {
     return context
   }

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

@@ -5,7 +5,7 @@ import {
 } 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 { serverWithSaveAndExit } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import {
   createPage,
   type PageControllerClass
@@ -274,16 +274,16 @@ describe('SummaryPageController', () => {
       },
       query: {},
       app: { model },
-      server: serverWithSaveAndReturn
+      server: serverWithSaveAndExit
     }
   })
 
-  describe('Save and Return functionality', () => {
-    it('should show save and return button on summary page', () => {
-      expect(controller.shouldShowSaveAndReturn(request.server)).toBe(true)
+  describe('Save and Exit functionality', () => {
+    it('should show save and exit button on summary page', () => {
+      expect(controller.shouldShowSaveAndExit(request.server)).toBe(true)
     })
 
-    it('should handle save and return from summary page', () => {
+    it('should handle save and exit from summary page', () => {
       const state: FormState = {
         $$__referenceNumber: 'foobar',
         orderType: 'collection',
@@ -293,7 +293,7 @@ describe('SummaryPageController', () => {
       const context = model.getFormContext(request, state)
       const viewModel = controller.getViewModel(request, context)
 
-      expect(viewModel).toHaveProperty('allowSaveAndReturn', true)
+      expect(viewModel).toHaveProperty('allowSaveAndExit', true)
     })
 
     it('should display correct page title', () => {

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

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

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

@@ -1,6 +1,7 @@
 import Joi from 'joi'
 
 import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
+import { CacheService } from '~/src/server/services/index.js'
 
 const logger = createLogger()
 
@@ -8,7 +9,10 @@ const pluginRegistrationOptionsSchema = Joi.object({
   model: Joi.object().optional(),
   services: Joi.object().optional(),
   controllers: Joi.object().pattern(Joi.string(), Joi.any()).optional(),
-  cacheName: Joi.string().optional(),
+  cache: Joi.alternatives().try(
+    Joi.object().instance(CacheService),
+    Joi.string()
+  ),
   globals: Joi.object().pattern(Joi.string(), Joi.any()).optional(),
   filters: Joi.object().pattern(Joi.string(), Joi.any()).optional(),
   pluginPath: Joi.string().optional(),
@@ -20,11 +24,7 @@ const pluginRegistrationOptionsSchema = Joi.object({
   preparePageEventRequestOptions: Joi.function().optional(),
   onRequest: Joi.function().optional(),
   baseUrl: Joi.string().uri().required(),
-  saveAndReturn: Joi.object({
-    keyGenerator: Joi.function(),
-    sessionHydrator: Joi.function(),
-    sessionPersister: Joi.function()
-  }).optional()
+  saveAndExit: Joi.function().optional()
 })
 
 /**

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

@@ -19,7 +19,7 @@ describe('validatePluginOptions', () => {
     expect(validatePluginOptions(validOptions)).toEqual(validOptions)
   })
 
-  it('accepts optional properties keyGenerator, sessionHydrator, and sessionPersister', () => {
+  it('accepts optional property saveAndExit', () => {
     /**
      * @type {PluginOptions}
      */
@@ -32,11 +32,7 @@ describe('validatePluginOptions', () => {
         return { hello: 'world' }
       },
       baseUrl: 'http://localhost:3009',
-      saveAndReturn: {
-        keyGenerator: () => 'test-key',
-        sessionHydrator: () => Promise.resolve({ someState: 'value' }),
-        sessionPersister: () => Promise.resolve(undefined)
-      }
+      saveAndExit: (request, h) => h.redirect('/save-and-exit')
     }
 
     expect(validatePluginOptions(validOptionsWithOptionals)).toEqual(

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

@@ -1,6 +1,5 @@
 /* eslint-disable @typescript-eslint/dot-notation */
 import { ComponentType, type ComponentDef } from '@defra/forms-model'
-import { type ResponseToolkit } from '@hapi/hapi'
 import { type ValidationErrorItem, type ValidationResult } from 'joi'
 
 import { tempItemSchema } from '~/src/server/plugins/engine/components/FileUploadField.js'
@@ -14,7 +13,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 { serverWithSaveAndExit } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import * as pageHelpers from '~/src/server/plugins/engine/pageControllers/helpers/index.js'
 import * as uploadService from '~/src/server/plugins/engine/services/uploadService.js'
 import {
@@ -30,7 +29,8 @@ import {
 } from '~/src/server/plugins/engine/types.js'
 import {
   type FormRequest,
-  type FormRequestPayload
+  type FormRequestPayload,
+  type FormResponseToolkit
 } 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'
@@ -1040,7 +1040,7 @@ describe('FileUploadPageController', () => {
       } as unknown as FormRequest
 
       const context = { state } as unknown as FormContext
-      const h = {} as unknown as Pick<ResponseToolkit, 'redirect' | 'view'>
+      const h = {} as unknown as FormResponseToolkit
 
       const handler = controller.makeGetItemDeleteRouteHandler()
 
@@ -1058,7 +1058,7 @@ describe('FileUploadPageController', () => {
 
       const h = {
         redirect: jest.fn()
-      } as unknown as Pick<ResponseToolkit, 'redirect' | 'view'>
+      } as unknown as FormResponseToolkit
 
       const context = {
         state: {}
@@ -1119,11 +1119,9 @@ describe('FileUploadPageController', () => {
     })
   })
 
-  describe('shouldShowSaveAndReturn', () => {
-    it('should return true when save and return is enabled', () => {
-      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
-        true
-      )
+  describe('shouldShowSaveAndExit', () => {
+    it('should return true when save and exit is enabled', () => {
+      expect(controller.shouldShowSaveAndExit(serverWithSaveAndExit)).toBe(true)
     })
   })
 })

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

@@ -1,6 +1,5 @@
 import { ComponentType, type PageFileUpload } from '@defra/forms-model'
 import Boom from '@hapi/boom'
-import { type ResponseToolkit } from '@hapi/hapi'
 import { wait } from '@hapi/hoek'
 import { type ValidationErrorItem } from 'joi'
 
@@ -23,6 +22,7 @@ import {
 import {
   FileStatus,
   UploadStatus,
+  type AnyFormRequest,
   type FeaturedFormPageViewModel,
   type FileState,
   type FormContext,
@@ -35,7 +35,8 @@ import {
 } from '~/src/server/plugins/engine/types.js'
 import {
   type FormRequest,
-  type FormRequestPayload
+  type FormRequestPayload,
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 
 const MAX_UPLOADS = 25
@@ -111,7 +112,7 @@ export class FileUploadPageController extends QuestionPageController {
     return payload
   }
 
-  async getState(request: FormRequest | FormRequestPayload) {
+  async getState(request: AnyFormRequest) {
     const { fileUpload } = this
 
     // Get the actual state
@@ -148,7 +149,7 @@ export class FileUploadPageController extends QuestionPageController {
     return (
       request: FormRequest,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { viewModel } = this
       const { params } = request
@@ -183,7 +184,7 @@ export class FileUploadPageController extends QuestionPageController {
     return async (
       request: FormRequestPayload,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { path } = this
       const { state } = context
@@ -279,7 +280,7 @@ export class FileUploadPageController extends QuestionPageController {
    * @param state - the form state
    */
   private async refreshUpload(
-    request: FormRequest | FormRequestPayload,
+    request: AnyFormRequest,
     state: FormSubmissionState
   ) {
     state = await this.checkUploadStatus(request, state)
@@ -295,7 +296,7 @@ export class FileUploadPageController extends QuestionPageController {
    * @param depth - the number of retries so far
    */
   private async checkUploadStatus(
-    request: FormRequest | FormRequestPayload,
+    request: AnyFormRequest,
     state: FormSubmissionState,
     depth = 1
   ): Promise<FormSubmissionState> {
@@ -417,7 +418,7 @@ export class FileUploadPageController extends QuestionPageController {
    * @param state - the form state
    */
   private async initiateAndStoreNewUpload(
-    request: FormRequest | FormRequestPayload,
+    request: AnyFormRequest,
     state: FormSubmissionState
   ) {
     const { fileUpload, href, path } = this

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

@@ -3,8 +3,11 @@ 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 { serverWithSaveAndExit } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
+import {
+  type FormRequest,
+  type FormResponseToolkit
+} from '~/src/server/routes/types.js'
 import definition from '~/test/form/definitions/basic.js'
 
 describe('PageController', () => {
@@ -155,7 +158,7 @@ describe('PageController', () => {
       app: { model }
     } as FormRequest
 
-    const h: Pick<ResponseToolkit, 'redirect' | 'view'> = {
+    const h: FormResponseToolkit = {
       redirect: jest.fn(),
       view: jest.fn()
     }
@@ -206,10 +209,10 @@ describe('PageController', () => {
       )
     })
 
-    it('supports save and return functionality', async () => {
+    it('supports save and exit functionality', async () => {
       const mockRequest = {
         ...request,
-        payload: { saveAndReturn: true }
+        payload: { saveAndExit: true }
       } as FormRequest
 
       const mockResponse = {
@@ -232,9 +235,9 @@ describe('PageController', () => {
     })
   })
 
-  describe('shouldShowSaveAndReturn', () => {
-    it('should return false (PageController does not allow save and return)', () => {
-      expect(controller1.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+  describe('shouldShowSaveAndExit', () => {
+    it('should return false (PageController does not allow save and exit)', () => {
+      expect(controller1.shouldShowSaveAndExit(serverWithSaveAndExit)).toBe(
         false
       )
     })

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

@@ -6,17 +6,12 @@ import {
   type Section
 } from '@defra/forms-model'
 import Boom from '@hapi/boom'
-import {
-  type Lifecycle,
-  type ResponseToolkit,
-  type RouteOptions,
-  type Server
-} from '@hapi/hapi'
+import { type Lifecycle, type RouteOptions, type Server } from '@hapi/hapi'
 
 import { type ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import {
   encodeUrl,
-  getSaveAndReturnHelpers,
+  getSaveAndExitHelpers,
   getStartPath,
   normalisePath
 } from '~/src/server/plugins/engine/helpers.js'
@@ -30,7 +25,8 @@ import {
   type FormRequest,
   type FormRequestPayload,
   type FormRequestPayloadRefs,
-  type FormRequestRefs
+  type FormRequestRefs,
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 
 export class PageController {
@@ -47,7 +43,7 @@ export class PageController {
   events?: Events
   collection?: ComponentCollection
   viewName = 'index'
-  allowSaveAndReturn = false
+  allowSaveAndExit = false
 
   constructor(model: FormModel, pageDef: Page) {
     const { def } = model
@@ -171,7 +167,7 @@ export class PageController {
   makeGetRouteHandler(): (
     request: FormRequest,
     context: FormContext,
-    h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    h: FormResponseToolkit
   ) => ReturnType<Lifecycle.Method<FormRequestRefs>> {
     return (request, context, h) => {
       const { viewModel, viewName } = this
@@ -182,14 +178,12 @@ export class PageController {
   makePostRouteHandler(): (
     request: FormRequestPayload,
     context: FormContext,
-    h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    h: FormResponseToolkit
   ) => ReturnType<Lifecycle.Method<FormRequestPayloadRefs>> {
     throw Boom.badRequest('Unsupported POST route handler for this page')
   }
 
-  shouldShowSaveAndReturn(server: Server): boolean {
-    return (
-      getSaveAndReturnHelpers(server) !== undefined && this.allowSaveAndReturn
-    )
+  shouldShowSaveAndExit(server: Server): boolean {
+    return getSaveAndExitHelpers(server) !== undefined && this.allowSaveAndExit
   }
 }