@dwp/govuk-casa 6.8.4 → 6.9.0

package/lib/validation/ObjectField.js

@@ -8,9 +8,10 @@
  *  }
  *
  * @param {object} obj Object of fields that will be tested
- * @param {array|null} validators Validation rules that must be satisfied
- * @param {function|null} condition Condition to meet before validators are run
- * @return {object} Validation object suitable for processing
+ * @param {Array|null} validators Validation rules that must be satisfied
+ * @param {Function|null} condition Condition to meet before validators are run
+ * @returns {object} Validation object suitable for processing
+ * @throws {TypeError} When arguments are invalid
  */
 module.exports = (obj = {}, validators = [], condition) => {
   if (Object.prototype.toString.call(obj) !== '[object Object]') {

package/lib/validation/SimpleField.js

@@ -1,9 +1,10 @@
 /**
  * A simple field.
  *
- * @param {array} validators Validation rules (bindable functions) to satisfy
- * @param {Function|null} condition Condition to meet before validators are run
- * @return {object} Validation object suitable for processing
+ * @param {Array} validators Validation rules (bindable functions) to satisfy.
+ * @param {Function|null} condition Condition to meet before validators are run.
+ * @returns {object} Validation object suitable for processing.
+ * @throws {TypeError} When validator or condition is an invalid type
  */
 module.exports = (validators = [], condition) => {
   validators.forEach((v) => {

package/lib/validation/ValidationError.js

@@ -14,13 +14,13 @@ class ValidationError {
    *   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
+   *   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
+   *   journeyContext => The full JourneyContext of the current request.
    *
    * Example function signature that can be used for `errorMsg`:
    *   ({ waypointId, fieldName, journeyContext }) => ({
@@ -31,7 +31,10 @@ class ValidationError {
    *   });
    *
    * @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
+   * @throws {TypeError} If errorMsg is not in a valid type
    */
   static make({ errorMsg, dataContext = {} }) {
     // Convert strings to the most basic object primitive

package/lib/validation/processor/flattenErrorArray.js

@@ -4,8 +4,9 @@ const ValidationError = require('../ValidationError.js');
  * Converts a (potentially) deeply nested array of ValidationErrors into a flat
  * array.
  *
- * @param  {array} errorsArray Array of errors
- * @return {array} The flatted array
+ * @param  {Array<ValidationError>} errorsArray Array of errors.
+ * @returns {Array} The flatted array.
+ * @throws {TypeError} When error is not a ValidationError
  */
 module.exports = (errorsArray = []) => {
   let errors = errorsArray;

package/lib/validation/processor/queue.js

@@ -10,13 +10,13 @@ const T_ARRAY_OBJECT = 'array_object';
 /**
  * Add a validator object to the processing queue.
  *
- * @param  {array} queue Queue to which validators will be added
- * @param  {string} waypointId Waypoint under validation
- * @param  {PageMeta} pageMeta Meta object representing the page being validated
- * @param  {object} journeyContext Full JourneyContext
- * @param  {string} field Field to validate (in square-brace notation)
- * @param  {object} validatorObj Validation attributes to apply
- * @return {void}
+ * @param  {Array} queue Queue to which validators will be added.
+ * @param  {string} waypointId Waypoint under validation.
+ * @param  {PageMeta} pageMeta Meta object representing the page being validated.
+ * @param  {object} journeyContext Full JourneyContext.
+ * @param  {string} field Field to validate (in square-brace notation).
+ * @param  {object} validatorObj Validation attributes to apply.
+ * @returns {void}
  */
 /* eslint-disable-next-line consistent-return,require-jsdoc */
 function queueValidator(queue, waypointId, pageMeta, journeyContext, field, validatorObj) {
@@ -51,13 +51,13 @@ function queueValidator(queue, waypointId, pageMeta, journeyContext, field, vali
 /**
  * Add a Validation.SimpleField object to the processing queue.
  *
- * @param  {array} queue Queue to which validators will be added
- * @param  {string} waypointId Waypoint under validation
- * @param  {PageMeta} pageMeta Meta object representing the page being validated
- * @param  {object} journeyContext Full JourneyContext
- * @param  {string} field Field to validate (in square-brace notation)
- * @param  {object} validatorObj Validation attributes to apply
- * @return {void}
+ * @param  {Array} queue Queue to which validators will be added.
+ * @param  {string} waypointId Waypoint under validation.
+ * @param  {PageMeta} pageMeta Meta object representing the page being validated.
+ * @param  {object} journeyContext Full JourneyContext.
+ * @param  {string} field Field to validate (in square-brace notation).
+ * @param  {object} validatorObj Validation attributes to apply.
+ * @returns {void}
  */
 function queueSimpleValidator(queue, waypointId, pageMeta, journeyContext, field, validatorObj) {
   // Ensure pageMeta.id is defined when extracting data for the waypoint
@@ -136,13 +136,13 @@ function queueSimpleValidator(queue, waypointId, pageMeta, journeyContext, field
 /**
  * Add a Validation.ObjectField object to the queue.
  *
- * @param  {array} queue Queue to which validators will be added
- * @param  {string} waypointId Waypoint under validation
- * @param  {PageMeta} pageMeta Meta object representing the page being validated
- * @param  {object} journeyContext Full JourneyContext
- * @param  {string} field Field to validate (in square-brace notation)
- * @param  {object} validatorObj Validation attributes to apply
- * @return {void}
+ * @param  {Array} queue Queue to which validators will be added.
+ * @param  {string} waypointId Waypoint under validation.
+ * @param  {PageMeta} pageMeta Meta object representing the page being validated.
+ * @param  {object} journeyContext Full JourneyContext.
+ * @param  {string} field Field to validate (in square-brace notation).
+ * @param  {object} validatorObj Validation attributes to apply.
+ * @returns {void}
  */
 function queueObjectValidator(queue, waypointId, pageMeta, journeyContext, field, validatorObj) {
   // Add this validator's rules to the queue (if any)
@@ -165,13 +165,13 @@ function queueObjectValidator(queue, waypointId, pageMeta, journeyContext, field
 /**
  * Add a Validation.ArrayObjectField object to the queue.
  *
- * @param  {array} queue Queue to which validators will be added
- * @param  {string} waypointId Waypoint under validation
- * @param  {PageMeta} pageMeta Meta object representing the page being validated
- * @param  {object} journeyContext Full JourneyContext
- * @param  {string} field Field to validate (in square-brace notation)
- * @param  {object} validatorObj Validation attributes to apply
- * @return {void}
+ * @param  {Array} queue Queue to which validators will be added.
+ * @param  {string} waypointId Waypoint under validation.
+ * @param  {PageMeta} pageMeta Meta object representing the page being validated.
+ * @param  {object} journeyContext Full JourneyContext.
+ * @param  {string} field Field to validate (in square-brace notation).
+ * @param  {object} validatorObj Validation attributes to apply.
+ * @returns {void}
  */
 function queueArrayObjectValidator(
   queue, waypointId, pageMeta, journeyContext, field, validatorObj,

package/lib/validation/processor.js

@@ -17,7 +17,11 @@ const { queueValidator } = require('./processor/queue.js');
  *   bool reduceErrors = Reduces each field to a single error (default false)
  *
  * @param {object} params Parameters object as above
- * @return {Promise} Promise
+ * @param {string} params.waypointId Waypoint ID
+ * @param {object} params.pageMeta Page meta
+ * @param {Function} params.journeyContext Journey context
+ * @param {boolean} params.reduceErrors True is errors should be reduced to a single error
+ * @returns {Promise} Promise
  */
 // module.exports = (fieldValidators = {}, userData = {}, options = {}) => {
 module.exports = ({
@@ -36,8 +40,8 @@ module.exports = ({
    * have multiple validation rules that may each be violated and thus result
    * in their own error messages, which can quickly stack up on larger pages.
    *
-   * @param {object} errors All errors
-   * @return {object} Reduced error list, indexed by field name
+   * @param {object} errors All errors.
+   * @returns {object} Reduced error list, indexed by field name.
    */
   function reduceGroupedErrors(errors) {
     const reduced = Object.create(null);
@@ -52,8 +56,8 @@ module.exports = ({
    * object indexed by the field names. This makes it easier to reference errors
    * in the front-end template.
    *
-   * @param  {array} errorsList Array of errors
-   * @return {Promise} Promise
+   * @param  {Array} errorsList Array of errors.
+   * @returns {Promise} Promise.
    */
   function gatherErrors(errorsList) {
     let grouped = Object.create(null);

package/lib/validation/rules/dateObject.js

@@ -7,7 +7,7 @@ const ValidationError = require('../ValidationError.js');
  *    dd: <string>,
  *    mm: <string>,
  *    yyyy: <string>
- *  }
+ *  }.
  *
  * Note that the time part of any injected "moment" objects will be zero'ed, as
  * we are only interested in the date component (minimum day resolution).
@@ -25,7 +25,7 @@ const ValidationError = require('../ValidationError.js');
  *
  * @param  {object} value Date object (see description)
  * @param  {object} dataContext Context
- * @return {Promise} Promise
+ * @returns {Promise} Promise
  */
 function dateObject(value, dataContext = {}) {
   const config = {

package/lib/validation/rules/email.js

@@ -7,7 +7,7 @@
  *   string|object errorMsg = Error message to use on validation failure
  *
  * @param  {string} value Email address
- * @return {Promise} Promise
+ * @returns {Promise} Promise
  */
 
 const { isEmail } = require('validator');

package/lib/validation/rules/inArray.js

@@ -2,13 +2,13 @@
  * Test if a value is present in an array.
  *
  * Bound attributes:
- *   Array source = Array of values to test against
+ *   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.
  *
- * @param  {mixed} value Value to find
- * @return {Promise} Promise
+ * @param  {any} value Value to find.
+ * @returns {Promise} Promise.
  */
 const ValidationError = require('../ValidationError.js');
 

package/lib/validation/rules/nino.js

@@ -3,14 +3,14 @@
  *
  * Bound attributes:
  *   string|object errorMsg = Error message to use on validation failure
- *   boolean allowWhitespace = will permit input values that contain spaces
+ *   boolean allowWhitespace = will permit input values that contain spaces.
  *
  * Ref:
  * https://en.wikipedia.org/wiki/National_Insurance_number#Format
  * https://design-system.service.gov.uk/patterns/national-insurance-numbers/
  *
  * @param  {string} value NI number
- * @return {Promise} Promise
+ * @returns {Promise} Promise
  */
 const ValidationError = require('../ValidationError.js');
 

package/lib/validation/rules/optional.js

@@ -4,8 +4,8 @@ const Util = require('../../Util.js');
  * This is different to all other rules in that it _must_ return a value
  * synchronously. You must not `bind()` this function to create a new one.
  *
- * @param  {mixed} value Value
- * @return {bool} Return true if the value is not present
+ * @param  {any} value Value.
+ * @returns {boolean} Return true if the value is not present.
  */
 function optional(value) {
   return Util.isEmpty(value);

package/lib/validation/rules/postalAddressObject.js

@@ -12,11 +12,11 @@
  *   string|object errorMsgAddress3 = Error message for address3 part
  *   string|object errorMsgAddress4 = Error message for address4 part
  *   string|object errorMsgPostcode = Error message for postcode part
- *   int strlenmax = Max. string length for each of the inputs appress[1-4]
+ *   int strlenmax = Max. String length for each of the inputs appress[1-4]
  *   array requiredFields = Field parts required (others become optional)
  *
  * @param {object} value Address object to test
- * @return {Promise} Promise
+ * @returns {Promise} Promise
  */
 const ValidationError = require('../ValidationError.js');
 

package/lib/validation/rules/regex.js

@@ -7,7 +7,7 @@
  *   boolean invert = return reject on positive regex match
  *
  * @param  {string} value String to check
- * @return {Promise} Promise
+ * @returns {Promise} Promise
  */
 const ValidationError = require('../ValidationError.js');
 

package/lib/validation/rules/required.js

@@ -1,5 +1,5 @@
 /**
- * required
+ * Required.
  */
 const Util = require('../../Util.js');
 const ValidationError = require('../ValidationError.js');
@@ -10,9 +10,9 @@ const ValidationError = require('../ValidationError.js');
  * Value is required. The following values will fail this rule:
  *  (all values that satisify `Util.isEmpty()`) plus '\s'
  *
- * @param  {mixed} value Value to test
+ * @param  {any} value Value to test
  * @param  {object} dataContext Context
- * @return {Promise} Promise
+ * @returns {Promise} Promise
  */
 function required(value, dataContext = {}) {
   let result;

package/lib/validation/rules/strlen.js

@@ -8,7 +8,7 @@
  *   int min = Minimum string length required
  *
  * @param  {string} inputValue Value to test
- * @return {Promise} Promise
+ * @returns {Promise} Promise
  */
 const ValidationError = require('../ValidationError.js');
 

package/lib/view-filters/formatDateObject.js

@@ -10,10 +10,13 @@ const moment = require('moment');
  * `date` may be any of the following types:
  *   object - {dd:'', mm:'', yyyy:''}
  *
- * @param  {mixed} date Date (see supported formats above)
- * @return {string} Formatted date
+ * @param  {object} date Date (see supported formats above)
+ * @param  {object} config Holds locale
+ * @returns {string} Formatted date
  */
-module.exports = function formatDateObject(date, { locale = 'en' } = {}) {
+module.exports = function formatDateObject(date, config = {}) {
+  const { locale = 'en' } = config;
+
   if (
     Object.prototype.toString.call(date) === '[object Object]'
     && 'yyyy' in date

package/lib/view-filters/includes.js

@@ -1,9 +1,9 @@
 /**
- * Test if an array includes the given element
+ * Test if an array includes the given element.
  *
- * @param  {array} source Array to search
- * @param  {mixed} search Element to search for
- * @return {boolean} Result
+ * @param  {Array} source Array to search.
+ * @param  {any} search Element to search for.
+ * @returns {boolean} Result.
  */
 module.exports = function includes(source = [], search = '') {
   return source.includes(search);

package/lib/view-filters/index.js

@@ -13,7 +13,7 @@ const makeEditLink = require('../utils/makeEditLink.js');
 /**
  * Load filters into the given Nunjucks environment
  *
- * @param {NunjucksEnvironment} env Nunjucks environment
+ * @param {any} env Nunjucks environment
  * @param {string} mountUrl Application mount URL
  * @returns {void}
  */

package/lib/view-filters/mergeObjectsDeep.js

@@ -3,8 +3,9 @@ const merge = require('lodash.merge');
 /**
  * Merge the given objects. The first object given will _not_ be mutated.
  *
- * @param  {object} objects... Objects to be merged
- * @return {object} Merged object
+ * @param {...any} objects Objects to be merged.
+ * @returns {object} Merged object.
+ * @throws {TypeError} When attempting to merge a non-object
  */
 module.exports = function mergeObjectsDeep(...objects) {
   // Validate

package/lib/view-filters/renderAsAttributes.js

@@ -13,7 +13,7 @@ const nunjucks = require('nunjucks');
  *   Output: class="basic" data-ga="3"
  *
  * @param  {object} attrsObject Attributes object (in name:value pairs)
- * @return {string} Formatted
+ * @returns {string} Formatted
  */
 module.exports = function renderAsAttributes(attrsObject) {
   const attrsList = [];

package/middleware/headers/config-defaults.js

@@ -42,11 +42,13 @@ module.exports = (app, cspConfig = {}) => {
   cspDirectives = Object.keys(cspDirectives).map((directive) => `${directive} ${cspDirectives[directive].join(' ')}`);
 
   // Prepare default headers
+  // added X-Robots-Tag based on https://www.gov.uk/service-manual/technology/get-a-domain-name
   const defaultHeaders = {
     'X-Content-Type-Options': 'nosniff',
     'X-XSS-Protection': '1; mode=block',
     'X-Frame-Options': 'DENY',
     'Content-Security-Policy': cspDirectives.join('; '),
+    'X-Robots-Tag': 'noindex, nofollow',
   };
 
   return {

package/middleware/i18n/i18n.js

@@ -1,19 +1,19 @@
 /**
-* Configure multi-lingual support.
-*
-* This middleware will determine the language to use for each request, by
-* inspecting the query and existing session.
-*
-* Enhances `req` with:
-*   string language = The language code to use (ISO 639-1)
-*   function i18nTranslator = A class instance to translate for the current req
-*
-* Enhances `req.session` with:
-*   string language = The language code to use (ISO 639-1)
-*
-* Enhances `req.casa.journeyContext.nav` with
-*   string language = The language code to use (ISO 639-1)
-*/
+ * Configure multi-lingual support.
+ *
+ * This middleware will determine the language to use for each request, by
+ * inspecting the query and existing session.
+ *
+ * Enhances `req` with:
+ *   string language = The language code to use (ISO 639-1).
+ *   Function i18nTranslator = A class instance to translate for the current req.
+ *
+ * Enhances `req.session` with:
+ *   string language = The language code to use (ISO 639-1).
+ *
+ * Enhances `req.casa.journeyContext.nav` with
+ *   string language = The language code to use (ISO 639-1).
+ */
 
 module.exports = (logger, supportedLocales = [], translatorFactory) => (req, res, next) => {
   const currentSessionLanguage = (req.session || Object.create(null)).language;

package/middleware/nunjucks/environment.js

@@ -8,23 +8,22 @@
  *
  * Enhances `res` with:
  *  function render = Function to render and return a template response
- *  Environment nunjucksEnvironment = Nunjucks environment for this request
+ *  Environment nunjucksEnvironment = Nunjucks environment for this request.
  */
 
 const nunjucks = require('nunjucks');
 const path = require('path');
 
 /**
- * `govukFrontendDir` must be the path to the layout template file
- * (template.njk), which would typically be passed in from
- * the result of:
+ * `govukFrontendDir` must be the path to the layout template file template.njk
+ * which would typically be passed in from the result of:
  *   require.resolve('govuk-frontend')
  *
- * @param {object} logger Logger
- * @param {Express} app Express app
- * @param {array} viewDirs List of view directories to register with Nunjucks
- * @param {string} govukFrontendDir Path to `govuk-frontend` module
- * @return {nunjucks.Environment} Configured environment
+ * @param {object} logger Logger.
+ * @param {Function} app Express app.
+ * @param {Array} viewDirs List of view directories to register with Nunjucks.
+ * @param {string} govukFrontendDir Path to `govuk-frontend` module.
+ * @returns {nunjucks.Environment} Configured environment.
  */
 module.exports = (logger, app, viewDirs = [], govukFrontendDir = '') => {
   // Resolve all application template search paths, and add CASA-specific dirs.

package/middleware/page/csrf.js

@@ -2,7 +2,7 @@
  * Generate CSRF protection to use on all mutating (POST) requests. The
  * `csrfSupplyToken` function will make the current token available to views
  * via the `casa.csrfToken` variable, which you can use as so:
- *   <input type="hidden" name="_csrf" value="{{ casa.csrfToken }}">
+ *   <input type="hidden" name="_csrf" value="{{ casa.csrfToken }}">.
  */
 
 const csrf = require('csurf');

package/middleware/page/gather.js

@@ -21,7 +21,7 @@ module.exports = (pageMeta = {}) => [mwBodyParser, (req, res, next) => {
   /**
    * Store data in request, clearing validation flags prior to validation.
    *
-   * @param {object} data Data to store
+   * @param {object} data Data to store.
    * @returns {void}
    */
   function storeSessionData(data) {

package/middleware/page/index.js

@@ -15,16 +15,16 @@
  *     hooks: {
  *       pregather: function(req, res, next) {},
  *       postvalidate: function(req, res, next) {},
- *       prerender: function(req, res, next) {}
- *     }
- *   }
+ *       prerender: function(req, res, next) {}.
+ *     }.
+ *   }.
  *
  * The `next()` function takes an optional error object containing an array of
  * errors for each field, e.g:
  *   next({
  *     <fieldName>: [{inline: '...', summary: '...'}, ...],
  *     ...
- *   })
+ *   }).
  *
  * "Override":
  * -----------
@@ -35,7 +35,7 @@
  *       get: function(req, res, next) {},
  *       post: function(req, res, next) {}
  *     }
- *   };
+ *   };.
  */
 
 const mwBodyParser = require('../../lib/commonBodyParser.js');

package/middleware/page/journey-continue.js

@@ -47,7 +47,9 @@ module.exports = (pageMeta = {}, mountUrl = '/', useStickyEdit = false) => (req,
       // `a, b, c, d` vs `a, c, d` <- should stop at `d` (`b` was removed) <- [.-..]
       // `a, b, c` vs `a, c, d`    <- should stop at `d` (`b` was removed, `d` was added) <- [.-..+]
       let compareIndex = 0;
-      const compareIndexMax = preGatherTraversalSnapshot.length - 1;
+      const compareIndexMax = useStickyEdit
+        ? currentTraversalSnapshot.length - 1
+        : preGatherTraversalSnapshot.length - 1;
       for (let i = 0, l = currentTraversalSnapshot.length; i < l; i++) {
         // Build waypoint URL for the current waypoint
         const waypointUrl = `${mountUrl}/${currentTraversalSnapshot[i].label.sourceOrigin || nextOrigin}/${currentTraversalSnapshot[i].source}`.replace(/\/+/g, '/');
@@ -64,7 +66,18 @@ module.exports = (pageMeta = {}, mountUrl = '/', useStickyEdit = false) => (req,
         while (compareIndex <= compareIndexMax) {
           nextWaypoint = waypointUrl;
           nextOrigin = currentTraversalSnapshot[i].label.targetOrigin || nextOrigin;
-          if (currentTraversalSnapshot[i].source === preGatherTraversalSnapshot[compareIndex++]) {
+          compareIndex++;
+
+          // If we've exhausted the pre-gathering waypoints, then sticky mode
+          // should try to send us as far along the remaining journey as possible
+          if (useStickyEdit && preGatherTraversalSnapshot[compareIndex - 1] === undefined) {
+            nextWaypoint = `${mountUrl}/${nextOrigin}/${currentTraversalSnapshot[compareIndex - 1].source}`;
+            /* eslint-disable-next-line max-len */
+            nextOrigin = currentTraversalSnapshot[compareIndex - 1].label.targetOrigin || nextOrigin;
+            break;
+          }
+
+          if (currentTraversalSnapshot[i].source === preGatherTraversalSnapshot[compareIndex - 1]) {
             // The current snapshot may include more waypoints than than the
             // previous. In this case, if we've exhausted the list of previous
             // waypoints, with the last one being a match, we must leave the user on

package/middleware/page/journey-rails.js

@@ -5,7 +5,7 @@
  *
  * Enhances `res.locals.casa` with:
  *  string journeyPreviousUrl = Absolute URL to the previous page in the journey
- *      (if applicable)
+ *      (if applicable).
  */
 
 const createLogger = require('../../lib/Logger.js');

package/middleware/page/prepare-request.js

@@ -1,9 +1,9 @@
 /**
  * Enhances `req.casa` with:
  *  string journeyWaypointId = Converts requested URL into a string suitable for
- *      use as a journey waypoint ID (i.e. remove trailing slashes)
+ *      use as a journey waypoint ID (i.e. Remove trailing slashes)
  *  object journeyOrigin = The origin from which traversals should start
- *  Plan plan = The grand Plan
+ *  Plan plan = The grand Plan.
  */
 
 const createLogger = require('../../lib/Logger.js');

package/middleware/page/skip.js

@@ -12,7 +12,7 @@
  * visited beforehand, so this middleware must come after journey-rails.
  *
  * Format:
- *  /current-waypoint?skipto=next-waypoint
+ *  /current-waypoint?skipto=next-waypoint.
  */
 
 const { URL, URLSearchParams } = require('url');