@dwp/govuk-casa 10.0.0 → 10.1.1

package/src/casa.js

@@ -90,7 +90,7 @@ export {
  *   representation of a waypoint
  * @property {string} waypoint The waypoint with which this page is associated
  * @property {string} view Template path
- * @property {ErrorVisibiltyFunction | symbol} errorVisibility Should page
+ * @property {ErrorVisibiltyFunction | symbol} [errorVisibility] Should page
  *   validation errors be visible on GET requests
  * @property {PageHook[]} [hooks=[]] Page-specific hooks (optional, default []).
  *   Default is `[]`
@@ -160,6 +160,14 @@ export {
  * @returns {HelmetOptions} The modified configuration object
  */
 
+/**
+ * @typedef {Omit<
+ *   import("nunjucks").Environment &
+ *     import("./lib/CasaTemplateLoader.js").default,
+ *   "getSource"
+ * >} CasaNunjucksEnvironment
+ */
+
 /**
  * Mounting function.
  *
@@ -171,9 +179,12 @@ export {
  *
  * @callback Mounter
  * @param {import("express").Express} app Express application
- * @param {object} opts Mounting options
+ * @param {object} [opts] Mounting options
  * @param {string} [opts.route='/'] Optional route to attach all
  *   middleware/routers too. Default is `'/'`
+ * @param {boolean} [opts.serveFirstWaypoint=false] Automatically redirect
+ *   requests to the mount route to the first waypoint in the plan. Default is
+ *   `false`
  * @returns {import("express").Express} The prepared ExpressJS app instance
  */
 
@@ -205,7 +216,7 @@ export {
 
 /**
  * @typedef {object} ConfigureResult Result of a call to configure() function
- * @property {import("nunjucks").Environment} nunjucksEnv Nunjucks environment
+ * @property {CasaNunjucksEnvironment} nunjucksEnv Nunjucks environment
  * @property {MutableRouter} staticRouter Router handling all static assets
  * @property {MutableRouter} ancillaryRouter Router handling ancillary routes
  * @property {MutableRouter} journeyRouter Router handling all waypoint requests
@@ -218,6 +229,7 @@ export {
  * @property {RequestHandler[]} cookieParserMiddleware Cookie-parsing middleware
  * @property {RequestHandler[]} i18nMiddleware I18n preparation middleware
  * @property {RequestHandler} bodyParserMiddleware Body parsing middleware
+ * @property {RequestHandler[]} dataMiddleware Data decoration middleware
  * @property {Mounter} mount Function used to mount all CASA artifacts onto an
  *   ExpressJS app
  * @property {ConfigurationOptions} config Ingested config supplied to

package/src/lib/MutableRouter.js

@@ -100,7 +100,7 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `all()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -111,7 +111,7 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `get()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -122,7 +122,7 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `post()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -133,7 +133,7 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `delete()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -144,7 +144,7 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `put()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -155,8 +155,9 @@ export default class MutableRouter {
   /**
    * Prepend middleware function(s) using the `use()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
-   * @param {...RequestHandler} callbacks Additional middleware functions
+   * @param {PathParams | RequestHandlerParams} path Route path or middleware
+   *   function
+   * @param {...RequestHandlerParams} callbacks Additional middleware functions
    * @returns {void}
    */
   prependUse(path, ...callbacks) {
@@ -168,7 +169,7 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `all()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -179,7 +180,7 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `get()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -190,7 +191,7 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `post()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -202,7 +203,7 @@ export default class MutableRouter {
    * Replace middleware function(s) that were mounted using the `delete()`
    * method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -213,7 +214,7 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `put()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -224,8 +225,9 @@ export default class MutableRouter {
   /**
    * Replace middleware function(s) that were mounted using the `use()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
-   * @param {...RequestHandler} callbacks Additional middleware functions
+   * @param {PathParams | RequestHandlerParams} path Route path or middleware
+   *   function
+   * @param {...RequestHandlerParams} callbacks Additional middleware functions
    * @returns {void}
    */
   replaceUse(path, ...callbacks) {
@@ -237,7 +239,7 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `all()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -248,7 +250,7 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `get()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -259,7 +261,7 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `post()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -270,7 +272,7 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `delete()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -281,7 +283,7 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `put()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
+   * @param {PathParams | RequestHandler} path Route path or middleware function
    * @param {...RequestHandler} callbacks Additional middleware functions
    * @returns {void}
    */
@@ -292,8 +294,9 @@ export default class MutableRouter {
   /**
    * Append middleware function(s) using the `use()` method.
    *
-   * @param {string | RequestHandler} path Route path or middleware function
-   * @param {...RequestHandler} callbacks Additional middleware functions
+   * @param {PathParams | RequestHandlerParams} path Route path or middleware
+   *   function
+   * @param {...RequestHandlerParams} callbacks Additional middleware functions
    * @returns {void}
    */
   use(path, ...callbacks) {
@@ -308,10 +311,12 @@ export default class MutableRouter {
 }
 
 /** @typedef {import("express").RequestHandler} RequestHandler */
+/** @typedef {import("express-serve-static-core").PathParams} PathParams */
+/** @typedef {import("express-serve-static-core").RequestHandlerParams} RequestHandlerParams */
 
 /**
  * @typedef {object} StackRoute Stack route
  * @property {string} method HTTP request method
- * @property {string} path Route path
- * @property {[string, ...RequestHandler[]]} args Router arguments
+ * @property {PathParams} path Route path
+ * @property {[PathParams, ...RequestHandler[]]} args Router arguments
  */

package/src/lib/nunjucks.js

@@ -18,7 +18,8 @@ import {
  * Create a Nunjucks environment.
  *
  * @param {NunjucksOptions} options Nunjucks options
- * @returns {Environment} Nunjucks Environment instance
+ * @returns {import("../casa.js").CasaNunjucksEnvironment} Nunjucks Environment
+ *   instance
  * @access private
  */
 export default function nunjucksConfig({ views = [] }) {

package/src/middleware/post.js

@@ -3,12 +3,14 @@ import logger from "../lib/logger.js";
 
 /**
  * @typedef {import("express").RequestHandler} RequestHandler
+ *
+ * @typedef {import("express").ErrorRequestHandler} ErrorRequestHandler
  * @access private
  */
 
 const log = logger("middleware:post");
 
-/** @returns {RequestHandler[]} Middleware functions */
+/** @returns {[RequestHandler, ErrorRequestHandler]} Middleware functions */
 export default function postMiddleware() {
   return [
     (req, res) => {