@dwp/govuk-casa 8.15.0 → 9.1.0

package/src/casa.js

@@ -1,17 +1,17 @@
 // NOTE: Any changes made here must be reflected in `scripts/esm-wrapper.js`
-import configure from './lib/configure.js';
-import validators from './lib/validators/index.js';
-import field from './lib/field.js';
-import Plan from './lib/Plan.js';
-import JourneyContext from './lib/JourneyContext.js';
-import ValidatorFactory from './lib/ValidatorFactory.js';
-import ValidationError from './lib/ValidationError.js';
-import MutableRouter from './lib/MutableRouter.js';
-import waypointUrl from './lib/waypoint-url.js';
-import endSession from './lib/end-session.js';
-import * as nunjucksFilters from './lib/nunjucks-filters.js';
-import * as constants from './lib/constants.js';
-import * as contextIdGenerators from './lib/context-id-generators.js';
+import configure from "./lib/configure.js";
+import validators from "./lib/validators/index.js";
+import field from "./lib/field.js";
+import Plan from "./lib/Plan.js";
+import JourneyContext from "./lib/JourneyContext.js";
+import ValidatorFactory from "./lib/ValidatorFactory.js";
+import ValidationError from "./lib/ValidationError.js";
+import MutableRouter from "./lib/MutableRouter.js";
+import waypointUrl from "./lib/waypoint-url.js";
+import endSession from "./lib/end-session.js";
+import * as nunjucksFilters from "./lib/nunjucks-filters.js";
+import * as constants from "./lib/constants.js";
+import * as contextIdGenerators from "./lib/context-id-generators.js";
 
 /** @module @dwp/govuk-casa */
 export {
@@ -41,9 +41,7 @@ export {
 /* ----------------------------------------------------------------- Typedefs */
 // These exist here so that consumer can import CASA's internal types
 
-/**
- * @typedef {import('./lib/field').PageField} PageField
- */
+/** @typedef {import("./lib/field").PageField} PageField */
 
 /**
  * @typedef {object} ContextEventHandlerOptions
@@ -61,7 +59,8 @@ export {
 
 /**
  * @typedef {object} ContextEventUserInfo
- * @property {symbol} [casaRequestPhase] Request phase at which event is triggered
+ * @property {symbol} [casaRequestPhase] Request phase at which event is
+ *   triggered
  */
 
 /**
@@ -72,48 +71,58 @@ export {
  */
 
 /**
- * @typedef {object} Page Page configuration. A Page is the interactive representation of a waypoint
+ * @typedef {object} Page Page configuration. A Page is the interactive
+ *   representation of a waypoint
  * @property {string} waypoint The waypoint with which this page is associated
  * @property {string} view Template path
- * @property {PageHook[]} [hooks=[]] Page-specific hooks (optional, default [])
- * @property {PageField[]} [fields=[]] Fields to be managed on this page (optional, default [])
+ * @property {PageHook[]} [hooks=[]] Page-specific hooks (optional, default []).
+ *   Default is `[]`
+ * @property {PageField[]} [fields=[]] Fields to be managed on this page
+ *   (optional, default []). Default is `[]`
  */
 
 /**
  * @typedef {object} I18nOptions
  * @property {string[]} dirs Directories to search for locale dictionaries
- * @property {string[]} [locales=['en', 'cy']] Supported locales
+ * @property {string[]} [locales=['en', 'cy']] Supported locales. Default is
+ *   `['en', 'cy']`
  */
 
 /**
  * @typedef {object} GlobalHook Hook configuration
  * @property {string} hook Hook name in format `<router>.<hook>`
- * @property {Function} middleware Middleware function to insert at the hook point
- * @property {string|RegExp} [path=undefined] Only run if route path matches this string/regexp
+ * @property {Function} middleware Middleware function to insert at the hook
+ *   point
+ * @property {string | RegExp} [path=undefined] Only run if route path matches
+ *   this string/regexp. Default is `undefined`
  */
 
 /**
  * @typedef {object} PageHook (extends GlobalHook)
  * @property {string} hook Hook name (without a scope prefix)
- * @property {Function} middleware Middleware function to insert at the hook point
+ * @property {Function} middleware Middleware function to insert at the hook
+ *   point
  */
 
 /**
  * @typedef {object} SessionOptions
- * @property {string} [name=casasession] Session name
- * @property {string} [secret=secret] Encryption secret
- * @property {number} [ttl=3600] Session ttl (seconds)
- * @property {boolean} [secure=false] Whether to use secure session cookies
- * @property {boolean|string} [cookieSameSite=true] SameSite (true = Strict)
+ * @property {string} [name=casasession] Session name. Default is `casasession`
+ * @property {string} [secret=secret] Encryption secret. Default is `secret`
+ * @property {number} [ttl=3600] Session ttl (seconds). Default is `3600`
+ * @property {boolean} [secure=false] Whether to use secure session cookies.
+ *   Default is `false`
+ * @property {boolean | string} [cookieSameSite=true] SameSite (true = Strict).
+ *   Default is `true`
  * @property {object} [store] Session store (default MemoryStore)
- * @property {string} [cookiePath] the URL path on which the session cookie
- * is valid (defaults to '/')
+ * @property {string} [cookiePath] The URL path on which the session cookie is
+ *   valid (defaults to '/')
  */
 
 /**
  * @typedef {object} IPlugin Plugin interface
  * @property {PluginConfigureFunction} [configure] Modify the app config
- * @property {PluginBootstrapFunction} [bootstrap] Modify post-configuration artifacts
+ * @property {PluginBootstrapFunction} [bootstrap] Modify post-configuration
+ *   artifacts
  */
 
 /**
@@ -135,17 +144,18 @@ export {
 /**
  * Mounting function.
  *
- * This will mount all of the routes and middleware in the correct order on
- * the given ExpressJS app.
+ * This will mount all of the routes and middleware in the correct order on the
+ * given ExpressJS app.
  *
  * Once this is called, you will not be able to modify any of the routers as
  * they will be "sealed".
  *
  * @callback Mounter
- * @param {import('express').Express} app Express application
+ * @param {import("express").Express} app Express application
  * @param {object} opts Mounting options
- * @param {string} [opts.route='/'] Optional route to attach all middleware/routers too
- * @returns {import('express').Express} The prepared ExpressJS app instance
+ * @param {string} [opts.route='/'] Optional route to attach all
+ *   middleware/routers too. Default is `'/'`
+ * @returns {import("express").Express} The prepared ExpressJS app instance
  */
 
 /**
@@ -153,76 +163,88 @@ export {
  *
  * @typedef {object} ConfigurationOptions Configuration options
  * @property {string} [mountUrl] Prefix for all URLS in browser address bar
- * @property {string[]} [views=[]] Template directories
+ * @property {string[]} [views=[]] Template directories. Default is `[]`
  * @property {SessionOptions} [session] Session configuration
- * @property {Page[]} [pages=[]] Pages the represent waypoints
- * @property {GlobalHook[]} [hooks=[]] Hooks to apply
- * @property {IPlugin[]} [plugins=[]] Plugins
+ * @property {Page[]} [pages=[]] Pages the represent waypoints. Default is `[]`
+ * @property {GlobalHook[]} [hooks=[]] Hooks to apply. Default is `[]`
+ * @property {IPlugin[]} [plugins=[]] Plugins. Default is `[]`
  * @property {I18nOptions} [i18n] I18n configuration
  * @property {Plan} [plan] CASA Plan
- * @property {ContextEvent[]} [events=[]] Handlers for JourneyContext events
- * @property {HelmetConfigurator} [helmetConfigurator] Helmet configuration manipulator function
- * @property {number} [formMaxParams=25] Max number of form parameters to ingest
- * @property {number|string} [formMaxBytes="50KB"] Max total form payload size to ingest
- * @property {ContextIdGenerator} [contextIdGenerator] Custom context ID generator
- * @property {symbol|Function} [errorVisibility] option to keep page errors active on GET request
+ * @property {ContextEvent[]} [events=[]] Handlers for JourneyContext events.
+ *   Default is `[]`
+ * @property {HelmetConfigurator} [helmetConfigurator] Helmet configuration
+ *   manipulator function
+ * @property {number} [formMaxParams=25] Max number of form parameters to
+ *   ingest. Default is `25`
+ * @property {number | string} [formMaxBytes="50KB"] Max total form payload size
+ *   to ingest. Default is `"50KB"`
+ * @property {ContextIdGenerator} [contextIdGenerator] Custom context ID
+ *   generator
+ * @property {symbol | Function} [errorVisibility] Option to keep page errors
+ *   active on GET request
  */
 
 /**
  * @typedef {object} ConfigureResult Result of a call to configure() function
- * @property {import('nunjucks').Environment} nunjucksEnv Nunjucks environment
+ * @property {import("nunjucks").Environment} nunjucksEnv Nunjucks environment
  * @property {MutableRouter} staticRouter Router handling all static assets
  * @property {MutableRouter} ancillaryRouter Router handling ancillary routes
  * @property {MutableRouter} journeyRouter Router handling all waypoint requests
- * @property {import('express').RequestHandler[]} preMiddleware Middleware mounted before everything
- * @property {import('express').RequestHandler[]} postMiddleware Middleware mounted after everything
- * @property {import('express').RequestHandler[]} csrfMiddleware CSRF get/set form middleware
- * @property {import('express').RequestHandler} sessionMiddleware Session middleware
- * @property {import('express').RequestHandler[]} cookieParserMiddleware Cookie-parsing middleware
- * @property {import('express').RequestHandler[]} i18nMiddleware I18n preparation middleware
- * @property {import('express').RequestHandler} bodyParserMiddleware Body parsing middleware
- * @property {Mounter} mount Function used to mount all CASA artifacts onto an ExpressJS app
- * @property {ConfigurationOptions} config Ingested config supplied to `configure()`
- */
-
-/**
- * Configuration for generating a ValidationError.
- * i.e. `new ValidationError(configObject)`
- * <br/><br/>
- *
- * The `fieldKeySuffix` is used to differentiate errors attached to
- * the same field name. For example, given these fields inputs ...
+ * @property {import("express").RequestHandler[]} preMiddleware Middleware
+ *   mounted before everything
+ * @property {import("express").RequestHandler[]} postMiddleware Middleware
+ *   mounted after everything
+ * @property {import("express").RequestHandler[]} csrfMiddleware CSRF get/set
+ *   form middleware
+ * @property {import("express").RequestHandler} sessionMiddleware Session
+ *   middleware
+ * @property {import("express").RequestHandler[]} cookieParserMiddleware
+ *   Cookie-parsing middleware
+ * @property {import("express").RequestHandler[]} i18nMiddleware I18n
+ *   preparation middleware
+ * @property {import("express").RequestHandler} bodyParserMiddleware Body
+ *   parsing middleware
+ * @property {Mounter} mount Function used to mount all CASA artifacts onto an
+ *   ExpressJS app
+ * @property {ConfigurationOptions} config Ingested config supplied to
+ *   `configure()`
+ */
+
+/**
+ * Configuration for generating a ValidationError. i.e. `new
+ * ValidationError(configObject)` <br/><br/>
  *
- * <pre>
- * &lt;input name="dateOfBirth[dd]" /&gt;
- * &lt;input name="dateOfBirth[mm]" /&gt;
- * &lt;input name="dateOfBirth[yyyy]" /&gt;
- * </pre>
+ * The `fieldKeySuffix` is used to differentiate errors attached to the same
+ * field name. For example, given these fields inputs ...<pre> <input
+ * name="dateOfBirth[dd]" /> <input name="dateOfBirth[mm]" /> <input
+ * name="dateOfBirth[yyyy]" /> </pre>
  *
- * If we wanted to generate an error specifically for the `dd`
- * element, then we'd include `{ fieldKeySuffix: '[dd]' }` in this
- * config.
- * <br/><br/>
+ * If we wanted to generate an error specifically for the `dd` element, then
+ * we'd include `{ fieldKeySuffix: '[dd]' }` in this config. <br/><br/>
  *
- * We can also use `focusSuffix` to control which properties of an
- * object field should be highlighted with a red border when in error. Looking
- * again at the `dateOfBirth` example above, if we did not specify
- * any `focusSuffix`, then all three inputs would be highlighted.
- * However, if we use `{ focusSuffix: ['[dd]', '[yyyy]'] }` then only
- * the `[dd]` and `[yyyy]` inputs would be highlighted.
- * <br/><br/>
+ * We can also use `focusSuffix` to control which properties of an object field
+ * should be highlighted with a red border when in error. Looking again at the
+ * `dateOfBirth` example above, if we did not specify any `focusSuffix`, then
+ * all three inputs would be highlighted. However, if we use `{ focusSuffix:
+ * ['[dd]', '[yyyy]'] }` then only the `[dd]` and `[yyyy]` inputs would be
+ * highlighted. <br/><br/>
  *
- * The `fieldHref` and `field` properties are strictly for
- * internal use only and public access may be removed at any point.
+ * The `fieldHref` and `field` properties are strictly for internal use only and
+ * public access may be removed at any point.
  *
  * @typedef {object} ErrorMessageConfigObject
  * @property {string} summary Summary message
- * @property {string} [inline] Inline message (@deprecated now uses summary everywhere)
- * @property {string|string[]} [focusSuffix] String(s) to append to URL hash for focusing inputs
- * @property {string} [fieldKeySuffix] Object fields may use this to show errors per sub-property
- * @property {object|ErrorMessageVariablesGenerator} [variables] Interpolation variables
+ * @property {string} [inline] Inline message (@deprecated now uses summary
+ *   everywhere)
+ * @property {string | string[]} [focusSuffix] String(s) to append to URL hash
+ *   for focusing inputs
+ * @property {string} [fieldKeySuffix] Object fields may use this to show errors
+ *   per sub-property
+ * @property {object | ErrorMessageVariablesGenerator} [variables]
+ *   Interpolation variables
  * @property {string} [validator] Name of the validator
- * @property {string} [fieldHref] (internal) URL hash to link to field in UI, i.e `#f-..`
+ * @property {string} [fieldHref] (internal) URL hash to link to field in UI,
+ *   i.e `#f-..`
  * @property {string} [field] (internal) Field name, including any focus suffix
  */
 
@@ -238,11 +260,14 @@ export {
 /**
  * @callback ErrorMessageConfigGenerator
  * @param {ValidateContext} dataContext Data context
- * @returns {string|ErrorMessageConfigObject} Compiled error message config
+ * @returns {string | ErrorMessageConfigObject} Compiled error message config
  */
 
 /**
- * @typedef {string|ErrorMessageConfigObject|ErrorMessageConfigGenerator|Error} ErrorMessageConfig
+ * @typedef {string
+ *   | ErrorMessageConfigObject
+ *   | ErrorMessageConfigGenerator
+ *   | Error} ErrorMessageConfig
  */
 
 /**
@@ -257,7 +282,7 @@ export {
 /**
  * @callback ValidateFunction
  * @param {any} value
- * @param {ValidateContext} context Vaildation context
+ * @param {ValidateContext} context Validation context
  * @returns {ValidationError[]}
  */
 
@@ -270,7 +295,8 @@ export {
 /**
  * @typedef {object} Validator
  * @property {ValidateFunction} validate Validation function
- * @property {FieldProcessorFunction} sanitise Sanitise a given value prior to validation
+ * @property {FieldProcessorFunction} sanitise Sanitise a given value prior to
+ *   validation
  * @property {object} config Configuration
  * @property {string} name Validator name
  */
@@ -280,7 +306,6 @@ export {
  * @property {string} fieldName Field name
  * @property {any} fieldValue Field value
  * @property {string} waypoint Waypoint
- * @property {string} waypointId [DEPRECATED] Waypoint (for backwards compatibility with v7)
  * @property {JourneyContext} journeyContext Journey Context
  */
 
@@ -309,29 +334,34 @@ export {
 
 /**
  * @typedef PlanTraverseOptions
- * @property {string} [startWaypoint] Waypoint from which to start (defaults to first in list)
+ * @property {string} [startWaypoint] Waypoint from which to start (defaults to
+ *   first in list)
  * @property {string} routeName Follow routes matching this name (next | prev)
  * @property {Map} history Used to detect loops in traversal (INTERNAL USE ONLY)
- * @property {Function} [stopCondition] If true, traversal will be stopped (useful for performance)
- * @property {string|PlanArbiter} [arbiter] Multiple target routes found, this decides which to use
+ * @property {Function} [stopCondition] If true, traversal will be stopped
+ *   (useful for performance)
+ * @property {string | PlanArbiter} [arbiter] Multiple target routes found, this
+ *   decides which to use
  */
 
 /**
  * @typedef {object} PlanArbiterParams
  * @property {PlanRoute[]} targets Potential target routes that need arbitration
  * @property {JourneyContext} journeyContext Journey Context
- * @property {PlanTraverseOptions} traverseOptions Original traverse options passed to `traverse()`
+ * @property {PlanTraverseOptions} traverseOptions Original traverse options
+ *   passed to `traverse()`
  */
 
 /**
  * @callback PlanArbiter
  * @param {PlanArbiterParams} route Route metadata
- * @returns {PlanRoute[]} Returns all routes, excluding those that the arbiter could eliminate
+ * @returns {PlanRoute[]} Returns all routes, excluding those that the arbiter
+ *   could eliminate
  */
 
 /**
  * @typedef {object} JourneyContextObject Journey Context Object
- * @property {Record<string,any>} [data] Data
+ * @property {Record<string, any>} [data] Data
  * @property {any} [validation] Validation state
  * @property {any} [nav] Navigation meta
  * @property {any} [identity] Identity meta
@@ -340,8 +370,9 @@ export {
 /**
  * @typedef ContextIdGeneratorParams
  * @property {object} args Arguments
- * @property {import('express').Request} args.req Request
- * @property {[string]} args.reservedIds List of IDs already in use in session or request
+ * @property {import("express").Request} args.req Request
+ * @property {[string]} args.reservedIds List of IDs already in use in session
+ *   or request
  */
 
 /**
@@ -349,6 +380,7 @@ export {
  * any other context IDs in the given session.
  *
  * The resulting ID must match these criteria:
+ *
  * - A string
  * - Between 1 and 64 characters
  * - Contain only the characters a-z, 0-9, -

package/src/lib/CasaTemplateLoader.js

@@ -1,29 +1,29 @@
-import { FileSystemLoader } from 'nunjucks';
+import { FileSystemLoader } from "nunjucks";
 
 /**
+ * @typedef {import("nunjucks").FileSystemLoaderOptions} FileSystemLoaderOptions
  * @access private
- * @typedef {import('nunjucks').FileSystemLoaderOptions} FileSystemLoaderOptions
  */
 
 /**
+ * @typedef {import("nunjucks").LoaderSource} LoaderSource
  * @access private
- * @typedef {import('nunjucks').LoaderSource} LoaderSource
  */
 
 const VALID_BLOCKS = [
-  'beforeContent',
-  'bodyEnd',
-  'bodyStart',
-  'casaPageTitle',
-  'content',
-  'footer',
-  'head',
-  'header',
-  'headIcons',
-  'journey_form',
-  'main',
-  'pageTitle',
-  'skipLink',
+  "beforeContent",
+  "bodyEnd",
+  "bodyStart",
+  "casaPageTitle",
+  "content",
+  "footer",
+  "head",
+  "header",
+  "headIcons",
+  "journey_form",
+  "main",
+  "pageTitle",
+  "skipLink",
 ];
 
 /**
@@ -33,8 +33,8 @@ const VALID_BLOCKS = [
  */
 
 /**
- * @access private
  * @augments FileSystemLoader
+ * @access private
  */
 export default class CasaTemplateLoader extends FileSystemLoader {
   #blockModifiers;
@@ -73,7 +73,9 @@ export default class CasaTemplateLoader extends FileSystemLoader {
   modifyBlock(block, modifier) {
     // Limit to only known block so the user can't do general string replacements
     if (!VALID_BLOCKS.includes(block)) {
-      throw new Error(`Block "${String(block)}" is not a recognised template block.`);
+      throw new Error(
+        `Block "${String(block)}" is not a recognised template block.`,
+      );
     }
 
     this.#blockModifiers.push({
@@ -96,7 +98,10 @@ export default class CasaTemplateLoader extends FileSystemLoader {
       const { block, modifier } = this.#blockModifiers[i];
       if (source.src.indexOf(`block ${block}`) > -1) {
         /* eslint-disable-next-line no-param-reassign */
-        source.src = source.src.replace(`block ${block} %}`, `block ${block} %}${modifier(name)}`);
+        source.src = source.src.replace(
+          `block ${block} %}`,
+          `block ${block} %}${modifier(name)}`,
+        );
       }
     }
     return source;