@dwp/govuk-casa 8.2.2 → 8.2.5

package/dist/lib/ValidatorFactory.d.ts

@@ -1,83 +1,73 @@
 /**
- * @typedef {import('./index').ProcessorFunction} ProcessorFunction
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfig} ErrorMessageConfig
  */
 /**
+ * @access private
  * @typedef {import('./index').JourneyContext} JourneyContext
  */
 /**
+ * @access private
  * @typedef {import('./index').ValidationError} ValidationError
  */
 /**
- * @typedef {object} Validator
- * @property {ValidateFunction} validate Validation function
- * @property {ProcessorFunction} sanitise Sanitise a given value prior to validation
- * @property {object} config Configuration
- * @property {string} name Validator name
+ * @access private
+ * @typedef {import('../casa').ValidateContext} ValidateContext
  */
 /**
- * @callback ValidateFunction
- * @param {any} value
- * @param {ValidateContext} context
- * @returns {ValidationError[]}
+ * @access private
+ * @typedef {import('../casa').Validator} Validator
  */
 /**
- * @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
+ * @typedef {object} ValidatorFactoryOptions
+ * @property {ErrorMessageConfig} errorMsg Error message
+ */
+/**
+ * @class
+ * @memberof module:@dwp/govuk-casa
  */
 export default class ValidatorFactory {
     /**
      * This is a convenience method that will return a consistently object
      * structure containing validation and sanitisation methods.
      *
-     * @param {object} config Validator config (custom to the validator being created)
+     * @param {ValidatorFactoryOptions} config Validator config (custom to each validator)
      * @returns {Validator} Validator object
      * @throws {TypeError} When configurarion is invalid.
      */
-    static make(config?: object): Validator;
-    static coerceToValidatorObject(input: any): any;
-    constructor(config?: {});
-    config: {};
-    validate(fieldValue: any, context: any): void;
-    sanitise(fieldValue: any): any;
-}
-export type ProcessorFunction = import('./index').ProcessorFunction;
-export type JourneyContext = import('./index').JourneyContext;
-export type ValidationError = import('./index').ValidationError;
-export type Validator = {
-    /**
-     * Validation function
-     */
-    validate: ValidateFunction;
-    /**
-     * Sanitise a given value prior to validation
-     */
-    sanitise: any;
-    /**
-     * Configuration
-     */
-    config: object;
+    static make(config?: ValidatorFactoryOptions): Validator;
     /**
-     * Validator name
+     * NEVER CALL THIS DIRECTLY. USE `make()`.
+     *
+     * @param {ValidatorFactoryOptions} config Validator config (custom to each validator)
      */
-    name: string;
-};
-export type ValidateFunction = (value: any, context: ValidateContext) => ValidationError[];
-/**
- * Context passed to validate function
- */
-export type ValidateContext = {
+    constructor(config?: ValidatorFactoryOptions);
+    config: ValidatorFactoryOptions;
     /**
-     * Journey context
+     * Validate the given value.
+     *
+     * @param {any} fieldValue Value to validate
+     * @param {ValidateContext} context Contextual information
+     * @returns {ValidationError[]} A list of errors (empty if no errors found)
+     * @throws {Error}
      */
-    journeyContext: JourneyContext;
+    validate(fieldValue: any, context: ValidateContext): ValidationError[];
     /**
-     * Waypoint
+     * Sanitise the given value.
+     *
+     * @param {any} fieldValue Value to validate
+     * @returns {any} The sanitised value
      */
-    waypoint: string;
+    sanitise(fieldValue: any): any;
+}
+export type ErrorMessageConfig = import('../casa').ErrorMessageConfig;
+export type JourneyContext = import('./index').JourneyContext;
+export type ValidationError = import('./index').ValidationError;
+export type ValidateContext = import('../casa').ValidateContext;
+export type Validator = import('../casa').Validator;
+export type ValidatorFactoryOptions = {
     /**
-     * Name of field being processed
+     * Error message
      */
-    fieldName: string;
+    errorMsg: ErrorMessageConfig;
 };

package/dist/lib/ValidatorFactory.js

@@ -7,39 +7,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const lodash_1 = __importDefault(require("lodash"));
 const { isPlainObject } = lodash_1.default; // CommonJS
 /**
- * @typedef {import('./index').ProcessorFunction} ProcessorFunction
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfig} ErrorMessageConfig
  */
 /**
+ * @access private
  * @typedef {import('./index').JourneyContext} JourneyContext
  */
 /**
+ * @access private
  * @typedef {import('./index').ValidationError} ValidationError
  */
 /**
- * @typedef {object} Validator
- * @property {ValidateFunction} validate Validation function
- * @property {ProcessorFunction} sanitise Sanitise a given value prior to validation
- * @property {object} config Configuration
- * @property {string} name Validator name
+ * @access private
+ * @typedef {import('../casa').ValidateContext} ValidateContext
  */
 /**
- * @callback ValidateFunction
- * @param {any} value
- * @param {ValidateContext} context
- * @returns {ValidationError[]}
+ * @access private
+ * @typedef {import('../casa').Validator} Validator
  */
 /**
- * @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
+ * @typedef {object} ValidatorFactoryOptions
+ * @property {ErrorMessageConfig} errorMsg Error message
+ */
+/**
+ * @class
+ * @memberof module:@dwp/govuk-casa
  */
 class ValidatorFactory {
     /**
      * This is a convenience method that will return a consistently object
      * structure containing validation and sanitisation methods.
      *
-     * @param {object} config Validator config (custom to the validator being created)
+     * @param {ValidatorFactoryOptions} config Validator config (custom to each validator)
      * @returns {Validator} Validator object
      * @throws {TypeError} When configurarion is invalid.
      */
@@ -57,48 +57,37 @@ class ValidatorFactory {
         Object.freeze(instance);
         return instance;
     }
-    static coerceToValidatorObject(input) {
-        let validator = Object.create(null);
-        validator.validate = () => (Promise.reject(new Error('validate() method has not been defined')));
-        validator.sanitise = (val) => (val);
-        validator.config = Object.create(null);
-        // An uninstantied Validator subclass
-        if (typeof input === 'function' && Reflect.getPrototypeOf(input) === ValidatorFactory) {
-            validator = input.make();
-        }
-        else if (typeof input === 'function') {
-            // A plain function is assumed to be just the validation logic. We do not
-            // bind the function to `validator` here because it may already be bound to
-            // another context in userland.
-            validator.name = input.name || input.constructor.name || 'unknown';
-            validator.validate = input;
-        }
-        else if (isPlainObject(input)) {
-            // A plain object
-            validator = {
-                validate: input.validate || validator.validate,
-                sanitise: input.sanitise || validator.sanitise,
-                config: input.config || validator.config,
-                name: input.name || validator.name,
-            };
-        }
-        else {
-            // An unsupported scenario
-            throw new TypeError(`Cannot coerce input to a validator object (typeof = ${typeof input})`);
-        }
-        return validator;
-    }
+    /**
+     * NEVER CALL THIS DIRECTLY. USE `make()`.
+     *
+     * @param {ValidatorFactoryOptions} config Validator config (custom to each validator)
+     */
     constructor(config = {}) {
         if (new.target === ValidatorFactory) {
             throw new TypeError('Cannot instantiate the abstract class, ValidatorFactory');
         }
         this.config = config;
     }
-    /* eslint-disable-next-line no-unused-vars */
+    /* eslint-disable no-unused-vars */
+    /* eslint-disable-next-line jsdoc/require-returns-check */
+    /**
+     * Validate the given value.
+     *
+     * @param {any} fieldValue Value to validate
+     * @param {ValidateContext} context Contextual information
+     * @returns {ValidationError[]} A list of errors (empty if no errors found)
+     * @throws {Error}
+     */
     validate(fieldValue, context) {
         throw new Error('validate() method has not been implemented');
     }
-    /* eslint-disable-next-line no-unused-vars */
+    /* eslint-disable-next-line jsdoc/require-returns-check */
+    /**
+     * Sanitise the given value.
+     *
+     * @param {any} fieldValue Value to validate
+     * @returns {any} The sanitised value
+     */
     sanitise(fieldValue) {
         return fieldValue;
     }

package/dist/lib/configuration-ingestor.d.ts

@@ -1,6 +1,7 @@
 /**
  * Validates and sanitises i18n obejct.
  *
+ * @access private
  * @param {object} i18n Object to validate.
  * @param {Function} cb Callback function that receives the validated value.
  * @throws {TypeError} For invalid object.
@@ -10,6 +11,7 @@ export function validateI18nObject(i18n?: object, cb?: Function): object;
 /**
  * Validates and sanitises i18n directory.
  *
+ * @access private
  * @param {Array} dirs Array of directories.
  * @throws {SyntaxError} For invalid directories.
  * @throws {TypeError} For invalid type.
@@ -19,6 +21,7 @@ export function validateI18nDirs(dirs?: any[]): any[];
 /**
  * Validates and sanitises i18n locales.
  *
+ * @access private
  * @param {Array} locales Array of locales.
  * @throws {SyntaxError} For invalid locales.
  * @throws {TypeError} For invalid type.
@@ -28,6 +31,7 @@ export function validateI18nLocales(locales?: any[]): any[];
 /**
  * Validates and sanitises mount url.
  *
+ * @access private
  * @param {string} mountUrl Prefix for all URLs in the browser address bar
  * @throws {SyntaxError} For invalid URL.
  * @returns {string|undefined} Sanitised URL.
@@ -36,6 +40,7 @@ export function validateMountUrl(mountUrl: string): string | undefined;
 /**
  * Validates and sanitises sessions object.
  *
+ * @access private
  * @param {object} session Object to validate.
  * @param {Function} cb Callback function that receives the validated value.
  * @throws {TypeError} For invalid object.
@@ -45,6 +50,7 @@ export function validateSessionObject(session?: object, cb?: Function): object;
 /**
  * Validates and sanitises view directory.
  *
+ * @access private
  * @param {Array} dirs Array of directories.
  * @throws {SyntaxError} For invalid directories.
  * @throws {TypeError} For invalid type.
@@ -54,6 +60,7 @@ export function validateViews(dirs?: any[]): any[];
 /**
  * Validates and sanitises sessions secret.
  *
+ * @access private
  * @param {string} secret Session secret.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -63,6 +70,7 @@ export function validateSessionSecret(secret: string): string;
 /**
  * Validates and sanitises sessions ttl.
  *
+ * @access private
  * @param {number} ttl Session ttl (seconds).
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -72,6 +80,7 @@ export function validateSessionTtl(ttl?: number): number;
 /**
  * Validates and sanitises sessions name.
  *
+ * @access private
  * @param {string} [name=casa-session] Session name.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -81,6 +90,7 @@ export function validateSessionName(name?: string | undefined): string;
 /**
  * Validates and sanitises sessions secure flag.
  *
+ * @access private
  * @param {boolean} [secure=false] Session secure flag.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -90,6 +100,7 @@ export function validateSessionSecure(secure?: boolean | undefined): string;
 /**
  * Validates and sanitises sessions store.
  *
+ * @access private
  * @param {Function} store Session store.
  * @returns {Function} Store.
  */
@@ -97,6 +108,7 @@ export function validateSessionStore(store: Function): Function;
 /**
  * Validates and sanitises sessions cookie url path.
  *
+ * @access private
  * @param {string} cookiePath Session cookie url path.
  * @param {string} defaultPath Default path if none specified.
  * @returns {string} Cookie path.
@@ -110,6 +122,7 @@ export function validateSessionCookiePath(cookiePath: string, defaultPath?: stri
  * Lax
  * None
  *
+ * @access private
  * @param {any} cookieSameSite Session cookie "sameSite" flag
  * @param {any} defaultFlag Default path if none specified
  * @returns {boolean} cookie path
@@ -126,6 +139,7 @@ export function validateEvents(events: any): any;
 /**
  * Validates helmet configuration function.
  *
+ * @access private
  * @param {HelmetConfigurator} helmetConfigurator Configuration function
  * @returns {HelmetConfigurator} Validated configuration function
  * @throws {TypeError} when passed a non-function
@@ -134,6 +148,7 @@ export function validateHelmetConfigurator(helmetConfigurator: HelmetConfigurato
 /**
  * Ingest, validate, sanitise and manipulate configuration parameters.
  *
+ * @access private
  * @param {ConfigurationOptions} config Config to ingest.
  * @throws {Error|SyntaxError|TypeError} For invalid config values.
  * @returns {object} Immutable config object.

package/dist/lib/configuration-ingestor.js

@@ -10,9 +10,11 @@ const Plan_js_1 = __importDefault(require("./Plan.js"));
 const logger_js_1 = __importDefault(require("./logger.js"));
 const utils_js_1 = require("./utils.js");
 /**
+ * @access private
  * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
  */
 /**
+ * @access private
  * @typedef {import('../casa').HelmetConfigurator} HelmetConfigurator
  */
 const log = (0, logger_js_1.default)('lib:configuration-ingestor');
@@ -20,6 +22,7 @@ const echo = (a) => (a);
 /**
  * Validates and sanitises i18n obejct.
  *
+ * @access private
  * @param {object} i18n Object to validate.
  * @param {Function} cb Callback function that receives the validated value.
  * @throws {TypeError} For invalid object.
@@ -35,6 +38,7 @@ exports.validateI18nObject = validateI18nObject;
 /**
  * Validates and sanitises i18n directory.
  *
+ * @access private
  * @param {Array} dirs Array of directories.
  * @throws {SyntaxError} For invalid directories.
  * @throws {TypeError} For invalid type.
@@ -55,6 +59,7 @@ exports.validateI18nDirs = validateI18nDirs;
 /**
  * Validates and sanitises i18n locales.
  *
+ * @access private
  * @param {Array} locales Array of locales.
  * @throws {SyntaxError} For invalid locales.
  * @throws {TypeError} For invalid type.
@@ -75,6 +80,7 @@ exports.validateI18nLocales = validateI18nLocales;
 /**
  * Validates and sanitises mount url.
  *
+ * @access private
  * @param {string} mountUrl Prefix for all URLs in the browser address bar
  * @throws {SyntaxError} For invalid URL.
  * @returns {string|undefined} Sanitised URL.
@@ -92,6 +98,7 @@ exports.validateMountUrl = validateMountUrl;
 /**
  * Validates and sanitises sessions object.
  *
+ * @access private
  * @param {object} session Object to validate.
  * @param {Function} cb Callback function that receives the validated value.
  * @throws {TypeError} For invalid object.
@@ -110,6 +117,7 @@ exports.validateSessionObject = validateSessionObject;
 /**
  * Validates and sanitises view directory.
  *
+ * @access private
  * @param {Array} dirs Array of directories.
  * @throws {SyntaxError} For invalid directories.
  * @throws {TypeError} For invalid type.
@@ -130,6 +138,7 @@ exports.validateViews = validateViews;
 /**
  * Validates and sanitises sessions secret.
  *
+ * @access private
  * @param {string} secret Session secret.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -148,6 +157,7 @@ exports.validateSessionSecret = validateSessionSecret;
 /**
  * Validates and sanitises sessions ttl.
  *
+ * @access private
  * @param {number} ttl Session ttl (seconds).
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -163,6 +173,7 @@ exports.validateSessionTtl = validateSessionTtl;
 /**
  * Validates and sanitises sessions name.
  *
+ * @access private
  * @param {string} [name=casa-session] Session name.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -178,6 +189,7 @@ exports.validateSessionName = validateSessionName;
 /**
  * Validates and sanitises sessions secure flag.
  *
+ * @access private
  * @param {boolean} [secure=false] Session secure flag.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -193,6 +205,7 @@ exports.validateSessionSecure = validateSessionSecure;
 /**
  * Validates and sanitises sessions store.
  *
+ * @access private
  * @param {Function} store Session store.
  * @returns {Function} Store.
  */
@@ -207,6 +220,7 @@ exports.validateSessionStore = validateSessionStore;
 /**
  * Validates and sanitises sessions cookie url path.
  *
+ * @access private
  * @param {string} cookiePath Session cookie url path.
  * @param {string} defaultPath Default path if none specified.
  * @returns {string} Cookie path.
@@ -226,6 +240,7 @@ exports.validateSessionCookiePath = validateSessionCookiePath;
  * Lax
  * None
  *
+ * @access private
  * @param {any} cookieSameSite Session cookie "sameSite" flag
  * @param {any} defaultFlag Default path if none specified
  * @returns {boolean} cookie path
@@ -356,6 +371,7 @@ exports.validateEvents = validateEvents;
 /**
  * Validates helmet configuration function.
  *
+ * @access private
  * @param {HelmetConfigurator} helmetConfigurator Configuration function
  * @returns {HelmetConfigurator} Validated configuration function
  * @throws {TypeError} when passed a non-function
@@ -370,6 +386,7 @@ exports.validateHelmetConfigurator = validateHelmetConfigurator;
 /**
  * Ingest, validate, sanitise and manipulate configuration parameters.
  *
+ * @access private
  * @param {ConfigurationOptions} config Config to ingest.
  * @throws {Error|SyntaxError|TypeError} For invalid config values.
  * @returns {object} Immutable config object.

package/dist/lib/configure.d.ts

@@ -1,15 +1,19 @@
 /**
+ * @access private
  * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
  */
 /**
+ * @access private
  * @typedef {import('../casa').ConfigurationOptions} ConfigureResult
  */
 /**
+ * @access private
  * @typedef {import('../casa').Mounter} Mounter
  */
 /**
  * Configure some middleware for use in creating a new CASA app.
  *
+ * @memberof module:@dwp/govuk-casa
  * @param {ConfigurationOptions} config Configuration options
  * @returns {ConfigureResult} Result
  */

package/dist/lib/configure.js

@@ -25,17 +25,21 @@ const data_js_1 = __importDefault(require("../middleware/data.js"));
 const body_parser_js_1 = __importDefault(require("../middleware/body-parser.js"));
 const csrf_js_1 = __importDefault(require("../middleware/csrf.js"));
 /**
+ * @access private
  * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
  */
 /**
+ * @access private
  * @typedef {import('../casa').ConfigurationOptions} ConfigureResult
  */
 /**
+ * @access private
  * @typedef {import('../casa').Mounter} Mounter
  */
 /**
  * Configure some middleware for use in creating a new CASA app.
  *
+ * @memberof module:@dwp/govuk-casa
  * @param {ConfigurationOptions} config Configuration options
  * @returns {ConfigureResult} Result
  */
@@ -47,6 +51,7 @@ function configure(config = {}) {
         plugin.configure(config);
     });
     // Extract config
+    const ingestedConfig = (0, configuration_ingestor_js_1.default)(config);
     const { mountUrl, views = [], session = {
         secret: 'secret',
         name: 'casasession',
@@ -58,7 +63,7 @@ function configure(config = {}) {
     }, pages = [], plan = null, hooks = [], plugins = [], events = [], i18n = {
         dirs: [],
         locales: ['en', 'cy'],
-    }, helmetConfigurator = undefined, } = (0, configuration_ingestor_js_1.default)(config);
+    }, helmetConfigurator = undefined, } = ingestedConfig;
     // Prepare all page hooks so they are prefixed with the `journey.` scope.
     pages.forEach((page) => {
         var _a;
@@ -150,7 +155,16 @@ function configure(config = {}) {
                 res.redirect(302, `${reqPath}${reqParams}`);
             });
         }
-        // Service static assets from the `app` rather than the `router`. The router
+        // Capture the mount path of this CASA app, before any parameterised path
+        // segments exert influence over `req.baseUrl` in the `router` further below.
+        // This can later be used by middleware that wants to use the
+        // "unparameterised" version of the request's `baseUrl`, such as the static
+        // router's middleware.
+        app.use((req, res, next) => {
+            req.unparameterisedBaseUrl = req.baseUrl;
+            next();
+        });
+        // Serve static assets from the `app` rather than the `router`. The router
         // may contain paramaterised path segments which would mean serving static
         // assets over a dynamic URL each time, thus causing lots of cache misses on
         // the browser.
@@ -201,6 +215,8 @@ function configure(config = {}) {
         dataMiddleware,
         // Mount function
         mount,
+        // Ingested config
+        config: ingestedConfig,
     };
     // Bootstrap all plugins
     plugins.filter((p) => p.bootstrap).forEach((plugin) => plugin === null || plugin === void 0 ? void 0 : plugin.bootstrap(configOutput));

package/dist/lib/end-session.d.ts

@@ -6,8 +6,9 @@
  * Note: this will not remove the session from server-side storage, which will
  * instead be left up to the storage mechanism to clean up.
  *
- * @param {object} req HTTP request
+ * @memberof module:@dwp/govuk-casa
+ * @param {import('express').Request} req HTTP request
  * @param {Function} next Chain
  * @returns {void}
  */
-export default function endSession(req: object, next: Function): void;
+export default function endSession(req: import('express').Request, next: Function): void;

package/dist/lib/end-session.js

@@ -13,7 +13,8 @@ const log = (0, logger_js_1.default)('lib:end-session');
  * Note: this will not remove the session from server-side storage, which will
  * instead be left up to the storage mechanism to clean up.
  *
- * @param {object} req HTTP request
+ * @memberof module:@dwp/govuk-casa
+ * @param {import('express').Request} req HTTP request
  * @param {Function} next Chain
  * @returns {void}
  */