@dwp/govuk-casa 9.7.0 → 10.0.0

package/src/core-plugins/edit-snapshot/src/utils.js

@@ -1,10 +1,15 @@
 /* eslint-disable security/detect-object-injection */
 import { JourneyContext } from "../../../casa.js";
+import NullObject from "../../../lib/NullObject.js";
 
 const SESSION_KEY = "casa_edit_snapshots";
 
 export const FLAG_FOR_PURGING = Symbol("flag_to_purge_edit_snapshot");
 
+/**
+ * @param {ExpressRequest} req Express request
+ * @returns {undefined | boolean} Whether the snapshot exists
+ */
 export const snapshotExists = (req) => {
   return (
     req?.session[SESSION_KEY] &&
@@ -12,6 +17,11 @@ export const snapshotExists = (req) => {
   );
 };
 
+/**
+ * @param {CASADebugLogger} log Express request
+ * @param {ExpressRequest} req Express request
+ * @returns {boolean} Reached edit origin
+ */
 export const reachedEditOrigin = (log, req) => {
   const { pathname: currentPathname } = new URL(
     req.originalUrl,
@@ -25,15 +35,25 @@ export const reachedEditOrigin = (log, req) => {
   return editOriginPathname === currentPathname;
 };
 
+/**
+ * @param {CASADebugLogger} log Express request
+ * @param {ExpressRequest} req Express request
+ * @returns {void}
+ */
 export const createSnapshot = (log, req) => {
   log.debug(
     `Creating a new edit snapshot for context '${req.casa.journeyContext.identity.id}'`,
   );
-  req.session[SESSION_KEY] ??= Object.create(null);
+  req.session[SESSION_KEY] ??= new NullObject();
   req.session[SESSION_KEY][req.casa.journeyContext.identity.id] =
     req.casa.journeyContext.toObject();
 };
 
+/**
+ * @param {CASADebugLogger} log Express request
+ * @param {ExpressRequest} req Express request
+ * @returns {void}
+ */
 export const recoverSnapshot = (log, req) => {
   log.debug(
     `Recovering snapshot for context '${req.casa.journeyContext.identity.id}'`,
@@ -45,9 +65,17 @@ export const recoverSnapshot = (log, req) => {
   deleteSnapshot(log, req);
 };
 
+/**
+ * @param {CASADebugLogger} log Express request
+ * @param {ExpressRequest} req Express request
+ * @returns {void}
+ */
 export const deleteSnapshot = (log, req) => {
   log.debug(
     `Purging edit snapshot for context '${req.casa.journeyContext.identity.id}'`,
   );
   req.session[SESSION_KEY][req.casa.journeyContext.identity.id] = undefined;
 };
+
+/** @typedef {import("../../../lib/logger.js").CASADebugLogger} CASADebugLogger */
+/** @typedef {import("express").Request} ExpressRequest */

package/src/lib/JourneyContext.js

@@ -6,15 +6,15 @@
  * - Validation errors on that data
  * - Navigation information about how the user got where they are.
  */
-import lodash from "lodash";
+import isPlainObject from "is-plain-obj";
+import { deepEqual } from "fast-equals";
 import rfdc from "rfdc";
+import NullObject from "./NullObject.js";
 import ValidationError from "./ValidationError.js";
 import logger from "./logger.js";
 import { notProto } from "./utils.js";
 import { uuid as uuidGenerator } from "./context-id-generators.js";
 
-const { isPlainObject, isObject, isEqual } = lodash; // CommonJS
-
 const log = logger("lib:journey-context");
 
 const uuid = uuidGenerator();
@@ -46,13 +46,18 @@ const clone = rfdc({ proto: false });
  * @access private
  */
 
+/**
+ * @typedef {import("../casa").JourneyContextIdentity} JourneyContextIdentity
+ * @access private
+ */
+
 /**
  * @typedef {import("express").Request} ExpressRequest
  * @access private
  */
 
 /**
- * @param {any} key Object key to validate
+ * @param {string} key Object key to validate
  * @returns {string} Validated key
  */
 export function validateObjectKey(key = "") {
@@ -67,7 +72,7 @@ export function validateObjectKey(key = "") {
   return String(key);
 }
 
-/** @memberof module:@dwp/govuk-casa */
+/** @memberof module:"@dwp/govuk-casa" */
 export default class JourneyContext {
   // Private properties
   #data;
@@ -109,10 +114,11 @@ export default class JourneyContext {
    * among a group of contexts stored in the session.
    *
    * @param {Record<string, any>} data Entire journey data.
-   * @param {object} validation Page errors (indexed by waypoint id).
-   * @param {object} nav Navigation context.
-   * @param {object} identity Some metadata for identifying this context among
-   *   others.
+   * @param {Record<string, ValidationError[] | null>} validation Page errors
+   *   (indexed by waypoint id).
+   * @param {{ language?: string }} nav Navigation context.
+   * @param {JourneyContextIdentity} identity Some metadata for identifying this
+   *   context among others.
    */
   constructor(data = {}, validation = {}, nav = {}, identity = {}) {
     this.#data = data;
@@ -129,7 +135,7 @@ export default class JourneyContext {
    * @returns {JourneyContextObject} Plain object.
    */
   toObject() {
-    return Object.assign(Object.create(null), {
+    return Object.assign(new NullObject(), {
       data: clone(this.#data),
       validation: clone(this.#validation),
       nav: clone(this.#nav),
@@ -144,14 +150,14 @@ export default class JourneyContext {
    * @returns {JourneyContext} Instance.
    */
   static fromObject({
-    data = Object.create(null),
-    validation = Object.create(null),
-    nav = Object.create(null),
-    identity = Object.create(null),
+    data = new NullObject(),
+    validation = new NullObject(),
+    nav = new NullObject(),
+    identity = new NullObject(),
   } = {}) {
     // As we're constructing a JourneyContext from a plain JS object, we need to
     // ensure any validation errors are instances of ValidationError.
-    const deserialisedValidation = Object.create(null);
+    const deserialisedValidation = new NullObject();
     for (const [waypoint, errors] of Object.entries(validation)) {
       let dErrors = errors;
 
@@ -341,7 +347,7 @@ export default class JourneyContext {
    */
   getValidationErrorsForPageByField(pageId) {
     const errors = this.getValidationErrorsForPage(pageId);
-    const obj = Object.create(null);
+    const obj = new NullObject();
 
     // ESLint disabled as `i` is an integer
     /* eslint-disable security/detect-object-injection */
@@ -394,8 +400,8 @@ export default class JourneyContext {
    * @param {string[]} waypoints Waypoints to be removed
    */
   purge(waypoints = []) {
-    const newData = Object.create(null);
-    const newValidation = Object.create(null);
+    const newData = new NullObject();
+    const newValidation = new NullObject();
     const toKeep = Object.keys(this.#data).filter(
       (w) => !waypoints.includes(w),
     );
@@ -483,12 +489,12 @@ export default class JourneyContext {
         logMessage = `Calling waypoint-specific event handler on "${waypoint}"`;
         runHandler =
           previousContext.data?.[waypoint] !== undefined &&
-          !isEqual(this.data?.[waypoint], previousContext.data?.[waypoint]);
+          !deepEqual(this.data?.[waypoint], previousContext.data?.[waypoint]);
       } else if (waypoint && field) {
         logMessage = `Calling field-specific event handler on "${waypoint} : ${field}"`;
         runHandler =
           previousContext.data?.[waypoint]?.[field] !== undefined &&
-          !isEqual(
+          !deepEqual(
             this.data?.[waypoint]?.[field],
             previousContext.data?.[waypoint]?.[field],
           );
@@ -773,7 +779,7 @@ export default class JourneyContext {
    * @throws {TypeError} When session is not a valid type, or context has no ID
    */
   static putContext(session, context, options = {}) {
-    if (!isObject(session)) {
+    if (typeof session !== "object" || session === null) {
       throw new TypeError("Session must be an object");
     } else if (!(context instanceof JourneyContext)) {
       throw new TypeError("Context must be a valid JourneyContext");
@@ -933,20 +939,17 @@ export default class JourneyContext {
     /* eslint-disable security/detect-object-injection */
     // Unset, with setSkipped(a, false)
     if (opts === false) {
-      this.data[waypoint] ??= Object.create(null);
-      this.data[waypoint].__skipped__ = undefined;
+      this.data[waypoint] ??= new NullObject();
       this.data[waypoint].__skip__ = undefined;
     }
     // Set, with setSkipped(a, true) and clear data
     else if (opts === true) {
-      this.data[waypoint] = Object.create(null);
-      this.data[waypoint].__skipped__ = true;
+      this.data[waypoint] = new NullObject();
       this.data[waypoint].__skip__ = { to: null };
     }
     // Set, with setSkipped(a, { to: b }) and clear data
     else if (typeof opts?.to === "string") {
-      this.data[waypoint] = Object.create(null);
-      this.data[waypoint].__skipped__ = true;
+      this.data[waypoint] = new NullObject();
       this.data[waypoint].__skip__ = { to: opts.to };
     } else {
       throw new TypeError(
@@ -969,7 +972,7 @@ export default class JourneyContext {
     const wpData = this.data[String(waypoint)];
 
     if (opts === undefined) {
-      return wpData?.__skipped__ === true || wpData?.__skip__ !== undefined;
+      return wpData?.__skip__ !== undefined;
     } else if (typeof opts.to === "string") {
       return wpData?.__skip__?.to === opts.to;
     }

package/src/lib/MutableRouter.js

@@ -1,8 +1,8 @@
 import { Router } from "express";
 
-/** @memberof module:@dwp/govuk-casa */
+/** @memberof module:"@dwp/govuk-casa" */
 export default class MutableRouter {
-  /** @type {Array} */
+  /** @type {StackRoute[]} */
   #stack;
 
   /** @type {Router} */
@@ -100,8 +100,8 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `all()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   prependAll(path, ...callbacks) {
@@ -111,8 +111,8 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `get()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   prependGet(path, ...callbacks) {
@@ -122,8 +122,8 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `post()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   prependPost(path, ...callbacks) {
@@ -133,8 +133,8 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `delete()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   prependDelete(path, ...callbacks) {
@@ -144,8 +144,8 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `put()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   prependPut(path, ...callbacks) {
@@ -155,8 +155,8 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `use()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   prependUse(path, ...callbacks) {
@@ -168,8 +168,8 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `all()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   replaceAll(path, ...callbacks) {
@@ -179,8 +179,8 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `get()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   replaceGet(path, ...callbacks) {
@@ -190,8 +190,8 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `post()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   replacePost(path, ...callbacks) {
@@ -202,8 +202,8 @@ export default class MutableRouter {
    * Replace middleware function(s) that were mounted using the `delete()`
    * method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   replaceDelete(path, ...callbacks) {
@@ -213,8 +213,8 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `put()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   replacePut(path, ...callbacks) {
@@ -224,8 +224,8 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `use()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   replaceUse(path, ...callbacks) {
@@ -237,8 +237,8 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `all()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   all(path, ...callbacks) {
@@ -248,8 +248,8 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `get()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   get(path, ...callbacks) {
@@ -259,8 +259,8 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `post()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   post(path, ...callbacks) {
@@ -270,8 +270,8 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `delete()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   delete(path, ...callbacks) {
@@ -281,8 +281,8 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `put()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   put(path, ...callbacks) {
@@ -292,8 +292,8 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `use()` method.
    *
-   * @param {string | Function} path Route path or middleware function
-   * @param {...Function} callbacks Additional middleware functions
+   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
   use(path, ...callbacks) {
@@ -306,3 +306,12 @@ export default class MutableRouter {
     );
   }
 }
+
+/** @typedef {import("express").RequestHandler} RequestHandler */
+
+/**
+ * @typedef {object} StackRoute Stack route
+ * @property {string} method HTTP request method
+ * @property {string} path Route path
+ * @property {[string, ...RequestHandler[]]} args Router arguments
+ */

package/src/lib/NullObject.js

@@ -0,0 +1,4 @@
+const NullObject = function () {};
+NullObject.prototype = Object.create(null);
+
+export default NullObject;