@dwp/govuk-casa 9.4.0 → 9.4.2

package/src/middleware/body-parser.js

@@ -1,9 +1,34 @@
 import { urlencoded as expressBodyParser } from "express";
 
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
+
+/**
+ * @typedef {import("express").Request} Request
+ * @access private
+ */
+
+/**
+ * @typedef {import("express").Response} Response
+ * @access private
+ */
+
 const rProto = /__proto__/i;
 const rPrototype = /prototype[='"[\]]/i;
 const rConstructor = /constructor[='"[\]]/i;
 
+/**
+ * Verify request body.
+ *
+ * @param {Request} req HTTP request
+ * @param {Response} res HTTP response
+ * @param {Buffer} buf Buffer
+ * @param {string} encoding Character encoding
+ * @returns {void}
+ * @throws {Error} For invalid bodies
+ */
 export function verifyBody(req, res, buf, encoding) {
   const body = decodeURI(buf.toString(encoding)).replace(
     /[\s\u200B-\u200D\uFEFF]/g,
@@ -20,6 +45,15 @@ export function verifyBody(req, res, buf, encoding) {
   }
 }
 
+/**
+ * Body parsing middleware.
+ *
+ * @param {object} opts Options
+ * @param {number} opts.formMaxParams Max number of parameters that should be
+ *   parsed
+ * @param {number} opts.formMaxBytes Max bytes that should be read
+ * @returns {RequestHandler[]} Middleware functions
+ */
 export default function bodyParserMiddleware({ formMaxParams, formMaxBytes }) {
   return [
     expressBodyParser({

package/src/middleware/csrf.js

@@ -1,9 +1,19 @@
 import { csrfSync } from "csrf-sync";
 
-// 2 middleware: one to generate the csrf token and check its validity (POST
-// only), and one to provide that token to templates via the `casa.csrfToken`
-// variable.
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
 
+/**
+ * Data middleware.
+ *
+ * 2 middleware: one to generate the csrf token and check its validity (POST
+ * only), and one to provide that token to templates via the `casa.csrfToken`
+ * variable.
+ *
+ * @returns {RequestHandler[]} Middleware functions
+ */
 export default function csrfMiddleware() {
   const { csrfSynchronisedProtection } = csrfSync({
     getTokenFromRequest: (req) => req.body._csrf,

package/src/middleware/data.js

@@ -1,10 +1,27 @@
-// Decorates the request with some contextual data about the user's journey
-// through the application. This is used by downstream middleware and templates.
-
 import JourneyContext from "../lib/JourneyContext.js";
 import { validateUrlPath } from "../lib/utils.js";
 import waypointUrl from "../lib/waypoint-url.js";
 
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa.js").Plan} Plan
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa.js").ContextEventHandler} ContextEventHandler
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa.js").ContextIdGenerator} ContextIdGenerator
+ * @access private
+ */
+
 const editOrigin = (req) => {
   if (Object.hasOwn(req.query, "editorigin")) {
     return waypointUrl({ waypoint: req.query.editorigin });
@@ -15,6 +32,19 @@ const editOrigin = (req) => {
   return "";
 };
 
+/**
+ * Data middleware.
+ *
+ * Decorates the request with some contextual data about the user's journey
+ * through the application. This is used by downstream middleware and
+ * templates.
+ *
+ * @param {object} opts Options
+ * @param {Plan} opts.plan CASA Plan
+ * @param {ContextEventHandler[]} opts.events Event handlers
+ * @param {ContextIdGenerator} opts.contextIdGenerator Content ID generator
+ * @returns {RequestHandler[]} Middleware functions
+ */
 export default function dataMiddleware({ plan, events, contextIdGenerator }) {
   return [
     (req, res, next) => {
@@ -36,8 +66,10 @@ export default function dataMiddleware({ plan, events, contextIdGenerator }) {
 
         // Edit mode
         editMode:
-          (Object.hasOwn(req.query, "edit") && Object.hasOwn(req.query, "editorigin")) ||
-          (Object.hasOwn(req.body, "edit") && Object.hasOwn(req.body, "editorigin")),
+          (Object.hasOwn(req.query, "edit") &&
+            Object.hasOwn(req.query, "editorigin")) ||
+          (Object.hasOwn(req.body, "edit") &&
+            Object.hasOwn(req.body, "editorigin")),
         editOrigin: editOrigin(req),
       };
 

package/src/middleware/gather-fields.js

@@ -20,7 +20,7 @@ import { REQUEST_PHASE_GATHER } from "../lib/constants.js";
  *
  * @param {object} obj Options
  * @param {string} obj.waypoint Waypoint
- * @param {PageField[]} [obj.fields=[]] Fields. Default is `[]`
+ * @param {PageField[]} [obj.fields] Fields. Default is `[]`
  * @returns {Array} Array of middleware
  */
 export default ({ waypoint, fields = [] }) => [

package/src/middleware/i18n.js

@@ -3,9 +3,14 @@ import { LanguageDetector, handle } from "i18next-http-middleware";
 import { resolve, basename } from "node:path";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import deepmerge from "deepmerge";
-import yaml from "js-yaml";
+import { load as jsYamlLoad } from "js-yaml";
 import logger from "../lib/logger.js";
 
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
+
 const log = logger("middleware:i18n");
 
 const loadJson = (file) => {
@@ -17,7 +22,7 @@ const loadJson = (file) => {
 };
 
 /* eslint-disable-next-line security/detect-non-literal-fs-filename */
-const loadYaml = (file) => yaml.load(readFileSync(file, "utf8"));
+const loadYaml = (file) => jsYamlLoad(readFileSync(file, "utf8"));
 
 const extract = (file) => {
   const ext = /.yaml$/i.test(file) ? ".yaml" : ".json";
@@ -63,6 +68,14 @@ const loadResources = (languages, directories) => {
   return store;
 };
 
+/**
+ * Internationalisation middleware.
+ *
+ * @param {object} opts Options
+ * @param {string[]} [opts.languages] Language codes
+ * @param {string[]} [opts.directories] Source translations directories
+ * @returns {RequestHandler[]} Middleware functions
+ */
 export default function i18nMiddleware({
   languages = ["en", "cy"],
   directories = [],
@@ -95,7 +108,6 @@ export default function i18nMiddleware({
   return [
     (req, res, next) => {
       if (!req.session.language) {
-        /* eslint-disable-next-line prefer-destructuring */
         req.session.language = languages[0];
       }
       if (req?.query.lang && languages.includes(req.query.lang)) {

package/src/middleware/post.js

@@ -1,8 +1,14 @@
 // 2 middleware: one as a fallback 404 handler, one to handle thrown errors
 import logger from "../lib/logger.js";
 
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
+
 const log = logger("middleware:post");
 
+/** @returns {RequestHandler[]} Middleware functions */
 export default function postMiddleware() {
   return [
     (req, res) => {

package/src/middleware/session.js

@@ -5,6 +5,11 @@ import expressSession, { MemoryStore } from "express-session";
 import logger from "../lib/logger.js";
 import { validateUrlPath } from "../lib/utils.js";
 
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
+
 const log = logger("middleware:session");
 
 const sessionExpiryMiddleware =
@@ -51,7 +56,7 @@ const sessionExpiryMiddleware =
             referrer: req.originalUrl,
             lang: language,
           });
-          /* eslint-disable-next-line prefer-template */
+
           res.redirect(
             302,
             validateUrlPath(`${req.baseUrl}/session-timeout`) +
@@ -66,10 +71,24 @@ const sessionExpiryMiddleware =
     }
   };
 
-// 3 middleware:
-// - set the session cookie
-// - parse request cookies
-// - handle expiry of server-side session
+/**
+ * Produces three middleware functions:
+ *
+ * - Set the session cookie
+ * - Parse request cookies
+ * - Handle expiry of server-side session
+ *
+ * @param {object} opts Options
+ * @param {RequestHandler} opts.cookieParserMiddleware Cookie parsing middleware
+ * @param {string} opts.secret Session encryption secret
+ * @param {string} opts.name Session cookie name
+ * @param {boolean} opts.secure Secure cookies only
+ * @param {number} opts.ttl Session data time-to-live
+ * @param {boolean | string} [opts.cookieSameSite] Cooke SameSite setting
+ * @param {string} [opts.cookiePath] Cookie path
+ * @param {object} [opts.store] Storage instance
+ * @returns {RequestHandler[]} Middleware functions
+ */
 export default function sessionMiddleware({
   cookieParserMiddleware,
   secret,

package/src/routes/journey.js

@@ -1,4 +1,3 @@
-/* eslint-disable object-curly-newline,max-len */
 import MutableRouter from "../lib/MutableRouter.js";
 import skipWaypointMiddlewareFactory from "../middleware/skip-waypoint.js";
 import steerJourneyMiddlewareFactory from "../middleware/steer-journey.js";
@@ -44,7 +43,10 @@ const renderMiddlewareFactory = (view, contextFactory) => [
         // Common template variables for both GET and POST requests
         inEditMode: req.casa.editMode,
         editOriginUrl: req.casa.editOrigin,
-        editCancelUrl: generateEditCancelUrl(req.casa.editOrigin, req.casa.waypoint),
+        editCancelUrl: generateEditCancelUrl(
+          req.casa.editOrigin,
+          req.casa.waypoint,
+        ),
         activeContextId: req.casa.journeyContext.identity.id,
         ...contextFactory(req),
       },
@@ -73,8 +75,8 @@ const generateGovukErrors = (errors, req) =>
   }));
 
 const generateEditCancelUrl = (editOrigin, waypoint) => {
-  const url = new URL(editOrigin, 'https://placeholder.test/');
-  url.searchParams.set('editcancel', waypoint);
+  const url = new URL(editOrigin, "https://placeholder.test/");
+  url.searchParams.set("editcancel", waypoint);
   return `${url.pathname}${url.search}`;
 };
 

package/src/core-plugins/edit-snapshot/readme.md

@@ -1,19 +0,0 @@
-# Edit snapshots plugin
-
-Include the `editSnapshot` core plugin to use this feature:
-
-```js
-import { configure, corePlugins } from "@dwp/govuk/casa";
-
-configure({
-  plugins: [
-    corePlugins.editSnapshot(),
-  ],
-});
-```
-
-This feature will alter the default behaviour of the "cancel" links during an editing workflow.
-
-When the user clicks "cancel", all changes made during the current editing session will be dropped, and the state of the current journey context will be restored to a point just before editing started.
-
-The same will also happen if the user navigates away from the editing workflow, i.e. the `edit` URL paramater is removed.

package/src/core-plugins/readme.md

@@ -1,3 +0,0 @@
-# Internal plugins
-
-These are isolated bits of functionality that may be candidates for exatracting into their own external plugins at some point.