@dwp/govuk-casa 8.1.0 → 8.2.0

package/dist/casa.d.ts

@@ -1,3 +1,213 @@
+export type PageField = import('./lib/field').PageField;
+export type ContextEventHandler = (journeyContext: JourneyContext, previousContext: JourneyContext) => void;
+export type ContextEvent = {
+    /**
+     * Waypoint to watch for changes
+     */
+    waypoint: string;
+    /**
+     * Field to watch for changes
+     */
+    field?: string | undefined;
+    /**
+     * Handler to invoke when change happens
+     */
+    handler: ContextEventHandler;
+};
+/**
+ * Page configuration. A Page is the interactive representation of a waypoint
+ */
+export type Page = {
+    /**
+     * The waypoint with which this page is associated
+     */
+    waypoint: string;
+    /**
+     * Template path
+     */
+    view: string;
+    /**
+     * Page-specific hooks (optional, default [])
+     */
+    hooks?: PageHook[] | undefined;
+    /**
+     * Fields to be managed on this page (optional, default [])
+     */
+    fields?: import("./lib/field.js").PageField[] | undefined;
+};
+export type I18nOptions = {
+    /**
+     * Directories to search for locale dictionaries
+     */
+    dirs: string[];
+    /**
+     * Supported locales
+     */
+    locales?: string[] | undefined;
+};
+/**
+ * Hook configuration
+ */
+export type GlobalHook = {
+    /**
+     * Hook name in format `<router>.<hook>`
+     */
+    hook: string;
+    /**
+     * Middleware function to insert at the hook point
+     */
+    middleware: Function;
+    /**
+     * Only run if route path matches this string/regexp
+     */
+    path?: string | RegExp | undefined;
+};
+/**
+ * (extends GlobalHook)
+ */
+export type PageHook = {
+    /**
+     * Hook name (without a scope prefix)
+     */
+    hook: string;
+    /**
+     * Middleware function to insert at the hook point
+     */
+    middleware: Function;
+};
+export type SessionOptions = {
+    /**
+     * Session name
+     */
+    name?: string | undefined;
+    /**
+     * Encryption secret
+     */
+    secret?: string | undefined;
+    /**
+     * Session ttl (seconds)
+     */
+    ttl?: number | undefined;
+    /**
+     * Whether to use secure session cookies
+     */
+    secure?: boolean | undefined;
+    /**
+     * SameSite (true = Strict)
+     */
+    cookieSameSite?: string | boolean | undefined;
+    /**
+     * Session store (default MemoryStore)
+     */
+    store?: object | undefined;
+};
+/**
+ * Plugin interface
+ */
+export type IPlugin = {
+    /**
+     * Modify the app config
+     */
+    configure?: Function | undefined;
+    /**
+     * Modify post-configuration artifacts
+     */
+    bootstrap?: Function | undefined;
+};
+export type PluginConfigureFunction = (con: object, : any) => any;
+export type HelmetConfigurator = (config: object) => object;
+export type Mounter = (app: import('express').Express, opts: object, route?: string | undefined) => import('express').Express;
+export type MutableRouter = import('./lib/index').MutableRouter;
+/**
+ * Configuration options
+ */
+export type ConfigurationOptions = {
+    /**
+     * Template directories
+     */
+    views?: string[] | undefined;
+    /**
+     * Session configuration
+     */
+    session?: SessionOptions | undefined;
+    /**
+     * Pages the represent waypoints
+     */
+    pages?: Page[] | undefined;
+    /**
+     * Hooks to apply
+     */
+    hooks?: GlobalHook[] | undefined;
+    /**
+     * Plugins
+     */
+    plugins?: IPlugin[] | undefined;
+    /**
+     * I18n configuration
+     */
+    i18n?: I18nOptions[] | undefined;
+    /**
+     * CASA Plan
+     */
+    plan: Plan;
+    /**
+     * Handlers for JourneyContext events
+     */
+    events?: ContextEvent[] | undefined;
+};
+/**
+ * Result of a call to configure() function
+ */
+export type ConfigureResult = {
+    /**
+     * Nunjucks environment
+     */
+    nunjucksEnv: import('nunjucks').Environment;
+    /**
+     * Router handling all static assets
+     */
+    staticRouter: MutableRouter;
+    /**
+     * Router handling ancillary routes
+     */
+    ancillaryRouter: MutableRouter;
+    /**
+     * Router handling all waypoint requests
+     */
+    journeyRouter: MutableRouter;
+    /**
+     * Middleware mounted before everything
+     */
+    preMiddleware: import('express').RequestHandler[];
+    /**
+     * Middleware mounted after everything
+     */
+    postMiddleware: import('express').RequestHandler[];
+    /**
+     * CSRF get/set form middleware
+     */
+    csrfMiddleware: import('express').RequestHandler[];
+    /**
+     * Session middleware
+     */
+    sessionMiddleware: import('express').RequestHandler;
+    /**
+     * Cookie-parsing middleware
+     */
+    cookieParserMiddleware: import('express').RequestHandler[];
+    /**
+     * I18n preparation middleware
+     */
+    i18nMiddleware: import('express').RequestHandler[];
+    /**
+     * Body parsing middleware
+     */
+    bodyParserMiddleware: import('express').RequestHandler;
+    /**
+     * Function used to mount all CASA artifacts onto an ExpressJS app
+     */
+    mount: Mounter;
+};
 import configure from "./lib/configure.js";
 import validators from "./lib/validators/index.js";
 import field from "./lib/field.js";

package/dist/casa.js

@@ -48,3 +48,105 @@ const end_session_js_1 = __importDefault(require("./lib/end-session.js"));
 exports.endSession = end_session_js_1.default;
 const nunjucksFilters = __importStar(require("./lib/nunjucks-filters.js"));
 exports.nunjucksFilters = nunjucksFilters;
+/* ----------------------------------------------------------------- Typedefs */
+// These exist here so that consumer can import CASA's internal types
+/**
+ * @typedef {import('./lib/field').PageField} PageField
+ */
+/**
+ * @callback ContextEventHandler
+ * @param {JourneyContext} journeyContext Context including changes
+ * @param {JourneyContext} previousContext Context prior to changes
+ * @returns {void}
+ */
+/**
+ * @typedef {object} ContextEvent
+ * @property {string} waypoint Waypoint to watch for changes
+ * @property {string} [field] Field to watch for changes
+ * @property {ContextEventHandler} handler Handler to invoke when change happens
+ */
+/**
+ * @typedef {object} Page Page configuration. A Page is the interactive representation of a waypoint
+ * @property {string} waypoint The waypoint with which this page is associated
+ * @property {string} view Template path
+ * @property {PageHook[]} [hooks=[]] Page-specific hooks (optional, default [])
+ * @property {PageField[]} [fields=[]] Fields to be managed on this page (optional, default [])
+ */
+/**
+ * @typedef {object} I18nOptions
+ * @property {string[]} dirs Directories to search for locale dictionaries
+ * @property {string[]} [locales=['en', 'cy']] Supported locales
+ */
+/**
+ * @typedef {object} GlobalHook Hook configuration
+ * @property {string} hook Hook name in format `<router>.<hook>`
+ * @property {Function} middleware Middleware function to insert at the hook point
+ * @property {string|RegExp} [path=undefined] Only run if route path matches this string/regexp
+ */
+/**
+ * @typedef {object} PageHook (extends GlobalHook)
+ * @property {string} hook Hook name (without a scope prefix)
+ * @property {Function} middleware Middleware function to insert at the hook point
+ */
+/**
+ * @typedef {object} SessionOptions
+ * @property {string} [name=casasession] Session name
+ * @property {string} [secret=secret] Encryption secret
+ * @property {number} [ttl=3600] Session ttl (seconds)
+ * @property {boolean} [secure=false] Whether to use secure session cookies
+ * @property {boolean|string} [cookieSameSite=true] SameSite (true = Strict)
+ * @property {object} [store] Session store (default MemoryStore)
+ */
+/**
+ * @typedef {object} IPlugin Plugin interface
+ * @property {Function} [configure] Modify the app config
+ * @property {Function} [bootstrap] Modify post-configuration artifacts
+ */
+/**
+ * @callback PluginConfigureFunction
+ * @param {object} con Options
+ * @param {}
+ */
+/**
+ * @callback HelmetConfigurator
+ * @param {object} config A default Helmet configuration provided by CASA
+ * @returns {object} The modified configuration object
+ */
+/**
+ * @callback Mounter
+ * @param {import('express').Express} app Express application
+ * @param {object} opts Mounting options
+ * @param {string} [opts.route=/] Optional route to attach all middleware/routers too
+ * @returns {import('express').Express} The prepared ExpressJS app instance
+ */
+/**
+ * @typedef {import('./lib/index').MutableRouter} MutableRouter
+ */
+/**
+ * Configure some middleware for use in creating a new CASA app.
+ *
+ * @typedef {object} ConfigurationOptions Configuration options
+ * @property {string[]} [views=[]] Template directories
+ * @property {SessionOptions} [session] Session configuration
+ * @property {Page[]} [pages=[]] Pages the represent waypoints
+ * @property {GlobalHook[]} [hooks=[]] Hooks to apply
+ * @property {IPlugin[]} [plugins=[]] Plugins
+ * @property {I18nOptions[]} [i18n] I18n configuration
+ * @property {Plan} plan CASA Plan
+ * @property {ContextEvent[]} [events=[]] Handlers for JourneyContext events
+ */
+/**
+ * @typedef {object} ConfigureResult Result of a call to configure() function
+ * @property {import('nunjucks').Environment} 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
+ * @property {import('express').RequestHandler[]} preMiddleware Middleware mounted before everything
+ * @property {import('express').RequestHandler[]} postMiddleware Middleware mounted after everything
+ * @property {import('express').RequestHandler[]} csrfMiddleware CSRF get/set form middleware
+ * @property {import('express').RequestHandler} sessionMiddleware Session middleware
+ * @property {import('express').RequestHandler[]} cookieParserMiddleware Cookie-parsing middleware
+ * @property {import('express').RequestHandler[]} i18nMiddleware I18n preparation middleware
+ * @property {import('express').RequestHandler} bodyParserMiddleware Body parsing middleware
+ * @property {Mounter} mount Function used to mount all CASA artifacts onto an ExpressJS app
+ */

package/dist/lib/JourneyContext.d.ts

@@ -1,17 +1,11 @@
 /**
- * @typedef {import('./configuration-ingestor').Page} Page
+ * @typedef {import('../casa').Page} Page
  */
 /**
- * @callback ContextEventHandler
- * @param {JourneyContext} journeyContext Context including changes
- * @param {JourneyContext} previousContext Context prior to changes
- * @returns {void}
+ * @typedef {import('../casa').ContextEventHandler} ContextEventHandler
  */
 /**
- * @typedef {object} ContextEvent
- * @property {string} waypoint Waypoint to watch for changes
- * @property {string} [field] Field to watch for changes
- * @property {ContextEventHandler} handler Handler to invoke when change happens
+ * @typedef {import('../casa').ContextEvent} ContextEvent
  */
 export function validateObjectKey(key?: string): string;
 export default class JourneyContext {
@@ -33,7 +27,13 @@ export default class JourneyContext {
         identity: object;
     }): JourneyContext;
     /**
-     * Construct a new JourneyContext instance frmo another instance.
+     * Construct a new ephemeral JourneyContext instance with a unique ID.
+     *
+     * @returns {JourneyContext} Constructed JourneyContext instance
+     */
+    static createEphemeralContext(): JourneyContext;
+    /**
+     * Construct a new JourneyContext instance from another instance.
      *
      * @param {JourneyContext} context Context to copy from
      * @returns {JourneyContext} Constructed JourneyContext instance
@@ -268,8 +268,9 @@ export default class JourneyContext {
      * @returns {JourneyContext} Chain
      */
     addEventListeners(events: ContextEvent[]): JourneyContext;
-    applyEventListeners({ event }: {
+    applyEventListeners({ event, session }: {
         event: any;
+        session: any;
     }): JourneyContext;
     /**
      * Convenience method to determine if this is the default context.
@@ -279,20 +280,7 @@ export default class JourneyContext {
     isDefault(): boolean;
     #private;
 }
-export type Page = import('./configuration-ingestor').Page;
-export type ContextEventHandler = (journeyContext: JourneyContext, previousContext: JourneyContext) => void;
-export type ContextEvent = {
-    /**
-     * Waypoint to watch for changes
-     */
-    waypoint: string;
-    /**
-     * Field to watch for changes
-     */
-    field?: string | undefined;
-    /**
-     * Handler to invoke when change happens
-     */
-    handler: ContextEventHandler;
-};
+export type Page = import('../casa').Page;
+export type ContextEventHandler = import('../casa').ContextEventHandler;
+export type ContextEvent = import('../casa').ContextEvent;
 import ValidationError from "./ValidationError.js";

package/dist/lib/JourneyContext.js

@@ -43,19 +43,13 @@ const utils_js_1 = require("./utils.js");
 const { cloneDeep, isPlainObject, isObject, has, isEqual, } = lodash_1.default; // CommonJS
 const log = (0, logger_js_1.default)('lib:journey-context');
 /**
- * @typedef {import('./configuration-ingestor').Page} Page
+ * @typedef {import('../casa').Page} Page
  */
 /**
- * @callback ContextEventHandler
- * @param {JourneyContext} journeyContext Context including changes
- * @param {JourneyContext} previousContext Context prior to changes
- * @returns {void}
+ * @typedef {import('../casa').ContextEventHandler} ContextEventHandler
  */
 /**
- * @typedef {object} ContextEvent
- * @property {string} waypoint Waypoint to watch for changes
- * @property {string} [field] Field to watch for changes
- * @property {ContextEventHandler} handler Handler to invoke when change happens
+ * @typedef {import('../casa').ContextEvent} ContextEvent
  */
 function validateObjectKey(key = '') {
     const keyLower = String.prototype.toLowerCase.call(key);
@@ -368,7 +362,7 @@ class JourneyContext {
         __classPrivateFieldSet(this, _JourneyContext_eventListenerPreState, this.toObject(), "f");
         return this;
     }
-    applyEventListeners({ event }) {
+    applyEventListeners({ event, session }) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         if (!__classPrivateFieldGet(this, _JourneyContext_eventListeners, "f").length) {
             return this;
@@ -397,7 +391,7 @@ class JourneyContext {
             }
             if (runHandler) {
                 log.trace(logMessage);
-                handler({ journeyContext: this, previousContext });
+                handler({ journeyContext: this, previousContext, session });
             }
         }
         /* eslint-enable security/detect-object-injection */
@@ -405,7 +399,19 @@ class JourneyContext {
     }
     /* ----------------------------------------------- session context handling */
     /**
-     * Construct a new JourneyContext instance frmo another instance.
+     * Construct a new ephemeral JourneyContext instance with a unique ID.
+     *
+     * @returns {JourneyContext} Constructed JourneyContext instance
+     */
+    static createEphemeralContext() {
+        return JourneyContext.fromObject({
+            identity: {
+                id: (0, uuid_1.v4)(),
+            },
+        });
+    }
+    /**
+     * Construct a new JourneyContext instance from another instance.
      *
      * @param {JourneyContext} context Context to copy from
      * @returns {JourneyContext} Constructed JourneyContext instance
@@ -546,11 +552,11 @@ class JourneyContext {
         // Apply context events
         context.applyEventListeners({
             event: 'waypoint-change',
-            previousContextObject: session.journeyContextList[context.identity.id],
+            session,
         });
         context.applyEventListeners({
             event: 'context-change',
-            previousContextObject: session.journeyContextList[context.identity.id],
+            session,
         });
         /* eslint-disable-next-line no-param-reassign */
         session.journeyContextList[context.identity.id] = context.toObject();
@@ -586,7 +592,11 @@ class JourneyContext {
     static extractContextFromRequest(req) {
         JourneyContext.initContextStore(req.session);
         let contextId;
-        if (has(req.query, 'contextid')) {
+        if (has(req === null || req === void 0 ? void 0 : req.params, 'contextid')) {
+            log.trace('Context ID found in req.params.contextid');
+            contextId = String(req.params.contextid);
+        }
+        else if (has(req.query, 'contextid')) {
             log.trace('Context ID found in req.query.contextid');
             contextId = String(req.query.contextid);
         }

package/dist/lib/configuration-ingestor.d.ts

@@ -6,7 +6,7 @@
  * @throws {TypeError} For invalid object.
  * @returns {object} Sanitised i18n object.
  */
-export function validateI18nObject(i18n: object, cb?: Function): object;
+export function validateI18nObject(i18n?: object, cb?: Function): object;
 /**
  * Validates and sanitises i18n directory.
  *
@@ -15,7 +15,7 @@ export function validateI18nObject(i18n: object, cb?: Function): object;
  * @throws {TypeError} For invalid type.
  * @returns {Array} Array of directories.
  */
-export function validateI18nDirs(dirs: any[]): any[];
+export function validateI18nDirs(dirs?: any[]): any[];
 /**
  * Validates and sanitises i18n locales.
  *
@@ -24,7 +24,7 @@ export function validateI18nDirs(dirs: any[]): any[];
  * @throws {TypeError} For invalid type.
  * @returns {Array} Array of locales.
  */
-export function validateI18nLocales(locales: any[]): any[];
+export function validateI18nLocales(locales?: any[]): any[];
 /**
  * Validates and sanitises mount url.
  *
@@ -42,7 +42,7 @@ export function validateMountUrl(mountUrl: string, name?: string): string;
  * @throws {TypeError} For invalid object.
  * @returns {object} Sanitised sessions object.
  */
-export function validateSessionObject(session: object, cb?: Function): object;
+export function validateSessionObject(session?: object, cb?: Function): object;
 /**
  * Validates and sanitises view directory.
  *
@@ -51,7 +51,7 @@ export function validateSessionObject(session: object, cb?: Function): object;
  * @throws {TypeError} For invalid type.
  * @returns {Array} Array of directories.
  */
-export function validateViews(dirs: any[]): any[];
+export function validateViews(dirs?: any[]): any[];
 /**
  * Validates and sanitises sessions secret.
  *
@@ -69,25 +69,25 @@ export function validateSessionSecret(secret: string): string;
  * @throws {TypeError} For invalid value.
  * @returns {number} Ttl.
  */
-export function validateSessionTtl(ttl: number): number;
+export function validateSessionTtl(ttl?: number): number;
 /**
  * Validates and sanitises sessions name.
  *
- * @param {string} name Session name.
+ * @param {string} [name=casa-session] Session name.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
  * @returns {string} Name.
  */
-export function validateSessionName(name: string): string;
+export function validateSessionName(name?: string | undefined): string;
 /**
  * Validates and sanitises sessions secure flag.
  *
- * @param {boolean} secure Session secure flag.
+ * @param {boolean} [secure=false] Session secure flag.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
  * @returns {string} Name.
  */
-export function validateSessionSecure(secure: boolean): string;
+export function validateSessionSecure(secure?: boolean | undefined): string;
 /**
  * Validates and sanitises sessions store.
  *
@@ -119,7 +119,7 @@ export function validateSessionCookiePath(cookiePath: string, defaultPath?: stri
 export function validateSessionCookieSameSite(cookieSameSite: any, defaultFlag: any): boolean;
 export function validatePageHooks(hooks: any): any[];
 export function validateFields(fields: any): any[];
-export function validatePages(pages: any): any[];
+export function validatePages(pages?: any[]): any[];
 export function validatePlan(plan: any): any;
 export function validateGlobalHooks(hooks: any): any[];
 export function validatePlugins(plugins: any): any;
@@ -140,132 +140,5 @@ export function validateHelmetConfigurator(helmetConfigurator: HelmetConfigurato
  * @returns {object} Immutable config object.
  */
 export default function ingest(config?: ConfigurationOptions): object;
-export type ContextEvent = import('./index').ContextEvent;
-export type SessionOptions = {
-    /**
-     * Session name
-     */
-    name?: string | undefined;
-    /**
-     * Encryption secret
-     */
-    secret?: string | undefined;
-    /**
-     * Session ttl (seconds)
-     */
-    ttl?: number | undefined;
-    /**
-     * Whether to use secure session cookies
-     */
-    secure?: boolean | undefined;
-    /**
-     * SameSite (true = Strict)
-     */
-    cookieSameSite?: string | boolean | undefined;
-    /**
-     * Session store (default MemoryStore)
-     */
-    store?: object | undefined;
-};
-export type I18nOptions = {
-    /**
-     * Directories to search for locale dictionaries
-     */
-    dirs: string[];
-    /**
-     * Supported locales
-     */
-    locales?: string[] | undefined;
-};
-/**
- * Hook configuration
- */
-export type GlobalHook = {
-    /**
-     * Hook name in format `<router>.<hook>`
-     */
-    hook: string;
-    /**
-     * Middleware function to insert at the hook point
-     */
-    middleware: Function;
-    /**
-     * Only run if route path matches this string/regexp
-     */
-    path?: string | RegExp | undefined;
-};
-/**
- * (extends GlobalHook)
- */
-export type PageHook = {
-    /**
-     * Hook name (without a scope prefix)
-     */
-    hook: string;
-    /**
-     * Middleware function to insert at the hook point
-     */
-    middleware: Function;
-};
-/**
- * Page configuration. A Page is the interactive representation of a waypoint
- */
-export type Page = {
-    /**
-     * The waypoint with which this page is associated
-     */
-    waypoint: string;
-    /**
-     * Template path
-     */
-    view: string;
-    /**
-     * Page-specific hooks (optional, default [])
-     */
-    hooks?: PageHook[] | undefined;
-    /**
-     * Fields to be managed on this page (optional, default [])
-     */
-    fields?: PageField[] | undefined;
-};
-export type HelmetConfigurator = (config: object) => object;
-/**
- * Configuration options
- */
-export type ConfigurationOptions = {
-    mountUrl?: string | undefined;
-    /**
-     * Template directories
-     */
-    views?: string[] | undefined;
-    /**
-     * Session configuration
-     */
-    session?: SessionOptions | undefined;
-    /**
-     * Pages the represent waypoints
-     */
-    pages?: Page[] | undefined;
-    /**
-     * Hooks to apply
-     */
-    hooks?: GlobalHook[] | undefined;
-    /**
-     * Plugins
-     */
-    plugins?: object[] | undefined;
-    /**
-     * I18n configuration
-     */
-    i18n?: I18nOptions[] | undefined;
-    /**
-     * CASA Plan
-     */
-    plan: Plan;
-    /**
-     * Handlers for JourneyContext events
-     */
-    events?: any[] | undefined;
-};
-import { PageField } from "./field.js";
-import Plan from "./Plan.js";
+export type ConfigurationOptions = import('../casa').ConfigurationOptions;
+export type HelmetConfigurator = import('../casa').HelmetConfigurator;