@dwp/govuk-casa 8.0.0-alpha2 → 8.0.1

package/dist/lib/CasaTemplateLoader.js

@@ -13,6 +13,24 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var _CasaTemplateLoader_instances, _CasaTemplateLoader_blockModifiers, _CasaTemplateLoader_applyBlockModifiers;
 Object.defineProperty(exports, "__esModule", { value: true });
 const nunjucks_1 = require("nunjucks");
+/**
+ * @typedef {import('nunjucks').FileSystemLoaderOptions} FileSystemLoaderOptions
+ */
+const VALID_BLOCKS = [
+    'beforeContent',
+    'bodyEnd',
+    'bodyStart',
+    'casaPageTitle',
+    'content',
+    'footer',
+    'head',
+    'header',
+    'headIcons',
+    'journey_form',
+    'main',
+    'pageTitle',
+    'skipLink',
+];
 /**
  * @callback BlockModifier
  * @param {string} templateName Path to the template being modified
@@ -23,7 +41,7 @@ class CasaTemplateLoader extends nunjucks_1.FileSystemLoader {
      * Constructor.
      *
      * @param {string[]} searchPaths Template directories
-     * @param {import('nunjucks').FileSystemLoaderOptions} opts Loader options
+     * @param {FileSystemLoaderOptions} opts Loader options
      */
     constructor(searchPaths, opts) {
         super(searchPaths, opts);
@@ -47,9 +65,13 @@ class CasaTemplateLoader extends nunjucks_1.FileSystemLoader {
      * @param {string} block Block name, e.g. `bodyStart`
      * @param {BlockModifier} modifier Modifier function
      * @returns {void}
+     * @throws {Error} If provided with an unrecognised block
      */
     modifyBlock(block, modifier) {
-        // TODO: Limit to only known block so the user can't do general string replacements
+        // Limit to only known block so the user can't do general string replacements
+        if (!VALID_BLOCKS.includes(block)) {
+            throw new Error(`Block "${String(block)}" is not a recognised template block.`);
+        }
         __classPrivateFieldGet(this, _CasaTemplateLoader_blockModifiers, "f").push({
             block,
             modifier,
@@ -58,9 +80,9 @@ class CasaTemplateLoader extends nunjucks_1.FileSystemLoader {
 }
 exports.default = CasaTemplateLoader;
 _CasaTemplateLoader_blockModifiers = new WeakMap(), _CasaTemplateLoader_instances = new WeakSet(), _CasaTemplateLoader_applyBlockModifiers = function _CasaTemplateLoader_applyBlockModifiers(name, source) {
-    // TODO: This is open to abuse by plugin authors, e,g
-    // `{% block bodyStart %}{% endblock %} <script src="evil.js"></script>`. Problem, or no?
     for (let i = 0, l = __classPrivateFieldGet(this, _CasaTemplateLoader_blockModifiers, "f").length; i < l; i++) {
+        // ESLint disabled as `i` is an integer
+        /* eslint-disable-next-line security/detect-object-injection */
         const { block, modifier } = __classPrivateFieldGet(this, _CasaTemplateLoader_blockModifiers, "f")[i];
         if (source.src.indexOf(`block ${block}`) > -1) {
             /* eslint-disable-next-line no-param-reassign */

package/dist/lib/JourneyContext.d.ts

@@ -1,3 +1,19 @@
+/**
+ * @typedef {import('./configuration-ingestor').Page} Page
+ */
+/**
+ * @callback ContextEventHandler
+ * @param {JourneyContext} journeyContext Context including changes
+ * @param {JourneyContext} previousContext Context prior to changes
+ * @returns {void}
+ */
+/**
+ * @typedef {object} ContextEvent
+ * @property {string} waypoint Waypoint to watch for changes
+ * @property {string} [field] Field to watch for changes
+ * @property {ContextEventHandler} handler Handler to invoke when change happens
+ */
+export function validateObjectKey(key?: string): string;
 export default class JourneyContext {
     static DEFAULT_CONTEXT_ID: string;
     /**
@@ -133,11 +149,11 @@ export default class JourneyContext {
     /**
      * Get data context for a specific a specific page.
      *
-     * @param  {string | PageMeta} 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: string | any): object;
+    getDataForPage(page: string | Page): object;
     getData(): object;
     /**
      * Overwrite the data context with a new object.
@@ -150,16 +166,16 @@ export default class JourneyContext {
      * Write field form data from a page HTML form, into the `data` model.
      *
      * By default this will store the data as-is, keyed against the page's
-     * waypoint ID. However, when passing a `PageMeta` instance, its
+     * waypoint ID. However, when passing a `Page` instance, its
      * `fieldWriter()` method will be called to transform the provided formData
      * before storing in `data`
      *
-     * @param {string | PageMeta} page Page waypoint ID, or PageMeta object
+     * @param {string | Page} page Page waypoint ID, or Page object
      * @param {object} webFormData Data to overwrite with
      * @returns {JourneyContext} Chain
      * @throws {TypeError} When page is invalid.
      */
-    setDataForPage(page: string | any, webFormData: object): JourneyContext;
+    setDataForPage(page: string | Page, webFormData: object): JourneyContext;
     /**
      * Return validation errors for all pages.
      *
@@ -251,7 +267,7 @@ export default class JourneyContext {
      * @param {ContextEvent[]} events Event listeners
      * @returns {JourneyContext} Chain
      */
-    addEventListeners(events: any[]): JourneyContext;
+    addEventListeners(events: ContextEvent[]): JourneyContext;
     applyEventListeners({ event }: {
         event: any;
     }): JourneyContext;
@@ -263,4 +279,20 @@ export default class JourneyContext {
     isDefault(): boolean;
     #private;
 }
+export type Page = import('./configuration-ingestor').Page;
+export type ContextEventHandler = (journeyContext: JourneyContext, previousContext: JourneyContext) => void;
+export type ContextEvent = {
+    /**
+     * Waypoint to watch for changes
+     */
+    waypoint: string;
+    /**
+     * Field to watch for changes
+     */
+    field?: string | undefined;
+    /**
+     * Handler to invoke when change happens
+     */
+    handler: ContextEventHandler;
+};
 import ValidationError from "./ValidationError.js";

package/dist/lib/JourneyContext.js

@@ -26,6 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 var _JourneyContext_data, _JourneyContext_validation, _JourneyContext_nav, _JourneyContext_identity, _JourneyContext_eventListeners, _JourneyContext_eventListenerPreState;
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateObjectKey = void 0;
 /**
  * Represents the state of a user's journey through the Plan. It contains
  * information about:
@@ -39,7 +40,30 @@ const lodash_1 = __importDefault(require("lodash"));
 const ValidationError_js_1 = __importDefault(require("./ValidationError.js"));
 const logger_js_1 = __importDefault(require("./logger.js"));
 const { cloneDeep, isPlainObject, isObject, has, isEqual, } = lodash_1.default; // CommonJS
-const log = (0, logger_js_1.default)('class:journey-context');
+const log = (0, logger_js_1.default)('lib:journey-context');
+/**
+ * @typedef {import('./configuration-ingestor').Page} Page
+ */
+/**
+ * @callback ContextEventHandler
+ * @param {JourneyContext} journeyContext Context including changes
+ * @param {JourneyContext} previousContext Context prior to changes
+ * @returns {void}
+ */
+/**
+ * @typedef {object} ContextEvent
+ * @property {string} waypoint Waypoint to watch for changes
+ * @property {string} [field] Field to watch for changes
+ * @property {ContextEventHandler} handler Handler to invoke when change happens
+ */
+function validateObjectKey(key = '') {
+    const keyLower = String.prototype.toLowerCase.call(key);
+    if (keyLower === 'prototype' || keyLower === '__proto__' || keyLower === 'constructor') {
+        throw new SyntaxError(`Invalid object key used, ${key}`);
+    }
+    return String(key);
+}
+exports.validateObjectKey = validateObjectKey;
 class JourneyContext {
     /**
      * Constructor.
@@ -123,16 +147,16 @@ class JourneyContext {
     /**
      * Get data context for a specific a specific page.
      *
-     * @param  {string | PageMeta} 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') {
-            return __classPrivateFieldGet(this, _JourneyContext_data, "f")[page];
+            return __classPrivateFieldGet(this, _JourneyContext_data, "f")[validateObjectKey(page)];
         }
         if (isPlainObject(page)) {
-            return __classPrivateFieldGet(this, _JourneyContext_data, "f")[page.waypoint];
+            return __classPrivateFieldGet(this, _JourneyContext_data, "f")[validateObjectKey(page.waypoint)];
         }
         throw new TypeError(`Page must be a string or Page object. Got ${typeof page}`);
     }
@@ -153,21 +177,21 @@ class JourneyContext {
      * Write field form data from a page HTML form, into the `data` model.
      *
      * By default this will store the data as-is, keyed against the page's
-     * waypoint ID. However, when passing a `PageMeta` instance, its
+     * waypoint ID. However, when passing a `Page` instance, its
      * `fieldWriter()` method will be called to transform the provided formData
      * before storing in `data`
      *
-     * @param {string | PageMeta} page Page waypoint ID, or PageMeta object
+     * @param {string | Page} page Page waypoint ID, or Page object
      * @param {object} webFormData Data to overwrite with
      * @returns {JourneyContext} Chain
      * @throws {TypeError} When page is invalid.
      */
     setDataForPage(page, webFormData) {
         if (typeof page === 'string') {
-            __classPrivateFieldGet(this, _JourneyContext_data, "f")[page] = webFormData;
+            __classPrivateFieldGet(this, _JourneyContext_data, "f")[validateObjectKey(page)] = webFormData;
         }
         else if (isPlainObject(page)) {
-            __classPrivateFieldGet(this, _JourneyContext_data, "f")[page.waypoint] = webFormData;
+            __classPrivateFieldGet(this, _JourneyContext_data, "f")[validateObjectKey(page.waypoint)] = webFormData;
         }
         else {
             throw new TypeError(`Page must be a string or Page object. Got ${typeof page}`);
@@ -205,7 +229,7 @@ class JourneyContext {
      * @returns {JourneyContext} Chain.
      */
     clearValidationErrorsForPage(pageId) {
-        __classPrivateFieldGet(this, _JourneyContext_validation, "f")[pageId] = null;
+        __classPrivateFieldGet(this, _JourneyContext_validation, "f")[validateObjectKey(pageId)] = null;
         return this;
     }
     /**
@@ -225,7 +249,7 @@ class JourneyContext {
                 throw new SyntaxError('Field errors must be a ValidationError');
             }
         });
-        __classPrivateFieldGet(this, _JourneyContext_validation, "f")[pageId] = errors;
+        __classPrivateFieldGet(this, _JourneyContext_validation, "f")[validateObjectKey(pageId)] = errors;
         return this;
     }
     /**
@@ -236,17 +260,21 @@ class JourneyContext {
      * @returns {ValidationError[]} An array of errors
      */
     getValidationErrorsForPage(pageId) {
-        return __classPrivateFieldGet(this, _JourneyContext_validation, "f")[pageId] || [];
+        var _a;
+        return (_a = __classPrivateFieldGet(this, _JourneyContext_validation, "f")[validateObjectKey(pageId)]) !== null && _a !== void 0 ? _a : [];
     }
     getValidationErrorsForPageByField(pageId) {
         const errors = this.getValidationErrorsForPage(pageId);
         const obj = Object.create(null);
+        // ESLint disabled as `i` is an integer
+        /* eslint-disable security/detect-object-injection */
         for (let i = 0, l = errors.length; i < l; i++) {
             if (!obj[errors[i].field]) {
                 obj[errors[i].field] = [];
             }
             obj[errors[i].field].push(errors[i]);
         }
+        /* eslint-enable security/detect-object-injection */
         return obj;
     }
     /**
@@ -258,7 +286,7 @@ class JourneyContext {
      */
     hasValidationErrorsForPage(pageId) {
         var _a, _b;
-        return ((_b = (_a = __classPrivateFieldGet(this, _JourneyContext_validation, "f")) === null || _a === void 0 ? void 0 : _a[pageId]) === null || _b === void 0 ? void 0 : _b.length) > 0;
+        return ((_b = (_a = __classPrivateFieldGet(this, _JourneyContext_validation, "f")) === null || _a === void 0 ? void 0 : _a[validateObjectKey(pageId)]) === null || _b === void 0 ? void 0 : _b.length) > 0;
     }
     /**
      * Set language of the context.
@@ -277,7 +305,7 @@ class JourneyContext {
      * @returns {boolean} True if the page is valid.
      */
     isPageValid(pageId) {
-        return __classPrivateFieldGet(this, _JourneyContext_validation, "f")[pageId] === null;
+        return __classPrivateFieldGet(this, _JourneyContext_validation, "f")[validateObjectKey(pageId)] === null;
     }
     /**
      * Remove information about these waypoints.
@@ -288,10 +316,13 @@ class JourneyContext {
         const newData = Object.create(null);
         const newValidation = Object.create(null);
         const toKeep = Object.keys(this.data).filter((w) => !waypoints.includes(w));
+        // ESLint disabled as `i` is an integer
+        /* eslint-disable security/detect-object-injection */
         for (let i = 0, l = toKeep.length; i < l; i++) {
             newData[toKeep[i]] = __classPrivateFieldGet(this, _JourneyContext_data, "f")[toKeep[i]];
             newValidation[toKeep[i]] = __classPrivateFieldGet(this, _JourneyContext_validation, "f")[toKeep[i]];
         }
+        /* eslint-enable security/detect-object-injection */
         __classPrivateFieldSet(this, _JourneyContext_data, Object.assign({}, newData), "f");
         __classPrivateFieldSet(this, _JourneyContext_validation, Object.assign({}, newValidation), "f");
     }
@@ -304,6 +335,8 @@ class JourneyContext {
      */
     invalidate(waypoints = []) {
         for (let i = 0, l = waypoints.length; i < l; i++) {
+            // ESLint disabled as `i` is an integer
+            /* eslint-disable-next-line security/detect-object-injection */
             this.removeValidationStateForPage(waypoints[i]);
         }
     }
@@ -325,12 +358,16 @@ class JourneyContext {
         return this;
     }
     applyEventListeners({ event }) {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         if (!__classPrivateFieldGet(this, _JourneyContext_eventListeners, "f").length) {
             return this;
         }
         const previousContext = JourneyContext.fromObject(__classPrivateFieldGet(this, _JourneyContext_eventListenerPreState, "f"));
         const listeners = __classPrivateFieldGet(this, _JourneyContext_eventListeners, "f").filter((l) => l.event === event);
+        // ESLint disabled as `listeners[i]` uses an integer key, and the other keys
+        // are derived from the list of `listeners`, which are not manipulated at
+        // runtime (only set by dev in code).
+        /* eslint-disable security/detect-object-injection */
         for (let i = 0, l = listeners.length; i < l; i++) {
             const { waypoint, field, handler } = listeners[i];
             let logMessage;
@@ -341,17 +378,18 @@ class JourneyContext {
             }
             else if (waypoint && !field) {
                 logMessage = `Calling waypoint-specific event handler on "${waypoint}"`;
-                runHandler = !isEqual((_a = this.data) === null || _a === void 0 ? void 0 : _a[waypoint], (_b = previousContext.data) === null || _b === void 0 ? void 0 : _b[waypoint]);
+                runHandler = ((_a = previousContext.data) === null || _a === void 0 ? void 0 : _a[waypoint]) !== undefined && !isEqual((_b = this.data) === null || _b === void 0 ? void 0 : _b[waypoint], (_c = previousContext.data) === null || _c === void 0 ? void 0 : _c[waypoint]);
             }
             else if (waypoint && field) {
                 logMessage = `Calling field-specific event handler on "${waypoint} : ${field}"`;
-                runHandler = !isEqual((_d = (_c = this.data) === null || _c === void 0 ? void 0 : _c[waypoint]) === null || _d === void 0 ? void 0 : _d[field], (_f = (_e = previousContext.data) === null || _e === void 0 ? void 0 : _e[waypoint]) === null || _f === void 0 ? void 0 : _f[field]);
+                runHandler = ((_e = (_d = previousContext.data) === null || _d === void 0 ? void 0 : _d[waypoint]) === null || _e === void 0 ? void 0 : _e[field]) !== undefined && !isEqual((_g = (_f = this.data) === null || _f === void 0 ? void 0 : _f[waypoint]) === null || _g === void 0 ? void 0 : _g[field], (_j = (_h = previousContext.data) === null || _h === void 0 ? void 0 : _h[waypoint]) === null || _j === void 0 ? void 0 : _j[field]);
             }
             if (runHandler) {
                 log.trace(logMessage);
                 handler({ journeyContext: this, previousContext });
             }
         }
+        /* eslint-enable security/detect-object-injection */
         return this;
     }
     /* ----------------------------------------------- session context handling */
@@ -425,6 +463,8 @@ class JourneyContext {
      */
     static getContextById(session, id) {
         if (has(session === null || session === void 0 ? void 0 : session.journeyContextList, id)) {
+            // ESLint disabled as `id` has been verified as an "own" property
+            /* eslint-disable-next-line security/detect-object-injection */
             return JourneyContext.fromObject(session.journeyContextList[id]);
         }
         return undefined;
@@ -518,7 +558,8 @@ class JourneyContext {
     }
     static removeContextById(session, id) {
         if (session && has(session.journeyContextList, id)) {
-            /* eslint-disable-next-line no-param-reassign */
+            // ESLint disabled as `id` has been verified as an "own" property
+            /* eslint-disable-next-line security/detect-object-injection, no-param-reassign */
             delete session.journeyContextList[id];
         }
     }

package/dist/lib/MutableRouter.js

@@ -48,6 +48,9 @@ class MutableRouter {
             return __classPrivateFieldGet(this, _MutableRouter_router, "f");
         }
         __classPrivateFieldGet(this, _MutableRouter_stack, "f").forEach(({ method, args }) => {
+            // ESLint disabled as `#router` is dev-controlled, and `seal()` is only
+            // run at boot-time before any user interaction
+            /* eslint-disable-next-line security/detect-object-injection */
             __classPrivateFieldGet(this, _MutableRouter_router, "f")[method].call(__classPrivateFieldGet(this, _MutableRouter_router, "f"), ...args);
         });
         __classPrivateFieldSet(this, _MutableRouter_sealed, true, "f");
@@ -115,7 +118,6 @@ class MutableRouter {
         __classPrivateFieldGet(this, _MutableRouter_instances, "m", _MutableRouter_prepend).call(this, 'use', path, ...callbacks);
     }
     /* -------------------------------------------------------------- replacers */
-    // TODO: How do we handle multiple routes on the same path?
     /**
      * Replace middleware function(s) that were mounted using the `all()` method.
      *
@@ -264,12 +266,14 @@ _MutableRouter_stack = new WeakMap(), _MutableRouter_router = new WeakMap(), _Mu
     if (__classPrivateFieldGet(this, _MutableRouter_sealed, "f")) {
         throw new Error('Cannot alter middleware in a sealed mutable router');
     }
-    const index = __classPrivateFieldGet(this, _MutableRouter_stack, "f").findIndex((command) => `${command.method}|${command.path}` === `${method}|${path}`);
+    const finder = (command) => `${command.method}|${command.path}` === `${method}|${path}`;
+    const index = __classPrivateFieldGet(this, _MutableRouter_stack, "f").findIndex(finder);
     if (index > -1) {
         __classPrivateFieldGet(this, _MutableRouter_stack, "f").splice(index, 1, {
             method,
             path,
             args: [path, ...callbacks],
         });
+        __classPrivateFieldSet(this, _MutableRouter_stack, __classPrivateFieldGet(this, _MutableRouter_stack, "f").filter((command, idx) => idx <= index || !finder(command)), "f");
     }
 };

package/dist/lib/Plan.d.ts

@@ -1,12 +1,44 @@
 export default class Plan {
-    static isExitNode(name: any): boolean;
+    /**
+     * Waypoints using the url:// protocol are known as "exit nodes" as they
+     * indicate an exit point to another Plan.
+     *
+     * @param {string} name Waypoint name
+     * @returns {boolean} True if the waypoint is a url:// type
+     */
+    static isExitNode(name: string): boolean;
     /**
      * 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
      */
-    constructor(opts?: object);
+    constructor(opts?: {
+        validateBeforeRouteCondition?: boolean | undefined;
+        arbiter?: string | Function | undefined;
+    });
     getOptions(): any;
+    /**
+     * Retrieve the list of skippable waypoints.
+     *
+     * @returns {string[]} List of skippable waypoints
+     */
+    getSkippables(): string[];
+    /**
+     * Add one or more skippable waypoints.
+     *
+     * @param  {...string} waypoints Waypoints
+     * @returns {Plan}{ Chain}
+     */
+    addSkippables(...waypoints: string[]): Plan;
+    /**
+     * Check if the user can skip the named waypoint.
+     *
+     * @param {string} waypoint Waypoint
+     * @returns {boolean} True if waypoint can be skipped
+     */
+    isSkippable(waypoint: string): boolean;
     getWaypoints(): any;
     containsWaypoint(waypoint: any): any;
     getRoutes(): any;
@@ -114,8 +146,9 @@ export default class Plan {
      * Get raw graph data structure. This can be used with other libraries to
      * generate graph visualisations, for example.
      *
-     * @returns {graphlib.Graph} Graph data structure.
+     * @returns {Graph} Graph data structure.
      */
-    getGraphStructure(): any;
+    getGraphStructure(): Graph;
+    #private;
 }
 import JourneyContext from "./JourneyContext.js";

package/dist/lib/Plan.js

@@ -1,12 +1,24 @@
 "use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+var _Plan_skippableWaypoints;
 Object.defineProperty(exports, "__esModule", { value: true });
 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)('class:plan');
+const log = (0, logger_js_1.default)('lib:plan');
 /**
  * Will check if the source waypoint has specifically passed validation, i.e
  * there is a "null" validation entry for the route source.
@@ -35,6 +47,9 @@ function validateWaypointId(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 /');
+    }
 }
 function validateRouteName(val) {
     if (typeof val !== 'string') {
@@ -43,6 +58,7 @@ function validateRouteName(val) {
     else if (!['next', 'prev'].includes(val)) {
         throw new ReferenceError(`Expected route name to be one of next or prev. Got ${val}`);
     }
+    return val;
 }
 function validateRouteCondition(val) {
     if (!(val instanceof Function)) {
@@ -74,15 +90,18 @@ const makeRouteObject = (dgraph, edge) => {
 const reExitNodeProtocol = /^[a-z]+:\/\//i;
 const priv = new WeakMap();
 class Plan {
-    static isExitNode(name) {
-        return reExitNodeProtocol.test(name);
-    }
     /**
      * 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
      */
     constructor(opts = {}) {
+        /**
+         * @type {string[]} These waypoints can be skipped
+         */
+        _Plan_skippableWaypoints.set(this, void 0);
         // This is our directed, multigraph representation
         const dgraph = new graphlib_1.Graph({
             directed: true,
@@ -106,10 +125,48 @@ class Plan {
             },
             options,
         });
+        __classPrivateFieldSet(this, _Plan_skippableWaypoints, [], "f");
+    }
+    /**
+     * Waypoints using the url:// protocol are known as "exit nodes" as they
+     * indicate an exit point to another Plan.
+     *
+     * @param {string} name Waypoint name
+     * @returns {boolean} True if the waypoint is a url:// type
+     */
+    static isExitNode(name) {
+        return reExitNodeProtocol.test(name);
     }
     getOptions() {
         return priv.get(this).options;
     }
+    /**
+     * Retrieve the list of skippable waypoints.
+     *
+     * @returns {string[]} List of skippable waypoints
+     */
+    getSkippables() {
+        return __classPrivateFieldGet(this, _Plan_skippableWaypoints, "f");
+    }
+    /**
+     * Add one or more skippable waypoints.
+     *
+     * @param  {...string} waypoints Waypoints
+     * @returns {Plan}{ Chain}
+     */
+    addSkippables(...waypoints) {
+        __classPrivateFieldSet(this, _Plan_skippableWaypoints, [...__classPrivateFieldGet(this, _Plan_skippableWaypoints, "f"), ...waypoints], "f");
+        return this;
+    }
+    /**
+     * Check if the user can skip the named waypoint.
+     *
+     * @param {string} waypoint Waypoint
+     * @returns {boolean} True if waypoint can be skipped
+     */
+    isSkippable(waypoint) {
+        return __classPrivateFieldGet(this, _Plan_skippableWaypoints, "f").indexOf(waypoint) > -1;
+    }
     getWaypoints() {
         return priv.get(this).dgraph.nodes();
     }
@@ -121,7 +178,7 @@ class Plan {
         return self.dgraph.edges().map((edge) => makeRouteObject(self.dgraph, edge));
     }
     getRouteCondition(src, tgt, name) {
-        return priv.get(this).follows[name][`${src}/${tgt}`];
+        return priv.get(this).follows[validateRouteName(name)][`${src}/${tgt}`];
     }
     /**
      * Return all outward routes (out-edges) from the given waypoint, to the
@@ -149,6 +206,8 @@ class Plan {
     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) {
+            // ESLint disabled as `i` is an integer
+            /* eslint-disable-next-line security/detect-object-injection */
             this.setRoute(waypoints[i], waypoints[i + 1]);
         }
     }
@@ -222,12 +281,12 @@ class Plan {
             validateRouteCondition(follow);
         }
         // Get routing function name to label edge
-        const label = follow && follow.name;
+        const conditionName = follow && follow.name;
         // 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);
         }
-        self.dgraph.setEdge(src, tgt, { label }, name);
+        self.dgraph.setEdge(src, tgt, { conditionName }, name);
         // Determine which follow function to use
         let followFunc;
         if (follow) {
@@ -253,6 +312,8 @@ class Plan {
         else {
             followFunc = defaultPrevFollow;
         }
+        // ESLint disabled as `name` has been validated further above
+        /* eslint-disable-next-line security/detect-object-injection */
         self.follows[name][`${src}/${tgt}`] = followFunc;
         return this;
     }
@@ -304,9 +365,7 @@ class Plan {
         if (!self.dgraph.hasNode(startWaypoint)) {
             throw new ReferenceError(`Plan does not contain waypoint '${startWaypoint}'`);
         }
-        if (routeName === undefined) {
-            throw new ReferenceError('Route name must be provided');
-        }
+        validateRouteName(routeName);
         const history = new Map();
         const traverse = (startWP) => {
             let target = self.dgraph.outEdges(startWP).filter((e) => {
@@ -315,6 +374,8 @@ class Plan {
                 }
                 const route = makeRouteObject(self.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);
                 }
                 catch (ex) {
@@ -357,6 +418,8 @@ class Plan {
                     const results = new Array(totalTrav + 1);
                     results[0] = route;
                     for (let i = 0; i < totalTrav; i++) {
+                        // ESLint disabled as `i` is an integer
+                        /* eslint-disable-next-line security/detect-object-injection */
                         results[i + 1] = traversed[i];
                     }
                     return results;
@@ -376,10 +439,11 @@ class Plan {
      * Get raw graph data structure. This can be used with other libraries to
      * generate graph visualisations, for example.
      *
-     * @returns {graphlib.Graph} Graph data structure.
+     * @returns {Graph} Graph data structure.
      */
     getGraphStructure() {
         return priv.get(this).dgraph;
     }
 }
 exports.default = Plan;
+_Plan_skippableWaypoints = new WeakMap();

package/dist/lib/ValidationError.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import('./ValidatorFactory').ValidateContext} ValidateContext
+ */
 export default class ValidationError {
     /**
      * Make a ValidationError instance from a primitive object (or a function that
@@ -61,10 +64,11 @@ export default class ValidationError {
      * @param {ValidateContext} context See structure above
      * @returns {ValidationError} Chain
      */
-    withContext(context: any): ValidationError;
+    withContext(context: ValidateContext): ValidationError;
     variables: any;
-    field: any;
+    field: string | undefined;
     fieldHref: string | undefined;
     focusSuffix: any;
     validator: any;
 }
+export type ValidateContext = import('./ValidatorFactory').ValidateContext;