@defra/forms-engine-plugin 4.0.28 → 4.0.30

package/src/server/plugins/engine/beta/form-context.ts

@@ -0,0 +1,250 @@
+import Boom from '@hapi/boom'
+import { type Request, type Server } from '@hapi/hapi'
+import { isEqual } from 'date-fns'
+
+import { PREVIEW_PATH_PREFIX } from '~/src/server/constants.js'
+import {
+  checkEmailAddressForLiveFormSubmission,
+  getCacheService
+} from '~/src/server/plugins/engine/helpers.js'
+import { FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { TerminalPageController } from '~/src/server/plugins/engine/pageControllers/index.js'
+import * as defaultServices from '~/src/server/plugins/engine/services/index.js'
+import {
+  type AnyRequest,
+  type FormContext,
+  type FormContextRequest,
+  type FormSubmissionError,
+  type FormSubmissionState
+} from '~/src/server/plugins/engine/types.js'
+import { FormStatus } from '~/src/server/routes/types.js'
+import { type Services } from '~/src/server/types.js'
+
+type JourneyState = FormStatus | 'preview'
+
+export interface FormModelOptions {
+  services?: Services
+  controllers?: Record<string, typeof PageController>
+  basePath?: string
+  versionNumber?: number
+  ordnanceSurveyApiKey?: string
+  formId?: string
+  routePrefix?: string
+  isPreview?: boolean
+}
+
+export interface FormContextOptions extends FormModelOptions {
+  errors?: FormSubmissionError[]
+}
+
+type SummaryRequest = FormContextRequest & {
+  yar: Request['yar']
+}
+
+export async function getFormModel(
+  slug: string,
+  state: JourneyState,
+  options: FormModelOptions = {}
+) {
+  const services = options.services ?? defaultServices
+  const { formsService } = services
+  const isPreview = isPreviewState(state, options)
+  const formState = resolveState(state)
+
+  const metadata = await formsService.getFormMetadata(slug)
+  const versionNumber =
+    options.versionNumber ?? metadata.versions?.[0]?.versionNumber
+
+  const definition = await formsService.getFormDefinition(
+    metadata.id,
+    formState
+  )
+
+  if (!definition) {
+    throw Boom.notFound(
+      `No definition found for form metadata ${metadata.id} (${slug}) ${state}`
+    )
+  }
+
+  return new FormModel(
+    definition,
+    {
+      basePath:
+        options.basePath ??
+        buildBasePath(options.routePrefix ?? '', slug, formState, isPreview),
+      versionNumber,
+      ordnanceSurveyApiKey: options.ordnanceSurveyApiKey,
+      formId: options.formId ?? metadata.id
+    },
+    services,
+    options.controllers
+  )
+}
+
+export async function getFormContext(
+  { server, yar }: Pick<Request, 'server' | 'yar'>,
+  slug: string,
+  state: JourneyState = FormStatus.Live,
+  options: FormContextOptions = {}
+): Promise<FormContext> {
+  const formModel = await resolveFormModel(server, slug, state, options)
+
+  const cacheService = getCacheService(server)
+
+  const summaryRequest: SummaryRequest = {
+    app: {},
+    method: 'get',
+    params: {
+      path: 'summary',
+      slug,
+      ...(isPreviewState(state, options) && {
+        state: resolveState(state)
+      })
+    },
+    path: `/${formModel.basePath}/summary`,
+    query: {},
+    url: new URL(
+      `/${formModel.basePath}/summary`,
+      'https://form-context.local'
+    ),
+    server,
+    yar
+  }
+
+  const cachedState = await cacheService.getState(
+    summaryRequest as unknown as AnyRequest
+  )
+
+  const formState = {
+    ...cachedState,
+    $$__referenceNumber: cachedState.$$__referenceNumber
+  } as unknown as FormSubmissionState
+
+  return formModel.getFormContext(
+    summaryRequest,
+    formState,
+    options.errors ?? []
+  )
+}
+
+export async function resolveFormModel(
+  server: Server,
+  slug: string,
+  state: JourneyState,
+  options: FormModelOptions = {}
+) {
+  const services = options.services ?? defaultServices
+  const { formsService } = services
+
+  const metadata = await formsService.getFormMetadata(slug)
+  const formState = resolveState(state)
+  const isPreview = options.isPreview ?? isPreviewState(state, options)
+  const stateMetadata = metadata[formState]
+
+  if (!stateMetadata) {
+    throw Boom.notFound(
+      `No '${formState}' state for form metadata ${metadata.id}`
+    )
+  }
+
+  // The models cache is created lazily per server instance
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!server.app.models) {
+    server.app.models = new Map<string, { model: FormModel; updatedAt: Date }>()
+  }
+
+  const cache = server.app.models as Map<
+    string,
+    { model: FormModel; updatedAt: Date }
+  >
+
+  const cacheKey = `${metadata.id}_${formState}_${isPreview}`
+  let entry = cache.get(cacheKey)
+
+  if (!entry || !isEqual(entry.updatedAt, stateMetadata.updatedAt)) {
+    const definition = await formsService.getFormDefinition(
+      metadata.id,
+      formState
+    )
+
+    if (!definition) {
+      throw Boom.notFound(
+        `No definition found for form metadata ${metadata.id} (${slug}) ${state}`
+      )
+    }
+
+    const emailAddress = metadata.notificationEmail ?? definition.outputEmail
+
+    checkEmailAddressForLiveFormSubmission(emailAddress, isPreview)
+
+    const routePrefix =
+      options.routePrefix ?? server.realm.modifiers.route.prefix
+
+    const model = new FormModel(
+      definition,
+      {
+        basePath:
+          options.basePath ??
+          buildBasePath(routePrefix, slug, formState, isPreview),
+        versionNumber:
+          options.versionNumber ?? metadata.versions?.[0]?.versionNumber,
+        ordnanceSurveyApiKey: options.ordnanceSurveyApiKey,
+        formId: options.formId ?? metadata.id
+      },
+      services,
+      options.controllers
+    )
+
+    entry = { model, updatedAt: stateMetadata.updatedAt }
+    cache.set(cacheKey, entry)
+  }
+
+  return entry.model
+}
+
+function buildBasePath(
+  routePrefix: string,
+  slug: string,
+  state: FormStatus,
+  isPreview: boolean
+) {
+  const base = (
+    isPreview
+      ? `${routePrefix}${PREVIEW_PATH_PREFIX}/${state}/${slug}`
+      : `${routePrefix}/${slug}`
+  ).replace(/\/{2,}/g, '/')
+
+  return base.startsWith('/') ? base.slice(1) : base
+}
+
+export function getFirstJourneyPage(
+  context?: Pick<FormContext, 'relevantPages'>
+) {
+  if (!context?.relevantPages) {
+    return undefined
+  }
+
+  const lastPageReached = context.relevantPages.at(-1)
+  const penultimatePageReached = context.relevantPages.at(-2)
+
+  if (
+    lastPageReached instanceof TerminalPageController &&
+    penultimatePageReached
+  ) {
+    return penultimatePageReached
+  }
+
+  return lastPageReached
+}
+
+function resolveState(state: JourneyState): FormStatus {
+  return state === 'preview' ? FormStatus.Live : state
+}
+
+function isPreviewState(
+  state: JourneyState,
+  options: FormModelOptions = {}
+): boolean {
+  return options.isPreview ?? state === 'preview'
+}

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

@@ -14,6 +14,12 @@ import * as filters from '~/src/server/plugins/nunjucks/filters/index.js'
 
 export { getPageHref } from '~/src/server/plugins/engine/helpers.js'
 export { context } from '~/src/server/plugins/nunjucks/context.js'
+export {
+  getFirstJourneyPage,
+  getFormContext,
+  getFormModel,
+  resolveFormModel
+} from '~/src/server/plugins/engine/beta/form-context.js'
 
 const globals = {
   checkComponentTemplates,

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

@@ -716,4 +716,74 @@ describe('FormModel - Joined Conditions', () => {
       expect(Object.keys(model.conditions)).toHaveLength(3)
     })
   })
+
+  describe('getSection', () => {
+    it('should look up section by name for V1 schema', () => {
+      const v1Definition = {
+        ...definition,
+        sections: [
+          { name: 'personal', title: 'Personal details' },
+          { name: 'contact', title: 'Contact details' }
+        ]
+      }
+
+      const model = new FormModel(v1Definition, { basePath: 'test' })
+
+      expect(model.getSection('personal')).toEqual(
+        expect.objectContaining({
+          name: 'personal',
+          title: 'Personal details'
+        })
+      )
+      expect(model.getSection('contact')).toEqual(
+        expect.objectContaining({
+          name: 'contact',
+          title: 'Contact details'
+        })
+      )
+      expect(model.getSection('nonexistent')).toBeUndefined()
+    })
+
+    it('should look up section by ID for V2 schema', () => {
+      const v2Definition = {
+        ...definitionV2,
+        sections: [
+          {
+            id: 'a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
+            name: 'personal',
+            title: 'Personal details'
+          },
+          {
+            id: 'b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e',
+            name: 'contact',
+            title: 'Contact details'
+          }
+        ]
+      }
+
+      formDefinitionV2Schema.validate = jest
+        .fn()
+        .mockReturnValue({ value: v2Definition })
+
+      const model = new FormModel(v2Definition, { basePath: 'test' })
+
+      expect(model.getSection('a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d')).toEqual(
+        expect.objectContaining({
+          id: 'a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
+          name: 'personal',
+          title: 'Personal details'
+        })
+      )
+      expect(model.getSection('b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e')).toEqual(
+        expect.objectContaining({
+          id: 'b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e',
+          name: 'contact',
+          title: 'Contact details'
+        })
+      )
+      // V2 should not find by name
+      expect(model.getSection('personal')).toBeUndefined()
+      expect(model.getSection('nonexistent')).toBeUndefined()
+    })
+  })
 })

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

@@ -21,7 +21,8 @@ import {
   type Engine,
   type FormDefinition,
   type List,
-  type Page
+  type Page,
+  type Section
 } from '@defra/forms-model'
 import { add, format } from 'date-fns'
 import { Parser, type Value } from 'expr-eval-fork'
@@ -321,12 +322,18 @@ export class FormModel {
       : this.lists.find((list) => list.id === nameOrId)
   }
 
+  getSection(nameOrId: string): Section | undefined {
+    return this.schemaVersion === SchemaVersion.V1
+      ? this.sections.find((section) => section.name === nameOrId)
+      : this.sections.find((section) => section.id === nameOrId)
+  }
+
   /**
    * Form context for the current page
    */
   getFormContext(
     request: FormContextRequest,
-    state: FormState,
+    state: FormSubmissionState,
     errors?: FormSubmissionError[]
   ): FormContext {
     const { query } = request
@@ -625,7 +632,7 @@ function validateFormState(
   return context
 }
 
-function getReferenceNumber(state: FormState): string {
+function getReferenceNumber(state: FormSubmissionState): string {
   if (
     !state.$$__referenceNumber ||
     typeof state.$$__referenceNumber !== 'string'

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

@@ -55,9 +55,9 @@ export class PageController {
     this.events = pageDef.events
 
     // Resolve section
-    this.section = model.sections.find(
-      (section) => section.name === pageDef.section
-    )
+    if (pageDef.section) {
+      this.section = model.getSection(pageDef.section)
+    }
 
     // Resolve condition
     if (pageDef.condition) {

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

@@ -1007,11 +1007,13 @@ describe('QuestionPageController V2', () => {
 
     it('returns the page section', () => {
       expect(controller1).toHaveProperty('section', undefined)
-      expect(controller2).toHaveProperty('section', {
-        name: 'marriage',
-        title: 'Your marriage',
-        hideTitle: false
-      })
+      expect(controller2.section).toEqual(
+        expect.objectContaining({
+          name: 'marriage',
+          title: 'Your marriage',
+          hideTitle: false
+        })
+      )
     })
   })
 

package/src/server/plugins/engine/routes/index.ts

@@ -4,19 +4,17 @@ import {
   type ResponseToolkit,
   type Server
 } from '@hapi/hapi'
-import { isEqual } from 'date-fns'
 
 import {
   EXTERNAL_STATE_APPENDAGE,
-  EXTERNAL_STATE_PAYLOAD,
-  PREVIEW_PATH_PREFIX
+  EXTERNAL_STATE_PAYLOAD
 } from '~/src/server/constants.js'
+import { resolveFormModel } from '~/src/server/plugins/engine/beta/form-context.js'
 import {
   FormComponent,
   isFormState
 } from '~/src/server/plugins/engine/components/FormComponent.js'
 import {
-  checkEmailAddressForLiveFormSubmission,
   checkFormStatus,
   findPage,
   getCacheService,
@@ -24,7 +22,6 @@ import {
   getStartPath,
   proceed
 } from '~/src/server/plugins/engine/helpers.js'
-import { FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
 import { generateUniqueReference } from '~/src/server/plugins/engine/referenceNumbers.js'
 import * as defaultServices from '~/src/server/plugins/engine/services/index.js'
@@ -179,8 +176,6 @@ export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
     ordnanceSurveyApiKey
   } = options
 
-  const { formsService } = services
-
   async function handler(request: AnyFormRequest, h: ResponseToolkit) {
     if (server.app.model) {
       request.app.model = server.app.model
@@ -192,71 +187,15 @@ export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
     const { slug } = params
     const { isPreview, state: formState } = checkFormStatus(params)
 
-    // Get the form metadata using the `slug` param
-    const metadata = await formsService.getFormMetadata(slug)
-
-    const { id, [formState]: state } = metadata
-
-    // Check the metadata supports the requested state
-    if (!state) {
-      throw Boom.notFound(`No '${formState}' state for form metadata ${id}`)
-    }
-
-    // Cache the models based on id, state and whether
-    // it's a preview or not. There could be up to 3 models
-    // cached for a single form:
-    // "{id}_live_false" (live/live)
-    // "{id}_live_true" (live/preview)
-    // "{id}_draft_true" (draft/preview)
-    const key = `${id}_${formState}_${isPreview}`
-    let item = server.app.models.get(key)
-
-    if (!item || !isEqual(item.updatedAt, state.updatedAt)) {
-      server.logger.info(`Getting form definition ${id} (${slug}) ${formState}`)
-
-      // Get the form definition using the `id` from the metadata
-      const definition = await formsService.getFormDefinition(id, formState)
-
-      if (!definition) {
-        throw Boom.notFound(
-          `No definition found for form metadata ${id} (${slug}) ${formState}`
-        )
-      }
-
-      const emailAddress = metadata.notificationEmail ?? definition.outputEmail
-
-      checkEmailAddressForLiveFormSubmission(emailAddress, isPreview)
-
-      // Build the form model
-      server.logger.info(
-        `Building model for form definition ${id} (${slug}) ${formState}`
-      )
-
-      // Set up the basePath for the model
-      const basePath = (
-        isPreview
-          ? `${prefix}${PREVIEW_PATH_PREFIX}/${formState}/${slug}`
-          : `${prefix}/${slug}`
-      ).substring(1)
-
-      const versionNumber = metadata.versions?.[0]?.versionNumber
-
-      // Construct the form model
-      const model = new FormModel(
-        definition,
-        { basePath, versionNumber, ordnanceSurveyApiKey, formId: id },
-        services,
-        controllers
-      )
-
-      // Create new item and add it to the item cache
-      item = { model, updatedAt: state.updatedAt }
-      server.app.models.set(key, item)
-    }
+    const model = await resolveFormModel(server, slug, formState, {
+      services,
+      controllers,
+      ordnanceSurveyApiKey,
+      routePrefix: prefix,
+      isPreview
+    })
 
-    // Assign the model to the request data
-    // for use in the downstream handler
-    request.app.model = item.model
+    request.app.model = model
 
     return h.continue
   }