@dwp/govuk-casa 8.7.9 → 8.8.0

package/src/lib/field.js

@@ -0,0 +1,456 @@
+import lodash from 'lodash';
+import { isEmpty } from './utils.js';
+import logger from './logger.js';
+
+const log = logger('lib:field');
+const { isFunction } = lodash;
+
+/**
+ * @access private
+ * @typedef {import('./index').JourneyContext} JourneyContext
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').Validator} Validator
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').ValidateContext} ValidateContext
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').ValidatorConditionFunction} ValidatorConditionFunction
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').FieldProcessorFunction} FieldProcessorFunction
+ */
+
+/**
+ * @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 class is not exposed via the public API. Instances should instead be
+ * instantiated through the `field()` factory function.
+ *
+ * @class
+ */
+export class PageField {
+  /**
+   * @type {string}
+   */
+  #name;
+
+  /**
+   * @type {FieldProcessorFunction[]}
+   */
+  #processors;
+
+  /**
+   * @type {Validator[]}
+   */
+  #validators;
+
+  /**
+   * @type {ValidatorConditionFunction[]}
+   */
+  #conditions;
+
+  /**
+   * @type {object}
+   */
+  #meta;
+
+  /**
+   * 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)) {
+    if (!name) {
+      throw new SyntaxError('A name for this field is required, i.e. "field(\'myField\')".');
+    }
+
+    this.#name = undefined;
+    this.#validators = [];
+    this.#processors = [];
+    this.#conditions = [];
+
+    this.#meta = {
+      optional,
+      persist,
+      complex: undefined,
+      complexFieldName: undefined,
+      complexFieldProperty: undefined,
+    };
+
+    // Apply name
+    /* eslint-disable-next-line security/detect-non-literal-fs-filename */
+    this.rename(name);
+  }
+
+  /**
+   * Clone this field.
+   *
+   * @returns {PageField} Cloned field
+   */
+  clone() {
+    const clone = new PageField(this.#name, {
+      optional: this.#meta.optional,
+      persist: this.#meta.persist,
+    });
+
+    if (this.getValidators()) {
+      clone.validators(this.getValidators());
+    }
+    if (this.getConditions()) {
+      clone.conditions(this.getConditions());
+    }
+    if (this.getProcessors()) {
+      clone.processors(this.getProcessors());
+    }
+
+    return clone;
+  }
+
+  /**
+   * 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
+   */
+  getValue(obj = Object.create(null)) {
+    if (this.#meta.complex) {
+      return obj[this.#meta.complexFieldName]?.[this.#meta.complexFieldProperty];
+    }
+    return obj[this.#name];
+  }
+
+  /**
+   * Store this field's value in the given object, using its name as the key.
+   *
+   * For complex fields, the field object will be created if it does not yet
+   * exist, before then storing the property within that object.
+   *
+   * @param {object} obj Object from which to extract the value
+   * @param {any} value Value to be stored
+   * @returns {any} Value extracted from object
+   */
+  putValue(obj = Object.create(null), value = undefined) {
+    if (this.#meta.complex) {
+      /* eslint-disable-next-line no-param-reassign */
+      obj[this.#meta.complexFieldName] = {
+        ...(obj[this.#meta.complexFieldName] ?? {}),
+        [this.#meta.complexFieldProperty]: value,
+      };
+    } else {
+      /* eslint-disable-next-line no-param-reassign */
+      obj[this.#name] = value;
+    }
+
+    return this;
+  }
+
+  /* -------------------------------------------------------------- configure */
+
+  get name() {
+    return this.#name;
+  }
+
+  get meta() {
+    return this.#meta;
+  }
+
+  /**
+   * Rename this field.
+   *
+   * @param {string} name New name to be applied
+   * @returns {PageField} Chain
+   * @throws {SyntaxError} When the name is invalid in some way
+   */
+  rename(name) {
+    if (reInvalidName.test(String(name))) {
+      throw new SyntaxError(`Field '${String(name)}' name contains invalid characters.`);
+    }
+
+    // Complex names are only supported to one level deep. For example,
+    // `field[prop]` is supported, whilst `field[prop][subprop]` is not. Throw
+    // early to aid developer.
+    const isComplex = reComplexType.test(name);
+    if (isComplex && name.match(/\[/g).length > 1) {
+      throw new SyntaxError('Complex field names are only supported to 1 property depth. E.g. a[b] is ok, a[b][c] is not');
+    }
+
+    this.#name = String(name);
+    this.#meta.complex = isComplex;
+
+    // Extract the field name and property from a complex type for later use
+    if (isComplex) {
+      const parts = name.match(reComplexType);
+      [, this.#meta.complexFieldName, this.#meta.complexFieldProperty] = parts;
+    }
+
+    return this;
+  }
+
+  /**
+   * Get validators
+   *
+   * @returns {Validator[]} A list containing all validators.
+   */
+  getValidators() {
+    return this.#validators;
+  }
+
+  /**
+   * Add/get value validators
+   * Some validators will include a `sanitise()` method which will be run at the
+   * same time as other "processors".
+   *
+   * @param {Validator[]} items Validation functions
+   * @returns {PageField} Chain - Deprecated: this currently gets all validators if
+   * empty or missing, in v9 this functionality will removed in favour of the
+   * function getValidators().
+   */
+  validators(items = []) {
+    if (!items.length) {
+      log.warn('Calling validators() to get all validators is deprecated, please use getValidators()');
+      return this.getValidators();
+    }
+    this.#validators = [...this.#validators, ...(items.flat())];
+    return this;
+  }
+
+  /**
+   * Get processors
+   *
+   * @returns {FieldProcessorFunction[]} A list containing all processors.
+   */
+  getProcessors() {
+    return this.#processors;
+  }
+
+  /**
+   * Add/get value pre-processors
+   * This is most often used to sanitise values to a particular data type.
+   *
+   * @param {FieldProcessorFunction[]} items Processor functions
+   * @returns {PageField} Chain - Deprecated: this currently gets all processors if
+   * empty or missing, in v9 this functionality will removed in favour of the
+   * function getProcessors().
+   */
+  processors(items = []) {
+    if (!items.length) {
+      log.warn('Calling processors() to get all processors is deprecated, please use getProcessors()');
+      return this.getProcessors();
+    }
+
+    this.#processors = [...this.#processors, ...(items.flat())];
+    return this;
+  }
+
+  /**
+   * Get conditions
+   *
+   * @returns {ValidatorConditionFunction[]} A list containing all conditions.
+   */
+  getConditions() {
+    return this.#conditions;
+  }
+
+  /**
+   * Add/get conditions
+   * All conditions must be met in order for this field to be considered
+   * "actionable".
+   *
+   * @param {ValidatorConditionFunction[]} items Condition functions
+   * @returns {PageField} Chain - Deprecated: this currently gets all conditions if
+   * empty or missing, in v9 this functionality will removed in favour of the
+   * function getConditions().
+   */
+  conditions(items = []) {
+    if (!items.length) {
+      log.warn('Calling conditions() to get all conditions is deprecated, please use getConditions()');
+      return this.getConditions();
+    }
+    this.#conditions = [...this.#conditions, ...(items.flat())];
+    return this;
+  }
+
+  /* ---------------------------------------------------------------- execute */
+
+  /**
+   * Run all validators and return array of errors, if applicable.
+   *
+   * @param {any} value Value to validate
+   * @param {ValidateContext} context Contextual validation information
+   * @returns {ValidationError[]} Errors, or an empty array if all valid
+   * @throws {TypeError} If validator does not return an array
+   */
+  runValidators(value, context = Object.create(null)) {
+    // Skip validation if the field is empty and optional
+    if (this.#meta.optional && isEmpty(value)) {
+      return [];
+    }
+
+    // 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 = context.fieldValue ?? value;
+    if (!this.testConditions(context)) {
+      return [];
+    }
+
+    let errors = [];
+    for (let i = 0, l = this.#validators.length; i < l; i++) {
+      // ESLint disabled as `i` is an integer
+      /* eslint-disable security/detect-object-injection */
+      // TODO: Replace `value` with `context.fieldValue` here
+      let fieldErrors = this.#validators[i].validate(value, context)
+      if (!Array.isArray(fieldErrors)) {
+        // Friendly message for developer
+        throw new TypeError(`The validator at index ${i} (name: ${this.#validators[i].name || 'unknown'}) for field '${this.#name}' did not return an array`);
+      }
+
+      fieldErrors = fieldErrors.map((e) => e.withContext({
+        ...context,
+        validator: this.#validators[i].name,
+      }));
+      /* eslint-enable security/detect-object-injection */
+
+      errors = [
+        ...errors,
+        ...(fieldErrors ?? []),
+      ];
+    }
+
+    return errors;
+  }
+
+  /**
+   * Apply all the processors to the given value.
+   *
+   * @param {any} value Value to process
+   * @returns {any} Processed value
+   */
+  applyProcessors(value) {
+    let processedValue = value;
+
+    // Some of the validators may have their own "sanitise()" methods. These
+    // should be run before any other processors
+    // ESLint disabled as `i` is an integer
+    /* eslint-disable security/detect-object-injection */
+    for (let i = 0, l = this.#validators.length; i < l; i++) {
+      if (isFunction(this.#validators[i].sanitise)) {
+        processedValue = this.#validators[i].sanitise(processedValue);
+      }
+    }
+    /* eslint-enable security/detect-object-injection */
+
+    for (let i = 0, l = this.#processors.length; i < l; i++) {
+      // ESLint disabled as `i` is an integer
+      /* eslint-disable-next-line security/detect-object-injection */
+      processedValue = this.#processors[i](processedValue);
+    }
+    return processedValue;
+  }
+
+  /**
+   * All conditions must return true to be considered a successful test.
+   *
+   * @param {ValidateContext} context Contextual validation information
+   * @returns {boolean} True if all conditions pass
+   */
+  testConditions({ fieldValue, waypoint, journeyContext }) {
+    const context = {
+      fieldName: this.#name,
+      fieldValue,
+      waypoint,
+      waypointId: waypoint, // [DEPRECATED] for backwards compatibility with v7
+      journeyContext,
+    };
+
+    let result = true;
+    for (let i = 0, l = this.#conditions.length; i < l; i++) {
+      // ESLint disabled as `i` is an integer
+      /* eslint-disable-next-line security/detect-object-injection */
+      result = result && this.#conditions[i](context);
+    }
+    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);
+  }
+}
+
+/**
+ * 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, opts) {
+  return new PageField(name, opts);
+}

package/src/lib/index.js

@@ -0,0 +1,33 @@
+/**
+ * Just used to collate type information for intellisense. This should not get
+ * imported anywhere in code, other than JSDoc references.
+ */
+
+import CasaTemplateLoader from './CasaTemplateLoader.js';
+import configure from './configure.js';
+import configurationIngestor from './configuration-ingestor.js';
+import endSession from './end-session.js';
+import field, { PageField } from './field.js';
+import JourneyContext from './JourneyContext.js';
+import MutableRouter from './MutableRouter.js';
+import Plan from './Plan.js';
+import ValidationError from './ValidationError.js';
+import ValidatorFactory from './ValidatorFactory.js';
+import waypointUrl from './waypoint-url.js';
+import * as utils from './utils.js';
+
+export {
+  CasaTemplateLoader,
+  configure,
+  configurationIngestor,
+  endSession,
+  field,
+  PageField,
+  JourneyContext,
+  MutableRouter,
+  Plan,
+  utils,
+  ValidationError,
+  ValidatorFactory,
+  waypointUrl,
+};

package/src/lib/logger.js

@@ -0,0 +1,16 @@
+import debug from 'debug';
+
+const casaDebugger = debug('casa');
+
+export default (namespace) => {
+  const logger = casaDebugger.extend(namespace);
+
+  return {
+    trace: logger.extend('trace'),
+    debug: logger.extend('debug'),
+    info: logger.extend('info'),
+    warn: logger.extend('warn'),
+    error: logger.extend('error'),
+    fatal: logger.extend('fatal'),
+  };
+}

package/src/lib/mount.js

@@ -0,0 +1,127 @@
+import { Router } from 'express';
+import { pathToRegexp } from 'path-to-regexp';
+
+import stripProxyPathMiddlewareFactory from '../middleware/strip-proxy-path.js';
+import serveFirstWaypointMiddlewareFactory from '../middleware/serve-first-waypoint.js';
+
+/**
+ * @access private
+ * @typedef {import('nunjucks').Environment} NunjucksEnvironment
+ */
+
+/**
+ * @access private
+ * @typedef {import('express').RequestHandler} ExpressRequestHandler
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').Mounter} Mounter
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').Plan} Plan
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').MutableRouter} MutableRouter
+ */
+
+/**
+ * Mounting function factory.
+ *
+ * @param {object} args Arguments
+ * @param {NunjucksEnvironment} args.nunjucksEnv Pre-configured Nunjucks environment
+ * @param {string} [args.mountUrl] Mount URL
+ * @param {Plan} [args.plan] CASA Plan
+ * @param {MutableRouter} args.staticRouter Router for all static assets
+ * @param {MutableRouter} args.ancillaryRouter Router for all ancillary routes
+ * @param {MutableRouter} args.journeyRouter Router for all waypoints
+ * @param {ExpressRequestHandler[]} args.preMiddleware Middleware
+ * @param {ExpressRequestHandler[]} args.sessionMiddleware Middleware
+ * @param {ExpressRequestHandler[]} args.i18nMiddleware Middleware
+ * @param {ExpressRequestHandler[]} args.bodyParserMiddleware Middleware
+ * @param {ExpressRequestHandler[]} args.dataMiddleware Middleware
+ * @param {ExpressRequestHandler[]} args.postMiddleware Middleware
+ * @returns {Mounter} mount
+ */
+export default ({
+  nunjucksEnv,
+  mountUrl,
+  plan,
+  staticRouter,
+  ancillaryRouter,
+  journeyRouter,
+  preMiddleware,
+  sessionMiddleware,
+  i18nMiddleware,
+  bodyParserMiddleware,
+  dataMiddleware,
+  postMiddleware,
+}) => (
+  app,
+  {
+    route = '/',
+    serveFirstWaypoint = false,
+  } = {},
+) => {
+  nunjucksEnv.express(app);
+  app.set('view engine', 'njk');
+
+  // If a `mountUrl` has been defined, then we're potentially in "proxy mode",
+  // in which we strip the proxy path prefix from the incoming request URLs.
+  if (mountUrl) {
+    app.use(stripProxyPathMiddlewareFactory({ mountUrl }));
+  }
+
+  // Attach a handler to redirect requests for `/` to the first waypoint in
+  // the plan
+  if (serveFirstWaypoint && plan) {
+    const re = pathToRegexp(`${route}`.replace(/\/+/g, '/'));
+    app.use(re, serveFirstWaypointMiddlewareFactory({ plan }));
+  }
+
+  // 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.
+  const sealedStaticRouter = staticRouter.seal();
+  app.use(preMiddleware);
+  app.use(sealedStaticRouter);
+
+  const router = Router({
+    // Required so that any parameters in the URL are propagated to middleware
+    mergeParams: true,
+  });
+
+  router.use(preMiddleware);
+  // !!! DEPRECATE in v9 !!! For performance reasons, static assets will
+  // always be handled via the `app` middleware rather than `router`.
+  // Anywhere `mountUrl` is used in templates to service static assets must be
+  // changed to use `staticMountUrl`.
+  // TASK: remove this line below
+  router.use(sealedStaticRouter);
+  router.use(sessionMiddleware);
+  router.use(i18nMiddleware);
+  router.use(bodyParserMiddleware);
+  router.use(dataMiddleware);
+  router.use(ancillaryRouter.seal());
+  router.use(journeyRouter.seal());
+  router.use(postMiddleware);
+
+  app.use(route, router);
+
+  return app;
+};