@defra/forms-engine-plugin 2.1.10 → 3.0.0

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

@@ -1,14 +1,12 @@
 import { type PageQuestion } from '@defra/forms-model'
-import { type ResponseToolkit } from '@hapi/hapi'
 
-import { getCacheService } from '~/src/server/plugins/engine/helpers.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
 import {
   buildFormContextRequest,
   buildFormRequest
 } 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 {
   type FormContext,
   type FormPageViewModel,
@@ -17,7 +15,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 { CacheService } from '~/src/server/services/cacheService.js'
 import conditionalReveal from '~/test/form/definitions/conditional-reveal.js'
@@ -594,7 +593,7 @@ describe('QuestionPageController', () => {
       code: jest.fn().mockImplementation(() => response)
     }
 
-    const h: Pick<ResponseToolkit, 'redirect' | 'view'> = {
+    const h: FormResponseToolkit = {
       redirect: jest.fn().mockReturnValue(response),
       view: jest.fn()
     }
@@ -1155,7 +1154,7 @@ describe('QuestionPageController V2', () => {
       code: jest.fn().mockImplementation(() => response)
     }
 
-    const h: Pick<ResponseToolkit, 'redirect' | 'view'> = {
+    const h: FormResponseToolkit = {
       redirect: jest.fn().mockReturnValue(response),
       view: jest.fn()
     }
@@ -1283,7 +1282,7 @@ describe('QuestionPageController V2', () => {
   })
 })
 
-describe('Save and Return functionality', () => {
+describe('Save and Exit functionality', () => {
   let model: FormModel
   let controller1: QuestionPageController
   let requestPage1: FormRequest
@@ -1314,7 +1313,7 @@ describe('Save and Return functionality', () => {
     code: jest.fn().mockImplementation(() => response)
   }
 
-  const h: Pick<ResponseToolkit, 'redirect' | 'view'> = {
+  const h: FormResponseToolkit = {
     redirect: jest.fn().mockReturnValue(response),
     view: jest.fn()
   }
@@ -1324,17 +1323,17 @@ describe('Save and Return functionality', () => {
     jest.spyOn(CacheService.prototype, 'setState')
   })
 
-  describe('shouldShowSaveAndReturn', () => {
+  describe('shouldShowSaveAndExit', () => {
     it('should return true by default', () => {
-      expect(controller1.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+      expect(controller1.shouldShowSaveAndExit(serverWithSaveAndExit)).toBe(
         true
       )
     })
   })
 
-  describe('handleSaveAndReturn', () => {
-    it('should save state and redirect to exit page', async () => {
-      const sessionPersisterMock = jest.fn()
+  describe('handleSaveAndExit', () => {
+    it('should invoke saveAndExit plugin option', () => {
+      const saveAndExitMock = jest.fn(() => ({}))
       const state: FormSubmissionState = {
         $$__referenceNumber: 'foobar',
         yesNoField: true
@@ -1344,9 +1343,7 @@ describe('Save and Return functionality', () => {
         server: {
           plugins: {
             'forms-engine-plugin': {
-              saveAndReturn: {
-                sessionPersister: sessionPersisterMock
-              },
+              saveAndExit: saveAndExitMock,
               cacheService: {
                 clearState: jest.fn()
               } as unknown as CacheService
@@ -1354,52 +1351,18 @@ describe('Save and Return functionality', () => {
           }
         },
         method: 'post',
-        payload: { yesNoField: true, action: 'save-and-return' }
-      } as unknown as FormRequestPayload
-
-      const cacheService = getCacheService(request.server)
-
-      const context = model.getFormContext(request, state)
-
-      await controller1.handleSaveAndReturn(request, context, h)
-
-      expect(sessionPersisterMock).toHaveBeenCalledWith(context.state, request)
-      expect(cacheService.clearState).toHaveBeenCalledWith(request)
-      expect(h.redirect).toHaveBeenCalledWith('/test/exit')
-    })
-
-    it('should throw if sessionPersister inside saveAndReturn options provided', async () => {
-      const sessionPersisterMock = jest.fn()
-      const state: FormSubmissionState = {
-        $$__referenceNumber: 'foobar',
-        yesNoField: true
-      }
-      const request = {
-        ...requestPage1,
-        server: {
-          plugins: {
-            'forms-engine-plugin': {
-              // No sessionPersister object
-              saveAndReturn: {}
-            }
-          }
-        },
-        method: 'post',
-        payload: { yesNoField: true, action: 'save-and-return' }
+        payload: { yesNoField: true, action: 'save-and-exit' }
       } as unknown as FormRequestPayload
 
       const context = model.getFormContext(request, state)
 
-      await expect(
-        controller1.handleSaveAndReturn(request, context, h)
-      ).rejects.toThrow('Server misconfigured for save and return')
+      controller1.handleSaveAndExit(request, context, h)
 
-      expect(sessionPersisterMock).not.toHaveBeenCalled()
-      expect(h.redirect).not.toHaveBeenCalled()
+      expect(saveAndExitMock).toHaveBeenCalledWith(request, h, context)
     })
 
-    it('should throw if no saveAndReturn options provided', async () => {
-      const sessionPersisterMock = jest.fn()
+    it('should throw if saveAndExit option not provided', () => {
+      const saveAndExitMock = jest.fn()
       const state: FormSubmissionState = {
         $$__referenceNumber: 'foobar',
         yesNoField: true
@@ -1409,57 +1372,27 @@ describe('Save and Return functionality', () => {
         server: {
           plugins: {
             'forms-engine-plugin': {
-              // No saveAndReturn object
+              // No function
+              saveAndExit: undefined
             }
           }
         },
         method: 'post',
-        payload: { yesNoField: true, action: 'save-and-return' }
-      } as unknown as FormRequestPayload
-
-      const context = model.getFormContext(request, state)
-
-      await expect(
-        controller1.handleSaveAndReturn(request, context, h)
-      ).rejects.toThrow('Server misconfigured for save and return')
-
-      expect(sessionPersisterMock).not.toHaveBeenCalled()
-      expect(h.redirect).not.toHaveBeenCalled()
-    })
-
-    it('should throw if sessionPersister throws as well with validation errors', async () => {
-      const sessionPersisterMock = jest.fn().mockImplementation(() => {
-        throw new Error('Session persister error')
-      })
-      const state: FormSubmissionState = { $$__referenceNumber: 'foobar' }
-      const request = {
-        ...requestPage1,
-        method: 'post',
-        server: {
-          plugins: {
-            'forms-engine-plugin': {
-              saveAndReturn: {
-                sessionPersister: sessionPersisterMock
-              }
-            }
-          }
-        },
-        payload: { action: 'save-and-return' }
+        payload: { yesNoField: true, action: 'save-and-exit' }
       } as unknown as FormRequestPayload
 
       const context = model.getFormContext(request, state)
 
-      await expect(
-        controller1.handleSaveAndReturn(request, context, h)
-      ).rejects.toThrow('Session persister error')
+      expect(() => controller1.handleSaveAndExit(request, context, h)).toThrow(
+        'Server misconfigured for save and exit'
+      )
 
-      expect(sessionPersisterMock).toHaveBeenCalledWith(context.state, request)
-      expect(h.redirect).not.toHaveBeenCalledWith('/test/exit')
+      expect(saveAndExitMock).not.toHaveBeenCalled()
     })
   })
 
-  describe('POST handler with save-and-return action', () => {
-    it('should handle FormAction.SaveAndReturn', async () => {
+  describe('POST handler with save-and-exit action', () => {
+    it('should handle FormAction.SaveAndExit', async () => {
       const state: FormSubmissionState = {
         $$__referenceNumber: 'foobar',
         yesNoField: true
@@ -1467,27 +1400,27 @@ describe('Save and Return functionality', () => {
       const request = {
         ...requestPage1,
         method: 'post',
-        payload: { yesNoField: true, action: 'save-and-return' }
+        payload: { yesNoField: true, action: 'save-and-exit' }
       } as unknown as FormRequestPayload
 
       const context = model.getFormContext(request, state)
 
       jest.spyOn(controller1, 'getState').mockResolvedValue({})
       jest
-        .spyOn(controller1, 'handleSaveAndReturn')
-        .mockResolvedValue(h.redirect('/test/exit'))
+        .spyOn(controller1, 'handleSaveAndExit')
+        .mockReturnValue(h.redirect('/custom-save-and-exit'))
 
       const postHandler = controller1.makePostRouteHandler()
       await postHandler(request, context, h)
 
-      expect(controller1.handleSaveAndReturn).toHaveBeenCalledWith(
+      expect(controller1.handleSaveAndExit).toHaveBeenCalledWith(
         request,
         context,
         h
       )
     })
 
-    it('should not call handleSaveAndReturn for continue action', async () => {
+    it('should not call handleSaveAndExit for continue action', async () => {
       const state: FormSubmissionState = {
         $$__referenceNumber: 'foobar',
         yesNoField: true
@@ -1502,8 +1435,8 @@ describe('Save and Return functionality', () => {
 
       jest.spyOn(controller1, 'getState').mockResolvedValue({})
       jest
-        .spyOn(controller1, 'handleSaveAndReturn')
-        .mockResolvedValue(h.redirect('/test/exit'))
+        .spyOn(controller1, 'handleSaveAndExit')
+        .mockReturnValue(h.redirect('/custom-save-and-exit'))
       jest.spyOn(controller1, 'setState').mockResolvedValue(state)
 
       const mockResponse = {
@@ -1518,7 +1451,7 @@ describe('Save and Return functionality', () => {
       const postHandler = controller1.makePostRouteHandler()
       await postHandler(request, context, mockH)
 
-      expect(controller1.handleSaveAndReturn).not.toHaveBeenCalled()
+      expect(controller1.handleSaveAndExit).not.toHaveBeenCalled()
     })
   })
 })

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

@@ -9,7 +9,7 @@ import {
   type Page
 } from '@defra/forms-model'
 import Boom from '@hapi/boom'
-import { type ResponseToolkit, type RouteOptions } from '@hapi/hapi'
+import { type RouteOptions } from '@hapi/hapi'
 import { type ValidationErrorItem } from 'joi'
 
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
@@ -18,13 +18,14 @@ import { type BackLink } from '~/src/server/plugins/engine/components/types.js'
 import {
   getCacheService,
   getErrors,
-  getSaveAndReturnHelpers,
+  getSaveAndExitHelpers,
   normalisePath,
   proceed
 } from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
 import {
+  type AnyFormRequest,
   type FormContext,
   type FormContextRequest,
   type FormPageViewModel,
@@ -39,7 +40,8 @@ import {
   type FormRequest,
   type FormRequestPayload,
   type FormRequestPayloadRefs,
-  type FormRequestRefs
+  type FormRequestRefs,
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 import {
   actionSchema,
@@ -51,7 +53,7 @@ import { merge } from '~/src/server/services/cacheService.js'
 export class QuestionPageController extends PageController {
   collection: ComponentCollection
   errorSummaryTitle = 'There is a problem'
-  allowSaveAndReturn = true
+  allowSaveAndExit = true
 
   constructor(model: FormModel, pageDef: Page) {
     super(model, pageDef)
@@ -177,14 +179,11 @@ export class QuestionPageController extends PageController {
       showTitle,
       components,
       errors,
-      allowSaveAndReturn: this.shouldShowSaveAndReturn(request.server)
+      allowSaveAndExit: this.shouldShowSaveAndExit(request.server)
     }
   }
 
-  getRelevantPath(
-    request: FormRequest | FormRequestPayload,
-    context: FormContext
-  ) {
+  getRelevantPath(request: AnyFormRequest, context: FormContext) {
     const { paths } = context
 
     const startPath = this.getStartPath()
@@ -296,7 +295,7 @@ export class QuestionPageController extends PageController {
     return getErrors(details)
   }
 
-  async getState(request: FormRequest | FormRequestPayload) {
+  async getState(request: AnyFormRequest) {
     const { query } = request
 
     // Skip get for preview URL direct access
@@ -309,10 +308,7 @@ export class QuestionPageController extends PageController {
     return cacheService.getState(request)
   }
 
-  async setState(
-    request: FormRequest | FormRequestPayload,
-    state: FormSubmissionState
-  ) {
+  async setState(request: AnyFormRequest, state: FormSubmissionState) {
     const { query } = request
 
     // Skip set for preview URL direct access
@@ -326,7 +322,7 @@ export class QuestionPageController extends PageController {
   }
 
   async mergeState(
-    request: FormRequest | FormRequestPayload,
+    request: AnyFormRequest,
     state: FormSubmissionState,
     update: object
   ) {
@@ -397,7 +393,7 @@ export class QuestionPageController extends PageController {
     return async (
       request: FormRequest,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { collection, model, viewName } = this
       const { evaluationState } = context
@@ -492,7 +488,7 @@ export class QuestionPageController extends PageController {
     return async (
       request: FormRequestPayload,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { collection, viewName, model } = this
       const { isForceAccess, state, evaluationState } = context
@@ -515,10 +511,10 @@ export class QuestionPageController extends PageController {
         return h.view(viewName, viewModel)
       }
 
-      // Check if this is a save-and-return action
+      // Check if this is a save-and-exit action
       const { action } = request.payload
-      if (action === FormAction.SaveAndReturn) {
-        return this.handleSaveAndReturn(request, context, h)
+      if (action === FormAction.SaveAndExit) {
+        return this.handleSaveAndExit(request, context, h)
       }
 
       // Save and proceed
@@ -529,7 +525,7 @@ export class QuestionPageController extends PageController {
 
   proceed(
     request: FormContextRequest,
-    h: Pick<ResponseToolkit, 'redirect' | 'view'>,
+    h: FormResponseToolkit,
     nextPath?: string
   ) {
     const nextUrl = nextPath
@@ -540,28 +536,20 @@ export class QuestionPageController extends PageController {
   }
 
   /**
-   * Handle save-and-return action by processing form data and redirecting to exit page
+   * Handle save-and-exit action
    */
-  async handleSaveAndReturn(
+  handleSaveAndExit(
     request: FormRequestPayload,
     context: FormContext,
-    h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    h: FormResponseToolkit
   ) {
-    const { state } = context
+    const saveAndExit = getSaveAndExitHelpers(request.server)
 
-    // Save the current state and redirect to exit page
-    const saveAndReturn = getSaveAndReturnHelpers(request.server)
-
-    if (!saveAndReturn?.sessionPersister) {
-      throw Boom.internal('Server misconfigured for save and return')
+    if (!saveAndExit) {
+      throw Boom.internal('Server misconfigured for save and exit')
     }
 
-    await saveAndReturn.sessionPersister(state, request)
-
-    const cacheService = getCacheService(request.server)
-    await cacheService.clearState(request)
-
-    return h.redirect(this.getHref('/exit'))
+    return saveAndExit(request, h, context)
   }
 
   /**

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

@@ -3,7 +3,7 @@ import { RepeatPageController } from '~/src/server/plugins/engine/pageController
 import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
 import {
   server,
-  serverWithSaveAndReturn
+  serverWithSaveAndExit
 } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import {
   type FormContextRequest,
@@ -271,11 +271,9 @@ describe('RepeatPageController', () => {
     })
   })
 
-  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/RepeatPageController.ts

@@ -2,7 +2,6 @@ import { randomUUID } from 'crypto'
 
 import { type PageRepeat, type Repeat } from '@defra/forms-model'
 import Boom from '@hapi/boom'
-import { type ResponseToolkit } from '@hapi/hapi'
 import Joi from 'joi'
 
 import { isRepeatState } from '~/src/server/plugins/engine/components/FormComponent.js'
@@ -25,7 +24,8 @@ import {
 import {
   FormAction,
   type FormRequest,
-  type FormRequestPayload
+  type FormRequestPayload,
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 
 export class RepeatPageController extends QuestionPageController {
@@ -128,10 +128,7 @@ export class RepeatPageController extends QuestionPageController {
     }
   }
 
-  proceed(
-    request: FormContextRequest,
-    h: Pick<ResponseToolkit, 'redirect' | 'view'>
-  ) {
+  proceed(request: FormContextRequest, h: FormResponseToolkit) {
     const nextPath = this.getSummaryPath(request)
     return super.proceed(request, h, nextPath)
   }
@@ -151,7 +148,7 @@ export class RepeatPageController extends QuestionPageController {
     return async (
       request: FormRequest,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { path } = this
       const { query } = request
@@ -179,7 +176,7 @@ export class RepeatPageController extends QuestionPageController {
     return (
       request: FormRequest,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { path } = this
       const { query } = request
@@ -205,7 +202,7 @@ export class RepeatPageController extends QuestionPageController {
     return (
       request: FormRequestPayload,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { path, repeat } = this
       const { query } = request
@@ -269,7 +266,7 @@ export class RepeatPageController extends QuestionPageController {
     return (
       request: FormRequest,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { viewModel } = this
       const { state } = context
@@ -304,7 +301,7 @@ export class RepeatPageController extends QuestionPageController {
     return async (
       request: FormRequestPayload,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { repeat } = this
       const { state } = context

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

@@ -1,6 +1,6 @@
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { StartPageController } from '~/src/server/plugins/engine/pageControllers/StartPageController.js'
-import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
+import { serverWithSaveAndExit } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import definition from '~/test/form/definitions/basic.js'
 
 describe('StartPageController', () => {
@@ -22,9 +22,9 @@ describe('StartPageController', () => {
     controller = new StartPageController(model, mockPage as any)
   })
 
-  describe('shouldShowSaveAndReturn', () => {
-    it('should return false (StartPageController does not allow save and return)', () => {
-      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+  describe('shouldShowSaveAndExit', () => {
+    it('should return false (StartPageController does not allow save and exit)', () => {
+      expect(controller.shouldShowSaveAndExit(serverWithSaveAndExit)).toBe(
         false
       )
     })

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

@@ -9,7 +9,7 @@ export class StartPageController extends QuestionPageController {
    * but start pages should really live on gov.uk (whitehall publisher) so a user can be properly signposted.
    */
 
-  allowSaveAndReturn = false
+  allowSaveAndExit = false
 
   getViewModel(request: FormRequest, context: FormContext) {
     return {

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

@@ -1,6 +1,6 @@
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { StatusPageController } from '~/src/server/plugins/engine/pageControllers/StatusPageController.js'
-import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
+import { serverWithSaveAndExit } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import definition from '~/test/form/definitions/basic.js'
 
 describe('StatusPageController', () => {
@@ -22,9 +22,9 @@ describe('StatusPageController', () => {
     controller = new StatusPageController(model, mockPage as any)
   })
 
-  describe('shouldShowSaveAndReturn', () => {
-    it('should return false (StatusPageController does not allow save and return)', () => {
-      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
+  describe('shouldShowSaveAndExit', () => {
+    it('should return false (StatusPageController does not allow save and exit)', () => {
+      expect(controller.shouldShowSaveAndExit(serverWithSaveAndExit)).toBe(
         false
       )
     })

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

@@ -1,15 +1,17 @@
 import { type PageStatus } from '@defra/forms-model'
-import { type ResponseToolkit } from '@hapi/hapi'
 
 import { getCacheService } from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
 import { type FormContext } from '~/src/server/plugins/engine/types.js'
-import { type FormRequest } from '~/src/server/routes/types.js'
+import {
+  type FormRequest,
+  type FormResponseToolkit
+} from '~/src/server/routes/types.js'
 
 export class StatusPageController extends QuestionPageController {
   declare pageDef: PageStatus
-  allowSaveAndReturn = false
+  allowSaveAndExit = false
 
   constructor(model: FormModel, pageDef: PageStatus) {
     super(model, pageDef)
@@ -24,7 +26,7 @@ export class StatusPageController extends QuestionPageController {
     return async (
       request: FormRequest,
       context: FormContext,
-      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      h: FormResponseToolkit
     ) => {
       const { viewModel, viewName } = this