@dwp/govuk-casa 8.15.0 → 9.1.0

package/src/lib/Plan.js

@@ -1,91 +1,103 @@
-import { Graph } from '@dagrejs/graphlib';
-import JourneyContext from './JourneyContext.js';
-import logger from './logger.js';
+import { Graph } from "@dagrejs/graphlib";
+import JourneyContext from "./JourneyContext.js";
+import logger from "./logger.js";
 
-const log = logger('lib:plan');
+const log = logger("lib:plan");
 
 /**
+ * @typedef {import("../casa").PlanRoute} PlanRoute
  * @access private
- * @typedef {import('../casa').PlanRoute} PlanRoute
  */
 
 /**
+ * @typedef {import("../casa").PlanRouteCondition} PlanRouteCondition
  * @access private
- * @typedef {import('../casa').PlanRouteCondition} PlanRouteCondition
  */
 
 /**
+ * @typedef {import("../casa").PlanTraverseOptions} PlanTraverseOptions
  * @access private
- * @typedef {import('../casa').PlanTraverseOptions} PlanTraverseOptions
  */
 
 /**
+ * @typedef {import("../casa").PlanArbiter} PlanArbiter
  * @access private
- * @typedef {import('../casa').PlanArbiter} PlanArbiter
  */
 
 /**
  * @typedef {object} PlanConstructorOptions
- * @property {boolean} [validateBeforeRouteCondition=true] Check page validity before conditions
- * @property {string|PlanArbiter} [arbiter=undefined] Arbitration mechanism
+ * @property {boolean} [validateBeforeRouteCondition=true] Check page validity
+ *   before conditions. Default is `true`
+ * @property {string | PlanArbiter} [arbiter=undefined] Arbitration mechanism.
+ *   Default is `undefined`
  */
 
 /**
  * Will check if the source waypoint has specifically passed validation, i.e
  * there is a "null" validation entry for the route source.
  *
- * @access private
  * @type {PlanRouteCondition}
+ * @access private
  */
 function defaultNextFollow(r, context) {
   const { validation: v = {} } = context.toObject();
-  return Object.prototype.hasOwnProperty.call(v, r.source) && v[r.source] === null;
+  return (
+    Object.prototype.hasOwnProperty.call(v, r.source) && v[r.source] === null
+  );
 }
 
 /**
  * Will check if the target waypoint (the one we're moving back to) has
  * specifically passed validation.
  *
- * @access private
  * @type {PlanRouteCondition}
+ * @access private
  */
 function defaultPrevFollow(r, context) {
   const { validation: v = {} } = context.toObject();
-  return Object.prototype.hasOwnProperty.call(v, r.target) && v[r.target] === null;
+  return (
+    Object.prototype.hasOwnProperty.call(v, r.target) && v[r.target] === null
+  );
 }
 
 /**
  * Validate a given waypoint ID.
  *
- * @access private
  * @param {string} val Waypoint ID
  * @returns {void}
  * @throws {TypeError} If waypoint ID is not a string
  * @throws {SyntaxError} If waypoint ID is incorrectly formatted
+ * @access private
  */
 function validateWaypointId(val) {
-  if (typeof val !== 'string') {
-    throw new TypeError(`Expected waypoint id to be a string, got ${typeof val}`);
+  if (typeof val !== "string") {
+    throw new TypeError(
+      `Expected waypoint id to be a string, got ${typeof val}`,
+    );
   }
-  if (val.substr(0, 6) === 'url://' && !val.endsWith('/')) {
-    throw new SyntaxError('url:// waypoints must include a trailing /')
+  if (val.substr(0, 6) === "url://" && !val.endsWith("/")) {
+    throw new SyntaxError("url:// waypoints must include a trailing /");
   }
 }
 
 /**
  * Validate a given route name.
  *
- * @access private
  * @param {string} val Route name
  * @returns {string} The route name
  * @throws {TypeError} If route name is not a string
  * @throws {ReferenceError} If route name is neither "next" or "prev"
+ * @access private
  */
 function validateRouteName(val) {
-  if (typeof val !== 'string') {
-    throw new TypeError(`Expected route name to be a string, got ${typeof val}`);
-  } else if (!['next', 'prev'].includes(val)) {
-    throw new ReferenceError(`Expected route name to be one of next or prev. Got ${val}`)
+  if (typeof val !== "string") {
+    throw new TypeError(
+      `Expected route name to be a string, got ${typeof val}`,
+    );
+  } else if (!["next", "prev"].includes(val)) {
+    throw new ReferenceError(
+      `Expected route name to be one of next or prev. Got ${val}`,
+    );
   }
   return val;
 }
@@ -93,26 +105,28 @@ function validateRouteName(val) {
 /**
  * Validate a given route condition.
  *
- * @access private
  * @param {PlanRouteCondition} val The condition function
  * @returns {void}
  * @throws {TypeError} If condition is not a string
+ * @access private
  */
 function validateRouteCondition(val) {
   if (!(val instanceof Function)) {
-    throw new TypeError(`Expected route condition to be a function, got ${typeof val}`);
+    throw new TypeError(
+      `Expected route condition to be a function, got ${typeof val}`,
+    );
   }
 }
 
 /**
- * Creates a user friendly route structure from a given graph edge which will
- * be used in userland. This is the object that will be passed into follow
+ * Creates a user friendly route structure from a given graph edge which will be
+ * used in userland. This is the object that will be passed into follow
  * functions too as the "route" parameter.
  *
- * @access private
  * @param {object} dgraph Directed graph instance.
  * @param {object} edge Graph edge object.
  * @returns {PlanRoute} Route.
+ * @access private
  */
 const makeRouteObject = (dgraph, edge) => {
   const label = dgraph.edge(edge) || {};
@@ -140,13 +154,9 @@ const reExitNodeProtocol = /^[a-z]+:\/\//i;
  */
 const priv = new WeakMap();
 
-/**
- * @memberof module:@dwp/govuk-casa
- */
+/** @memberof module:@dwp/govuk-casa */
 export default class Plan {
-  /**
-   * @type {string[]} These waypoints can be skipped
-   */
+  /** @type {string[]} These Waypoints can be skipped */
   #skippableWaypoints;
 
   /**
@@ -174,14 +184,18 @@ export default class Plan {
     });
 
     // Gather options
-    const options = Object.assign(Object.create(null), {
-      // When true, the validation state of the source node must be `null` (i.e.
-      // no validation errors) before any custom route conditions are evaluated.
-      validateBeforeRouteCondition: true,
-
-      // Traversal arbitration
-      arbiter: undefined,
-    }, opts);
+    const options = Object.assign(
+      Object.create(null),
+      {
+        // When true, the validation state of the source node must be `null` (i.e.
+        // no validation errors) before any custom route conditions are evaluated.
+        validateBeforeRouteCondition: true,
+
+        // Traversal arbitration
+        arbiter: undefined,
+      },
+      opts,
+    );
     Object.freeze(options);
 
     priv.set(this, {
@@ -217,7 +231,7 @@ export default class Plan {
   /**
    * Add one or more skippable waypoints.
    *
-   * @param  {...string} waypoints Waypoints
+   * @param {...string} waypoints Waypoints
    * @returns {Plan} Chain
    */
   addSkippables(...waypoints) {
@@ -261,7 +275,9 @@ export default class Plan {
    */
   getRoutes() {
     const self = priv.get(this);
-    return self.dgraph.edges().map((edge) => makeRouteObject(self.dgraph, edge));
+    return self.dgraph
+      .edges()
+      .map((edge) => makeRouteObject(self.dgraph, edge));
   }
 
   /**
@@ -286,7 +302,9 @@ export default class Plan {
    */
   getOutwardRoutes(src, tgt = null) {
     const self = priv.get(this);
-    return self.dgraph.outEdges(src, tgt).map((e) => makeRouteObject(self.dgraph, e));
+    return self.dgraph
+      .outEdges(src, tgt)
+      .map((e) => makeRouteObject(self.dgraph, e));
   }
 
   /**
@@ -298,14 +316,14 @@ export default class Plan {
    * @returns {PlanRoute[]} Route objects found.
    */
   getPrevOutwardRoutes(src, tgt = null) {
-    return this.getOutwardRoutes(src, tgt).filter((r) => r.name === 'prev');
+    return this.getOutwardRoutes(src, tgt).filter((r) => r.name === "prev");
   }
 
   /**
    * Add a sequence of waypoints that will follow on from each other, with no
    * routing logic between them.
    *
-   * @param  {...string} waypoints Waypoints to add
+   * @param {...string} waypoints Waypoints to add
    * @returns {void}
    */
   addSequence(...waypoints) {
@@ -326,7 +344,7 @@ export default class Plan {
    * @returns {Plan} Chain
    */
   setNextRoute(src, tgt, follow) {
-    return this.setNamedRoute(src, tgt, 'next', follow);
+    return this.setNamedRoute(src, tgt, "next", follow);
   }
 
   /**
@@ -338,7 +356,7 @@ export default class Plan {
    * @returns {Plan} Chain
    */
   setPrevRoute(src, tgt, follow) {
-    return this.setNamedRoute(src, tgt, 'prev', follow);
+    return this.setNamedRoute(src, tgt, "prev", follow);
   }
 
   /**
@@ -349,8 +367,8 @@ export default class Plan {
    * condition must be true, and so to reverse the direction we also need that
    * same condition to be true.
    *
-   * However, if the condition function uses the `source`/`target` property
-   * of the route in some way, then we must reverse these before passing to the
+   * However, if the condition function uses the `source`/`target` property of
+   * the route in some way, then we must reverse these before passing to the
    * condition on the "prev" route because `source` in the condition will almost
    * certainly be referring to the source of the "next" route.
    *
@@ -364,21 +382,24 @@ export default class Plan {
    * @returns {Plan} Chain
    */
   setRoute(src, tgt, followNext = undefined, followPrev = undefined) {
-    this.setNamedRoute(src, tgt, 'next', followNext);
+    this.setNamedRoute(src, tgt, "next", followNext);
 
     let followPrevious = followPrev;
     if (followPrevious === undefined) {
-      followPrevious = followNext === undefined ? undefined : (r, c) => {
-        const invertedRoute = {
-          ...r,
-          source: r.target,
-          target: r.source,
-        };
-        return followNext(invertedRoute, c);
-      }
+      followPrevious =
+        followNext === undefined
+          ? undefined
+          : (r, c) => {
+              const invertedRoute = {
+                ...r,
+                source: r.target,
+                target: r.source,
+              };
+              return followNext(invertedRoute, c);
+            };
     }
 
-    this.setNamedRoute(tgt, src, 'prev', followPrevious);
+    this.setNamedRoute(tgt, src, "prev", followPrevious);
 
     return this;
   }
@@ -386,20 +407,22 @@ export default class Plan {
   /**
    * Create a named route between two waypoints, and give that route a function
    * that determine whether it should be followed during traversal operations.
-   * Note that the source waypoint must be in a successful validation state
-   * to be considered for traversal, regardless of what the custom function
+   * Note that the source waypoint must be in a successful validation state to
+   * be considered for traversal, regardless of what the custom function
    * determines.
    *
    * You may also define routes that take the user to any generic URL within the
-   * same domain by using the `url://` protocol. These are considered
-   * "exit nodes".
+   * same domain by using the `url://` protocol. These are considered "exit
+   * nodes".
    *
-   * setNamedRoute("my-waypoint", "url:///some/absolute/url");
+   * SetNamedRoute("my-waypoint", "url:///some/absolute/url");
    *
    * @param {string} src Source waypoint.
    * @param {string} tgt Target waypoint.
-   * @param {string} name Name of the route (must be unique for this waypoint pairing).
-   * @param {PlanRouteCondition} follow Test function to determine if route can be followed.
+   * @param {string} name Name of the route (must be unique for this waypoint
+   *   pairing).
+   * @param {PlanRouteCondition} follow Test function to determine if route can
+   *   be followed.
    * @returns {Plan} Chain
    * @throws {Error} If attempting to create a "next" route from an exit node
    */
@@ -419,7 +442,12 @@ export default class Plan {
 
     // Warn if we're overwriting an existing edge on the same name
     if (self.dgraph.hasEdge(src, tgt, name)) {
-      log.warn('Setting a route that already exists (%s, %s, %s). Will be overridden', src, tgt, name);
+      log.warn(
+        "Setting a route that already exists (%s, %s, %s). Will be overridden",
+        src,
+        tgt,
+        name,
+      );
     }
     self.dgraph.setEdge(src, tgt, { conditionName }, name);
 
@@ -428,18 +456,18 @@ export default class Plan {
     if (follow) {
       if (!self.options.validateBeforeRouteCondition) {
         followFunc = follow;
-      } else if (name === 'next') {
+      } else if (name === "next") {
         // Retain the original function name of route condition
         followFunc = {
-          [follow.name]: (r, c) => (defaultNextFollow(r, c) && follow(r, c)),
+          [follow.name]: (r, c) => defaultNextFollow(r, c) && follow(r, c),
         }[follow.name];
       } else {
         // Retain the original function name of route condition
         followFunc = {
-          [follow.name]: (r, c) => (defaultPrevFollow(r, c) && follow(r, c)),
+          [follow.name]: (r, c) => defaultPrevFollow(r, c) && follow(r, c),
         }[follow.name];
       }
-    } else if (name === 'next') {
+    } else if (name === "next") {
       followFunc = defaultNextFollow;
     } else {
       followFunc = defaultPrevFollow;
@@ -453,8 +481,8 @@ export default class Plan {
   }
 
   /**
-   * This is a convenience method for traversing all "next" routes, and returning
-   * the IDs of all waypoints visited along the way.
+   * This is a convenience method for traversing all "next" routes, and
+   * returning the IDs of all waypoints visited along the way.
    *
    * @param {JourneyContext} context Journey Context
    * @param {PlanTraverseOptions} options Options
@@ -473,7 +501,7 @@ export default class Plan {
    * @returns {PlanRoute[]} List of traversed waypoints
    */
   traverseNextRoutes(context, options = {}) {
-    return this.traverseRoutes(context, { ...options, routeName: 'next' })
+    return this.traverseRoutes(context, { ...options, routeName: "next" });
   }
 
   /**
@@ -485,15 +513,16 @@ export default class Plan {
    * @returns {PlanRoute[]} List of traversed waypoints
    */
   traversePrevRoutes(context, options = {}) {
-    return this.traverseRoutes(context, { ...options, routeName: 'prev' })
+    return this.traverseRoutes(context, { ...options, routeName: "prev" });
   }
 
   /**
    * Traverse through the plan from a particular starting waypoint. This is a
    * non-exhaustive Graph Exploration.
    *
-   * The last route in the list will contain the source of the last waypoint that
-   * can be reached, i.e. The waypoint that has no further satisfiable out-edges.
+   * The last route in the list will contain the source of the last waypoint
+   * that can be reached, i.e. The waypoint that has no further satisfiable
+   * out-edges.
    *
    * If a cyclical set of routes are encountered, traversal will stop after
    * reaching the first repeated waypoint.
@@ -505,7 +534,9 @@ export default class Plan {
    */
   traverseRoutes(context, options = {}) {
     if (!(context instanceof JourneyContext)) {
-      throw new TypeError(`Expected context to be an instance of JourneyContext, got ${typeof context}`);
+      throw new TypeError(
+        `Expected context to be an instance of JourneyContext, got ${typeof context}`,
+      );
     }
 
     const self = priv.get(this);
@@ -513,13 +544,15 @@ export default class Plan {
     /** @type {PlanTraverseOptions} */
     const {
       startWaypoint = this.getWaypoints()[0],
-      stopCondition = () => (false),
+      stopCondition = () => false,
       arbiter = self.options.arbiter,
       routeName,
     } = options;
 
     if (!self.dgraph.hasNode(startWaypoint)) {
-      throw new ReferenceError(`Plan does not contain waypoint '${startWaypoint}'`);
+      throw new ReferenceError(
+        `Plan does not contain waypoint '${startWaypoint}'`,
+      );
     }
 
     validateRouteName(routeName);
@@ -537,7 +570,11 @@ export default class Plan {
           /* eslint-disable-next-line security/detect-object-injection */
           return self.follows[routeName][`${e.v}/${e.w}`](route, context);
         } catch (ex) {
-          log.warn('Route follow function threw an exception, "%s" (%s)', ex.message, `${e.v} -> ${e.w}`);
+          log.warn(
+            'Route follow function threw an exception, "%s" (%s)',
+            ex.message,
+            `${e.v} -> ${e.w}`,
+          );
           return false;
         }
       });
@@ -545,10 +582,12 @@ export default class Plan {
       // When there's more than one candidate route to take, we need help to choose
       if (target.length > 1) {
         const satisfied = target.map((t) => `${t.v} -> ${t.w}`);
-        log.debug(`Multiple routes were satisfied for "${routeName}" from "${startWP}" (${satisfied.join(' / ')}). Deciding how to resolve ...`);
+        log.debug(
+          `Multiple routes were satisfied for "${routeName}" from "${startWP}" (${satisfied.join(" / ")}). Deciding how to resolve ...`,
+        );
 
-        if (arbiter === 'auto') {
-          log.debug('Using automatic arbitration process');
+        if (arbiter === "auto") {
+          log.debug("Using automatic arbitration process");
           const targetNames = target.map(({ w }) => w);
           const forwardTraversal = this.traverseNextRoutes(context, {
             stopCondition: ({ source }) => targetNames.includes(source),
@@ -556,7 +595,7 @@ export default class Plan {
           const resolved = forwardTraversal.pop();
           target = target.filter((t) => t.w === resolved.source);
         } else if (arbiter instanceof Function) {
-          log.debug('Using custom arbitration process');
+          log.debug("Using custom arbitration process");
           // Convert to routeObject and back to edge object so that only the
           // routeObject is used in the public API
           target = arbiter({
@@ -564,9 +603,13 @@ export default class Plan {
             journeyContext: context,
             travereOptions: options,
           });
-          target = target.map((r) => ({ v: r.source, w: r.target, name: r.name }));
+          target = target.map((r) => ({
+            v: r.source,
+            w: r.target,
+            name: r.name,
+          }));
         } else {
-          log.warn('Unable to arbitrate');
+          log.warn("Unable to arbitrate");
           target = [];
         }
       }
@@ -593,15 +636,20 @@ export default class Plan {
 
           return results;
         }
-        log.debug('Encountered loop (%s). Stopping traversal.', `${route.source} -> ${route.target}`);
+        log.debug(
+          "Encountered loop (%s). Stopping traversal.",
+          `${route.source} -> ${route.target}`,
+        );
       }
 
-      return [makeRouteObject(self.dgraph, {
-        v: startWP,
-        w: null,
-        name: routeName,
-        label: {},
-      })];
+      return [
+        makeRouteObject(self.dgraph, {
+          v: startWP,
+          w: null,
+          name: routeName,
+          label: {},
+        }),
+      ];
     };
 
     return traverse(startWaypoint);

package/src/lib/ValidationError.js

@@ -1,27 +1,27 @@
-import lodash from 'lodash';
+import lodash from "lodash";
 
 const { isPlainObject } = lodash; // CommonJS
 
 const params = new WeakMap();
 
 /**
+ * @typedef {import("../casa").ValidateContext} ValidateContext
  * @access private
- * @typedef {import('../casa').ValidateContext} ValidateContext
  */
 
 /**
+ * @typedef {import("../casa").ErrorMessageConfig} ErrorMessageConfig
  * @access private
- * @typedef {import('../casa').ErrorMessageConfig} ErrorMessageConfig
  */
 
 /**
+ * @typedef {import("../casa").ErrorMessageConfigObject} ErrorMessageConfigObject
  * @access private
- * @typedef {import('../casa').ErrorMessageConfigObject} ErrorMessageConfigObject
  */
 
 /**
- * @class
  * @memberof module:@dwp/govuk-casa
+ * @class
  */
 export default class ValidationError {
   /**
@@ -30,24 +30,25 @@ export default class ValidationError {
    * <br/><br/>
    *
    * In the case of `errorMsg` being a function, this will be called at runtime,
-   * at the point that errors are generated within the `validate()`,
-   * methods, and will be passed the `dataContext`.
-   * <br/><br/>
+   * at the point that errors are generated within the `validate()`, methods,
+   * and will be passed the `dataContext`. <br/><br/>
    *
    * `dataContext` is an object containing the same data passed to all
-   * validators' `validate()` methods. In the case of `errorMsg` being
-   * a function, this data is passed to that function in order to help resolve to
+   * validators' `validate()` methods. In the case of `errorMsg` being a
+   * function, this data is passed to that function in order to help resolve to
    * an error message config object.
    *
    * @param {object} args Arguments
-   * @param {ErrorMessageConfig} args.errorMsg Error message config to seed ValidationError
-   * @param {ValidateContext} [args.dataContext={}] Data for error msg function
+   * @param {ErrorMessageConfig} args.errorMsg Error message config to seed
+   *   ValidationError
+   * @param {ValidateContext} [args.dataContext={}] Data for error msg function.
+   *   Default is `{}`
    * @returns {ValidationError} Error instance
    * @throws {TypeError} If errorMsg is not in a valid type
    */
   static make({ errorMsg, dataContext = {} }) {
     // Convert strings to the most basic object primitive
-    if (typeof errorMsg === 'string') {
+    if (typeof errorMsg === "string") {
       return new ValidationError({
         summary: errorMsg,
         inline: errorMsg,
@@ -63,7 +64,7 @@ export default class ValidationError {
 
     // Use the user-defined function to generate an error primitive for the
     // given context
-    if (typeof errorMsg === 'function') {
+    if (typeof errorMsg === "function") {
       return new ValidationError(errorMsg.call(null, { ...dataContext }));
     }
 
@@ -77,19 +78,22 @@ export default class ValidationError {
     }
 
     // Unsupported
-    throw new TypeError('errorMsg must be a string, Error, primitive object or function that generates a primitive object');
+    throw new TypeError(
+      "errorMsg must be a string, Error, primitive object or function that generates a primitive object",
+    );
   }
 
   /**
    * Create a ValidationError.
    *
-   * @param {string|ErrorMessageConfigObject} errorParam Error configuration
+   * @param {string | ErrorMessageConfigObject} errorParam Error configuration
    */
   constructor(errorParam = {}) {
-    if (!isPlainObject(errorParam) && typeof errorParam !== 'string') {
-      throw new TypeError('Constructor requires a string or object');
+    if (!isPlainObject(errorParam) && typeof errorParam !== "string") {
+      throw new TypeError("Constructor requires a string or object");
     }
-    const error = typeof errorParam === 'string' ? { summary: errorParam } : errorParam;
+    const error =
+      typeof errorParam === "string" ? { summary: errorParam } : errorParam;
 
     // Store parameters for later use in applying contexts
     const originals = {
@@ -133,7 +137,7 @@ export default class ValidationError {
     const originals = params.get(this);
 
     // Expand variables
-    if (typeof originals.variables === 'function') {
+    if (typeof originals.variables === "function") {
       this.variables = originals.variables.call(this, context);
     }
 
@@ -150,7 +154,7 @@ export default class ValidationError {
         fieldHref += focusSuffix[0];
       }
 
-      this.field = context.fieldName + (originals.fieldKeySuffix || '');
+      this.field = context.fieldName + (originals.fieldKeySuffix || "");
       this.fieldHref = fieldHref;
       this.focusSuffix = focusSuffix || [];
     }