@dwp/govuk-casa 8.2.2 → 8.2.5

package/dist/lib/field.d.ts

@@ -1,16 +1,56 @@
-export default function field(...args: any[]): PageField;
+/**
+ * Factory for creating PageField instances.
+ *
+ * @memberof module:@dwp/govuk-casa
+ * @param {string} name Field name
+ * @param {object} opts Options
+ * @param {boolean} [opts.optional=false] Whether this field is optional
+ * @param {boolean} [opts.persist=true] Whether this field will persist in `req.body`
+ * @returns {PageField} A PageField
+ */
+export default function field(name: string, opts: {
+    optional?: boolean | undefined;
+    persist?: boolean | undefined;
+}): PageField;
+/**
+ * This class is not exposed via the public API. Instances should instead be
+ * instantiated through the `field()` factory function.
+ *
+ * @class
+ */
 export class PageField {
-    constructor(name: any, { optional, persist }?: any);
     /**
-     * For complex fields, we need may need to drill into an object to extract the
+     * Create a field.
+     *
+     * @param {string} name Field name
+     * @param {object} opts Options
+     * @param {boolean} [opts.optional=false] Whether this field is optional
+     * @param {boolean} [opts.persist=true] Whether this field will persist in `req.body`
+     */
+    constructor(name: string, { optional, persist }?: {
+        optional?: boolean | undefined;
+        persist?: boolean | undefined;
+    });
+    /**
+     * Extract this field's value from the given object.
+     *
+     * For complex fields, we may need to drill into an object to extract the
      * value.
      *
      * @param {object} obj Object from which to extract the value
      * @returns {any} Value extracted from object
-     * @throws {Error} When run on a complex field
+     * @throws {Error} When run on a complex field (not yet supported)
      */
     getValue(obj?: object): any;
-    putValue(obj?: any, value?: undefined): PageField;
+    /**
+     * Store this field's value in the given object, using its name as the key.
+     *
+     * @param {object} obj Object from which to extract the value
+     * @param {any} value Value to be stored
+     * @returns {any} Value extracted from object
+     * @throws {Error} When run on a complex field (not yet supported)
+     */
+    putValue(obj?: object, value?: any): any;
     get name(): string;
     get meta(): object;
     /**
@@ -18,60 +58,82 @@ export class PageField {
      * Some validators will include a `sanitise()` method which will be run at the
      * same time as other "processors".
      *
-     * @param {ValidateFunction[]} items Validation functions
-     * @returns {PageField | ValidateFunction[]} Chain or return all validators
+     * @param {Validator[]} items Validation functions
+     * @returns {PageField | Validator[]} Chain or return all validators
      */
-    validators(items?: ValidateFunction[]): PageField | ValidateFunction[];
+    validators(items?: Validator[]): PageField | Validator[];
     /**
      * Add/get value pre-processors
      * This is most often used to sanitise values to a particular data type.
      *
-     * @param {ProcessorFunction[]} items Processor functions
-     * @returns {PageField | ProcessorFunction[]} Chain or return all processors
+     * @param {FieldProcessorFunction[]} items Processor functions
+     * @returns {PageField | FieldProcessorFunction[]} Chain or return all processors
      */
-    processors(items?: ProcessorFunction[]): PageField | ProcessorFunction[];
+    processors(items?: FieldProcessorFunction[]): PageField | FieldProcessorFunction[];
     /**
      * Add/get conditions
      * All conditions must be met in order for this field to be considered
      * "actionable".
      *
-     * @param {ConditionFunction[]} items Condition functions
-     * @returns {PageField | ConditionFunction[]} Chain or return all conditions
+     * @param {ValidatorConditionFunction[]} items Condition functions
+     * @returns {PageField | ValidatorConditionFunction[]} Chain or return all conditions
      */
-    conditions(items?: ConditionFunction[]): PageField | ConditionFunction[];
+    conditions(items?: ValidatorConditionFunction[]): PageField | ValidatorConditionFunction[];
     /**
      * Run all validators and return array of errors, if applicable.
      *
      * @param {any} value Value to validate
-     * @param {ValidateContext} context Contextual information
+     * @param {ValidateContext} context Contextual validation information
      * @returns {ValidationError[]} Errors, or an empty array if all valid
      */
-    runValidators(value: any, context?: any): ValidationError[];
+    runValidators(value: any, context?: ValidateContext): ValidationError[];
+    /**
+     * Apply all the processors to the given value.
+     *
+     * @param {any} value Value to process
+     * @returns {any} Processed value
+     */
     applyProcessors(value: any): any;
     /**
-     * Apply all conditions to get the resulting boolean
+     * All conditions must return true to be considered a successful test.
      *
-     * @param {object} params Parameters
-     * @param {string} params.fieldValue Field value
-     * @param {string} params.waypoint Waypoint
-     * @param {object} params.journeyContext JourneyContext
+     * @param {ValidateContext} context Contextual validation information
      * @returns {boolean} True if all conditions pass
      */
-    testConditions({ fieldValue, waypoint, journeyContext }: {
-        fieldValue: string;
-        waypoint: string;
-        journeyContext: object;
-    }): boolean;
-    validator(validator: any): any[] | PageField;
-    processor(processor: any): PageField | ProcessorFunction[];
-    condition(condition: any): PageField | ConditionFunction[];
-    if(...args: any[]): PageField | ConditionFunction[];
+    testConditions({ fieldValue, waypoint, journeyContext }: ValidateContext): boolean;
+    /**
+     * Add a single validator.
+     *
+     * @param {Validator} validator Validation function
+     * @returns {PageField} Chain
+     */
+    validator(validator: Validator): PageField;
+    /**
+     * Add a single pre-processors
+     *
+     * @param {FieldProcessorFunction} processor Processor function
+     * @returns {PageField} Chain
+     */
+    processor(processor: FieldProcessorFunction): PageField;
+    /**
+     * Add a single condition.
+     *
+     * @param {ValidatorConditionFunction} condition Condition function
+     * @returns {PageField} Chain
+     */
+    condition(condition: ValidatorConditionFunction): PageField;
+    /**
+     * Alias for `conditions()`.
+     *
+     * @param {...ValidatorConditionFunction} args Condition functions
+     * @returns {PageField} Chain
+     */
+    if(...args: ValidatorConditionFunction[]): PageField;
     #private;
 }
 export type JourneyContext = import('./index').JourneyContext;
-export type Validator = import('./index').Validator;
-export type ValidateFunction = import('./index').ValidateFunction;
-export type ValidateContext = import('./index').ValidateContext;
+export type Validator = import('../casa').Validator;
+export type ValidateContext = import('../casa').ValidateContext;
+export type ValidatorConditionFunction = import('../casa').ValidatorConditionFunction;
+export type FieldProcessorFunction = import('../casa').FieldProcessorFunction;
 export type ValidationError = import('./index').ValidationError;
-export type ProcessorFunction = (value: any) => any;
-export type ConditionFunction = (context: Object, fieldName: string, fieldValue: any, waypoint: string, waypointId: string, journeyContext: JourneyContext) => boolean;

package/dist/lib/field.js

@@ -20,57 +20,63 @@ const lodash_1 = __importDefault(require("lodash"));
 const utils_js_1 = require("./utils.js");
 const { isFunction } = lodash_1.default;
 /**
+ * @access private
  * @typedef {import('./index').JourneyContext} JourneyContext
  */
 /**
- * @typedef {import('./index').Validator} Validator
+ * @access private
+ * @typedef {import('../casa').Validator} Validator
  */
 /**
- * @typedef {import('./index').ValidateFunction} ValidateFunction
+ * @access private
+ * @typedef {import('../casa').ValidateContext} ValidateContext
  */
 /**
- * @typedef {import('./index').ValidateContext} ValidateContext
+ * @access private
+ * @typedef {import('../casa').ValidatorConditionFunction} ValidatorConditionFunction
  */
 /**
- * @typedef {import('./index').ValidationError} ValidationError
- */
-/**
- * @callback ProcessorFunction
- * @param {any} value Value to be processed
- * @returns {any}
+ * @access private
+ * @typedef {import('../casa').FieldProcessorFunction} FieldProcessorFunction
  */
 /**
- * @callback ConditionFunction
- * @param {Object} context Value to be processed
- * @param {string} context.fieldName Field name
- * @param {any} context.fieldValue Field value
- * @param {string} context.waypoint Waypoint
- * @param {string} context.waypointId [DEPRECATED] Waypoint (for backwards compatibility with v7)
- * @param {JourneyContext} journeyContext Journey Context
- * @returns {boolean} True if the validators should be run
+ * @access private
+ * @typedef {import('./index').ValidationError} ValidationError
  */
 // Quick check to see if the field name corresponds to a non-primitive complex
 // type. For example, `my_field[nested]`.
 const reComplexType = /\[/;
 const reInvalidName = /[^a-z0-9_.\-[\]]/i;
-// This is never exposed via a public API, and instead users are encouraged to
-// use the `field()` factory instead
+/**
+ * This class is not exposed via the public API. Instances should instead be
+ * instantiated through the `field()` factory function.
+ *
+ * @class
+ */
 class PageField {
+    /**
+     * Create a field.
+     *
+     * @param {string} name Field name
+     * @param {object} opts Options
+     * @param {boolean} [opts.optional=false] Whether this field is optional
+     * @param {boolean} [opts.persist=true] Whether this field will persist in `req.body`
+     */
     constructor(name, { optional = false, persist = true } = Object.create(null)) {
-        /*
+        /**
          * @type {string}
          */
         _PageField_name.set(this, void 0);
         /**
-         * @type {ProcessorFunction[]}
+         * @type {FieldProcessorFunction[]}
          */
         _PageField_processors.set(this, void 0);
         /**
-         * @type {ValidateFunction[]}
+         * @type {Validator[]}
          */
         _PageField_validators.set(this, void 0);
         /**
-         * @type {ConditionFunction[]}
+         * @type {ValidatorConditionFunction[]}
          */
         _PageField_conditions.set(this, void 0);
         /**
@@ -94,12 +100,14 @@ class PageField {
         }, "f");
     }
     /**
-     * For complex fields, we need may need to drill into an object to extract the
+     * Extract this field's value from the given object.
+     *
+     * For complex fields, we may need to drill into an object to extract the
      * value.
      *
      * @param {object} obj Object from which to extract the value
      * @returns {any} Value extracted from object
-     * @throws {Error} When run on a complex field
+     * @throws {Error} When run on a complex field (not yet supported)
      */
     getValue(obj = Object.create(null)) {
         if (!__classPrivateFieldGet(this, _PageField_meta, "f").complex) {
@@ -107,6 +115,14 @@ class PageField {
         }
         throw new Error('Not yet supporting complex field types');
     }
+    /**
+     * Store this field's value in the given object, using its name as the key.
+     *
+     * @param {object} obj Object from which to extract the value
+     * @param {any} value Value to be stored
+     * @returns {any} Value extracted from object
+     * @throws {Error} When run on a complex field (not yet supported)
+     */
     putValue(obj = Object.create(null), value = undefined) {
         if (!__classPrivateFieldGet(this, _PageField_meta, "f").complex) {
             /* eslint-disable-next-line no-param-reassign */
@@ -127,8 +143,8 @@ class PageField {
      * Some validators will include a `sanitise()` method which will be run at the
      * same time as other "processors".
      *
-     * @param {ValidateFunction[]} items Validation functions
-     * @returns {PageField | ValidateFunction[]} Chain or return all validators
+     * @param {Validator[]} items Validation functions
+     * @returns {PageField | Validator[]} Chain or return all validators
      */
     validators(items = []) {
         if (!items.length) {
@@ -141,8 +157,8 @@ class PageField {
      * Add/get value pre-processors
      * This is most often used to sanitise values to a particular data type.
      *
-     * @param {ProcessorFunction[]} items Processor functions
-     * @returns {PageField | ProcessorFunction[]} Chain or return all processors
+     * @param {FieldProcessorFunction[]} items Processor functions
+     * @returns {PageField | FieldProcessorFunction[]} Chain or return all processors
      */
     processors(items = []) {
         if (!items.length) {
@@ -156,8 +172,8 @@ class PageField {
      * All conditions must be met in order for this field to be considered
      * "actionable".
      *
-     * @param {ConditionFunction[]} items Condition functions
-     * @returns {PageField | ConditionFunction[]} Chain or return all conditions
+     * @param {ValidatorConditionFunction[]} items Condition functions
+     * @returns {PageField | ValidatorConditionFunction[]} Chain or return all conditions
      */
     conditions(items = []) {
         if (!items.length) {
@@ -171,7 +187,7 @@ class PageField {
      * Run all validators and return array of errors, if applicable.
      *
      * @param {any} value Value to validate
-     * @param {ValidateContext} context Contextual information
+     * @param {ValidateContext} context Contextual validation information
      * @returns {ValidationError[]} Errors, or an empty array if all valid
      */
     runValidators(value, context = Object.create(null)) {
@@ -182,6 +198,8 @@ class PageField {
         }
         // Skip validation if conditions are not met
         // We duplicate value in context.fieldValue for historical reasons
+        // @todo explain these historical reasons! And deprecate the need for
+        // `value` altogether
         context.fieldValue = (_a = context.fieldValue) !== null && _a !== void 0 ? _a : value;
         if (!this.testConditions(context)) {
             return [];
@@ -190,6 +208,7 @@ class PageField {
         for (let i = 0, l = __classPrivateFieldGet(this, _PageField_validators, "f").length; i < l; i++) {
             // ESLint disabled as `i` is an integer
             /* eslint-disable security/detect-object-injection */
+            // TODO: Replace `value` with `context.fieldValue` here
             const fieldErrors = __classPrivateFieldGet(this, _PageField_validators, "f")[i].validate(value, context).map((e) => e.withContext(Object.assign(Object.assign({}, context), { validator: __classPrivateFieldGet(this, _PageField_validators, "f")[i].name })));
             /* eslint-enable security/detect-object-injection */
             errors = [
@@ -199,7 +218,7 @@ class PageField {
         }
         return errors;
     }
-    /*
+    /**
      * Apply all the processors to the given value.
      *
      * @param {any} value Value to process
@@ -225,12 +244,9 @@ class PageField {
         return processedValue;
     }
     /**
-     * Apply all conditions to get the resulting boolean
+     * All conditions must return true to be considered a successful test.
      *
-     * @param {object} params Parameters
-     * @param {string} params.fieldValue Field value
-     * @param {string} params.waypoint Waypoint
-     * @param {object} params.journeyContext JourneyContext
+     * @param {ValidateContext} context Contextual validation information
      * @returns {boolean} True if all conditions pass
      */
     testConditions({ fieldValue, waypoint, journeyContext }) {
@@ -250,23 +266,56 @@ class PageField {
         return result;
     }
     /* ---------------------------------------------------------------- aliases */
+    /**
+     * Add a single validator.
+     *
+     * @param {Validator} validator Validation function
+     * @returns {PageField} Chain
+     */
     validator(validator) {
         return this.validators([validator]);
     }
+    /**
+     * Add a single pre-processors
+     *
+     * @param {FieldProcessorFunction} processor Processor function
+     * @returns {PageField} Chain
+     */
     processor(processor) {
         return this.processors([processor]);
     }
+    /**
+     * Add a single condition.
+     *
+     * @param {ValidatorConditionFunction} condition Condition function
+     * @returns {PageField} Chain
+     */
     condition(condition) {
         return this.conditions([condition]);
     }
+    /**
+     * Alias for `conditions()`.
+     *
+     * @param {...ValidatorConditionFunction} args Condition functions
+     * @returns {PageField} Chain
+     */
     if(...args) {
         return this.conditions(...args);
     }
 }
 exports.PageField = PageField;
 _PageField_name = new WeakMap(), _PageField_processors = new WeakMap(), _PageField_validators = new WeakMap(), _PageField_conditions = new WeakMap(), _PageField_meta = new WeakMap();
-// Factory for convenience
-function field(...args) {
-    return new PageField(...args);
+/**
+ * Factory for creating PageField instances.
+ *
+ * @memberof module:@dwp/govuk-casa
+ * @param {string} name Field name
+ * @param {object} opts Options
+ * @param {boolean} [opts.optional=false] Whether this field is optional
+ * @param {boolean} [opts.persist=true] Whether this field will persist in `req.body`
+ * @returns {PageField} A PageField
+ */
+function field(name, opts) {
+    return new PageField(name, opts);
 }
 exports.default = field;

package/dist/lib/nunjucks-filters.d.ts

@@ -1,5 +1,13 @@
 export function mergeObjects(...objects: any[]): object;
-export function includes(source?: any[], search?: string): boolean;
+/**
+ * Determine whether a value exists in a list.
+ *
+ * @memberof NunjucksFilters
+ * @param {any[]} source List of items to search
+ * @param {any} search Item to search within the `source`
+ * @returns {boolean} True if the search item was found
+ */
+export function includes(source?: any[], search?: any): boolean;
 /**
  * Format a given date.
  *
@@ -8,6 +16,7 @@ export function includes(source?: any[], search?: string): boolean;
  * `date` may be any of the following types:
  *   object - {dd:'', mm:'', yyyy:''}
  *
+ * @memberof NunjucksFilters
  * @param  {object} date Date (see supported formats above)
  * @param  {object} config Holds locale
  * @returns {string} Formatted date
@@ -20,7 +29,8 @@ export function formatDateObject(date: object, config?: object): string;
  *   Given: {class: 'basic', 'data-ga': 3}
  *   Output: class="basic" data-ga="3"
  *
- * @param  {object} attrsObject Attributes object (in name:value pairs)
+ * @memberof NunjucksFilters
+ * @param {object} attrsObject Attributes object (in name:value pairs)
  * @returns {string} Formatted
  */
 export function renderAsAttributes(attrsObject: object): string;

package/dist/lib/nunjucks-filters.js

@@ -33,6 +33,14 @@ function mergeObjects(...objects) {
     return deepmergeAll([Object.create(null), ...objects], { arrayMerge: combineMerge });
 }
 exports.mergeObjects = mergeObjects;
+/**
+ * Determine whether a value exists in a list.
+ *
+ * @memberof NunjucksFilters
+ * @param {any[]} source List of items to search
+ * @param {any} search Item to search within the `source`
+ * @returns {boolean} True if the search item was found
+ */
 function includes(source = [], search = '') {
     return source.includes(search);
 }
@@ -45,6 +53,7 @@ exports.includes = includes;
  * `date` may be any of the following types:
  *   object - {dd:'', mm:'', yyyy:''}
  *
+ * @memberof NunjucksFilters
  * @param  {object} date Date (see supported formats above)
  * @param  {object} config Holds locale
  * @returns {string} Formatted date
@@ -71,7 +80,8 @@ exports.formatDateObject = formatDateObject;
  *   Given: {class: 'basic', 'data-ga': 3}
  *   Output: class="basic" data-ga="3"
  *
- * @param  {object} attrsObject Attributes object (in name:value pairs)
+ * @memberof NunjucksFilters
+ * @param {object} attrsObject Attributes object (in name:value pairs)
  * @returns {string} Formatted
  */
 function renderAsAttributes(attrsObject) {

package/dist/lib/nunjucks.d.ts

@@ -5,6 +5,7 @@
 /**
  * Create a Nunjucks environment.
  *
+ * @access private
  * @param {NunjucksOptions} options Nunjucks options
  * @returns {Environment} Nunjucks Environment instance
  */

package/dist/lib/nunjucks.js

@@ -16,6 +16,7 @@ const nunjucks_filters_js_1 = require("./nunjucks-filters.js");
 /**
  * Create a Nunjucks environment.
  *
+ * @access private
  * @param {NunjucksOptions} options Nunjucks options
  * @returns {Environment} Nunjucks Environment instance
  */

package/dist/lib/utils.d.ts

@@ -1,9 +1,11 @@
 /**
+ * @access private
  * @typedef {import('../casa').GlobalHook | import('../casa').PageHook} Hook
  */
 /**
  * Test is a value can be stringifed (numbers or strings)
  *
+ * @access private
  * @param {any} value Item to test
  * @returns {boolean} Whether the value is stringable or not
  */
@@ -11,6 +13,7 @@ export function isStringable(value: any): boolean;
 /**
  * Coerce an input to a string.
  *
+ * @access private
  * @param {any} input Input to be stringified
  * @param {string} fallback Fallback to use if input can't be stringified
  * @returns {string} The stringified input
@@ -19,6 +22,7 @@ export function stringifyInput(input: any, fallback: string, ...args: any[]): st
 /**
  * Determine if value is empty. Recurse over objects.
  *
+ * @access private
  * @param  {any} val Value to check
  * @returns {boolean} True if the object is empty
  */
@@ -27,33 +31,61 @@ export function isEmpty(val: any): boolean;
  * Extract the middleware functions that are relevant for the given hook and
  * path.
  *
+ * @access private
  * @param {string} hookName Hook name (including scope prefix)
  * @param {string} path URL path to match (relative to mountUrl)
  * @param {Hook[]} hooks Hooks to be applied at the page level
  * @returns {Function[]} An array of middleware that should be applied
  */
 export function resolveMiddlewareHooks(hookName: string, path: string, hooks?: Hook[]): Function[];
-export function validateWaypoint(waypoint: any): void;
-export function validateUrlPath(path: any): string;
-export function validateView(view: any): void;
-export function validateHookName(hookName: any): void;
+/**
+ * Validate a waypoint.
+ *
+ * @access private
+ * @param {string} waypoint Waypoint
+ * @returns {void}
+ * @throws {TypeError}
+ * @throws {SyntaxError}
+ */
+export function validateWaypoint(waypoint: string): void;
+/**
+ * Validate a URL path.
+ *
+ * @access private
+ * @param {string} path URL path
+ * @returns {string} Same string, if valid
+ * @throws {TypeError}
+ * @throws {SyntaxError}
+ */
+export function validateUrlPath(path: string): string;
+/**
+ * Validate a template name.
+ *
+ * @access private
+ * @param {string} view Template name
+ * @returns {void}
+ * @throws {TypeError}
+ * @throws {SyntaxError}
+ */
+export function validateView(view: string): void;
+/**
+ * Validate a hook name.
+ *
+ * @access private
+ * @param {string} hookName Hook name
+ * @returns {void}
+ * @throws {TypeError}
+ * @throws {SyntaxError}
+ */
+export function validateHookName(hookName: string): void;
 export function validateHookPath(path: any): void;
 /**
  * Checks if the given string can be used as an object key.
  *
+ * @access private
  * @param {string} key Proposed Object key
  * @returns {string} Same key if it's valid
  * @throws {Error} if proposed key is an invalid keyword
  */
 export function notProto(key: string): string;
-/**
- * Remove any path segments from the URL that are present in the `mountpath`,
- * but not in the `baseUrl`. Those segments are considered to be part of an
- * internal proxying arrangement, and should not be used by CASA.
- *
- * @param {import('express').Request} req Express request
- * @throws {Error} When multiple mountpaths are present
- * @returns {string} URL path with any proxy prefixes removed
- */
-export function stripProxyFromUrlPath(req: import('express').Request): string;
 export type Hook = import('../casa').GlobalHook | import('../casa').PageHook;