@dwp/govuk-casa 8.2.3 → 8.2.4

package/dist/lib/ValidationError.d.ts

@@ -1,65 +1,53 @@
 /**
- * @typedef {import('./ValidatorFactory').ValidateContext} ValidateContext
+ * @access private
+ * @typedef {import('../casa').ValidateContext} ValidateContext
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfigObject} ErrorMessageConfigObject
+ */
+/**
+ * @class
+ * @memberof module:@dwp/govuk-casa
  */
 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.
+     * <br/><br/>
      *
-     * 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.
+     * In the case of `errorMsg` being a function, this will be called at runtime,
+     * at the point that errors are generated within the `validate()`,
+     * methods, and will be passed the `dataContext`.
+     * <br/><br/>
      *
-     * 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,
-     *     }
-     *   });
+     * `dataContext` is an object containing the same data passed to all
+     * validators' `validate()` methods. In the case of `errorMsg` being
+     * a function, this data is passed to that function in order to help resolve to
+     * an error message config object.
      *
-     * @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
+     * @param {object} args Arguments
+     * @param {ErrorMessageConfig} args.errorMsg Error message config to seed ValidationError
+     * @param {ValidateContext} [args.dataContext={}] Data for error msg function
+     * @returns {ValidationError} Error instance
      * @throws {TypeError} If errorMsg is not in a valid type
      */
     static make({ errorMsg, dataContext }: {
-        errorMsg: any;
-        dataContext: object;
-    }): object;
+        errorMsg: ErrorMessageConfig;
+        dataContext?: import("../casa").ValidateContext | undefined;
+    }): ValidationError;
     /**
-     * `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'
-     *   }
-     * }
+     * Create a ValidationError.
      *
-     * @param {object|string} errorParam See object structure above
+     * @param {string|ErrorMessageConfigObject} errorParam Error configuration
      */
-    constructor(errorParam?: object | string);
+    constructor(errorParam?: string | ErrorMessageConfigObject);
     /**
-     * Modifies the error to reflect the given context.
+     * Modifies this instance to reflect the given validation context.
      *
      * @param {ValidateContext} context See structure above
      * @returns {ValidationError} Chain
@@ -69,6 +57,8 @@ export default class ValidationError {
     field: string | undefined;
     fieldHref: string | undefined;
     focusSuffix: any;
-    validator: any;
+    validator: string | undefined;
 }
-export type ValidateContext = import('./ValidatorFactory').ValidateContext;
+export type ValidateContext = import('../casa').ValidateContext;
+export type ErrorMessageConfig = import('../casa').ErrorMessageConfig;
+export type ErrorMessageConfigObject = import('../casa').ErrorMessageConfigObject;

package/dist/lib/ValidationError.js

@@ -7,40 +7,41 @@ const lodash_1 = __importDefault(require("lodash"));
 const { isPlainObject } = lodash_1.default; // CommonJS
 const params = new WeakMap();
 /**
- * @typedef {import('./ValidatorFactory').ValidateContext} ValidateContext
+ * @access private
+ * @typedef {import('../casa').ValidateContext} ValidateContext
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+/**
+ * @access private
+ * @typedef {import('../casa').ErrorMessageConfigObject} ErrorMessageConfigObject
+ */
+/**
+ * @class
+ * @memberof module:@dwp/govuk-casa
  */
 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.
+     * <br/><br/>
      *
-     * 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.
+     * In the case of `errorMsg` being a function, this will be called at runtime,
+     * at the point that errors are generated within the `validate()`,
+     * methods, and will be passed the `dataContext`.
+     * <br/><br/>
      *
-     * 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,
-     *     }
-     *   });
+     * `dataContext` is an object containing the same data passed to all
+     * validators' `validate()` methods. In the case of `errorMsg` being
+     * a function, this data is passed to that function in order to help resolve to
+     * an error message config object.
      *
-     * @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
+     * @param {object} args Arguments
+     * @param {ErrorMessageConfig} args.errorMsg Error message config to seed ValidationError
+     * @param {ValidateContext} [args.dataContext={}] Data for error msg function
+     * @returns {ValidationError} Error instance
      * @throws {TypeError} If errorMsg is not in a valid type
      */
     static make({ errorMsg, dataContext = {} }) {
@@ -74,22 +75,9 @@ class ValidationError {
         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'
-     *   }
-     * }
+     * Create a ValidationError.
      *
-     * @param {object|string} errorParam See object structure above
+     * @param {string|ErrorMessageConfigObject} errorParam Error configuration
      */
     constructor(errorParam = {}) {
         if (!isPlainObject(errorParam) && typeof errorParam !== 'string') {
@@ -126,7 +114,7 @@ class ValidationError {
         });
     }
     /**
-     * Modifies the error to reflect the given context.
+     * Modifies this instance to reflect the given validation context.
      *
      * @param {ValidateContext} context See structure above
      * @returns {ValidationError} Chain

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.