@dwp/govuk-casa 8.15.0 → 9.1.0

package/src/lib/configure.js

@@ -1,42 +1,42 @@
-import { MemoryStore } from 'express-session';
-import { resolve } from 'path';
-import { createRequire } from 'module';
-import cookieParserFactory from 'cookie-parser';
-import dirname from './dirname.cjs';
+import { MemoryStore } from "express-session";
+import { resolve } from "path";
+import { createRequire } from "module";
+import cookieParserFactory from "cookie-parser";
+import dirname from "./dirname.cjs";
 
-import configurationIngestor from './configuration-ingestor.js';
-import nunjucks from './nunjucks.js';
-import mountFactory from './mount.js';
+import configurationIngestor from "./configuration-ingestor.js";
+import nunjucks from "./nunjucks.js";
+import mountFactory from "./mount.js";
 
-import staticRoutes from '../routes/static.js';
-import ancillaryRoutes from '../routes/ancillary.js';
-import journeyRoutes from '../routes/journey.js';
+import staticRoutes from "../routes/static.js";
+import ancillaryRoutes from "../routes/ancillary.js";
+import journeyRoutes from "../routes/journey.js";
 
-import preMiddlewareFactory from '../middleware/pre.js';
-import postMiddlewareFactory from '../middleware/post.js';
+import preMiddlewareFactory from "../middleware/pre.js";
+import postMiddlewareFactory from "../middleware/post.js";
 
-import sessionMiddlewareFactory from '../middleware/session.js';
-import i18nMiddlewareFactory from '../middleware/i18n.js';
-import dataMiddlewareFactory from '../middleware/data.js';
+import sessionMiddlewareFactory from "../middleware/session.js";
+import i18nMiddlewareFactory from "../middleware/i18n.js";
+import dataMiddlewareFactory from "../middleware/data.js";
 
-import bodyParserMiddlewareFactory from '../middleware/body-parser.js';
-import csrfMiddlewareFactory from '../middleware/csrf.js';
+import bodyParserMiddlewareFactory from "../middleware/body-parser.js";
+import csrfMiddlewareFactory from "../middleware/csrf.js";
 
-import { CONFIG_ERROR_VISIBILITY_ONSUBMIT } from './constants.js';
+import { CONFIG_ERROR_VISIBILITY_ONSUBMIT } from "./constants.js";
 
 /**
+ * @typedef {import("../casa").ConfigurationOptions} ConfigurationOptions
  * @access private
- * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
  */
 
 /**
+ * @typedef {import("../casa").ConfigureResult} ConfigureResult
  * @access private
- * @typedef {import('../casa').ConfigureResult} ConfigureResult
  */
 
 /**
+ * @typedef {import("../casa").Mounter} Mounter
  * @access private
- * @typedef {import('../casa').Mounter} Mounter
  */
 
 /**
@@ -60,12 +60,12 @@ export default function configure(config = {}) {
     errorVisibility = CONFIG_ERROR_VISIBILITY_ONSUBMIT,
     views = [],
     session = {
-      secret: 'secret',
-      name: 'casasession',
+      secret: "secret",
+      name: "casasession",
       secure: false,
       ttl: 3600,
       cookieSameSite: true,
-      cookiePath: '/',
+      cookiePath: "/",
       store: undefined,
     },
     pages = [],
@@ -75,7 +75,7 @@ export default function configure(config = {}) {
     events = [],
     i18n = {
       dirs: [],
-      locales: ['en', 'cy'],
+      locales: ["en", "cy"],
     },
     helmetConfigurator = undefined,
     formMaxParams,
@@ -86,7 +86,7 @@ export default function configure(config = {}) {
   // Prepare all page hooks so they are prefixed with the `journey.` scope.
   pages.forEach((page) => {
     /* eslint-disable-next-line no-param-reassign,no-return-assign */
-    (page?.hooks ?? []).forEach((h) => h.hook = `journey.${h.hook}`);
+    (page?.hooks ?? []).forEach((h) => (h.hook = `journey.${h.hook}`));
   });
 
   // Prepare a Nunjucks environment for rendering all templates.
@@ -94,8 +94,8 @@ export default function configure(config = {}) {
   const nunjucksEnv = nunjucks({
     views: [
       ...views,
-      resolve(dirname, '../../views'),
-      resolve(createRequire(dirname).resolve('govuk-frontend'), '../../'),
+      resolve(dirname, "../../views"),
+      resolve(createRequire(dirname).resolve("govuk-frontend"), "../../"),
     ],
   });
 
@@ -120,7 +120,7 @@ export default function configure(config = {}) {
   const i18nMiddleware = i18nMiddlewareFactory({
     directories: [
       // Order is important; latter directories take precedence
-      resolve(dirname, '../../locales/'),
+      resolve(dirname, "../../locales/"),
       ...i18n.dirs,
     ],
     languages: i18n.locales,
@@ -148,7 +148,7 @@ export default function configure(config = {}) {
   });
 
   // Setup waypoint router, which includes routes for every defined waypoint
-  const globalErrorVisibility = errorVisibility
+  const globalErrorVisibility = errorVisibility;
   const journeyRouter = journeyRoutes({
     globalHooks: hooks,
     pages,
@@ -207,7 +207,9 @@ export default function configure(config = {}) {
   };
 
   // Bootstrap all plugins
-  plugins.filter((p) => p.bootstrap).forEach((plugin) => plugin?.bootstrap(configOutput));
+  plugins
+    .filter((p) => p.bootstrap)
+    .forEach((plugin) => plugin?.bootstrap(configOutput));
 
   // Finished configuration
   return configOutput;

package/src/lib/constants.js

@@ -1,11 +1,9 @@
-/**
- * General-purpose references to the different request lifecycle phases.
- */
-export const REQUEST_PHASE_STEER = Symbol('steer');
-export const REQUEST_PHASE_SANITISE = Symbol('sanitise');
-export const REQUEST_PHASE_GATHER = Symbol('gather');
-export const REQUEST_PHASE_VALIDATE = Symbol('validate');
-export const REQUEST_PHASE_REDIRECT = Symbol('redirect');
-export const REQUEST_PHASE_RENDER = Symbol('render');
-export const CONFIG_ERROR_VISIBILITY_ONSUBMIT = Symbol('onsubmit');
-export const CONFIG_ERROR_VISIBILITY_ALWAYS = Symbol('always');
+/** General-purpose references to the different request lifecycle phases. */
+export const REQUEST_PHASE_STEER = Symbol("steer");
+export const REQUEST_PHASE_SANITISE = Symbol("sanitise");
+export const REQUEST_PHASE_GATHER = Symbol("gather");
+export const REQUEST_PHASE_VALIDATE = Symbol("validate");
+export const REQUEST_PHASE_REDIRECT = Symbol("redirect");
+export const REQUEST_PHASE_RENDER = Symbol("render");
+export const CONFIG_ERROR_VISIBILITY_ONSUBMIT = Symbol("onsubmit");
+export const CONFIG_ERROR_VISIBILITY_ALWAYS = Symbol("always");

package/src/lib/context-id-generators.js

@@ -1,9 +1,7 @@
 /* eslint-disable import/no-cycle */
-import { randomUUID } from 'node:crypto';
+import { randomUUID } from "node:crypto";
 
-/**
- * @typedef {import('../casa.js').ContextIdGenerator} ContextIdGenerator
- */
+/** @typedef {import("../casa.js").ContextIdGenerator} ContextIdGenerator */
 
 /**
  * Creates an instance of a UUID generator.
@@ -21,51 +19,50 @@ const uuid = () => () => randomUUID();
  *
  * @returns {ContextIdGenerator} Generator function
  */
-const sequentialInteger = () => ({ reservedIds }) => {
-  const contextIds = Array.from(reservedIds).sort();
+const sequentialInteger =
+  () =>
+  ({ reservedIds }) => {
+    const contextIds = Array.from(reservedIds).sort();
 
-  if (!contextIds.length) {
-    return '1';
-  }
+    if (!contextIds.length) {
+      return "1";
+    }
 
-  // Find the first numeric ID that we can increment
-  let lastInSequence;
-  do {
-    lastInSequence = Number.parseInt(contextIds.pop(), 10);
-  } while (contextIds.length && Number.isNaN(lastInSequence));
+    // Find the first numeric ID that we can increment
+    let lastInSequence;
+    do {
+      lastInSequence = Number.parseInt(contextIds.pop(), 10);
+    } while (contextIds.length && Number.isNaN(lastInSequence));
 
-  return String(!Number.isNaN(lastInSequence) ? lastInSequence + 1 : 1);
-};
+    return String(!Number.isNaN(lastInSequence) ? lastInSequence + 1 : 1);
+  };
 
-const shortGuid = ({
-  length = 5,
-  prefix = '',
-  pool = 'abcdefhkmnprtwxy346789',
-} = {}) => ({ reservedIds }) => {
-  // Ambiguous characters excluded
-  const poolSize = pool.length;
+const shortGuid =
+  ({ length = 5, prefix = "", pool = "abcdefhkmnprtwxy346789" } = {}) =>
+  ({ reservedIds }) => {
+    // Ambiguous characters excluded
+    const poolSize = pool.length;
 
-  const maxAttempts = 10;
-  let attempts = maxAttempts;
-  let id;
+    const maxAttempts = 10;
+    let attempts = maxAttempts;
+    let id;
 
-  do {
-    id = Array(length).fill(0).map(() => pool.charAt(Math.floor(Math.random() * poolSize))).join('');
-    attempts--;
-  } while (attempts > 0 && reservedIds.includes(id));
+    do {
+      id = Array(length)
+        .fill(0)
+        .map(() => pool.charAt(Math.floor(Math.random() * poolSize)))
+        .join("");
+      attempts--;
+    } while (attempts > 0 && reservedIds.includes(id));
 
-  if (attempts === 0) {
-    throw new Error(`Failed to generate GUID after ${maxAttempts} iterations`);
-  }
+    if (attempts === 0) {
+      throw new Error(
+        `Failed to generate GUID after ${maxAttempts} iterations`,
+      );
+    }
 
-  return `${prefix}${id}`;
-}
+    return `${prefix}${id}`;
+  };
 
-/**
- * @namespace ContextIdGenerators
- */
-export {
-  uuid,
-  sequentialInteger,
-  shortGuid,
-};
+/** @namespace ContextIdGenerators */
+export { uuid, sequentialInteger, shortGuid };

package/src/lib/end-session.js

@@ -1,17 +1,17 @@
-import logger from './logger.js';
+import logger from "./logger.js";
 
-const log = logger('lib:end-session');
+const log = logger("lib:end-session");
 
 /**
  * A convenience for ending the current session, but retaining some data in it,
- * like the current language. It persists an empty session before regenerating
- * a new ID.
+ * like the current language. It persists an empty session before regenerating a
+ * new ID.
  *
  * Note: this will not remove the session from server-side storage, which will
  * instead be left up to the storage mechanism to clean up.
  *
  * @memberof module:@dwp/govuk-casa
- * @param {import('express').Request} req HTTP request
+ * @param {import("express").Request} req HTTP request
  * @param {Function} next Chain
  * @returns {void}
  */
@@ -19,7 +19,7 @@ export default function endSession(req, next) {
   const { language } = req.session;
 
   Object.entries(req.session).forEach(([k]) => {
-    if (!['cookie'].includes(k)) {
+    if (!["cookie"].includes(k)) {
       // ESLint disabled as `Object.entries()` returns "own" properties, and
       // all values are being null'd, so not assigned any user-controlled values
       /* eslint-disable-next-line security/detect-object-injection */

package/src/lib/field.js

@@ -1,38 +1,36 @@
-import lodash from 'lodash';
-import { isEmpty } from './utils.js';
-import logger from './logger.js';
+import lodash from "lodash";
+import { isEmpty } from "./utils.js";
 
-const log = logger('lib:field');
 const { isFunction } = lodash;
 
 /**
+ * @typedef {import("./index").JourneyContext} JourneyContext
  * @access private
- * @typedef {import('./index').JourneyContext} JourneyContext
  */
 
 /**
+ * @typedef {import("../casa").Validator} Validator
  * @access private
- * @typedef {import('../casa').Validator} Validator
  */
 
 /**
+ * @typedef {import("../casa").ValidateContext} ValidateContext
  * @access private
- * @typedef {import('../casa').ValidateContext} ValidateContext
  */
 
 /**
+ * @typedef {import("../casa").ValidatorConditionFunction} ValidatorConditionFunction
  * @access private
- * @typedef {import('../casa').ValidatorConditionFunction} ValidatorConditionFunction
  */
 
 /**
+ * @typedef {import("../casa").FieldProcessorFunction} FieldProcessorFunction
  * @access private
- * @typedef {import('../casa').FieldProcessorFunction} FieldProcessorFunction
  */
 
 /**
+ * @typedef {import("./index").ValidationError} ValidationError
  * @access private
- * @typedef {import('./index').ValidationError} ValidationError
  */
 
 // Quick check to see if the field name corresponds to a non-primitive complex
@@ -48,29 +46,19 @@ const reInvalidName = /[^a-z0-9_.\-[\]]/i;
  * @class
  */
 export class PageField {
-  /**
-   * @type {string}
-   */
+  /** @type {string} */
   #name;
 
-  /**
-   * @type {FieldProcessorFunction[]}
-   */
+  /** @type {FieldProcessorFunction[]} */
   #processors;
 
-  /**
-   * @type {Validator[]}
-   */
+  /** @type {Validator[]} */
   #validators;
 
-  /**
-   * @type {ValidatorConditionFunction[]}
-   */
+  /** @type {ValidatorConditionFunction[]} */
   #conditions;
 
-  /**
-   * @type {object}
-   */
+  /** @type {object} */
   #meta;
 
   /**
@@ -78,12 +66,19 @@ export class PageField {
    *
    * @param {string} name Field name
    * @param {object} [opts] Options
-   * @param {boolean} [opts.optional=false] Whether this field is optional
-   * @param {boolean} [opts.persist=true] Whether this field will persist in `req.body`
+   * @param {boolean} [opts.optional=false] Whether this field is optional.
+   *   Default is `false`
+   * @param {boolean} [opts.persist=true] Whether this field will persist in
+   *   `req.body`. Default is `true`
    */
-  constructor(name, { optional = false, persist = true } = Object.create(null)) {
+  constructor(
+    name,
+    { optional = false, persist = true } = Object.create(null),
+  ) {
     if (!name) {
-      throw new SyntaxError('A name for this field is required, i.e. "field(\'myField\')".');
+      throw new SyntaxError(
+        "A name for this field is required, i.e. \"field('myField')\".",
+      );
     }
 
     this.#name = undefined;
@@ -139,7 +134,9 @@ export class PageField {
    */
   getValue(obj = Object.create(null)) {
     if (this.#meta.complex) {
-      return obj[this.#meta.complexFieldName]?.[this.#meta.complexFieldProperty];
+      return obj[this.#meta.complexFieldName]?.[
+        this.#meta.complexFieldProperty
+      ];
     }
     return obj[this.#name];
   }
@@ -188,7 +185,9 @@ export class PageField {
    */
   rename(name) {
     if (reInvalidName.test(String(name))) {
-      throw new SyntaxError(`Field '${String(name)}' name contains invalid characters.`);
+      throw new SyntaxError(
+        `Field '${String(name)}' name contains invalid characters.`,
+      );
     }
 
     // Complex names are only supported to one level deep. For example,
@@ -196,7 +195,9 @@ export class PageField {
     // early to aid developer.
     const isComplex = reComplexType.test(name);
     if (isComplex && name.match(/\[/g).length > 1) {
-      throw new SyntaxError('Complex field names are only supported to 1 property depth. E.g. a[b] is ok, a[b][c] is not');
+      throw new SyntaxError(
+        "Complex field names are only supported to 1 property depth. E.g. a[b] is ok, a[b][c] is not",
+      );
     }
 
     this.#name = String(name);
@@ -221,21 +222,19 @@ export class PageField {
   }
 
   /**
-   * Add/get value validators
-   * Some validators will include a `sanitise()` method which will be run at the
-   * same time as other "processors".
+   * Add value validators Some validators will include a `sanitise()` method
+   * which will be run at the same time as other "processors".
    *
    * @param {Validator[]} items Validation functions
-   * @returns {PageField} Chain - Deprecated: this currently gets all validators if
-   * empty or missing, in v9 this functionality will removed in favour of the
-   * function getValidators().
+   * @returns {PageField} Chain
    */
   validators(items = []) {
     if (!items.length) {
-      log.warn('Calling validators() to get all validators is deprecated, please use getValidators()');
-      return this.getValidators();
+      throw new Error(
+        "Calling validators() to get all validators is no longer supported, please use getValidators()",
+      );
     }
-    this.#validators = [...this.#validators, ...(items.flat())];
+    this.#validators = [...this.#validators, ...items.flat()];
     return this;
   }
 
@@ -249,21 +248,20 @@ export class PageField {
   }
 
   /**
-   * Add/get value pre-processors
-   * This is most often used to sanitise values to a particular data type.
+   * Add value pre-processors This is most often used to sanitise values to a
+   * particular data type.
    *
    * @param {FieldProcessorFunction[]} items Processor functions
-   * @returns {PageField} Chain - Deprecated: this currently gets all processors if
-   * empty or missing, in v9 this functionality will removed in favour of the
-   * function getProcessors().
+   * @returns {PageField} Chain
    */
   processors(items = []) {
     if (!items.length) {
-      log.warn('Calling processors() to get all processors is deprecated, please use getProcessors()');
-      return this.getProcessors();
+      throw new Error(
+        "Calling processors() to get all processors is no longer supported, please use getProcessors()",
+      );
     }
 
-    this.#processors = [...this.#processors, ...(items.flat())];
+    this.#processors = [...this.#processors, ...items.flat()];
     return this;
   }
 
@@ -277,21 +275,19 @@ export class PageField {
   }
 
   /**
-   * Add/get conditions
-   * All conditions must be met in order for this field to be considered
-   * "actionable".
+   * Add conditions All conditions must be met in order for this field to be
+   * considered "actionable".
    *
    * @param {ValidatorConditionFunction[]} items Condition functions
-   * @returns {PageField} Chain - Deprecated: this currently gets all conditions if
-   * empty or missing, in v9 this functionality will removed in favour of the
-   * function getConditions().
+   * @returns {PageField} Chain
    */
   conditions(items = []) {
     if (!items.length) {
-      log.warn('Calling conditions() to get all conditions is deprecated, please use getConditions()');
-      return this.getConditions();
+      throw new Error(
+        "Calling conditions() to get all conditions is no longer supported, please use getConditions()",
+      );
     }
-    this.#conditions = [...this.#conditions, ...(items.flat())];
+    this.#conditions = [...this.#conditions, ...items.flat()];
     return this;
   }
 
@@ -300,22 +296,17 @@ export class PageField {
   /**
    * Run all validators and return array of errors, if applicable.
    *
-   * @param {any} value Value to validate
    * @param {ValidateContext} context Contextual validation information
    * @returns {ValidationError[]} Errors, or an empty array if all valid
    * @throws {TypeError} If validator does not return an array
    */
-  runValidators(value, context = Object.create(null)) {
+  runValidators(context = Object.create(null)) {
     // Skip validation if the field is empty and optional
-    if (this.#meta.optional && isEmpty(value)) {
+    if (this.#meta.optional && isEmpty(context?.fieldValue)) {
       return [];
     }
 
     // Skip validation if conditions are not met
-    // We duplicate value in context.fieldValue for historical reasons
-    // @todo explain these historical reasons! And deprecate the need for
-    // `value` altogether
-    context.fieldValue = context.fieldValue ?? value;
     if (!this.testConditions(context)) {
       return [];
     }
@@ -325,22 +316,26 @@ export class PageField {
       // ESLint disabled as `i` is an integer
       /* eslint-disable security/detect-object-injection */
       // TODO: Replace `value` with `context.fieldValue` here
-      let fieldErrors = this.#validators[i].validate(value, context)
+      let fieldErrors = this.#validators[i].validate(
+        context.fieldValue,
+        context,
+      );
       if (!Array.isArray(fieldErrors)) {
         // Friendly message for developer
-        throw new TypeError(`The validator at index ${i} (name: ${this.#validators[i].name || 'unknown'}) for field '${this.#name}' did not return an array`);
+        throw new TypeError(
+          `The validator at index ${i} (name: ${this.#validators[i].name || "unknown"}) for field '${this.#name}' did not return an array`,
+        );
       }
 
-      fieldErrors = fieldErrors.map((e) => e.withContext({
-        ...context,
-        validator: this.#validators[i].name,
-      }));
+      fieldErrors = fieldErrors.map((e) =>
+        e.withContext({
+          ...context,
+          validator: this.#validators[i].name,
+        }),
+      );
       /* eslint-enable security/detect-object-injection */
 
-      errors = [
-        ...errors,
-        ...(fieldErrors ?? []),
-      ];
+      errors = [...errors, ...(fieldErrors ?? [])];
     }
 
     return errors;
@@ -385,7 +380,6 @@ export class PageField {
       fieldName: this.#name,
       fieldValue,
       waypoint,
-      waypointId: waypoint, // [DEPRECATED] for backwards compatibility with v7
       journeyContext,
     };
 
@@ -447,8 +441,10 @@ export class PageField {
  * @memberof module:@dwp/govuk-casa
  * @param {string} name Field name
  * @param {object} [opts] Options
- * @param {boolean} [opts.optional=false] Whether this field is optional
- * @param {boolean} [opts.persist=true] Whether this field will persist in `req.body`
+ * @param {boolean} [opts.optional=false] Whether this field is optional.
+ *   Default is `false`
+ * @param {boolean} [opts.persist=true] Whether this field will persist in
+ *   `req.body`. Default is `true`
  * @returns {PageField} A PageField
  */
 export default function field(name, opts) {

package/src/lib/index.js

@@ -3,18 +3,18 @@
  * imported anywhere in code, other than JSDoc references.
  */
 
-import CasaTemplateLoader from './CasaTemplateLoader.js';
-import configure from './configure.js';
-import configurationIngestor from './configuration-ingestor.js';
-import endSession from './end-session.js';
-import field, { PageField } from './field.js';
-import JourneyContext from './JourneyContext.js';
-import MutableRouter from './MutableRouter.js';
-import Plan from './Plan.js';
-import ValidationError from './ValidationError.js';
-import ValidatorFactory from './ValidatorFactory.js';
-import waypointUrl from './waypoint-url.js';
-import * as utils from './utils.js';
+import CasaTemplateLoader from "./CasaTemplateLoader.js";
+import configure from "./configure.js";
+import configurationIngestor from "./configuration-ingestor.js";
+import endSession from "./end-session.js";
+import field, { PageField } from "./field.js";
+import JourneyContext from "./JourneyContext.js";
+import MutableRouter from "./MutableRouter.js";
+import Plan from "./Plan.js";
+import ValidationError from "./ValidationError.js";
+import ValidatorFactory from "./ValidatorFactory.js";
+import waypointUrl from "./waypoint-url.js";
+import * as utils from "./utils.js";
 
 export {
   CasaTemplateLoader,

package/src/lib/logger.js

@@ -1,16 +1,16 @@
-import debug from 'debug';
+import debug from "debug";
 
-const casaDebugger = debug('casa');
+const casaDebugger = debug("casa");
 
 export default (namespace) => {
   const logger = casaDebugger.extend(namespace);
 
   return {
-    trace: logger.extend('trace'),
-    debug: logger.extend('debug'),
-    info: logger.extend('info'),
-    warn: logger.extend('warn'),
-    error: logger.extend('error'),
-    fatal: logger.extend('fatal'),
+    trace: logger.extend("trace"),
+    debug: logger.extend("debug"),
+    info: logger.extend("info"),
+    warn: logger.extend("warn"),
+    error: logger.extend("error"),
+    fatal: logger.extend("fatal"),
   };
-}
+};