@dwp/govuk-casa 8.2.2 → 8.2.5

package/dist/lib/JourneyContext.js

@@ -43,14 +43,21 @@ const utils_js_1 = require("./utils.js");
 const { cloneDeep, isPlainObject, isObject, has, isEqual, } = lodash_1.default; // CommonJS
 const log = (0, logger_js_1.default)('lib:journey-context');
 /**
+ * @access private
  * @typedef {import('../casa').Page} Page
  */
 /**
+ * @access private
  * @typedef {import('../casa').ContextEventHandler} ContextEventHandler
  */
 /**
+ * @access private
  * @typedef {import('../casa').ContextEvent} ContextEvent
  */
+/**
+ * @access private
+ * @typedef {import('express').Request} ExpressRequest
+ */
 function validateObjectKey(key = '') {
     const keyLower = String.prototype.toLowerCase.call(key);
     if (keyLower === 'prototype' || keyLower === '__proto__' || keyLower === 'constructor') {
@@ -59,6 +66,9 @@ function validateObjectKey(key = '') {
     return String(key);
 }
 exports.validateObjectKey = validateObjectKey;
+/**
+ * @memberof module:@dwp/govuk-casa
+ */
 class JourneyContext {
     /**
      * Constructor.
@@ -165,6 +175,11 @@ class JourneyContext {
         }
         throw new TypeError(`Page must be a string or Page object. Got ${typeof page}`);
     }
+    /**
+     * Get all data.
+     *
+     * @returns {object} Page data
+     */
     getData() {
         return __classPrivateFieldGet(this, _JourneyContext_data, "f");
     }
@@ -181,11 +196,6 @@ 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 `Page` instance, its
-     * `fieldWriter()` method will be called to transform the provided formData
-     * before storing in `data`
-     *
      * @param {string | Page} page Page waypoint ID, or Page object
      * @param {object} webFormData Data to overwrite with
      * @returns {JourneyContext} Chain
@@ -268,6 +278,14 @@ class JourneyContext {
         var _a;
         return (_a = __classPrivateFieldGet(this, _JourneyContext_validation, "f")[validateObjectKey(pageId)]) !== null && _a !== void 0 ? _a : [];
     }
+    /**
+     * Same as `getValidationErrorsForPage()`, but the return value is
+     * an object whose keys are the field names, and values are the list of errors
+     * associated with that particular field.
+     *
+     * @param {string} pageId Page ID.
+     * @returns {object} Object indexed by field names; values containing list of errors
+     */
     getValidationErrorsForPageByField(pageId) {
         const errors = this.getValidationErrorsForPage(pageId);
         const obj = Object.create(null);
@@ -362,6 +380,14 @@ class JourneyContext {
         __classPrivateFieldSet(this, _JourneyContext_eventListenerPreState, this.toObject(), "f");
         return this;
     }
+    /**
+     * Execute all listeners for the given event.
+     *
+     * @param {object} params Params
+     * @param {string} params.event Event (waypoint-change | context-change)
+     * @param {object} params.session Session
+     * @returns {JourneyContext} Chain
+     */
     applyEventListeners({ event, session }) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         if (!__classPrivateFieldGet(this, _JourneyContext_eventListeners, "f").length) {
@@ -440,10 +466,19 @@ class JourneyContext {
      * @returns {void}
      */
     static initContextStore(session) {
+        // For existing sessions that were created prior to `journeyContextList`
+        // being remodelled as an array, we need to convert the "legacy" structure
+        // into an equivalent array.
+        if (isPlainObject(session === null || session === void 0 ? void 0 : session.journeyContextList)) {
+            log.trace('Session context list already initialised as an object (legacy structure). Will convert from object to array.');
+            /* eslint-disable-next-line no-param-reassign */
+            session.journeyContextList = Object.entries(session.journeyContextList);
+        }
+        // Initialise new context list in the session
         if (!has(session, 'journeyContextList')) {
             log.trace('Initialising session with a default journey context list');
             /* eslint-disable-next-line no-param-reassign */
-            session.journeyContextList = Object.create(null);
+            session.journeyContextList = [];
             const defaultContext = new JourneyContext();
             defaultContext.identity.id = JourneyContext.DEFAULT_CONTEXT_ID;
             JourneyContext.putContext(session, defaultContext);
@@ -471,6 +506,16 @@ class JourneyContext {
         }
         return id;
     }
+    /**
+     * Retrieve the default Journey Context. This is just a convenient wrapper
+     * around `getContextById()`.
+     *
+     * @param {object} session Request session
+     * @returns {JourneyContext} The default Journey Context
+     */
+    static getDefaultContext(session) {
+        return JourneyContext.getContextById(session, JourneyContext.DEFAULT_CONTEXT_ID);
+    }
     /**
      * Lookup context from session using the ID.
      *
@@ -479,10 +524,11 @@ class JourneyContext {
      * @returns {JourneyContext} The discovered JourneyContext instance
      */
     static getContextById(session, id) {
-        if (has(session === null || session === void 0 ? void 0 : session.journeyContextList, id)) {
+        const list = new Map(session === null || session === void 0 ? void 0 : session.journeyContextList);
+        if (list.has(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 JourneyContext.fromObject(list.get(id));
         }
         return undefined;
     }
@@ -495,7 +541,8 @@ class JourneyContext {
      */
     static getContextByName(session, name) {
         if (session) {
-            const context = Object.values(session.journeyContextList).find((c) => (c.identity.name === name));
+            const list = new Map(session === null || session === void 0 ? void 0 : session.journeyContextList);
+            const context = [...list.values()].find((c) => (c.identity.name === name));
             if (context) {
                 return JourneyContext.fromObject(context);
             }
@@ -511,7 +558,8 @@ class JourneyContext {
      */
     static getContextsByTag(session, tag) {
         if (session) {
-            return Object.values(session.journeyContextList).filter((c) => { var _a; return ((_a = c.identity.tags) === null || _a === void 0 ? void 0 : _a.includes(tag)); }).map((c) => (JourneyContext.fromObject(c)));
+            const list = new Map(session === null || session === void 0 ? void 0 : session.journeyContextList);
+            return [...list.values()].filter((c) => { var _a; return ((_a = c.identity.tags) === null || _a === void 0 ? void 0 : _a.includes(tag)); }).map((c) => (JourneyContext.fromObject(c)));
         }
         return undefined;
     }
@@ -523,7 +571,7 @@ class JourneyContext {
      */
     static getContexts(session) {
         if (has(session, 'journeyContextList')) {
-            return Object.values(session.journeyContextList).map((contextObj) => (JourneyContext.fromObject(contextObj)));
+            return session.journeyContextList.map(([, contextObj]) => (JourneyContext.fromObject(contextObj)));
         }
         return [];
     }
@@ -558,8 +606,10 @@ class JourneyContext {
             event: 'context-change',
             session,
         });
+        const list = new Map(session.journeyContextList);
+        list.set(context.identity.id, context.toObject());
         /* eslint-disable-next-line no-param-reassign */
-        session.journeyContextList[context.identity.id] = context.toObject();
+        session.journeyContextList = [...list.entries()];
     }
     /**
      * Remove a context from the session store.
@@ -573,22 +623,59 @@ class JourneyContext {
             JourneyContext.removeContextById(session, context.identity.id);
         }
     }
+    /**
+     * Remove context from session using the ID.
+     *
+     * @param {object} session Request session
+     * @param {string} id Context ID
+     * @returns {void}
+     */
     static removeContextById(session, id) {
-        if (session && has(session.journeyContextList, id)) {
-            // 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];
+        var _a;
+        const index = ((_a = session === null || session === void 0 ? void 0 : session.journeyContextList) !== null && _a !== void 0 ? _a : []).findIndex(([contextId]) => contextId === id);
+        if (index > -1) {
+            session.journeyContextList.splice(index, 1);
         }
     }
+    /**
+     * Remove context from session using the name.
+     *
+     * @param {object} session Request session
+     * @param {string} name Context name
+     * @returns {void}
+     */
     static removeContextByName(session, name) {
         JourneyContext.removeContext(session, JourneyContext.getContextByName(session, name));
     }
+    /**
+     * Remove context from session using the tag.
+     *
+     * @param {object} session Request session
+     * @param {string} tag Context tag
+     * @returns {void}
+     */
     static removeContextsByTag(session, tag) {
         JourneyContext.getContextsByTag(session, tag).forEach((c) => JourneyContext.removeContext(session, c));
     }
+    /**
+     * Remove call contexts.
+     *
+     * @param {object} session Request session
+     * @returns {void}
+     */
     static removeContexts(session) {
         JourneyContext.getContexts(session).forEach((c) => JourneyContext.removeContext(session, c));
     }
+    /**
+     * Extract the Journey Context referred to in the incoming request.
+     *
+     * This will look in `req.params`, `req.query` and
+     * `req.body` for a `contextid` parameter, and use that
+     * to load the correct Journey Context from the session.
+     *
+     * @param {ExpressRequest} req ExpressJS incoming request
+     * @returns {JourneyContext} The Journey Context
+     */
     static extractContextFromRequest(req) {
         JourneyContext.initContextStore(req.session);
         let contextId;

package/dist/lib/Plan.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @memberof module:@dwp/govuk-casa
+ */
 export default class Plan {
     /**
      * Waypoints using the url:// protocol are known as "exit nodes" as they
@@ -10,15 +13,15 @@ export default 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?: {
-        validateBeforeRouteCondition?: boolean | undefined;
-        arbiter?: string | Function | undefined;
-    });
-    getOptions(): any;
+    constructor(opts?: PlanConstructorOptions);
+    /**
+     * Retrieve the options set on this Plan.
+     *
+     * @returns {PlanConstructorOptions} Options map
+     */
+    getOptions(): PlanConstructorOptions;
     /**
      * Retrieve the list of skippable waypoints.
      *
@@ -29,7 +32,7 @@ export default class Plan {
      * Add one or more skippable waypoints.
      *
      * @param  {...string} waypoints Waypoints
-     * @returns {Plan}{ Chain}
+     * @returns {Plan} Chain
      */
     addSkippables(...waypoints: string[]): Plan;
     /**
@@ -39,40 +42,87 @@ export default class Plan {
      * @returns {boolean} True if waypoint can be skipped
      */
     isSkippable(waypoint: string): boolean;
-    getWaypoints(): any;
-    containsWaypoint(waypoint: any): any;
-    getRoutes(): any;
-    getRouteCondition(src: any, tgt: any, name: any): any;
+    /**
+     * Retrieve all waypoints in this Plan (order is arbitrary).
+     *
+     * @returns {string[]} List of waypoints
+     */
+    getWaypoints(): string[];
+    /**
+     * Determine if the given waypoint exists in this Plan.
+     *
+     * @param {string} waypoint Waypoint to search for
+     * @returns {boolean} Result
+     */
+    containsWaypoint(waypoint: string): boolean;
+    /**
+     * Get all route information.
+     *
+     * @returns {PlanRoute[]} Routes
+     */
+    getRoutes(): PlanRoute[];
+    /**
+     * 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: string, tgt: string, name: string): PlanRouteCondition;
     /**
      * 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.
+     * @param {string} [tgt] Target waypoint.
+     * @returns {PlanRoute[]} Route objects found.
      */
-    getOutwardRoutes(src: string, tgt?: string): Array<object>;
+    getOutwardRoutes(src: string, tgt?: string | undefined): PlanRoute[];
     /**
      * 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.
+     * @param {string} [tgt] Target waypoint.
+     * @returns {PlanRoute[]} Route objects found.
      */
-    getPrevOutwardRoutes(src: string, tgt?: string): Array<object>;
-    addSequence(...waypoints: any[]): void;
-    setNextRoute(src: any, tgt: any, follow: any): Plan;
-    setPrevRoute(src: any, tgt: any, follow: any): Plan;
+    getPrevOutwardRoutes(src: string, tgt?: string | undefined): PlanRoute[];
+    /**
+     * 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: string[]): void;
+    /**
+     * 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: string, tgt: string, follow: PlanRouteCondition): Plan;
+    /**
+     * 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: string, tgt: string, follow: PlanRouteCondition): Plan;
     /**
      * 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.
@@ -82,11 +132,11 @@ export default 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: string, tgt: string, followNext?: Function, followPrev?: Function): Plan;
+    setRoute(src: string, tgt: string, followNext?: import("../casa").PlanRouteCondition | undefined, followPrev?: import("../casa").PlanRouteCondition | undefined): Plan;
     /**
      * Create a named route between two waypoints, and give that route a function
      * that determine whether it should be followed during traversal operations.
@@ -103,22 +153,38 @@ export default 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
      */
-    setNamedRoute(src: string, tgt: string, name: string, follow: Function): Plan;
+    setNamedRoute(src: string, tgt: string, name: string, follow: PlanRouteCondition): 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: JourneyContext, options?: object): Array<string>;
-    traverseNextRoutes(context: any, options?: {}): object[];
-    traversePrevRoutes(context: any, options?: {}): object[];
+    traverse(context: JourneyContext, options?: PlanTraverseOptions): string[];
+    /**
+     * 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: JourneyContext, options?: PlanTraverseOptions): PlanRoute[];
+    /**
+     * 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: JourneyContext, options?: PlanTraverseOptions): PlanRoute[];
     /**
      * Traverse through the plan from a particular starting waypoint. This is a
      * non-exhaustive Graph Exploration.
@@ -129,19 +195,12 @@ export default 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: JourneyContext, options?: object): Array<object>;
+    traverseRoutes(context: JourneyContext, options?: PlanTraverseOptions): PlanRoute[];
     /**
      * Get raw graph data structure. This can be used with other libraries to
      * generate graph visualisations, for example.
@@ -151,4 +210,18 @@ export default class Plan {
     getGraphStructure(): Graph;
     #private;
 }
+export type PlanRoute = import('../casa').PlanRoute;
+export type PlanRouteCondition = import('../casa').PlanRouteCondition;
+export type PlanTraverseOptions = import('../casa').PlanTraverseOptions;
+export type PlanArbiter = import('../casa').PlanArbiter;
+export type PlanConstructorOptions = {
+    /**
+     * Check page validity before conditions
+     */
+    validateBeforeRouteCondition?: boolean | undefined;
+    /**
+     * Arbitration mechanism
+     */
+    arbiter?: string | import("../casa").PlanArbiter | undefined;
+};
 import JourneyContext from "./JourneyContext.js";