@dwp/govuk-casa 8.2.1 → 8.2.4

package/dist/lib/Plan.js

@@ -19,13 +19,33 @@ const graphlib_1 = require("graphlib");
 const JourneyContext_js_1 = __importDefault(require("./JourneyContext.js"));
 const logger_js_1 = __importDefault(require("./logger.js"));
 const log = (0, logger_js_1.default)('lib:plan');
+/**
+ * @access private
+ * @typedef {import('../casa').PlanRoute} PlanRoute
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').PlanRouteCondition} PlanRouteCondition
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').PlanTraverseOptions} PlanTraverseOptions
+ */
+/**
+ * @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
+ */
 /**
  * Will check if the source waypoint has specifically passed validation, i.e
  * there is a "null" validation entry for the route source.
  *
- * @param {object} r Route meta.
- * @param {JourneyContext} context Journey Context.
- * @returns {boolean} Condition result.
+ * @access private
+ * @type {PlanRouteCondition}
  */
 function defaultNextFollow(r, context) {
     const { validation: v = {} } = context.toObject();
@@ -35,14 +55,22 @@ function defaultNextFollow(r, context) {
  * Will check if the target waypoint (the one we're moving back to) has
  * specifically passed validation.
  *
- * @param {object} r Route meta.
- * @param {JourneyContext} context Journey context.
- * @returns {boolean} Condition result.
+ * @access private
+ * @type {PlanRouteCondition}
  */
 function defaultPrevFollow(r, context) {
     const { validation: v = {} } = context.toObject();
     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
+ */
 function validateWaypointId(val) {
     if (typeof val !== 'string') {
         throw new TypeError(`Expected waypoint id to be a string, got ${typeof val}`);
@@ -51,6 +79,15 @@ function validateWaypointId(val) {
         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"
+ */
 function validateRouteName(val) {
     if (typeof val !== 'string') {
         throw new TypeError(`Expected route name to be a string, got ${typeof val}`);
@@ -60,6 +97,14 @@ function validateRouteName(val) {
     }
     return val;
 }
+/**
+ * Validate a given route condition.
+ *
+ * @access private
+ * @param {PlanRouteCondition} val The condition function
+ * @returns {void}
+ * @throws {TypeError} If condition is not a string
+ */
 function validateRouteCondition(val) {
     if (!(val instanceof Function)) {
         throw new TypeError(`Expected route condition to be a function, got ${typeof val}`);
@@ -70,9 +115,10 @@ function validateRouteCondition(val) {
  * 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 {object} Route.
+ * @returns {PlanRoute} Route.
  */
 const makeRouteObject = (dgraph, edge) => {
     const label = dgraph.edge(edge) || {};
@@ -86,16 +132,25 @@ const makeRouteObject = (dgraph, edge) => {
 };
 /**
  * Exit nodes begin with a protocol format, such as `url://`, `http://`, etc
+ *
+ * @access private
  */
 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
+ */
 class Plan {
     /**
      * Create a Plan.
      *
-     * @param {object} opts Options
-     * @param {boolean} [opts.validateBeforeRouteCondition=true] Check page validity before conditions
-     * @param {Function|string} [opts.arbiter=undefined] Arbitration mechanism
+     * @param {PlanConstructorOptions} opts Options
      */
     constructor(opts = {}) {
         /**
@@ -137,6 +192,11 @@ class Plan {
     static isExitNode(name) {
         return reExitNodeProtocol.test(name);
     }
+    /**
+     * Retrieve the options set on this Plan.
+     *
+     * @returns {PlanConstructorOptions} Options map
+     */
     getOptions() {
         return priv.get(this).options;
     }
@@ -152,7 +212,7 @@ class Plan {
      * Add one or more skippable waypoints.
      *
      * @param  {...string} waypoints Waypoints
-     * @returns {Plan}{ Chain}
+     * @returns {Plan} Chain
      */
     addSkippables(...waypoints) {
         __classPrivateFieldSet(this, _Plan_skippableWaypoints, [...__classPrivateFieldGet(this, _Plan_skippableWaypoints, "f"), ...waypoints], "f");
@@ -167,16 +227,40 @@ class Plan {
     isSkippable(waypoint) {
         return __classPrivateFieldGet(this, _Plan_skippableWaypoints, "f").indexOf(waypoint) > -1;
     }
+    /**
+     * Retrieve all waypoints in this Plan (order is arbitrary).
+     *
+     * @returns {string[]} List of waypoints
+     */
     getWaypoints() {
         return priv.get(this).dgraph.nodes();
     }
+    /**
+     * Determine if the given waypoint exists in this Plan.
+     *
+     * @param {string} waypoint Waypoint to search for
+     * @returns {boolean} Result
+     */
     containsWaypoint(waypoint) {
         return this.getWaypoints().includes(waypoint);
     }
+    /**
+     * Get all route information.
+     *
+     * @returns {PlanRoute[]} Routes
+     */
     getRoutes() {
         const self = priv.get(this);
         return self.dgraph.edges().map((edge) => makeRouteObject(self.dgraph, edge));
     }
+    /**
+     * Get the condition function for the given parameters.
+     *
+     * @param {string} src Source waypoint
+     * @param {string} tgt Target waypoint
+     * @param {string} name Route name
+     * @returns {PlanRouteCondition} Route condition function
+     */
     getRouteCondition(src, tgt, name) {
         return priv.get(this).follows[validateRouteName(name)][`${src}/${tgt}`];
     }
@@ -185,8 +269,8 @@ class Plan {
      * optional target waypoint.
      *
      * @param {string} src Source waypoint.
-     * @param {string} tgt Target waypoint (optional).
-     * @returns {Array<object>} Route objects found.
+     * @param {string} [tgt] Target waypoint.
+     * @returns {PlanRoute[]} Route objects found.
      */
     getOutwardRoutes(src, tgt = null) {
         const self = priv.get(this);
@@ -197,12 +281,19 @@ class Plan {
      * optional target waypoint, matching the "prev" name.
      *
      * @param {string} src Source waypoint.
-     * @param {string} tgt Target waypoint (optional).
-     * @returns {Array<object>} Route objects found.
+     * @param {string} [tgt] Target waypoint.
+     * @returns {PlanRoute[]} Route objects found.
      */
     getPrevOutwardRoutes(src, tgt = null) {
         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
+     * @returns {void}
+     */
     addSequence(...waypoints) {
         // Setup simple double routes (next/prev) between all waypoints in this list
         for (let i = 0, l = waypoints.length - 1; i < l; i += 1) {
@@ -211,21 +302,37 @@ class Plan {
             this.setRoute(waypoints[i], waypoints[i + 1]);
         }
     }
+    /**
+     * Create a new directed route between two waypoints, labelled as "next".
+     *
+     * @param {string} src Source waypoint
+     * @param {string} tgt Target waypoint
+     * @param {PlanRouteCondition} follow Route condition function
+     * @returns {Plan} Chain
+     */
     setNextRoute(src, tgt, follow) {
         return this.setNamedRoute(src, tgt, 'next', follow);
     }
+    /**
+     * Create a new directed route between two waypoints, labelled as "prev".
+     *
+     * @param {string} src Source waypoint
+     * @param {string} tgt Target waypoint
+     * @param {PlanRouteCondition} follow Route condition function
+     * @returns {Plan} Chain
+     */
     setPrevRoute(src, tgt, follow) {
         return this.setNamedRoute(src, tgt, 'prev', follow);
     }
     /**
      * Adds both a "next" and "prev" route between the two waypoints.
      *
-     * By default, the "prev" route will use the same "follow" test as the "next"
-     * route. This makes sense in that in order to get the target, the test must
-     * have been true, and so to reverse the direction we also need that same test
-     * to be true.
+     * By default, the "prev" route will use the same "follow" condition as the
+     * "next" route. This makes sense in that in order to get to the target, the
+     * 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`
+     * 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.
@@ -235,9 +342,9 @@ class Plan {
      *
      * @param {string} src Source waypoint.
      * @param {string} tgt Target waypoint.
-     * @param {Function} followNext Follow test function.
-     * @param {Function} followPrev Follow test function.
-     * @returns {Plan} Self.
+     * @param {PlanRouteCondition} [followNext] Follow test function.
+     * @param {PlanRouteCondition} [followPrev] Follow test function.
+     * @returns {Plan} Chain
      */
     setRoute(src, tgt, followNext = undefined, followPrev = undefined) {
         this.setNamedRoute(src, tgt, 'next', followNext);
@@ -267,7 +374,7 @@ class Plan {
      * @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 {Function} follow Test function to determine if route can be followed.
+     * @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
      */
@@ -321,16 +428,32 @@ class Plan {
      * 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 {object} options Options.
-     * @returns {Array<string>} List of traversed waypoints.
+     * @param {JourneyContext} context Journey Context
+     * @param {PlanTraverseOptions} options Options
+     * @returns {string[]} List of traversed waypoints
      */
     traverse(context, options = {}) {
         return this.traverseNextRoutes(context, options).map((e) => e.source);
     }
+    /**
+     * Traverse the Plan by following all "next" routes, and returning the IDs of
+     * all waypoints visited along the way.
+     *
+     * @param {JourneyContext} context Journey Context
+     * @param {PlanTraverseOptions} options Options
+     * @returns {PlanRoute[]} List of traversed waypoints
+     */
     traverseNextRoutes(context, options = {}) {
         return this.traverseRoutes(context, Object.assign(Object.assign({}, options), { routeName: 'next' }));
     }
+    /**
+     * Traverse the Plan by following all "prev" routes, and returning the IDs of
+     * all waypoints visited along the way.
+     *
+     * @param {JourneyContext} context Journey Context
+     * @param {PlanTraverseOptions} options Options
+     * @returns {PlanRoute[]} List of traversed waypoints
+     */
     traversePrevRoutes(context, options = {}) {
         return this.traverseRoutes(context, Object.assign(Object.assign({}, options), { routeName: 'prev' }));
     }
@@ -344,16 +467,9 @@ class Plan {
      * If a cyclical set of routes are encountered, traversal will stop after
      * reaching the first repeated waypoint.
      *
-     * Options:
-     * string startWaypoint = Waypoint from which to start traversal
-     * string routeName = Follow routes matching this name (next | prev)
-     * Map history = Used to detect loops in traversal (internal use)
-     * function stopCondition = Condition that, if true, will stop traversal (useful for performance)
-     * function|string arbiter = If mutliple target routes found, this decides which to use (if any)
-     *
      * @param {JourneyContext} context Journey context
-     * @param {object} options Options
-     * @returns {Array<object>} Routes that were traversed
+     * @param {PlanTraverseOptions} options Options
+     * @returns {PlanRoute[]} Routes that were traversed
      * @throws {TypeError} When context is not a JourneyContext
      */
     traverseRoutes(context, options = {}) {
@@ -361,6 +477,7 @@ class Plan {
             throw new TypeError(`Expected context to be an instance of JourneyContext, got ${typeof context}`);
         }
         const self = priv.get(this);
+        /** @type {PlanTraverseOptions} */
         const { startWaypoint = this.getWaypoints()[0], stopCondition = () => (false), arbiter = self.options.arbiter, routeName, } = options;
         if (!self.dgraph.hasNode(startWaypoint)) {
             throw new ReferenceError(`Plan does not contain waypoint '${startWaypoint}'`);
@@ -398,7 +515,14 @@ class Plan {
                 }
                 else if (arbiter instanceof Function) {
                     log.debug('Using custom arbitration process');
-                    target = arbiter(target, Object.assign({ context }, options));
+                    // 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)),
+                        journeyContext: context,
+                        travereOptions: options,
+                    });
+                    target = target.map((r) => ({ v: r.source, w: r.target, name: r.name }));
                 }
                 else {
                     log.warn('Unable to arbitrate');

package/dist/lib/ValidationError.d.ts

@@ -1,65 +1,53 @@
 /**
- * @typedef {import('./ValidatorFactory').ValidateContext} ValidateContext
+ * @access private
+ * @typedef {import('../casa').ValidateContext} ValidateContext
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfigObject} ErrorMessageConfigObject
+ */
+/**
+ * @class
+ * @memberof module:@dwp/govuk-casa
  */
 export default class ValidationError {
     /**
      * Make a ValidationError instance from a primitive object (or a function that
      * returns a primitive object) that is specific to the given journey context.
+     * <br/><br/>
      *
-     * The returned `error` (or the function that returns the equivalent) must
-     * match the structure required by the ValidationError constructor.
-     *
-     * `errorMsg` can be one of these formats:
-     *   String => 'common:errors.my-error-message'
-     *   Object => (see constructor argument for structure of this object)
-     *   Function => Function returns object suitable for constructor (see example below)
-     *   Error => A JavaScript error. It's `message` will be used as the error.
-     *
-     * `dataContext` is an object containing the same data passed to all validator
-     * functions, and contains:
-     *   waypointId => The current waypoint being requested
-     *   fieldName => Name of the field being validated
-     *   journeyContext => The full JourneyContext of the current request.
+     * 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/>
      *
-     * Example function signature that can be used for `errorMsg`:
-     *   ({ waypointId, fieldName, journeyContext }) => ({
-     *     summary: 'my-waypoint:some.key.to.say.hello',
-     *     variables: {
-     *       name: journeyContext.getDataForPage(waypointId).name,
-     *     }
-     *   });
+     * `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
+     * an error message config object.
      *
-     * @param {object} args See args above
-     * @param {any} args.errorMsg Error message to seed the ValidationError
-     * @param {object} args.dataContext Validation context
-     * @returns {object} Primitive error matching structure above
+     * @param {object} args Arguments
+     * @param {ErrorMessageConfig} args.errorMsg Error message config to seed ValidationError
+     * @param {ValidateContext} [args.dataContext={}] Data for error msg function
+     * @returns {ValidationError} Error instance
      * @throws {TypeError} If errorMsg is not in a valid type
      */
     static make({ errorMsg, dataContext }: {
-        errorMsg: any;
-        dataContext: object;
-    }): object;
+        errorMsg: ErrorMessageConfig;
+        dataContext?: import("../casa").ValidateContext | undefined;
+    }): ValidationError;
     /**
-     * `error` may be a simple string, in which case that string reppresents the
-     * error mesaage (equivalent to `error.summary` in the structure below).
-     *
-     * `error`, when passed as an object, must match this structure:
-     *
-     * {
-     *   summary: "",         // required
-     *   inline: "",          // optional, may be deprecated in future
-     *   focusSuffix: "",     // optional
-     *   fieldKeySuffix: "",  // optional
-     *   variables: {         // optional
-     *     myVariable: 'a value'
-     *   }
-     * }
+     * Create a ValidationError.
      *
-     * @param {object|string} errorParam See object structure above
+     * @param {string|ErrorMessageConfigObject} errorParam Error configuration
      */
-    constructor(errorParam?: object | string);
+    constructor(errorParam?: string | ErrorMessageConfigObject);
     /**
-     * Modifies the error to reflect the given context.
+     * Modifies this instance to reflect the given validation context.
      *
      * @param {ValidateContext} context See structure above
      * @returns {ValidationError} Chain
@@ -69,6 +57,8 @@ export default class ValidationError {
     field: string | undefined;
     fieldHref: string | undefined;
     focusSuffix: any;
-    validator: any;
+    validator: string | undefined;
 }
-export type ValidateContext = import('./ValidatorFactory').ValidateContext;
+export type ValidateContext = import('../casa').ValidateContext;
+export type ErrorMessageConfig = import('../casa').ErrorMessageConfig;
+export type ErrorMessageConfigObject = import('../casa').ErrorMessageConfigObject;

package/dist/lib/ValidationError.js

@@ -7,40 +7,41 @@ const lodash_1 = __importDefault(require("lodash"));
 const { isPlainObject } = lodash_1.default; // CommonJS
 const params = new WeakMap();
 /**
- * @typedef {import('./ValidatorFactory').ValidateContext} ValidateContext
+ * @access private
+ * @typedef {import('../casa').ValidateContext} ValidateContext
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfigObject} ErrorMessageConfigObject
+ */
+/**
+ * @class
+ * @memberof module:@dwp/govuk-casa
  */
 class ValidationError {
     /**
      * Make a ValidationError instance from a primitive object (or a function that
      * returns a primitive object) that is specific to the given journey context.
+     * <br/><br/>
      *
-     * The returned `error` (or the function that returns the equivalent) must
-     * match the structure required by the ValidationError constructor.
-     *
-     * `errorMsg` can be one of these formats:
-     *   String => 'common:errors.my-error-message'
-     *   Object => (see constructor argument for structure of this object)
-     *   Function => Function returns object suitable for constructor (see example below)
-     *   Error => A JavaScript error. It's `message` will be used as the error.
-     *
-     * `dataContext` is an object containing the same data passed to all validator
-     * functions, and contains:
-     *   waypointId => The current waypoint being requested
-     *   fieldName => Name of the field being validated
-     *   journeyContext => The full JourneyContext of the current request.
+     * 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/>
      *
-     * Example function signature that can be used for `errorMsg`:
-     *   ({ waypointId, fieldName, journeyContext }) => ({
-     *     summary: 'my-waypoint:some.key.to.say.hello',
-     *     variables: {
-     *       name: journeyContext.getDataForPage(waypointId).name,
-     *     }
-     *   });
+     * `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
+     * an error message config object.
      *
-     * @param {object} args See args above
-     * @param {any} args.errorMsg Error message to seed the ValidationError
-     * @param {object} args.dataContext Validation context
-     * @returns {object} Primitive error matching structure above
+     * @param {object} args Arguments
+     * @param {ErrorMessageConfig} args.errorMsg Error message config to seed ValidationError
+     * @param {ValidateContext} [args.dataContext={}] Data for error msg function
+     * @returns {ValidationError} Error instance
      * @throws {TypeError} If errorMsg is not in a valid type
      */
     static make({ errorMsg, dataContext = {} }) {
@@ -74,22 +75,9 @@ class ValidationError {
         throw new TypeError('errorMsg must be a string, Error, primitive object or function that generates a primitive object');
     }
     /**
-     * `error` may be a simple string, in which case that string reppresents the
-     * error mesaage (equivalent to `error.summary` in the structure below).
-     *
-     * `error`, when passed as an object, must match this structure:
-     *
-     * {
-     *   summary: "",         // required
-     *   inline: "",          // optional, may be deprecated in future
-     *   focusSuffix: "",     // optional
-     *   fieldKeySuffix: "",  // optional
-     *   variables: {         // optional
-     *     myVariable: 'a value'
-     *   }
-     * }
+     * Create a ValidationError.
      *
-     * @param {object|string} errorParam See object structure above
+     * @param {string|ErrorMessageConfigObject} errorParam Error configuration
      */
     constructor(errorParam = {}) {
         if (!isPlainObject(errorParam) && typeof errorParam !== 'string') {
@@ -126,7 +114,7 @@ class ValidationError {
         });
     }
     /**
-     * Modifies the error to reflect the given context.
+     * Modifies this instance to reflect the given validation context.
      *
      * @param {ValidateContext} context See structure above
      * @returns {ValidationError} Chain