@defra/forms-engine-plugin 2.1.9 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/forms-engine-plugin",
-  "version": "2.1.9",
+  "version": "3.0.0",
   "description": "Defra forms engine",
   "type": "module",
   "files": [
@@ -28,7 +28,9 @@
     "./services/*": "./.server/server/plugins/engine/services/*",
     "./engine/*": "./.server/server/plugins/engine/*",
     "./helpers.js": "./.server/server/plugins/engine/components/helpers.js",
+    "./schema.js": "./.server/server/schemas/index.js",
     "./templates/*": "./.server/server/plugins/engine/views/*",
+    "./cache-service.js": "./.server/server/services/cacheService.js",
     "./package.json": "./package.json"
   },
   "scripts": {

package/src/server/index.test.ts

@@ -639,42 +639,3 @@ describe('prepareEnvironment', () => {
     )
   })
 })
-
-describe('Exit route handlers', () => {
-  let server: Server
-
-  beforeAll(async () => {
-    server = await createServer({
-      services: defaultServices
-    })
-    await server.initialize()
-  })
-
-  afterAll(async () => {
-    await server.stop()
-  })
-
-  beforeEach(() => {
-    jest.mocked(getFormMetadata).mockResolvedValue(fixtures.form.metadata)
-    server.app.models.clear()
-  })
-
-  test('GET /exit returns 200 with exit page content', async () => {
-    jest.mocked(getFormMetadata).mockResolvedValueOnce({
-      ...fixtures.form.metadata,
-      live: fixtures.form.state
-    })
-
-    jest.mocked(getFormDefinition).mockResolvedValue(fixtures.form.definition)
-
-    const options = {
-      method: 'GET',
-      url: `${FORM_PREFIX}/slug/exit`
-    }
-
-    const res = await server.inject(options)
-
-    expect(res.statusCode).toBe(StatusCodes.OK)
-    expect(res.result).toContain('Your progress has been saved')
-  })
-})

package/src/server/index.ts

@@ -82,8 +82,11 @@ export async function createServer(routeConfig?: RouteConfig) {
     prepareSecureContext(server)
   }
 
+  const cacheService = routeConfig?.cacheServiceCreator
+    ? routeConfig.cacheServiceCreator(server)
+    : undefined
   const pluginCrumb = configureCrumbPlugin(routeConfig)
-  const pluginEngine = await configureEnginePlugin(routeConfig)
+  const pluginEngine = await configureEnginePlugin(routeConfig, cacheService)
 
   await server.register(pluginSession)
   await server.register(pluginPulse)

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

@@ -86,9 +86,9 @@ There are a number of `LiquidJS` filters available to you from within the templa
 ]
 ```
 
-### Save and return
+### Save and exit
 
-See [our save and return feature page](/docs/features/code-based/SAVE_AND_RETURN.md).
+See [our save and exit feature page](/docs/features/code-based/SAVE_AND_EXIT.md).
 
 ### Additional notes
 

package/src/server/plugins/engine/components/MultilineTextField.test.ts

@@ -161,6 +161,17 @@ describe('MultilineTextField', () => {
         expect(answer2).toBe('')
       })
 
+      it('returns multiline text from state, collapsing multiple newlines into one', () => {
+        const state1 = getFormState('Line 1\r\nLine 2\r\nLine 3')
+        const state2 = getFormState('Line 1\r\n\r\nLine 2\r\n\r\n\r\nLine 3')
+
+        const answer1 = getAnswer(field, state1)
+        const answer2 = getAnswer(field, state2)
+
+        expect(answer1).toBe('Line 1<br>Line 2<br>Line 3<br>')
+        expect(answer2).toBe('Line 1<br>Line 2<br>Line 3<br>')
+      })
+
       it('returns payload from state', () => {
         const state1 = getFormState('Textarea')
         const state2 = getFormState(null)

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

@@ -315,7 +315,7 @@ export function getAnswerMarkdown(
   } else if (field instanceof Components.MultilineTextField) {
     // Preserve Multiline text new lines
     answerEscaped = answer
-      .split(/\r?\n/)
+      .split(/(?:\r?\n)+/)
       .map(escapeMarkdown)
       .join('\n')
       .concat('\n')

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

@@ -25,7 +25,7 @@ describe('helpers tests', () => {
 })
 
 describe('ComponentBase tests', () => {
-  test('should handle save and return functionality', () => {
+  test('should handle save and exit functionality', () => {
     const mockComponentDef = {
       type: 'TextField',
       name: 'testField',

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

@@ -10,17 +10,21 @@ import { formsService } from '~/src/server/plugins/engine/services/localFormsSer
 import { type PluginOptions } from '~/src/server/plugins/engine/types.js'
 import { findPackageRoot } from '~/src/server/plugins/engine/vision.js'
 import { devtoolContext } from '~/src/server/plugins/nunjucks/context.js'
+import { type CacheService } from '~/src/server/services/cacheService.js'
 import { type RouteConfig } from '~/src/server/types.js'
 
-export const configureEnginePlugin = async ({
-  formFileName,
-  formFilePath,
-  services,
-  controllers,
-  preparePageEventRequestOptions,
-  onRequest,
-  saveAndReturn
-}: RouteConfig = {}): Promise<{
+export const configureEnginePlugin = async (
+  {
+    formFileName,
+    formFilePath,
+    services,
+    controllers,
+    preparePageEventRequestOptions,
+    onRequest,
+    saveAndExit
+  }: RouteConfig = {},
+  cache?: CacheService
+): Promise<{
   plugin: typeof plugin
   options: PluginOptions
 }> => {
@@ -50,7 +54,7 @@ export const configureEnginePlugin = async ({
         formsService: await formsService()
       },
       controllers,
-      cacheName: 'session',
+      cache: cache ?? 'session',
       nunjucks: {
         baseLayoutPath: 'dxt-devtool-baselayout.html',
         paths: [join(findPackageRoot(), 'src/server/devserver')] // custom layout to make it really clear this is not the same as the runner
@@ -59,7 +63,7 @@ export const configureEnginePlugin = async ({
       preparePageEventRequestOptions,
       onRequest,
       baseUrl: 'http://localhost:3009', // always runs locally
-      saveAndReturn
+      saveAndExit
     }
   }
 }

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

@@ -30,7 +30,8 @@ import {
 import {
   FormAction,
   FormStatus,
-  type FormRequest
+  type FormRequest,
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 import definition from '~/test/form/definitions/basic.js'
 import templateDefinition from '~/test/form/definitions/templates.js'
@@ -47,7 +48,7 @@ type HrefFilter = (this: NunjucksContext, path: string) => string | undefined
 describe('Helpers', () => {
   let page: PageControllerClass
   let request: FormContextRequest
-  let h: Pick<ResponseToolkit, 'redirect' | 'view'>
+  let h: FormResponseToolkit
 
   beforeEach(() => {
     const model = new FormModel(definition, {

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