@dwp/govuk-casa 7.0.6 → 8.0.0-alpha1

package/dist/lib/Plan.js

@@ -0,0 +1,382 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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');
+/**
+ * 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.
+ */
+function defaultNextFollow(r, context) {
+    const { validation: v = {} } = context.toObject();
+    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.
+ *
+ * @param {object} r Route meta.
+ * @param {JourneyContext} context Journey context.
+ * @returns {boolean} Condition result.
+ */
+function defaultPrevFollow(r, context) {
+    const { validation: v = {} } = context.toObject();
+    return Object.prototype.hasOwnProperty.call(v, r.target) && v[r.target] === null;
+}
+function validateWaypointId(val) {
+    if (typeof val !== 'string') {
+        throw new TypeError(`Expected waypoint id to be a string, got ${typeof val}`);
+    }
+}
+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}`);
+    }
+}
+function validateRouteCondition(val) {
+    if (!(val instanceof Function)) {
+        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
+ * functions too as the "route" parameter.
+ *
+ * @param {object} dgraph Directed graph instance.
+ * @param {object} edge Graph edge object.
+ * @returns {object} Route.
+ */
+const makeRouteObject = (dgraph, edge) => {
+    const label = dgraph.edge(edge) || {};
+    return {
+        source: edge.v,
+        target: edge.w,
+        name: edge.name,
+        // label: {},
+        label,
+    };
+};
+/**
+ * Exit nodes begin with a protocol format, such as `url://`, `http://`, etc
+ */
+const reExitNodeProtocol = /^[a-z]+:\/\//i;
+const priv = new WeakMap();
+class Plan {
+    static isExitNode(name) {
+        return reExitNodeProtocol.test(name);
+    }
+    /**
+     * @param {object} opts
+     */
+    constructor(opts = {}) {
+        // This is our directed, multigraph representation
+        const dgraph = new graphlib_1.Graph({
+            directed: true,
+            multigraph: true,
+            compound: false,
+        });
+        // 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);
+        Object.freeze(options);
+        priv.set(this, {
+            dgraph,
+            follows: {
+                next: {},
+                prev: {},
+            },
+            options,
+        });
+    }
+    getOptions() {
+        return priv.get(this).options;
+    }
+    getWaypoints() {
+        return priv.get(this).dgraph.nodes();
+    }
+    containsWaypoint(waypoint) {
+        return this.getWaypoints().includes(waypoint);
+    }
+    getRoutes() {
+        const self = priv.get(this);
+        return self.dgraph.edges().map((edge) => makeRouteObject(self.dgraph, edge));
+    }
+    getRouteCondition(src, tgt, name) {
+        return priv.get(this).follows[name][`${src}/${tgt}`];
+    }
+    /**
+     * Return all outward routes (out-edges) from the given waypoint, to the
+     * optional target waypoint.
+     *
+     * @param {string} src Source waypoint.
+     * @param {string} tgt Target waypoint (optional).
+     * @returns {Array<object>} Route objects found.
+     */
+    getOutwardRoutes(src, tgt = null) {
+        const self = priv.get(this);
+        return self.dgraph.outEdges(src, tgt).map((e) => makeRouteObject(self.dgraph, e));
+    }
+    /**
+     * Return all outward routes (out-edges) from the given waypoint, to the
+     * optional target waypoint, matching the "prev" name.
+     *
+     * @param {string} src Source waypoint.
+     * @param {string} tgt Target waypoint (optional).
+     * @returns {Array<object>} Route objects found.
+     */
+    getPrevOutwardRoutes(src, tgt = null) {
+        return this.getOutwardRoutes(src, tgt).filter((r) => r.name === 'prev');
+    }
+    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) {
+            this.setRoute(waypoints[i], waypoints[i + 1]);
+        }
+    }
+    setNextRoute(src, tgt, follow) {
+        return this.setNamedRoute(src, tgt, 'next', follow);
+    }
+    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.
+     *
+     * However, if the condition function uses the `source`/`target`
+     * 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.
+     *
+     * If `tgt` is an egress node, do not create a `prev` route for it, because
+     * there's no way back from that point to this 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.
+     */
+    setRoute(src, tgt, followNext = undefined, followPrev = undefined) {
+        this.setNamedRoute(src, tgt, 'next', followNext);
+        if (followPrev === undefined) {
+            followPrev = followNext === undefined ? undefined : (r, c) => {
+                const invertedRoute = Object.assign(Object.assign({}, r), { source: r.target, target: r.source });
+                return followNext(invertedRoute, c);
+            };
+        }
+        this.setNamedRoute(tgt, src, 'prev', followPrev);
+        return this;
+    }
+    /**
+     * 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
+     * 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".
+     *
+     * 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 {Function} 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
+     */
+    setNamedRoute(src, tgt, name, follow) {
+        const self = priv.get(this);
+        // Validate
+        validateWaypointId(src);
+        validateWaypointId(tgt);
+        validateRouteName(name);
+        if (follow !== undefined) {
+            validateRouteCondition(follow);
+        }
+        // Get routing function name to label edge
+        const label = 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);
+        // Determine which follow function to use
+        let followFunc;
+        if (follow) {
+            if (!self.options.validateBeforeRouteCondition) {
+                followFunc = follow;
+            }
+            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];
+            }
+            else {
+                // Retain the original function name of route condition
+                followFunc = {
+                    [follow.name]: (r, c) => (defaultPrevFollow(r, c) && follow(r, c)),
+                }[follow.name];
+            }
+        }
+        else if (name === 'next') {
+            followFunc = defaultNextFollow;
+        }
+        else {
+            followFunc = defaultPrevFollow;
+        }
+        self.follows[name][`${src}/${tgt}`] = followFunc;
+        return this;
+    }
+    /**
+     * 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.
+     */
+    traverse(context, options = {}) {
+        return this.traverseNextRoutes(context, options).map((e) => e.source);
+    }
+    traverseNextRoutes(context, options = {}) {
+        return this.traverseRoutes(context, Object.assign(Object.assign({}, options), { routeName: 'next' }));
+    }
+    traversePrevRoutes(context, options = {}) {
+        return this.traverseRoutes(context, Object.assign(Object.assign({}, 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.
+     *
+     * 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 = When mutliple target routes are found, this will decide which one to choose (if any)
+     *
+     * @param {JourneyContext} context Journey context
+     * @param {object} options Options
+     * @returns {Array<object>} Routes that were traversed
+     * @throws {TypeError} When context is not a JourneyContext
+     */
+    traverseRoutes(context, options = {}) {
+        if (!(context instanceof JourneyContext_js_1.default)) {
+            throw new TypeError(`Expected context to be an instance of JourneyContext, got ${typeof context}`);
+        }
+        const self = priv.get(this);
+        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}'`);
+        }
+        if (routeName === undefined) {
+            throw new ReferenceError('Route name must be provided');
+        }
+        const history = new Map();
+        const traverse = (startWP) => {
+            let target = self.dgraph.outEdges(startWP).filter((e) => {
+                if (e.name !== routeName) {
+                    return false;
+                }
+                const route = makeRouteObject(self.dgraph, e);
+                try {
+                    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}`);
+                    return false;
+                }
+            });
+            // When there's more than one candidate route to take, we need help to choose
+            if (target.length > 1) {
+                const satisifed = target.map((t) => `${t.v} -> ${t.w}`);
+                log.debug(`Multiple routes were satisfied for "${routeName}" from "${startWP}" (${satisifed.join(' / ')}). Deciding how to resolve ...`);
+                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),
+                    });
+                    const resolved = forwardTraversal.pop();
+                    target = target.filter(t => t.w === resolved.source);
+                }
+                else if (arbiter instanceof Function) {
+                    log.debug('Using custom arbitration process');
+                    target = arbiter(target, Object.assign({ context }, options));
+                }
+                else {
+                    log.warn('Unable to arbitrate');
+                    target = [];
+                }
+            }
+            if (target.length === 1) {
+                const route = makeRouteObject(self.dgraph, target[0]);
+                const routeHash = `${route.name}/${route.source}/${route.target}`;
+                if (stopCondition(route)) {
+                    return [route];
+                }
+                if (!history.has(routeHash)) {
+                    history.set(routeHash, null);
+                    const traversed = traverse(target[0].w);
+                    const totalTrav = traversed.length;
+                    const results = new Array(totalTrav + 1);
+                    results[0] = route;
+                    for (let i = 0; i < totalTrav; i++) {
+                        results[i + 1] = traversed[i];
+                    }
+                    return results;
+                }
+                log.debug('Encountered loop (%s). Stopping traversal.', `${route.source} -> ${route.target}`);
+            }
+            return [makeRouteObject(self.dgraph, {
+                    v: startWP,
+                    w: null,
+                    name: routeName,
+                    label: {},
+                })];
+        };
+        return traverse(startWaypoint);
+    }
+    /**
+     * Get raw graph data structure. This can be used with other libraries to
+     * generate graph visualisations, for example.
+     *
+     * @returns {graphlib.Graph} Graph data structure.
+     */
+    getGraphStructure() {
+        return priv.get(this).dgraph;
+    }
+}
+exports.default = Plan;

package/dist/lib/ValidationError.d.ts

@@ -0,0 +1,70 @@
+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.
+     *
+     * 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.
+     *
+     * 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,
+     *     }
+     *   });
+     *
+     * @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
+     * @throws {TypeError} If errorMsg is not in a valid type
+     */
+    static make({ errorMsg, dataContext }: {
+        errorMsg: any;
+        dataContext: object;
+    }): 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'
+     *   }
+     * }
+     *
+     * @param {object|string} errorParam See object structure above
+     */
+    constructor(errorParam?: object | string);
+    /**
+     * Modifies the error to reflect the given context.
+     *
+     * @param {ValidateContext} context See structure above
+     * @returns {ValidationError} Chain
+     */
+    withContext(context: any): ValidationError;
+    variables: any;
+    field: any;
+    fieldHref: string | undefined;
+    focusSuffix: any;
+    validator: any;
+}

package/dist/lib/ValidationError.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const lodash_1 = __importDefault(require("lodash"));
+const { isPlainObject } = lodash_1.default; // CommonJS
+const params = new WeakMap();
+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.
+     *
+     * 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.
+     *
+     * 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,
+     *     }
+     *   });
+     *
+     * @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
+     * @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') {
+            return new ValidationError({
+                summary: errorMsg,
+                inline: errorMsg,
+                focusSuffix: [],
+            });
+        }
+        // No contextual changes applicable; return ValidationErorr made from the
+        // original object
+        if (isPlainObject(errorMsg)) {
+            return new ValidationError(errorMsg);
+        }
+        // Use the user-defined function to generate an error primitive for the
+        // given context
+        if (typeof errorMsg === 'function') {
+            return new ValidationError(errorMsg.call(null, Object.assign({}, dataContext)));
+        }
+        // Core Error
+        if (errorMsg instanceof Error) {
+            return new ValidationError({
+                summary: errorMsg.message,
+                inline: errorMsg.message,
+                focusSuffix: errorMsg.focusSuffix || [],
+            });
+        }
+        // Unsupported
+        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'
+     *   }
+     * }
+     *
+     * @param {object|string} errorParam See object structure above
+     */
+    constructor(errorParam = {}) {
+        if (!isPlainObject(errorParam) && typeof errorParam !== 'string') {
+            throw new TypeError('Constructor requires a string or object');
+        }
+        const error = typeof errorParam === 'string' ? { summary: errorParam } : errorParam;
+        // Store parameters for later use in applying contexts
+        const originals = {
+            summary: error.summary,
+            // may be deprecated; summary and inline should always match
+            inline: error.inline || error.summary,
+            focusSuffix: error.focusSuffix || [],
+            fieldKeySuffix: error.fieldKeySuffix || undefined,
+            variables: error.variables || {},
+            message: error.summary,
+            field: error.field || undefined,
+            fieldHref: error.fieldHref || undefined,
+            validator: error.validator || undefined,
+        };
+        params.set(this, originals);
+        // Duplicate parameters to make them available in public scope. These are
+        // the values that will be readable, and reflect any context that may have
+        // been applied
+        Object.keys(originals).forEach((o) => {
+            Object.defineProperty(this, o, {
+                value: originals[o],
+                enumerable: true,
+                writable: true,
+            });
+        });
+    }
+    /**
+     * Modifies the error to reflect the given context.
+     *
+     * @param {ValidateContext} context See structure above
+     * @returns {ValidationError} Chain
+     */
+    withContext(context) {
+        // Get original constructor parameters
+        const originals = params.get(this);
+        // Expand variables
+        if (typeof originals.variables === 'function') {
+            this.variables = originals.variables.call(this, context);
+        }
+        // Set field name
+        if (context.fieldName) {
+            let focusSuffix;
+            let fieldHref = `#f-${context.fieldName}`;
+            if (originals.fieldKeySuffix) {
+                fieldHref += originals.fieldKeySuffix;
+            }
+            else if (originals.focusSuffix && originals.focusSuffix.length) {
+                focusSuffix = Array.isArray(originals.focusSuffix)
+                    ? originals.focusSuffix
+                    : [originals.focusSuffix];
+                fieldHref += focusSuffix[0];
+            }
+            this.field = context.fieldName + (originals.fieldKeySuffix || '');
+            this.fieldHref = fieldHref;
+            this.focusSuffix = focusSuffix || [];
+        }
+        // Set validator name
+        this.validator = context.validator || undefined;
+        return this;
+    }
+}
+exports.default = ValidationError;

package/dist/lib/ValidatorFactory.d.ts

@@ -0,0 +1,24 @@
+export default class ValidatorFactory {
+    /**
+     * This is a convenience method that will bind and return this class'
+     * `validate()` function, so you can call it directly rather than calling the
+     * method. i.e.
+     *
+     *  MyValidator.make()('value to validate')
+     *    versus
+     *  (new MyValidator()).validate('value to validate')
+     *
+     * It also attaches the `sanitise()` method as a static property to that
+     * function.
+     *
+     * @param {object} config Validator config
+     * @returns {object} Validator object
+     * @throws {TypeError} When configurarion is invalid.
+     */
+    static make(config?: object): object;
+    static coerceToValidatorObject(input: any): any;
+    constructor(config?: {});
+    config: {};
+    validate(fieldValue: any, context: any): void;
+    sanitise(fieldValue: any): any;
+}