@dwp/govuk-casa 8.2.3 → 8.2.4

package/README.md

@@ -20,6 +20,7 @@ npm -E @dwp/govuk-casa
 ```
 
 * [Documentation](docs/index.md)
+* [API Reference](docs/api-reference.md)
 * [Examples](examples/)
 
 

package/dist/casa.d.ts

@@ -212,6 +212,204 @@ export type ConfigureResult = {
      */
     mount: Mounter;
 };
+/**
+ * Configuration for generating a ValidationError.
+ * i.e. `new ValidationError(configObject)`
+ * <br/><br/>
+ *
+ * The `fieldKeySuffix` is used to differentiate errors attached to
+ * the same field name. For example, given these fields inputs ...
+ *
+ * <pre>
+ * &lt;input name="dateOfBirth[dd]" /&gt;
+ * &lt;input name="dateOfBirth[mm]" /&gt;
+ * &lt;input name="dateOfBirth[yyyy]" /&gt;
+ * </pre>
+ *
+ * If we wanted to generate an error specifically for the `dd`
+ * element, then we'd include `{ fieldKeySuffix: '[dd]' }` in this
+ * config.
+ * <br/><br/>
+ *
+ * We can also use `focusSuffix` to control which properties of an
+ * object field should be highlighted with a red border when in error. Looking
+ * again at the `dateOfBirth` example above, if we did not specify
+ * any `focusSuffix`, then all three inputs would be highlighted.
+ * However, if we use `{ focusSuffix: ['[dd]', '[yyyy]'] }` then only
+ * the `[dd]` and `[yyyy]` inputs would be highlighted.
+ * <br/><br/>
+ *
+ * The `fieldHref` and `field` properties are strictly for
+ * internal use only and public access may be removed at any point.
+ */
+export type ErrorMessageConfigObject = {
+    /**
+     * Summary message
+     */
+    summary: string;
+    /**
+     * Inline message (@deprecated now uses summary everywhere)
+     */
+    inline?: string | undefined;
+    /**
+     * String(s) to append to URL hash for focusing inputs
+     */
+    focusSuffix?: string | string[] | undefined;
+    /**
+     * Object fields may use this to show errors per sub-property
+     */
+    fieldKeySuffix?: string | undefined;
+    /**
+     * Interpolation variables
+     */
+    variables?: object | ErrorMessageVariablesGenerator | undefined;
+    /**
+     * Name of the validator
+     */
+    validator?: string | undefined;
+    /**
+     * (internal) URL hash to link to field in UI, i.e `#f-..`
+     */
+    fieldHref?: string | undefined;
+    /**
+     * (internal) Field name, including any focus suffix
+     */
+    field?: string | undefined;
+};
+/**
+ * Function to generate interpolation variables for injecting into the error
+ * message string.
+ */
+export type ErrorMessageVariablesGenerator = (dataContext: ValidateContext) => object;
+export type ErrorMessageConfigGenerator = (dataContext: ValidateContext) => string | ErrorMessageConfigObject;
+export type ErrorMessageConfig = string | ErrorMessageConfigObject | ErrorMessageConfigGenerator | Error;
+/**
+ * Context passed to validate function
+ */
+export type ValidateContext = {
+    /**
+     * Journey context
+     */
+    journeyContext: JourneyContext;
+    /**
+     * Waypoint
+     */
+    waypoint: string;
+    /**
+     * Name of field being processed
+     */
+    fieldName: string;
+    /**
+     * Current value of the field being validated
+     */
+    fieldValue?: any;
+    /**
+     * Name of the validator
+     */
+    validator?: string | undefined;
+};
+export type ValidateFunction = (value: any, context: ValidateContext) => ValidationError[];
+export type FieldProcessorFunction = (value: any) => any;
+export type Validator = {
+    /**
+     * Validation function
+     */
+    validate: ValidateFunction;
+    /**
+     * Sanitise a given value prior to validation
+     */
+    sanitise: FieldProcessorFunction;
+    /**
+     * Configuration
+     */
+    config: object;
+    /**
+     * Validator name
+     */
+    name: string;
+};
+export type ValidatorConditionFunctionParams = {
+    /**
+     * Field name
+     */
+    fieldName: string;
+    /**
+     * Field value
+     */
+    fieldValue: any;
+    /**
+     * Waypoint
+     */
+    waypoint: string;
+    /**
+     * [DEPRECATED] Waypoint (for backwards compatibility with v7)
+     */
+    waypointId: string;
+    /**
+     * Journey Context
+     */
+    journeyContext: JourneyContext;
+};
+/**
+ * Condition functions are executed unbound.
+ */
+export type ValidatorConditionFunction = (context: ValidatorConditionFunctionParams) => boolean;
+export type PlanRoute = {
+    /**
+     * Source waypoint
+     */
+    source: string;
+    /**
+     * Target waypoint
+     */
+    target: string;
+    /**
+     * Name
+     */
+    name: string;
+    /**
+     * Label
+     */
+    label: string;
+};
+export type PlanRouteCondition = (route: PlanRoute, context: JourneyContext) => boolean;
+export type PlanTraverseOptions = {
+    /**
+     * Waypoint from which to start (defaults to first in list)
+     */
+    startWaypoint?: string | undefined;
+    /**
+     * Follow routes matching this name (next | prev)
+     */
+    routeName: string;
+    /**
+     * Used to detect loops in traversal (INTERNAL USE ONLY)
+     */
+    history: Map<any, any>;
+    /**
+     * If true, traversal will be stopped (useful for performance)
+     */
+    stopCondition?: Function | undefined;
+    /**
+     * Mutliple target routes found, this decides which to use
+     */
+    arbiter?: string | PlanArbiter | undefined;
+};
+export type PlanArbiterParams = {
+    /**
+     * Potential target routes that need arbitration
+     */
+    targets: PlanRoute[];
+    /**
+     * Journey Context
+     */
+    journeyContext: JourneyContext;
+    /**
+     * Original traverse options passed to `traverse()`
+     */
+    traverseOptions: PlanTraverseOptions;
+};
+export type PlanArbiter = (route: PlanArbiterParams) => PlanRoute[];
 import configure from "./lib/configure.js";
 import validators from "./lib/validators/index.js";
 import field from "./lib/field.js";

package/dist/casa.js

@@ -150,3 +150,132 @@ exports.nunjucksFilters = nunjucksFilters;
  * @property {import('express').RequestHandler} bodyParserMiddleware Body parsing middleware
  * @property {Mounter} mount Function used to mount all CASA artifacts onto an ExpressJS app
  */
+/**
+ * Configuration for generating a ValidationError.
+ * i.e. `new ValidationError(configObject)`
+ * <br/><br/>
+ *
+ * The `fieldKeySuffix` is used to differentiate errors attached to
+ * the same field name. For example, given these fields inputs ...
+ *
+ * <pre>
+ * &lt;input name="dateOfBirth[dd]" /&gt;
+ * &lt;input name="dateOfBirth[mm]" /&gt;
+ * &lt;input name="dateOfBirth[yyyy]" /&gt;
+ * </pre>
+ *
+ * If we wanted to generate an error specifically for the `dd`
+ * element, then we'd include `{ fieldKeySuffix: '[dd]' }` in this
+ * config.
+ * <br/><br/>
+ *
+ * We can also use `focusSuffix` to control which properties of an
+ * object field should be highlighted with a red border when in error. Looking
+ * again at the `dateOfBirth` example above, if we did not specify
+ * any `focusSuffix`, then all three inputs would be highlighted.
+ * However, if we use `{ focusSuffix: ['[dd]', '[yyyy]'] }` then only
+ * the `[dd]` and `[yyyy]` inputs would be highlighted.
+ * <br/><br/>
+ *
+ * The `fieldHref` and `field` properties are strictly for
+ * internal use only and public access may be removed at any point.
+ *
+ * @typedef {object} ErrorMessageConfigObject
+ * @property {string} summary Summary message
+ * @property {string} [inline] Inline message (@deprecated now uses summary everywhere)
+ * @property {string|string[]} [focusSuffix] String(s) to append to URL hash for focusing inputs
+ * @property {string} [fieldKeySuffix] Object fields may use this to show errors per sub-property
+ * @property {object|ErrorMessageVariablesGenerator} [variables] Interpolation variables
+ * @property {string} [validator] Name of the validator
+ * @property {string} [fieldHref] (internal) URL hash to link to field in UI, i.e `#f-..`
+ * @property {string} [field] (internal) Field name, including any focus suffix
+ */
+/**
+ * Function to generate interpolation variables for injecting into the error
+ * message string.
+ *
+ * @callback ErrorMessageVariablesGenerator
+ * @param {ValidateContext} dataContext Data context
+ * @returns {object} Variables name:value hash
+ */
+/**
+ * @callback ErrorMessageConfigGenerator
+ * @param {ValidateContext} dataContext Data context
+ * @returns {string|ErrorMessageConfigObject} Compiled error mesasge config
+ */
+/**
+ * @typedef {string|ErrorMessageConfigObject|ErrorMessageConfigGenerator|Error} ErrorMessageConfig
+ */
+/**
+ * @typedef {object} ValidateContext Context passed to validate function
+ * @property {JourneyContext} journeyContext Journey context
+ * @property {string} waypoint Waypoint
+ * @property {string} fieldName Name of field being processed
+ * @property {any} [fieldValue] Current value of the field being validated
+ * @property {string} [validator] Name of the validator
+ */
+/**
+ * @callback ValidateFunction
+ * @param {any} value
+ * @param {ValidateContext} context Vaildation context
+ * @returns {ValidationError[]}
+ */
+/**
+ * @callback FieldProcessorFunction
+ * @param {any} value Value to be processed
+ * @returns {any}
+ */
+/**
+ * @typedef {object} Validator
+ * @property {ValidateFunction} validate Validation function
+ * @property {FieldProcessorFunction} sanitise Sanitise a given value prior to validation
+ * @property {object} config Configuration
+ * @property {string} name Validator name
+ */
+/**
+ * @typedef {object} ValidatorConditionFunctionParams
+ * @property {string} fieldName Field name
+ * @property {any} fieldValue Field value
+ * @property {string} waypoint Waypoint
+ * @property {string} waypointId [DEPRECATED] Waypoint (for backwards compatibility with v7)
+ * @property {JourneyContext} journeyContext Journey Context
+ */
+/**
+ * Condition functions are executed unbound.
+ *
+ * @callback ValidatorConditionFunction
+ * @param {ValidatorConditionFunctionParams} context Value to be processed
+ * @returns {boolean} True if the validators should be run
+ */
+/**
+ * @typedef {object} PlanRoute
+ * @property {string} source Source waypoint
+ * @property {string} target Target waypoint
+ * @property {string} name Name
+ * @property {string} label Label
+ */
+/**
+ * @callback PlanRouteCondition
+ * @param {PlanRoute} route Route metadata
+ * @param {JourneyContext} context Journey Context
+ * @returns {boolean} Returns true is route should be followed
+ */
+/**
+ * @typedef PlanTraverseOptions
+ * @property {string} [startWaypoint] Waypoint from which to start (defaults to first in list)
+ * @property {string} routeName Follow routes matching this name (next | prev)
+ * @property {Map} history Used to detect loops in traversal (INTERNAL USE ONLY)
+ * @property {Function} [stopCondition] If true, traversal will be stopped (useful for performance)
+ * @property {string|PlanArbiter} [arbiter] Mutliple target routes found, this decides which to use
+ */
+/**
+ * @typedef {object} PlanArbiterParams
+ * @property {PlanRoute[]} targets Potential target routes that need arbitration
+ * @property {JourneyContext} journeyContext Journey Context
+ * @property {PlanTraverseOptions} traverseOptions Original traverse options passed to `traverse()`
+ */
+/**
+ * @callback PlanArbiter
+ * @param {PlanArbiterParams} route Route metadata
+ * @returns {PlanRoute[]} Returns all routes, excluding those that the arbiter could eliminate
+ */

package/dist/lib/CasaTemplateLoader.d.ts

@@ -3,6 +3,10 @@
  * @param {string} templateName Path to the template being modified
  * @returns {string} The modified template source
  */
+/**
+ * @access private
+ * @augments FileSystemLoader
+ */
 export default class CasaTemplateLoader extends FileSystemLoader {
     /**
      * Constructor.

package/dist/lib/CasaTemplateLoader.js

@@ -14,6 +14,7 @@ var _CasaTemplateLoader_instances, _CasaTemplateLoader_blockModifiers, _CasaTemp
 Object.defineProperty(exports, "__esModule", { value: true });
 const nunjucks_1 = require("nunjucks");
 /**
+ * @access private
  * @typedef {import('nunjucks').FileSystemLoaderOptions} FileSystemLoaderOptions
  */
 const VALID_BLOCKS = [
@@ -36,6 +37,10 @@ const VALID_BLOCKS = [
  * @param {string} templateName Path to the template being modified
  * @returns {string} The modified template source
  */
+/**
+ * @access private
+ * @augments FileSystemLoader
+ */
 class CasaTemplateLoader extends nunjucks_1.FileSystemLoader {
     /**
      * Constructor.

package/dist/lib/JourneyContext.d.ts

@@ -1,13 +1,23 @@
 /**
+ * @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
+ */
 export function validateObjectKey(key?: string): string;
+/**
+ * @memberof module:@dwp/govuk-casa
+ */
 export default class JourneyContext {
     static DEFAULT_CONTEXT_ID: string;
     /**
@@ -58,6 +68,14 @@ export default class JourneyContext {
      * @throws {SyntaxError} When id is not a valid uuid format
      */
     static validateContextId(id: string): string;
+    /**
+     * 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: object): JourneyContext;
     /**
      * Lookup context from session using the ID.
      *
@@ -106,11 +124,48 @@ export default class JourneyContext {
      * @returns {void}
      */
     static removeContext(session: object, context: JourneyContext): void;
-    static removeContextById(session: any, id: any): void;
-    static removeContextByName(session: any, name: any): void;
-    static removeContextsByTag(session: any, tag: any): void;
-    static removeContexts(session: any): void;
-    static extractContextFromRequest(req: any): JourneyContext;
+    /**
+     * Remove context from session using the ID.
+     *
+     * @param {object} session Request session
+     * @param {string} id Context ID
+     * @returns {void}
+     */
+    static removeContextById(session: object, id: string): void;
+    /**
+     * Remove context from session using the name.
+     *
+     * @param {object} session Request session
+     * @param {string} name Context name
+     * @returns {void}
+     */
+    static removeContextByName(session: object, name: string): void;
+    /**
+     * Remove context from session using the tag.
+     *
+     * @param {object} session Request session
+     * @param {string} tag Context tag
+     * @returns {void}
+     */
+    static removeContextsByTag(session: object, tag: string): void;
+    /**
+     * Remove call contexts.
+     *
+     * @param {object} session Request session
+     * @returns {void}
+     */
+    static removeContexts(session: object): void;
+    /**
+     * 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: ExpressRequest): JourneyContext;
     /**
      * Constructor.
      *
@@ -154,6 +209,11 @@ export default class JourneyContext {
      * @throws {TypeError} When page is invalid.
      */
     getDataForPage(page: string | Page): object;
+    /**
+     * Get all data.
+     *
+     * @returns {object} Page data
+     */
     getData(): object;
     /**
      * Overwrite the data context with a new object.
@@ -165,11 +225,6 @@ 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 `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
@@ -218,7 +273,15 @@ export default class JourneyContext {
      * @returns {ValidationError[]} An array of errors
      */
     getValidationErrorsForPage(pageId: string): ValidationError[];
-    getValidationErrorsForPageByField(pageId: any): any;
+    /**
+     * 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: string): object;
     /**
      * Determine whether the specified page has any errors in its validation
      * context.
@@ -268,9 +331,17 @@ export default class JourneyContext {
      * @returns {JourneyContext} Chain
      */
     addEventListeners(events: ContextEvent[]): JourneyContext;
+    /**
+     * 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 }: {
-        event: any;
-        session: any;
+        event: string;
+        session: object;
     }): JourneyContext;
     /**
      * Convenience method to determine if this is the default context.
@@ -283,4 +354,5 @@ export default class JourneyContext {
 export type Page = import('../casa').Page;
 export type ContextEventHandler = import('../casa').ContextEventHandler;
 export type ContextEvent = import('../casa').ContextEvent;
+export type ExpressRequest = import('express').Request;
 import ValidationError from "./ValidationError.js";

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;