@dwp/govuk-casa 8.7.12 → 8.8.0

package/src/lib/validators/inArray.js

@@ -0,0 +1,81 @@
+/* eslint-disable class-methods-use-this */
+/**
+ * Test if a value is present in an array.
+ *
+ * Config options:
+ *   Array source = Array of values to test against
+ *
+ * If the value itself is an array, all values within that array must be present
+ * in the `source` array in order to pass validation.
+ */
+import ValidationError from '../ValidationError.js';
+import ValidatorFactory from '../ValidatorFactory.js';
+import { stringifyInput, isStringable } from '../utils.js';
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} ArrayConfigOptions
+ * @property {ErrorMessageConfig} errorMsg Error message config
+ * @property {string[]} source Array of values to test against
+ */
+
+/**
+ * Test if a value is present in an array.
+ *
+ * If the value itself is an array, all values within that array must be present
+ * in the `source` array in order to pass validation.
+ *
+ * See {@link ArrayConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class InArray extends ValidatorFactory {
+  /** @property {string} name Validator name ("inArray") */
+  name = 'inArray';
+
+  validate(value, dataContext = {}) {
+    let valid = false;
+    const source = this.config.source || [];
+    const errorMsg = this.config.errorMsg || {
+      inline: 'validation:rule.inArray.inline',
+      summary: 'validation:rule.inArray.summary',
+    };
+
+    if (value !== null && typeof value !== 'undefined') {
+      const search = Array.isArray(value) ? value : [value];
+      for (let i = 0, l = search.length; i < l; i += 1) {
+        if (source.indexOf(search[parseInt(i, 10)]) > -1) {
+          valid = true;
+        } else {
+          valid = false;
+          break;
+        }
+      }
+    }
+
+    return valid ? [] : [ValidationError.make({ errorMsg, dataContext })];
+  }
+
+  sanitise(value) {
+    const coerce = (val) => (stringifyInput(val, undefined));
+
+    // Basic stringable
+    if (isStringable(value)) {
+      return stringifyInput(value);
+    }
+
+    // Coerce all elements to Strings.
+    // This only supports one dimensional array, with stringable element.
+    if (Array.isArray(value)) {
+      return value.map(coerce);
+    }
+
+    // Unsupported value
+    return undefined;
+  }
+}

package/src/lib/validators/index.js

@@ -0,0 +1,24 @@
+import dateObject from './dateObject.js';
+import email from './email.js';
+import inArray from './inArray.js';
+import nino from './nino.js';
+import postalAddressObject from './postalAddressObject.js';
+import regex from './regex.js';
+import required from './required.js';
+import strlen from './strlen.js';
+import wordCount from './wordCount.js';
+
+/**
+ * @namespace Validators
+ */
+export default {
+  dateObject,
+  email,
+  inArray,
+  nino,
+  postalAddressObject,
+  regex,
+  required,
+  strlen,
+  wordCount,
+}

package/src/lib/validators/nino.js

@@ -0,0 +1,57 @@
+/* eslint-disable class-methods-use-this */
+import ValidationError from '../ValidationError.js';
+import ValidatorFactory from '../ValidatorFactory.js';
+import { stringifyInput } from '../utils.js';
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} NinoConfigOptions
+ * @property {ErrorMessageConfig} errorMsg Error message config
+ * @property {boolean} allowWhitespace Will permit input values that contain spaces.
+ */
+
+/**
+ * UK National Insurance number.
+ *
+ * Ref:
+ * https://en.wikipedia.org/wiki/National_Insurance_number#Format
+ * https://design-system.service.gov.uk/patterns/national-insurance-numbers/
+ *
+ * See {@link NinoConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class Nino extends ValidatorFactory {
+  name = 'nino';
+
+  validate(value, dataContext = {}) {
+    const {
+      allowWhitespace,
+      errorMsg = {
+        inline: 'validation:rule.nino.inline',
+        summary: 'validation:rule.nino.summary',
+      },
+    } = this.config;
+
+    if (typeof allowWhitespace !== 'undefined' && typeof allowWhitespace !== 'boolean') {
+      throw new TypeError(`NINO validation rule option "allowWhitespace" must been a boolean. received ${typeof allowWhitespace}`);
+    }
+    const valid = typeof value === 'string'
+      && value.replace((typeof allowWhitespace !== 'undefined' && allowWhitespace) ? /\u0020/g : '', '')
+        .match(/^(?!BG|GB|NK|KN|TN|NT|ZZ)[ABCEGHJ-PRSTW-Z][ABCEGHJ-NPRSTW-Z]\d{6}[A-D]$/i);
+
+    return valid ? [] : [ValidationError.make({ errorMsg, dataContext })];
+  }
+
+  sanitise(value) {
+    if (value !== undefined) {
+      return stringifyInput(value);
+    }
+    return undefined;
+  }
+}

package/src/lib/validators/postalAddressObject.js

@@ -0,0 +1,162 @@
+/* eslint-disable class-methods-use-this */
+import lodash from 'lodash';
+import ValidationError from '../ValidationError.js';
+import ValidatorFactory from '../ValidatorFactory.js';
+import { stringifyInput } from '../utils.js';
+
+const { isPlainObject } = lodash; // CommonjS
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} PostalAddressObjectConfigOptions
+ * @property {ErrorMessageConfig} [errorMsg] General error message for the entire address block
+ * @property {string|object} [errorMsgAddress1] Error message for address1 part
+ * @property {string|object} [errorMsgAddress2] Error message for address2 part
+ * @property {string|object} [errorMsgAddress3] Error message for address3 part
+ * @property {string|object} [errorMsgAddress4] Error message for address4 part
+ * @property {string|object} [errorMsgPostcode] Error message for postcode part
+ * @property {number} [strlenmax] Max. String length for each of the inputs address[1-4]
+ * @property {string[]} [requiredFields] Field parts required (others become optional). One of
+ * 'address1'|'address2'|'address3'|'address4'|'postcode'
+ */
+
+/**
+ * Works hand in hand with the core CASA `postalAddressObject` form
+ * macro.
+ *
+ * The errors sent back from this validator are specific to each subfield. For
+ * example, if the field name being tested is "address", any errors related to
+ * the "postcode" component would be associated with "address[postcode]".
+ *
+ * See {@link PostalAddressObjectConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class PostalAddressObject extends ValidatorFactory {
+  name = 'postalAddressObject';
+
+  validate(value, dataContext = {}) {
+    const cfg = {
+      requiredFields: ['address1', 'address3', 'postcode'],
+      strlenmax: undefined,
+      errorMsgAddress1: {
+        inline: 'validation:rule.postalAddressObject.address1.inline',
+        summary: 'validation:rule.postalAddressObject.address1.summary',
+        focusSuffix: '[address1]',
+      },
+      errorMsgAddress2: {
+        inline: 'validation:rule.postalAddressObject.address2.inline',
+        summary: 'validation:rule.postalAddressObject.address2.summary',
+        focusSuffix: '[address2]',
+      },
+      errorMsgAddress3: {
+        inline: 'validation:rule.postalAddressObject.address3.inline',
+        summary: 'validation:rule.postalAddressObject.address3.summary',
+        focusSuffix: '[address3]',
+      },
+      errorMsgAddress4: {
+        inline: 'validation:rule.postalAddressObject.address4.inline',
+        summary: 'validation:rule.postalAddressObject.address4.summary',
+        focusSuffix: '[address4]',
+      },
+      errorMsgPostcode: {
+        inline: 'validation:rule.postalAddressObject.postcode.inline',
+        summary: 'validation:rule.postalAddressObject.postcode.summary',
+        focusSuffix: '[postcode]',
+      },
+      errorMsg: {
+        inline: 'validation:rule.postalAddressObject.group.inline',
+        summary: 'validation:rule.postalAddressObject.group.summary',
+        focusSuffix: '[address1]',
+      },
+      ...this.config,
+    };
+
+    /* eslint-disable-next-line require-jsdoc */
+    const objectifyError = (err) => (typeof err === 'string' ? {
+      inline: err,
+      summary: err,
+    } : err);
+
+    // Work out required/optional parts based on config
+    const reqF = Object.create(null);
+    const reqC = cfg.requiredFields;
+    ['address1', 'address2', 'address3', 'address4', 'postcode'].forEach((k) => {
+      // ESLint disabled as `k` is a known value from a constant list
+      /* eslint-disable-next-line security/detect-object-injection */
+      reqF[k] = reqC.indexOf(k) > -1;
+    });
+
+    let valid = true;
+    const errorMsgs = [];
+
+    if (typeof value === 'object') {
+      const reAddr = /^[^\s]+[a-z0-9\-,.&#()/\\:;'" ]+$/i;
+      const reAddrLine1 = /^\d+|[^\s]+[a-z0-9\-,.&#()/\\:;'" ]+$/i;
+      // UK Postcode regex taken from the dwp java pc checker
+      // https://github.com/dwp/postcode-format-validation
+      const rePostcode = /^(?![QVX])[A-Z]((?![IJZ])[A-Z][0-9](([0-9]?)|([ABEHMNPRVWXY]?))|([0-9]([0-9]?|[ABCDEFGHJKPSTUW]?))) ?[0-9]((?![CIKMOV])[A-Z]){2}$|^(BFPO)[ ]?[0-9]{1,4}$/i;
+
+      // [required, regex, strlenmax, error message]
+      const attributes = {
+        address1: [reqF.address1, reAddrLine1, cfg.strlenmax, cfg.errorMsgAddress1],
+        address2: [reqF.address2, reAddr, cfg.strlenmax, cfg.errorMsgAddress2],
+        address3: [reqF.address3, reAddr, cfg.strlenmax, cfg.errorMsgAddress3],
+        address4: [reqF.address4, reAddr, cfg.strlenmax, cfg.errorMsgAddress4],
+        postcode: [reqF.postcode, rePostcode, null, cfg.errorMsgPostcode],
+      };
+      // ESLint disabled as `k` is a known value from the constant list above
+      /* eslint-disable security/detect-object-injection */
+      Object.keys(attributes).forEach((k) => {
+        const attr = attributes[k];
+        const hasProperty = Object.prototype.hasOwnProperty.call(value, k);
+        const hasContent = hasProperty && value[k].length > 0;
+
+        const condMissingOrRegexMismatch = (attr[0] || hasContent)
+          && (!hasProperty || !value[k].match(attr[1]));
+        const condExceedStrlen = attr[2] > 0 && hasContent
+          && String(value[k]).length > attr[2];
+
+        if (condMissingOrRegexMismatch || condExceedStrlen) {
+          valid = false;
+          errorMsgs.push(Object.assign(Object.create(null), objectifyError(attr[3]), {
+            fieldKeySuffix: `[${k}]`,
+          }));
+        }
+      });
+      /* eslint-enable security/detect-object-injection */
+    } else {
+      valid = false;
+      errorMsgs.push(cfg.errorMsg);
+    }
+
+    // Build ValidationErrorGroup
+    const errorGroup = errorMsgs.map((err) => (
+      ValidationError.make({ errorMsg: err, dataContext })));
+
+    return valid ? [] : [...errorGroup];
+  }
+
+  sanitise(value) {
+    // Only objects are supported
+    if (!isPlainObject(value)) {
+      return Object.create(null);
+    }
+
+    // Prune unrecognised attributes, and coerce to Strings
+    const validKeys = ['address1', 'address2', 'address3', 'address4', 'postcode'];
+    const pruned = Object.fromEntries(
+      Object.entries(value).filter(
+        ([k]) => (validKeys.includes(k)),
+      ).map(
+        ([k, v]) => ([k, stringifyInput(v)]),
+      ),
+    );
+    return Object.assign(Object.create(null), pruned);
+  }
+}

package/src/lib/validators/regex.js

@@ -0,0 +1,48 @@
+/* eslint-disable class-methods-use-this */
+import ValidatorFactory from '../ValidatorFactory.js';
+import ValidationError from '../ValidationError.js';
+import { stringifyInput } from '../utils.js';
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} RegexConfigOptions
+ * @property {ErrorMessageConfig} errorMsg Error message config
+ * @property {RegExp} pattern Regular expression to test against
+ * @property {boolean} invert Return error on positive regex match
+ */
+
+/**
+ * Match a string pattern.
+ *
+ * See {@link RegexConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class Regex extends ValidatorFactory {
+  name = 'regex';
+
+  validate(value = '', dataContext = {}) {
+    const invert = this.config.invert || false;
+    const match = value.match(this.config.pattern || /.*/);
+    const valid = invert ? !match : match;
+
+    const errorMsg = this.config.errorMsg || {
+      inline: 'validation:rule.regex.inline',
+      summary: 'validation:rule.regex.summary',
+    };
+
+    return valid ? [] : [ValidationError.make({ errorMsg, dataContext })];
+  }
+
+  sanitise(value) {
+    if (value !== undefined) {
+      return stringifyInput(value);
+    }
+    return undefined;
+  }
+}

package/src/lib/validators/required.js

@@ -0,0 +1,74 @@
+/* eslint-disable class-methods-use-this */
+import lodash from 'lodash';
+import { isEmpty, isStringable, stringifyInput } from '../utils.js';
+import ValidatorFactory from '../ValidatorFactory.js';
+import ValidationError from '../ValidationError.js';
+
+const { isPlainObject } = lodash; // CommonJS
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} RequiredConfigOptions
+ * @property {ErrorMessageConfig} errorMsg Error message config
+ */
+
+/**
+ * Test if value is present.
+ *
+ * Value is required. The following values will fail this rule:
+ *  (all values that satisfy `isEmpty()`) plus '\s'
+ *
+ * See {@link RequiredConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class Required extends ValidatorFactory {
+  name = 'required';
+
+  validate(value, dataContext = {}) {
+    const {
+      errorMsg = {
+        inline: 'validation:rule.required.inline',
+        summary: 'validation:rule.required.summary',
+      },
+    } = this.config;
+
+    if (!isEmpty(value)) {
+      return []
+    }
+
+    return [
+      ValidationError.make({ errorMsg, dataContext }),
+    ];
+  }
+
+  sanitise(value) {
+    const coerce = (val) => {
+      const s = stringifyInput(val, undefined);
+      return s === undefined ? undefined : s.replace(/^\s+$/, '');
+    };
+
+    if (isStringable(value)) {
+      return coerce(value);
+    }
+
+    // Coerce all elements to Strings.
+    // This only supports one dimensional array, with stringable element.
+    if (Array.isArray(value)) {
+      return value.map(coerce);
+    }
+
+    // Coerce all elements to Strings.
+    // This only supports a one dimensional object, with stringable elements.
+    if (isPlainObject(value)) {
+      return Object.fromEntries(Object.entries(value).map(([k, v]) => ([k, coerce(v)])));
+    }
+
+    return undefined;
+  }
+}

package/src/lib/validators/strlen.js

@@ -0,0 +1,66 @@
+/* eslint-disable class-methods-use-this */
+import ValidatorFactory from '../ValidatorFactory.js';
+import ValidationError from '../ValidationError.js';
+import { stringifyInput } from '../utils.js';
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} StrlenConfigOptions
+ * @property {ErrorMessageConfig} errorMsgMax Error message to use on max length failure
+ * @property {ErrorMessageConfig} errorMsgMin Error message to use on min length failure
+ * @property {number} max Maximum string length allowed
+ * @property {number} min Minimum string length required
+ */
+
+/**
+ * Test the length of a string.
+ *
+ * See {@link StrlenConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class Strlen extends ValidatorFactory {
+  name = 'strlen';
+
+  validate(inputValue = '', dataContext = {}) {
+    const {
+      errorMsgMax = {
+        inline: 'validation:rule.strlen.max.inline',
+        summary: 'validation:rule.strlen.max.summary',
+      },
+      errorMsgMin = {
+        inline: 'validation:rule.strlen.min.inline',
+        summary: 'validation:rule.strlen.min.summary',
+      },
+      min,
+      max,
+    } = this.config;
+
+    let errorMsg;
+    let valid = true;
+
+    if (typeof max !== 'undefined' && inputValue.length > max) {
+      valid = false;
+      errorMsg = errorMsgMax;
+    }
+
+    if (typeof min !== 'undefined' && inputValue.length < min) {
+      valid = false;
+      errorMsg = errorMsgMin;
+    }
+
+    return valid ? [] : [ValidationError.make({ errorMsg, dataContext })];
+  }
+
+  sanitise(value) {
+    if (value !== undefined) {
+      return stringifyInput(value);
+    }
+    return undefined;
+  }
+}

package/src/lib/validators/wordCount.js

@@ -0,0 +1,70 @@
+/* eslint-disable class-methods-use-this */
+import ValidatorFactory from '../ValidatorFactory.js';
+import ValidationError from '../ValidationError.js';
+import { stringifyInput } from '../utils.js';
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} WordcountConfigOptions
+ * @property {ErrorMessageConfig} errorMsgMax Error message to use on max length failure
+ * @property {ErrorMessageConfig} errorMsgMin Error message to use on min length failure
+ * @property {number} max Maximum string length allowed
+ * @property {number} min Minimum string length required
+ */
+
+/**
+ * Test the number of words in a string.
+ *
+ * See {@link WordcountConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class WordCount extends ValidatorFactory {
+  name = 'wordCount';
+
+  count(input) {
+    return (input.match(/\S+/g) || []).length;
+  }
+
+  validate(inputValue = '', dataContext = {}) {
+    const {
+      errorMsgMax = {
+        inline: 'validation:rule.wordCount.max.inline',
+        summary: 'validation:rule.wordCount.max.summary',
+      },
+      errorMsgMin = {
+        inline: 'validation:rule.wordCount.min.inline',
+        summary: 'validation:rule.wordCount.min.summary',
+      },
+      min,
+      max,
+    } = this.config;
+
+    let errorMsg;
+    let valid = true;
+
+    if (typeof max !== 'undefined' && (inputValue.match(/\S+/g) || []).length > max) {
+      valid = false;
+      errorMsg = errorMsgMax;
+    }
+
+    if (typeof min !== 'undefined' && (inputValue.match(/\S+/g) || []).length < min) {
+      valid = false;
+      errorMsg = errorMsgMin;
+    }
+
+    return valid ? [] : [ValidationError.make({ errorMsg, dataContext })];
+  }
+
+  sanitise(value) {
+    if (value !== undefined) {
+      return stringifyInput(value);
+    }
+    return undefined;
+  }
+}

package/src/lib/waypoint-url.js

@@ -0,0 +1,93 @@
+/**
+ * @access private
+ * @typedef {import('./index').JourneyContext} JourneyContext
+ */
+
+/** @access private */
+const reUrlProtocolExtract = /^url:\/\/(.+)$/i
+
+/**
+ * Sanitise a waypoint string.
+ *
+ * @access private
+ * @param {string} w Waypoint
+ * @returns {string} Sanitised waypoint
+ */
+const sanitiseWaypoint = (w) => w.replace(/[^/a-z0-9_-]/ig, '').replace(/\/+/g, '/');
+
+/**
+ * Generate a URL pointing at a particular waypoint.
+ *
+ * @example
+ * // generates: /path/details?edit&editorigin=%2Fsomewhere%2Felse
+ * waypointUrl({
+ *   mountUrl: '/path/',
+ *   waypoint: 'details',
+ *   edit: true,
+ *   editOrigin: '/somewhere/else'
+ * })
+ * @memberof module:@dwp/govuk-casa
+ * @param {object} obj Options
+ * @param {string} [obj.waypoint=""] Waypoint
+ * @param {string} [obj.mountUrl="/"] Mount URL
+ * @param {JourneyContext} [obj.journeyContext] JourneyContext
+ * @param {boolean} [obj.edit=false] Turn edit mode on or off
+ * @param {string} [obj.editOrigin] Edit mode original URL
+ * @param {boolean} [obj.skipTo] Skip to this waypoint from the current one
+ * @param {string} [obj.routeName=next] Plan route name; next | prev
+ * @returns {string} URL
+ */
+export default function waypointUrl({
+  waypoint = '',
+  mountUrl = '/',
+  journeyContext,
+  edit = false,
+  editOrigin,
+  skipTo,
+  routeName = 'next',
+} = Object.create(null)) {
+  const url = new URL('https://placeholder.test');
+
+  // Handle url:// protocol
+  // - This will generate a link to the root handler "_" for the given mount path
+  if (String(waypoint).substr(0, 7) === 'url:///') {
+    const m = waypoint.match(reUrlProtocolExtract);
+
+    const u = new URL(m[1], 'https://placeholder.test/');
+    url.pathname = `${sanitiseWaypoint(u.pathname)}/_/`;
+
+    url.searchParams.append('refmount', `url://${mountUrl}`);
+    url.searchParams.append('route', routeName);
+  } else {
+    url.pathname = `${mountUrl}${waypoint}`;
+  }
+
+  // Attach context ID as query parameter for non-default contexts.
+  // To avoid messy URLs with duplicated content, this parameter will _not_ be
+  // added if the context ID already appears in the url path, i.e. to avoid
+  // `/path/1234-abcd/waypoint?contextid=1234-abcd` scenarios
+  if (
+    journeyContext
+    && !journeyContext.isDefault()
+    && journeyContext.identity.id
+    && !mountUrl.includes(journeyContext.identity.id)
+  ) {
+    url.searchParams.append('contextid', journeyContext.identity.id);
+  }
+
+  // Attach edit mode flag
+  if (edit === true) {
+    url.searchParams.append('edit', 'true');
+  }
+
+  if (edit && editOrigin) {
+    url.searchParams.append('editorigin', sanitiseWaypoint(editOrigin));
+  }
+
+  // Skipto
+  if (skipTo) {
+    url.searchParams.append('skipto', sanitiseWaypoint(skipTo));
+  }
+
+  return `${sanitiseWaypoint(url.pathname)}${url.search}`;
+}