@dwp/govuk-casa 9.7.0 → 10.0.0

package/src/lib/Plan.js

@@ -1,5 +1,6 @@
 import { Graph } from "@dagrejs/graphlib";
 import JourneyContext from "./JourneyContext.js";
+import NullObject from "./NullObject.js";
 import logger from "./logger.js";
 
 const log = logger("lib:plan");
@@ -140,18 +141,26 @@ const makeRouteObject = (dgraph, edge) => {
  */
 const reExitNodeProtocol = /^[a-z]+:\/\//i;
 
-/**
- * For storing private properties for each instance
- *
- * @access private
- * @todo Use property private class properties.
- */
-const priv = new WeakMap();
-
-/** @memberof module:@dwp/govuk-casa */
+/** @memberof module:"@dwp/govuk-casa" */
 export default class Plan {
+  /** @type {graphlib.Graph} - This is our directed, multigraph representation */
+  #dgraph = new Graph({
+    directed: true,
+    multigraph: true,
+    compound: false,
+  });
+
   /** @type {string[]} These Waypoints can be skipped */
-  #skippableWaypoints;
+  #skippableWaypoints = [];
+
+  /** @type {{ next: object; previous: object }} */
+  #follows = {
+    next: {},
+    prev: {},
+  };
+
+  /** @type {PlanConstructorOptions} */
+  #options;
 
   /**
    * Waypoints using the url:// protocol are known as "exit nodes" as they
@@ -170,16 +179,9 @@ export default class Plan {
    * @param {PlanConstructorOptions} opts Options
    */
   constructor(opts = {}) {
-    // This is our directed, multigraph representation
-    const dgraph = new Graph({
-      directed: true,
-      multigraph: true,
-      compound: false,
-    });
-
     // Gather options
     const options = Object.assign(
-      Object.create(null),
+      new NullObject(),
       {
         // When true, the validation state of the source node must be `null` (i.e.
         // no validation errors) before any custom route conditions are evaluated.
@@ -191,17 +193,7 @@ export default class Plan {
       opts,
     );
     Object.freeze(options);
-
-    priv.set(this, {
-      dgraph,
-      follows: {
-        next: {},
-        prev: {},
-      },
-      options,
-    });
-
-    this.#skippableWaypoints = [];
+    this.#options = options;
   }
 
   /**
@@ -210,7 +202,7 @@ export default class Plan {
    * @returns {PlanConstructorOptions} Options map
    */
   getOptions() {
-    return priv.get(this).options;
+    return this.#options;
   }
 
   /**
@@ -249,7 +241,7 @@ export default class Plan {
    * @returns {string[]} List of waypoints
    */
   getWaypoints() {
-    return priv.get(this).dgraph.nodes();
+    return this.#dgraph.nodes();
   }
 
   /**
@@ -268,10 +260,9 @@ export default class Plan {
    * @returns {PlanRoute[]} Routes
    */
   getRoutes() {
-    const self = priv.get(this);
-    return self.dgraph
+    return this.#dgraph
       .edges()
-      .map((edge) => makeRouteObject(self.dgraph, edge));
+      .map((edge) => makeRouteObject(this.#dgraph, edge));
   }
 
   /**
@@ -283,7 +274,7 @@ export default class Plan {
    * @returns {PlanRouteCondition} Route condition function
    */
   getRouteCondition(src, tgt, name) {
-    return priv.get(this).follows[validateRouteName(name)][`${src}/${tgt}`];
+    return this.#follows[validateRouteName(name)][`${src}/${tgt}`];
   }
 
   /**
@@ -295,10 +286,9 @@ export default class Plan {
    * @returns {PlanRoute[]} Route objects found.
    */
   getOutwardRoutes(src, tgt = null) {
-    const self = priv.get(this);
-    return self.dgraph
+    return this.#dgraph
       .outEdges(src, tgt)
-      .map((e) => makeRouteObject(self.dgraph, e));
+      .map((e) => makeRouteObject(this.#dgraph, e));
   }
 
   /**
@@ -421,8 +411,6 @@ export default class Plan {
    * @throws {Error} If attempting to create a "next" route from an exit node
    */
   setNamedRoute(src, tgt, name, follow) {
-    const self = priv.get(this);
-
     // Validate
     validateWaypointId(src);
     validateWaypointId(tgt);
@@ -435,7 +423,7 @@ export default class Plan {
     const conditionName = follow && follow.name;
 
     // Warn if we're overwriting an existing edge on the same name
-    if (self.dgraph.hasEdge(src, tgt, name)) {
+    if (this.#dgraph.hasEdge(src, tgt, name)) {
       log.warn(
         "Setting a route that already exists (%s, %s, %s). Will be overridden",
         src,
@@ -443,12 +431,12 @@ export default class Plan {
         name,
       );
     }
-    self.dgraph.setEdge(src, tgt, { conditionName }, name);
+    this.#dgraph.setEdge(src, tgt, { conditionName }, name);
 
     // Determine which follow function to use
     let followFunc;
     if (follow) {
-      if (!self.options.validateBeforeRouteCondition) {
+      if (!this.#options.validateBeforeRouteCondition) {
         followFunc = follow;
       } else if (name === "next") {
         // Retain the original function name of route condition
@@ -469,7 +457,7 @@ export default class Plan {
 
     // ESLint disabled as `name` has been validated further above
     /* eslint-disable-next-line security/detect-object-injection */
-    self.follows[name][`${src}/${tgt}`] = followFunc;
+    this.#follows[name][`${src}/${tgt}`] = followFunc;
 
     return this;
   }
@@ -533,17 +521,15 @@ export default class Plan {
       );
     }
 
-    const self = priv.get(this);
-
     /** @type {PlanTraverseOptions} */
     const {
       startWaypoint = this.getWaypoints()[0],
       stopCondition = () => false,
-      arbiter = self.options.arbiter,
+      arbiter = this.#options.arbiter,
       routeName,
     } = options;
 
-    if (!self.dgraph.hasNode(startWaypoint)) {
+    if (!this.#dgraph.hasNode(startWaypoint)) {
       throw new ReferenceError(
         `Plan does not contain waypoint '${startWaypoint}'`,
       );
@@ -554,15 +540,15 @@ export default class Plan {
     const history = new Map();
 
     const traverse = (startWP) => {
-      let target = self.dgraph.outEdges(startWP).filter((e) => {
+      let target = this.#dgraph.outEdges(startWP).filter((e) => {
         if (e.name !== routeName) {
           return false;
         }
-        const route = makeRouteObject(self.dgraph, e);
+        const route = makeRouteObject(this.#dgraph, e);
         try {
           // ESLint disabled as `routeName` has been validated further above
           /* eslint-disable-next-line security/detect-object-injection */
-          return self.follows[routeName][`${e.v}/${e.w}`](route, context);
+          return this.#follows[routeName][`${e.v}/${e.w}`](route, context);
         } catch (ex) {
           log.warn(
             'Route follow function threw an exception, "%s" (%s)',
@@ -593,7 +579,7 @@ export default class Plan {
           // Convert to routeObject and back to edge object so that only the
           // routeObject is used in the public API
           target = arbiter({
-            targets: target.map((t) => makeRouteObject(self.dgraph, t)),
+            targets: target.map((t) => makeRouteObject(this.#dgraph, t)),
             journeyContext: context,
             travereOptions: options,
           });
@@ -609,7 +595,7 @@ export default class Plan {
       }
 
       if (target.length === 1) {
-        const route = makeRouteObject(self.dgraph, target[0]);
+        const route = makeRouteObject(this.#dgraph, target[0]);
         const routeHash = `${route.name}/${route.source}/${route.target}`;
 
         if (stopCondition(route)) {
@@ -637,7 +623,7 @@ export default class Plan {
       }
 
       return [
-        makeRouteObject(self.dgraph, {
+        makeRouteObject(this.#dgraph, {
           v: startWP,
           w: null,
           name: routeName,
@@ -656,6 +642,6 @@ export default class Plan {
    * @returns {Graph} Graph data structure.
    */
   getGraphStructure() {
-    return priv.get(this).dgraph;
+    return this.#dgraph;
   }
 }

package/src/lib/ValidationError.js

@@ -1,6 +1,4 @@
-import lodash from "lodash";
-
-const { isPlainObject } = lodash; // CommonJS
+import isPlainObject from "is-plain-obj";
 
 const params = new WeakMap();
 
@@ -20,7 +18,7 @@ const params = new WeakMap();
  */
 
 /**
- * @memberof module:@dwp/govuk-casa
+ * @memberof module:"@dwp/govuk-casa"
  * @class
  */
 export default class ValidationError {

package/src/lib/ValidatorFactory.js

@@ -1,6 +1,4 @@
-import lodash from "lodash";
-
-const { isPlainObject } = lodash; // CommonJS
+import isPlainObject from "is-plain-obj";
 
 /**
  * @typedef {import("../casa").ErrorMessageConfig} ErrorMessageConfig
@@ -28,12 +26,12 @@ const { isPlainObject } = lodash; // CommonJS
  */
 
 /**
- * @typedef {Object<string, unknown>} ValidatorFactoryOptions
+ * @typedef {{ [key: string]: unknown }} ValidatorFactoryOptions
  * @property {ErrorMessageConfig} errorMsg Error message
  */
 
 /**
- * @memberof module:@dwp/govuk-casa
+ * @memberof module:"@dwp/govuk-casa"
  * @class
  */
 export default class ValidatorFactory {

package/src/lib/configuration-ingestor.js

@@ -1,5 +1,6 @@
 import bytes from "bytes";
 import { PageField } from "./field.js";
+import NullObject from "./NullObject.js";
 import Plan from "./Plan.js";
 import logger from "./logger.js";
 import {
@@ -54,6 +55,11 @@ import {
  * @access private
  */
 
+/**
+ * @typedef {true | false | "Lax" | "None" | "Strict" | "auto"} CookieSameSite
+ * @access private
+ */
+
 const log = logger("lib:configuration-ingestor");
 
 const echo = (a) => a;
@@ -67,7 +73,7 @@ const echo = (a) => a;
  * @throws {TypeError} For invalid object.
  * @access private
  */
-export function validateI18nObject(i18n = Object.create(null), cb = echo) {
+export function validateI18nObject(i18n = new NullObject(), cb = echo) {
   if (Object.prototype.toString.call(i18n) !== "[object Object]") {
     throw new TypeError("I18n must be an object");
   }
@@ -95,6 +101,7 @@ export function validateI18nDirs(dirs = []) {
         `I18n directory must be a string, got ${typeof dir} (i18n.dirs[${i++}])`,
       );
     }
+    i++;
   }
   return dirs;
 }
@@ -120,6 +127,7 @@ export function validateI18nLocales(locales = ["en", "cy"]) {
         `I18n locale must be a string, got ${typeof locale} (i18n.locales[${i++}])`,
       );
     }
+    i++;
   }
   return locales;
 }
@@ -179,10 +187,7 @@ export function validateMountUrl(mountUrl) {
  * @throws {TypeError} For invalid object.
  * @access private
  */
-export function validateSessionObject(
-  session = Object.create(null),
-  cb = echo,
-) {
+export function validateSessionObject(session = new NullObject(), cb = echo) {
   if (session === undefined) {
     return cb(session);
   }
@@ -215,6 +220,7 @@ export function validateViews(dirs = []) {
         `View directory must be a string, got ${typeof dir} (views[${i++}])`,
       );
     }
+    i++;
   }
   return dirs;
 }
@@ -322,17 +328,6 @@ export function validateSessionCookiePath(cookiePath, defaultPath = "/") {
   return cookiePath;
 }
 
-/**
- * Validates and sanitises sessions cookie "sameSite" flag. One of: true
- * (Strict) false (will not set the flag at all) Strict Lax None
- *
- * @param {any} cookieSameSite Session cookie "sameSite" flag
- * @param {any} defaultFlag Default path if none specified
- * @returns {boolean} Cookie path
- * @throws {TypeError} When invalid arguments are provided
- * @access private
- */
-
 /**
  * Validates errorVisibility.
  *
@@ -361,9 +356,14 @@ export function validateErrorVisibility(
 }
 
 /**
- * @param {boolean | string} cookieSameSite Cookie SameSite value
- * @param {boolean | string} defaultFlag Default value
+ * Validates and sanitises sessions cookie "sameSite" flag. One of: true
+ * (Strict) false (will not set the flag at all) Strict Lax None
+ *
+ * @param {CookieSameSite} cookieSameSite Session cookie "sameSite" flag
+ * @param {CookieSameSite} defaultFlag Default value
  * @returns {boolean | string} Validated value
+ * @throws {TypeError} When invalid arguments are provided
+ * @access private
  */
 export function validateSessionCookieSameSite(cookieSameSite, defaultFlag) {
   const validValues = [true, false, "Strict", "Lax", "None"];
@@ -634,24 +634,6 @@ export function validateContextIdGenerator(generator) {
   return generator;
 }
 
-/**
- * Validates the govuk rebrand feature flag.
- *
- * @param {boolean} [govukRebrand] Govuk rebrand feature flag
- * @returns {boolean | true} Boolean.
- * @throws {TypeError} For invalid feagure flag is set.
- * @access private
- */
-export function validateGovukRebrand(govukRebrand) {
-  if (govukRebrand === undefined) {
-    return false;
-  }
-  if (typeof govukRebrand !== "boolean") {
-    throw new TypeError("govukRebrand must be a boolean");
-  }
-  return govukRebrand;
-}
-
 /**
  * Ingest, validate, sanitise and manipulate configuration parameters.
  *
@@ -716,8 +698,6 @@ export default function ingest(config = {}) {
 
     // Context ID generator
     contextIdGenerator: validateContextIdGenerator(config.contextIdGenerator),
-
-    govukRebrand: validateGovukRebrand(config.govukRebrand),
   };
 
   // Freeze to modifications

package/src/lib/configure.js

@@ -2,7 +2,6 @@ import { MemoryStore } from "express-session";
 import { resolve } from "node:path";
 import { createRequire } from "node:module";
 import cookieParserFactory from "cookie-parser";
-import dirname from "./dirname.cjs";
 
 import configurationIngestor from "./configuration-ingestor.js";
 import nunjucks from "./nunjucks.js";
@@ -42,7 +41,7 @@ import { CONFIG_ERROR_VISIBILITY_ONSUBMIT } from "./constants.js";
 /**
  * Configure some middleware for use in creating a new CASA app.
  *
- * @memberof module:@dwp/govuk-casa
+ * @memberof module:"@dwp/govuk-casa"
  * @param {ConfigurationOptions} config Configuration options
  * @returns {ConfigureResult} Result
  */
@@ -81,7 +80,6 @@ export default function configure(config = {}) {
     formMaxParams,
     formMaxBytes,
     contextIdGenerator,
-    govukRebrand = false,
   } = ingestedConfig;
 
   // Prepare all page hooks so they are prefixed with the `journey.` scope.
@@ -98,10 +96,12 @@ export default function configure(config = {}) {
   const nunjucksEnv = nunjucks({
     views: [
       ...views,
-      resolve(dirname, "../../views"),
-      resolve(createRequire(dirname).resolve("govuk-frontend"), "../../"),
+      resolve(import.meta.dirname, "../../views"),
+      resolve(
+        createRequire(import.meta.dirname).resolve("govuk-frontend"),
+        "../../",
+      ),
     ],
-    govukRebrand,
   });
 
   // Prepare mandatory middleware
@@ -125,7 +125,7 @@ export default function configure(config = {}) {
   const i18nMiddleware = i18nMiddlewareFactory({
     directories: [
       // Order is important; latter directories take precedence
-      resolve(dirname, "../../locales/"),
+      resolve(import.meta.dirname, "../../locales/"),
       ...i18n.dirs,
     ],
     languages: i18n.locales,
@@ -135,7 +135,6 @@ export default function configure(config = {}) {
     plan,
     events,
     contextIdGenerator,
-    govukRebrand,
   });
 
   // Prepare form middleware and its constituent parts
@@ -185,8 +184,6 @@ export default function configure(config = {}) {
     // Nunjucks environment, so it can be attached to other ExpressJS instances
     // using `nunjucksEnv.express(myApp); myApp.set('view engine', 'njk');`.
     nunjucksEnv,
-    // govuk rebrand flag
-    govukRebrand,
 
     // Mandatory middleware. User must add these to their ExpressJS app.
     preMiddleware,

package/src/lib/end-session.js

@@ -10,7 +10,7 @@ const log = logger("lib:end-session");
  * 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
+ * @memberof module:"@dwp/govuk-casa"
  * @param {import("express").Request} req HTTP request
  * @param {Function} next Chain
  * @returns {void}

package/src/lib/field.js

@@ -1,7 +1,5 @@
-import lodash from "lodash";
 import { isEmpty } from "./utils.js";
-
-const { isFunction } = lodash;
+import NullObject from "./NullObject.js";
 
 /**
  * @typedef {import("./index").JourneyContext} JourneyContext
@@ -71,10 +69,7 @@ export class PageField {
    * @param {boolean} [opts.persist] 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 } = new NullObject()) {
     if (!name) {
       throw new SyntaxError(
         "A name for this field is required, i.e. \"field('myField')\".",
@@ -132,7 +127,7 @@ export class PageField {
    * @param {object} obj Object from which to extract the value
    * @returns {any} Value extracted from object
    */
-  getValue(obj = Object.create(null)) {
+  getValue(obj = new NullObject()) {
     if (this.#meta.complex) {
       return obj[this.#meta.complexFieldName]?.[
         this.#meta.complexFieldProperty
@@ -151,7 +146,7 @@ export class PageField {
    * @param {any} value Value to be stored
    * @returns {any} Value extracted from object
    */
-  putValue(obj = Object.create(null), value = undefined) {
+  putValue(obj = new NullObject(), value = undefined) {
     if (this.#meta.complex) {
       obj[this.#meta.complexFieldName] = {
         ...(obj[this.#meta.complexFieldName] ?? {}),
@@ -298,7 +293,7 @@ export class PageField {
    * @returns {ValidationError[]} Errors, or an empty array if all valid
    * @throws {TypeError} If validator does not return an array
    */
-  runValidators(context = Object.create(null)) {
+  runValidators(context = new NullObject()) {
     // Skip validation if the field is empty and optional
     if (this.#meta.optional && isEmpty(context?.fieldValue)) {
       return [];
@@ -352,7 +347,7 @@ export class PageField {
     // ESLint disabled as `i` is an integer
     /* eslint-disable security/detect-object-injection */
     for (let i = 0, l = this.#validators.length; i < l; i++) {
-      if (isFunction(this.#validators[i].sanitise)) {
+      if (this.#validators[i].sanitise instanceof Function) {
         processedValue = this.#validators[i].sanitise(processedValue);
       }
     }
@@ -435,7 +430,7 @@ export class PageField {
 /**
  * Factory for creating PageField instances.
  *
- * @memberof module:@dwp/govuk-casa
+ * @memberof module:"@dwp/govuk-casa"
  * @param {string} name Field name
  * @param {object} [opts] Options
  * @param {boolean} [opts.optional] Whether this field is optional. Default is

package/src/lib/logger.js

@@ -2,6 +2,12 @@ import debug from "debug";
 
 const casaDebugger = debug("casa");
 
+/**
+ * Get a debug logger for a given namespace
+ *
+ * @param {string} namespace Debug log namespace
+ * @returns {CASADebugLogger} CASA Debug logger
+ */
 export default (namespace) => {
   const logger = casaDebugger.extend(namespace);
 
@@ -14,3 +20,13 @@ export default (namespace) => {
     fatal: logger.extend("fatal"),
   };
 };
+
+/**
+ * @typedef {object} CASADebugLogger CASA Debug logger
+ * @property {debug.Debugger} trace Trace level logger
+ * @property {debug.Debugger} debug Debug level logger
+ * @property {debug.Debugger} info Info level logger
+ * @property {debug.Debugger} warn Warn level logger
+ * @property {debug.Debugger} error Error level logger
+ * @property {debug.Debugger} fatal Fatal level logger
+ */

package/src/lib/mount.js

@@ -103,9 +103,9 @@ export default ({
     });
 
     router.use(preMiddleware);
+    router.use(bodyParserMiddleware);
     router.use(sessionMiddleware);
     router.use(i18nMiddleware);
-    router.use(bodyParserMiddleware);
     router.use(dataMiddleware);
     router.use(ancillaryRouter.seal());
     router.use(journeyRouter.seal());