@defra/forms-engine-plugin 2.1.10 → 3.0.1

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
   }
 }

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)
     })
   })
 })