@dwp/govuk-casa 8.2.1 → 8.2.4

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) {
@@ -471,6 +497,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.
      *
@@ -573,6 +609,13 @@ 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
@@ -580,15 +623,45 @@ class JourneyContext {
             delete session.journeyContextList[id];
         }
     }
+    /**
+     * 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";