@dwp/govuk-casa 9.0.0 → 9.2.0

package/src/lib/JourneyContext.js

@@ -6,61 +6,61 @@
  * - Validation errors on that data
  * - Navigation information about how the user got where they are.
  */
-import lodash from 'lodash';
-import ValidationError from './ValidationError.js';
-import logger from './logger.js';
-import { notProto } from './utils.js';
-import { uuid as uuidGenerator } from './context-id-generators.js';
+import lodash from "lodash";
+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, has, isEqual,
-} = lodash; // CommonJS
+const { isPlainObject, isObject, has, isEqual } = lodash; // CommonJS
 
-const log = logger('lib:journey-context');
+const log = logger("lib:journey-context");
 
 const uuid = uuidGenerator();
 
 /**
+ * @typedef {import("../casa").ContextEventUserInfo} ContextEventUserInfo
  * @access private
- * @typedef {import('../casa').ContextEventUserInfo} ContextEventUserInfo
  */
 
 /**
+ * @typedef {import("../casa").Page} Page
  * @access private
- * @typedef {import('../casa').Page} Page
  */
 
 /**
+ * @typedef {import("../casa").ContextEventHandler} ContextEventHandler
  * @access private
- * @typedef {import('../casa').ContextEventHandler} ContextEventHandler
  */
 
 /**
+ * @typedef {import("../casa").ContextEvent} ContextEvent
  * @access private
- * @typedef {import('../casa').ContextEvent} ContextEvent
  */
 
 /**
+ * @typedef {import("../casa").JourneyContextObject} JourneyContextObject
  * @access private
- * @typedef {import('../casa').JourneyContextObject} JourneyContextObject
  */
 
 /**
+ * @typedef {import("express").Request} ExpressRequest
  * @access private
- * @typedef {import('express').Request} ExpressRequest
  */
 
-export function validateObjectKey(key = '') {
+export function validateObjectKey(key = "") {
   const keyLower = String.prototype.toLowerCase.call(key);
-  if (keyLower === 'prototype' || keyLower === '__proto__' || keyLower === 'constructor') {
+  if (
+    keyLower === "prototype" ||
+    keyLower === "__proto__" ||
+    keyLower === "constructor"
+  ) {
     throw new SyntaxError(`Invalid object key used, ${key}`);
   }
   return String(key);
 }
 
-/**
- * @memberof module:@dwp/govuk-casa
- */
+/** @memberof module:@dwp/govuk-casa */
 export default class JourneyContext {
   // Private properties
   #data;
@@ -75,24 +75,20 @@ export default class JourneyContext {
 
   #eventListenerPreState;
 
-  static DEFAULT_CONTEXT_ID = 'default';
+  static DEFAULT_CONTEXT_ID = "default";
 
-  /**
-   * @type {symbol}
-   */
-  static ID_GENERATOR_REQ_LOG = Symbol('generatedContextIds');
+  /** @type {symbol} */
+  static ID_GENERATOR_REQ_LOG = Symbol("generatedContextIds");
 
-  /**
-   * @type {symbol}
-   */
-  static ID_GENERATOR_REQ_KEY = Symbol('generateContextId');
+  /** @type {symbol} */
+  static ID_GENERATOR_REQ_KEY = Symbol("generateContextId");
 
   /**
    * Constructor.
    *
    * `data` is the "single source of truth" for all data gathered during the
    * user's journey. This is referred to as the "canonical data model".
-   *  Page-specific "views" of this data are generated at runtime in order to
+   * Page-specific "views" of this data are generated at runtime in order to
    * populate/validate specific form fields.
    *
    * `validation` holds the results of form field validation carried out when
@@ -105,10 +101,11 @@ export default class JourneyContext {
    * `identity` holds information that helps uniquely identify this context
    * among a group of contexts stored in the session.
    *
-   * @param {Record<string,any>} data Entire journey data.
+   * @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 {object} identity Some metadata for identifying this context among
+   *   others.
    */
   constructor(data = {}, validation = {}, nav = {}, identity = {}) {
     this.#data = data;
@@ -152,7 +149,9 @@ export default class JourneyContext {
       let dErrors = errors;
 
       if (Array.isArray(errors)) {
-        dErrors = errors.map((e) => (e instanceof ValidationError ? e : new ValidationError(e)));
+        dErrors = errors.map((e) =>
+          e instanceof ValidationError ? e : new ValidationError(e),
+        );
       }
 
       deserialisedValidation[notProto(waypoint)] = dErrors;
@@ -184,18 +183,20 @@ export default class JourneyContext {
   /**
    * Get data context for a specific a specific page.
    *
-   * @param  {string | Page} page Page waypoint ID, or Page object.
+   * @param {string | Page} page Page waypoint ID, or Page object.
    * @returns {object} Page data.
    * @throws {TypeError} When page is invalid.
    */
   getDataForPage(page) {
-    if (typeof page === 'string') {
+    if (typeof page === "string") {
       return this.#data[validateObjectKey(page)];
     }
     if (isPlainObject(page)) {
       return this.#data[validateObjectKey(page.waypoint)];
     }
-    throw new TypeError(`Page must be a string or Page object. Got ${typeof page}`);
+    throw new TypeError(
+      `Page must be a string or Page object. Got ${typeof page}`,
+    );
   }
 
   /**
@@ -227,12 +228,14 @@ export default class JourneyContext {
    * @throws {TypeError} When page is invalid.
    */
   setDataForPage(page, webFormData) {
-    if (typeof page === 'string') {
+    if (typeof page === "string") {
       this.#data[validateObjectKey(page)] = webFormData;
     } else if (isPlainObject(page)) {
       this.#data[validateObjectKey(page.waypoint)] = webFormData;
     } else {
-      throw new TypeError(`Page must be a string or Page object. Got ${typeof page}`)
+      throw new TypeError(
+        `Page must be a string or Page object. Got ${typeof page}`,
+      );
     }
 
     return this;
@@ -286,12 +289,14 @@ export default class JourneyContext {
    */
   setValidationErrorsForPage(pageId, errors = []) {
     if (!Array.isArray(errors)) {
-      throw new SyntaxError(`Errors must be an Array. Received ${Object.prototype.toString.call(errors)}`);
+      throw new SyntaxError(
+        `Errors must be an Array. Received ${Object.prototype.toString.call(errors)}`,
+      );
     }
 
     errors.forEach((error) => {
       if (!(error instanceof ValidationError)) {
-        throw new SyntaxError('Field errors must be a ValidationError');
+        throw new SyntaxError("Field errors must be a ValidationError");
       }
     });
 
@@ -312,12 +317,13 @@ export default class JourneyContext {
   }
 
   /**
-   * Same as `getValidationErrorsForPage()`, but the return value is
-   * an object whose keys are the field names, and values are the list of errors
+   * Same as `getValidationErrorsForPage()`, but the return value is an object
+   * whose keys are the field names, and values are the list of errors
    * associated with that particular field.
    *
    * @param {string} pageId Page ID.
-   * @returns {object} Object indexed by field names; values containing list of errors
+   * @returns {object} Object indexed by field names; values containing list of
+   *   errors
    */
   getValidationErrorsForPageByField(pageId) {
     const errors = this.getValidationErrorsForPage(pageId);
@@ -353,7 +359,7 @@ export default class JourneyContext {
    * @param {string} language Language to set (ISO 639-1 2-letter code).
    * @returns {JourneyContext} Chain.
    */
-  setNavigationLanguage(language = 'en') {
+  setNavigationLanguage(language = "en") {
     this.#nav.language = language;
     return this;
   }
@@ -376,7 +382,9 @@ export default class JourneyContext {
   purge(waypoints = []) {
     const newData = Object.create(null);
     const newValidation = Object.create(null);
-    const toKeep = Object.keys(this.#data).filter((w) => !waypoints.includes(w));
+    const toKeep = Object.keys(this.#data).filter(
+      (w) => !waypoints.includes(w),
+    );
 
     // ESLint disabled as `i` is an integer
     /* eslint-disable security/detect-object-injection */
@@ -405,8 +413,8 @@ export default class JourneyContext {
   }
 
   /**
-   * Event listeners are transient. They are not stored in session, and generally
-   * only apply for the current request.
+   * Event listeners are transient. They are not stored in session, and
+   * generally only apply for the current request.
    *
    * They also only act on a fixed snapshot of this context's state, which is
    * taken at the point of attaching the listeners (in the "data" middleware).
@@ -431,7 +439,7 @@ export default class JourneyContext {
    * @param {object} params Params
    * @param {string} params.event Event (waypoint-change | context-change)
    * @param {object} params.session Session
-   * @param {ContextEventUserInfo|object} [params.userInfo] Pass-through info
+   * @param {ContextEventUserInfo | object} [params.userInfo] Pass-through info
    * @returns {JourneyContext} Chain
    */
   applyEventListeners({ event, session, userInfo }) {
@@ -439,7 +447,9 @@ export default class JourneyContext {
       return this;
     }
 
-    const previousContext = JourneyContext.fromObject(this.#eventListenerPreState);
+    const previousContext = JourneyContext.fromObject(
+      this.#eventListenerPreState,
+    );
     const listeners = this.#eventListeners.filter((l) => l.event === event);
 
     // ESLint disabled as `listeners[i]` uses an integer key, and the other keys
@@ -453,20 +463,21 @@ export default class JourneyContext {
       let runHandler = false;
 
       if (!waypoint && !field) {
-        logMessage = 'Calling generic event handler';
+        logMessage = "Calling generic event handler";
         runHandler = true;
       } else if (waypoint && !field) {
         logMessage = `Calling waypoint-specific event handler on "${waypoint}"`;
-        runHandler = previousContext.data?.[waypoint] !== undefined && !isEqual(
-          this.data?.[waypoint],
-          previousContext.data?.[waypoint],
-        );
+        runHandler =
+          previousContext.data?.[waypoint] !== undefined &&
+          !isEqual(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(
-          this.data?.[waypoint]?.[field],
-          previousContext.data?.[waypoint]?.[field],
-        );
+        runHandler =
+          previousContext.data?.[waypoint]?.[field] !== undefined &&
+          !isEqual(
+            this.data?.[waypoint]?.[field],
+            previousContext.data?.[waypoint]?.[field],
+          );
       }
 
       if (runHandler) {
@@ -514,7 +525,7 @@ export default class JourneyContext {
    */
   static fromContext(context, req) {
     if (!(context instanceof JourneyContext)) {
-      throw new TypeError('Source context must be a JourneyContext');
+      throw new TypeError("Source context must be a JourneyContext");
     }
 
     const newContextObj = context.toObject();
@@ -543,14 +554,16 @@ export default class JourneyContext {
     // being remodelled as an array, we need to convert the "legacy" structure
     // into an equivalent array.
     if (isPlainObject(session?.journeyContextList)) {
-      log.trace('Session context list already initialised as an object (legacy structure). Will convert from object to array.');
+      log.trace(
+        "Session context list already initialised as an object (legacy structure). Will convert from object to array.",
+      );
       /* eslint-disable-next-line no-param-reassign */
       session.journeyContextList = Object.entries(session.journeyContextList);
     }
 
     // Initialise new context list in the session
-    if (!has(session, 'journeyContextList')) {
-      log.trace('Initialising session with a default journey context list');
+    if (!has(session, "journeyContextList")) {
+      log.trace("Initialising session with a default journey context list");
       /* eslint-disable-next-line no-param-reassign */
       session.journeyContextList = [];
 
@@ -562,6 +575,7 @@ export default class JourneyContext {
 
   /**
    * Validate the format of a context ID:
+   *
    * - Between 1 and 64 characters
    * - Contain only the characters a-z, 0-9, -
    *
@@ -575,18 +589,18 @@ export default class JourneyContext {
       return JourneyContext.DEFAULT_CONTEXT_ID;
     }
 
-    if (typeof id !== 'string') {
-      throw new TypeError('Context ID must be a string');
+    if (typeof id !== "string") {
+      throw new TypeError("Context ID must be a string");
     } else if (!id.match(/^[a-z0-9-]{1,64}$/)) {
-      throw new SyntaxError('Context ID is not in the correct format');
+      throw new SyntaxError("Context ID is not in the correct format");
     }
 
     return id;
   }
 
   /**
-   * Generate a new context ID, validate it, and throw if the ID has already been
-   * generated during this request lifecycle. This may happen if an ID was
+   * Generate a new context ID, validate it, and throw if the ID has already
+   * been generated during this request lifecycle. This may happen if an ID was
    * generated, but never used to store a new context in the session. Therefore
    * it is important for user code to always call `putContext()` before
    * generating another ID.
@@ -599,12 +613,14 @@ export default class JourneyContext {
     // Can't generate custom ID when no request object is provided, because the
     // custom generator function itself exists on that object.
     if (!req) {
-      throw new Error('Missing required request object.')
+      throw new Error("Missing required request object.");
     }
 
     // Define a default context ID generator if required
     if (!Object.hasOwn(req, JourneyContext.ID_GENERATOR_REQ_KEY)) {
-      log.warn('A context ID generator is not present in the request. Reverting to uuid().');
+      log.warn(
+        "A context ID generator is not present in the request. Reverting to uuid().",
+      );
       Object.defineProperty(req, JourneyContext.ID_GENERATOR_REQ_KEY, {
         value: uuid,
         enumerable: false,
@@ -620,14 +636,18 @@ export default class JourneyContext {
       .map((c) => c.identity.id)
       .filter((id) => id !== JourneyContext.DEFAULT_CONTEXT_ID);
     const inRequestIds = req[JourneyContext.ID_GENERATOR_REQ_LOG] ?? [];
-    const reservedIds = Array.from(new Set([...inSessionIds, ...inRequestIds]).values());
+    const reservedIds = Array.from(
+      new Set([...inSessionIds, ...inRequestIds]).values(),
+    );
 
     // Generate and log the ID
     const id = JourneyContext.validateContextId(
       req[JourneyContext.ID_GENERATOR_REQ_KEY].call(null, { req, reservedIds }),
     );
     if (reservedIds.includes(id)) {
-      throw new Error(`Regenerated a context ID, ${String(id)}. It has likely not yet been used to store a new context in session using JourneyContext.putContext().`);
+      throw new Error(
+        `Regenerated a context ID, ${String(id)}. It has likely not yet been used to store a new context in session using JourneyContext.putContext().`,
+      );
     }
 
     if (!req[JourneyContext.ID_GENERATOR_REQ_LOG]) {
@@ -650,7 +670,10 @@ export default class JourneyContext {
    * @returns {JourneyContext} The default Journey Context
    */
   static getDefaultContext(session) {
-    return JourneyContext.getContextById(session, JourneyContext.DEFAULT_CONTEXT_ID);
+    return JourneyContext.getContextById(
+      session,
+      JourneyContext.DEFAULT_CONTEXT_ID,
+    );
   }
 
   /**
@@ -681,9 +704,7 @@ export default class JourneyContext {
   static getContextByName(session, name) {
     if (session) {
       const list = new Map(session?.journeyContextList);
-      const context = [...list.values()].find(
-        (c) => (c.identity.name === name),
-      );
+      const context = [...list.values()].find((c) => c.identity.name === name);
       if (context) {
         return JourneyContext.fromObject(context);
       }
@@ -697,14 +718,14 @@ export default class JourneyContext {
    *
    * @param {object} session Request session
    * @param {string} tag Context tag
-   * @returns {Array<JourneyContext>} The discovered JourneyContext instance
+   * @returns {JourneyContext[]} The discovered JourneyContext instance
    */
   static getContextsByTag(session, tag) {
     if (session) {
       const list = new Map(session?.journeyContextList);
-      return [...list.values()].filter(
-        (c) => (c.identity.tags?.includes(tag)),
-      ).map((c) => (JourneyContext.fromObject(c)));
+      return [...list.values()]
+        .filter((c) => c.identity.tags?.includes(tag))
+        .map((c) => JourneyContext.fromObject(c));
     }
 
     return undefined;
@@ -717,10 +738,10 @@ export default class JourneyContext {
    * @returns {Array} Array of contexts
    */
   static getContexts(session) {
-    if (has(session, 'journeyContextList')) {
-      return session.journeyContextList.map(([, contextObj]) => (
-        JourneyContext.fromObject(contextObj)
-      ));
+    if (has(session, "journeyContextList")) {
+      return session.journeyContextList.map(([, contextObj]) =>
+        JourneyContext.fromObject(contextObj),
+      );
     }
 
     return [];
@@ -732,21 +753,22 @@ export default class JourneyContext {
    * @param {object} session Request session
    * @param {JourneyContext} context Context
    * @param {object} options Options
-   * @param {ContextEventUserInfo|object} [options.userInfo] Pass-through event info
+   * @param {ContextEventUserInfo | object} [options.userInfo] Pass-through
+   *   event info
    * @returns {void}
    * @throws {TypeError} When session is not a valid type, or context has no ID
    */
   static putContext(session, context, options = {}) {
     if (!isObject(session)) {
-      throw new TypeError('Session must be an object');
+      throw new TypeError("Session must be an object");
     } else if (!(context instanceof JourneyContext)) {
-      throw new TypeError('Context must be a valid JourneyContext');
+      throw new TypeError("Context must be a valid JourneyContext");
     } else if (context.identity.id === undefined) {
-      throw new TypeError('Context must have an ID before storing in session');
+      throw new TypeError("Context must have an ID before storing in session");
     }
 
     // Initialise the session if necessary
-    if (!has(session, 'journeyContextList')) {
+    if (!has(session, "journeyContextList")) {
       JourneyContext.initContextStore(session);
     }
 
@@ -754,13 +776,13 @@ export default class JourneyContext {
     const { userInfo = undefined } = options;
 
     context.applyEventListeners({
-      event: 'waypoint-change',
+      event: "waypoint-change",
       session,
       userInfo,
     });
 
     context.applyEventListeners({
-      event: 'context-change',
+      event: "context-change",
       session,
       userInfo,
     });
@@ -792,7 +814,9 @@ export default class JourneyContext {
    * @returns {void}
    */
   static removeContextById(session, id) {
-    const index = (session?.journeyContextList ?? []).findIndex(([contextId]) => contextId === id);
+    const index = (session?.journeyContextList ?? []).findIndex(
+      ([contextId]) => contextId === id,
+    );
     if (index > -1) {
       session.journeyContextList.splice(index, 1);
     }
@@ -820,8 +844,8 @@ export default class JourneyContext {
    * @returns {void}
    */
   static removeContextsByTag(session, tag) {
-    JourneyContext.getContextsByTag(session, tag).forEach(
-      (c) => JourneyContext.removeContext(session, c),
+    JourneyContext.getContextsByTag(session, tag).forEach((c) =>
+      JourneyContext.removeContext(session, c),
     );
   }
 
@@ -832,15 +856,17 @@ export default class JourneyContext {
    * @returns {void}
    */
   static removeContexts(session) {
-    JourneyContext.getContexts(session).forEach((c) => JourneyContext.removeContext(session, c));
+    JourneyContext.getContexts(session).forEach((c) =>
+      JourneyContext.removeContext(session, c),
+    );
   }
 
   /**
    * Extract the Journey Context referred to in the incoming request.
    *
-   * This will look in `req.params`, `req.query` and
-   * `req.body` for a `contextid` parameter, and use that
-   * to load the correct Journey Context from the session.
+   * This will look in `req.params`, `req.query` and `req.body` for a
+   * `contextid` parameter, and use that to load the correct Journey Context
+   * from the session.
    *
    * @param {ExpressRequest} req ExpressJS incoming request
    * @returns {JourneyContext} The Journey Context
@@ -849,17 +875,19 @@ export default class JourneyContext {
     JourneyContext.initContextStore(req.session);
 
     let contextId;
-    if (has(req?.params, 'contextid')) {
-      log.trace('Context ID found in req.params.contextid');
+    if (has(req?.params, "contextid")) {
+      log.trace("Context ID found in req.params.contextid");
       contextId = String(req.params.contextid);
-    } else if (has(req.query, 'contextid')) {
-      log.trace('Context ID found in req.query.contextid');
+    } else if (has(req.query, "contextid")) {
+      log.trace("Context ID found in req.query.contextid");
       contextId = String(req.query.contextid);
-    } else if (has(req?.body, 'contextid')) {
-      log.trace('Context ID found in req.body.contextid');
+    } else if (has(req?.body, "contextid")) {
+      log.trace("Context ID found in req.body.contextid");
       contextId = String(req.body.contextid);
     } else {
-      log.trace('Context ID not specified or not found; will attempt to use default');
+      log.trace(
+        "Context ID not specified or not found; will attempt to use default",
+      );
       contextId = JourneyContext.DEFAULT_CONTEXT_ID;
     }
 
@@ -867,13 +895,68 @@ export default class JourneyContext {
       contextId = JourneyContext.validateContextId(contextId);
       const context = JourneyContext.getContextById(req.session, contextId);
       if (!context) {
-        throw (new Error(`Could not find a context with id, ${contextId}`));
+        throw new Error(`Could not find a context with id, ${contextId}`);
       }
       return context;
     } catch (err) {
       log.debug(err.message);
-      log.trace('Falling back to default context');
-      return JourneyContext.getContextById(req.session, JourneyContext.DEFAULT_CONTEXT_ID);
+      log.trace("Falling back to default context");
+      return JourneyContext.getContextById(
+        req.session,
+        JourneyContext.DEFAULT_CONTEXT_ID,
+      );
+    }
+  }
+
+  /**
+   * Set page skipped status.
+   *
+   * @param {string} waypoint Waypoint to skip.
+   * @param {boolean | object} opts Is skipped flag or options.
+   * @param {string} opts.to Waypoint to skip to.
+   */
+  setSkipped(waypoint, opts) {
+    // Unset, with setSkipped(a, false)
+    if (opts === false) {
+      this.data[waypoint] ??= Object.create(null);
+      this.data[waypoint].__skipped__ = undefined;
+      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].__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].__skip__ = { to: opts.to };
+    } else {
+      throw new TypeError(
+        `setSkipped opts must be a boolean or object with a "to" prop of waypoint to skip to, got: ${typeof opts}`,
+      );
+    }
+  }
+
+  /**
+   * Tests if a page has been skipped.
+   *
+   * @param {string} page Page ID (waypoint).
+   * @param {object} opts Skip ptions.
+   * @param {string} opts.to Waypoint that should be skipped to.
+   * @returns {boolean} True if the page has been skipped, or if it has been
+   *   skipped to a specific page.
+   */
+  isSkipped(waypoint, opts) {
+    if (opts === undefined) {
+      return (
+        this.data[waypoint]?.__skipped__ === true ||
+        this.data[waypoint]?.__skip__ !== undefined
+      );
+    } else if (typeof opts.to === "string") {
+      return this.data[waypoint]?.__skip__?.to === opts.to;
     }
   }
 }