@dwp/govuk-casa 8.0.2 → 8.2.0

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,11 +119,19 @@ 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;
 export function validateEvents(events: any): any;
+/**
+ * Validates helmet configuration function.
+ *
+ * @param {HelmetConfigurator} helmetConfigurator Configuration function
+ * @returns {HelmetConfigurator} Validated configuration function
+ * @throws {TypeError} when passed a non-function
+ */
+export function validateHelmetConfigurator(helmetConfigurator: HelmetConfigurator): HelmetConfigurator;
 /**
  * Ingest, validate, sanitise and manipulate configuration parameters.
  *
@@ -132,131 +140,5 @@ export function validateEvents(events: any): any;
  * @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;
-};
-/**
- * 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;

package/dist/lib/configuration-ingestor.js

@@ -3,63 +3,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateEvents = exports.validatePlugins = exports.validateGlobalHooks = exports.validatePlan = exports.validatePages = exports.validateFields = exports.validatePageHooks = exports.validateSessionCookieSameSite = exports.validateSessionCookiePath = exports.validateSessionStore = exports.validateSessionSecure = exports.validateSessionName = exports.validateSessionTtl = exports.validateSessionSecret = exports.validateViews = exports.validateSessionObject = exports.validateMountUrl = exports.validateI18nLocales = exports.validateI18nDirs = exports.validateI18nObject = void 0;
+exports.validateHelmetConfigurator = exports.validateEvents = exports.validatePlugins = exports.validateGlobalHooks = exports.validatePlan = exports.validatePages = exports.validateFields = exports.validatePageHooks = exports.validateSessionCookieSameSite = exports.validateSessionCookiePath = exports.validateSessionStore = exports.validateSessionSecure = exports.validateSessionName = exports.validateSessionTtl = exports.validateSessionSecret = exports.validateViews = exports.validateSessionObject = exports.validateMountUrl = exports.validateI18nLocales = exports.validateI18nDirs = exports.validateI18nObject = void 0;
 /* eslint-disable sonarjs/no-duplicate-string */
 const field_js_1 = require("./field.js");
 const Plan_js_1 = __importDefault(require("./Plan.js"));
 const logger_js_1 = __importDefault(require("./logger.js"));
 const utils_js_1 = require("./utils.js");
 /**
- * @typedef {import('./index').ContextEvent} ContextEvent
+ * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
  */
 /**
- * @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} 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} 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 [])
- */
-/**
- * Configure some middleware for use in creating a new CASA app.
- *
- * `mountUrl` is used to ensure the CSS content uses the correct reference to
- * static assets in the `govuk-frontend` module.
- *
- * @typedef {object} ConfigurationOptions Configuration options
- * @property {string} [mountUrl=/] URL path to root of CASA app
- * @property {string[]} [views=[]] Template directories
- * @property {SessionOptions} [session] Session configuration
- * @property {Page[]} [pages=[]] Pages the represent waypoints
- * @property {GlobalHook[]} [hooks=[]] Hooks to apply
- * @property {object[]} [plugins=[]] Plugins
- * @property {I18nOptions[]} [i18n] I18n configuration
- * @property {Plan} plan CASA Plan
- * @property {ContextEvent[]} [events=[]] Handlers for JourneyContext events
+ * @typedef {import('../casa').HelmetConfigurator} HelmetConfigurator
  */
 const log = (0, logger_js_1.default)('lib:configuration-ingestor');
 const echo = (a) => (a);
@@ -71,7 +25,7 @@ const echo = (a) => (a);
  * @throws {TypeError} For invalid object.
  * @returns {object} Sanitised i18n object.
  */
-function validateI18nObject(i18n, cb = echo) {
+function validateI18nObject(i18n = Object.create(null), cb = echo) {
     if (Object.prototype.toString.call(i18n) !== '[object Object]') {
         throw new TypeError('I18n must be an object');
     }
@@ -86,11 +40,8 @@ exports.validateI18nObject = validateI18nObject;
  * @throws {TypeError} For invalid type.
  * @returns {Array} Array of directories.
  */
-function validateI18nDirs(dirs) {
-    if (typeof dirs === 'undefined') {
-        throw ReferenceError('I18n directories are missing (i18n.dirs)');
-    }
-    else if (!Array.isArray(dirs)) {
+function validateI18nDirs(dirs = []) {
+    if (!Array.isArray(dirs)) {
         throw new TypeError('I18n directories must be an array (i18n.dirs)');
     }
     dirs.forEach((dir, i) => {
@@ -109,11 +60,8 @@ exports.validateI18nDirs = validateI18nDirs;
  * @throws {TypeError} For invalid type.
  * @returns {Array} Array of locales.
  */
-function validateI18nLocales(locales) {
-    if (typeof locales === 'undefined') {
-        throw ReferenceError('I18n locales are missing (i18n.locales)');
-    }
-    else if (!Array.isArray(locales)) {
+function validateI18nLocales(locales = ['en', 'cy']) {
+    if (!Array.isArray(locales)) {
         throw new TypeError('I18n locales must be an array (i18n.locales)');
     }
     locales.forEach((locale, i) => {
@@ -150,7 +98,7 @@ exports.validateMountUrl = validateMountUrl;
  * @throws {TypeError} For invalid object.
  * @returns {object} Sanitised sessions object.
  */
-function validateSessionObject(session, cb = echo) {
+function validateSessionObject(session = Object.create(null), cb = echo) {
     if (session === undefined) {
         return cb(session);
     }
@@ -168,11 +116,8 @@ exports.validateSessionObject = validateSessionObject;
  * @throws {TypeError} For invalid type.
  * @returns {Array} Array of directories.
  */
-function validateViews(dirs) {
-    if (typeof dirs === 'undefined') {
-        throw ReferenceError('View directories are missing (views)');
-    }
-    else if (!Array.isArray(dirs)) {
+function validateViews(dirs = []) {
+    if (!Array.isArray(dirs)) {
         throw new TypeError('View directories must be an array (views)');
     }
     dirs.forEach((dir, i) => {
@@ -209,11 +154,8 @@ exports.validateSessionSecret = validateSessionSecret;
  * @throws {TypeError} For invalid value.
  * @returns {number} Ttl.
  */
-function validateSessionTtl(ttl) {
-    if (typeof ttl === 'undefined') {
-        throw ReferenceError('Session ttl is missing (session.ttl)');
-    }
-    else if (typeof ttl !== 'number') {
+function validateSessionTtl(ttl = 3600) {
+    if (typeof ttl !== 'number') {
         throw new TypeError('Session ttl must be an integer (session.ttl)');
     }
     return ttl;
@@ -222,16 +164,13 @@ exports.validateSessionTtl = validateSessionTtl;
 /**
  * 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.
  */
-function validateSessionName(name) {
-    if (typeof name === 'undefined') {
-        throw ReferenceError('Session name is missing (session.name)');
-    }
-    else if (typeof name !== 'string') {
+function validateSessionName(name = 'casa-session') {
+    if (typeof name !== 'string') {
         throw new TypeError('Session name must be a string (session.name)');
     }
     return name;
@@ -240,16 +179,13 @@ exports.validateSessionName = validateSessionName;
 /**
  * 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.
  */
-function validateSessionSecure(secure) {
-    if (typeof secure === 'undefined') {
-        throw ReferenceError('Session secure flag is missing (session.secure)');
-    }
-    else if (typeof secure !== 'boolean') {
+function validateSessionSecure(secure = false) {
+    if (typeof secure !== 'boolean') {
         throw new TypeError('Session secure flag must be boolean (session.secure)');
     }
     return secure;
@@ -366,7 +302,7 @@ const validatePage = (page, index) => {
         throw err;
     }
 };
-function validatePages(pages) {
+function validatePages(pages = []) {
     if (!Array.isArray(pages)) {
         throw new TypeError('Pages must be an array (pages)');
     }
@@ -418,6 +354,20 @@ function validateEvents(events) {
     return events;
 }
 exports.validateEvents = validateEvents;
+/**
+ * Validates helmet configuration function.
+ *
+ * @param {HelmetConfigurator} helmetConfigurator Configuration function
+ * @returns {HelmetConfigurator} Validated configuration function
+ * @throws {TypeError} when passed a non-function
+ */
+function validateHelmetConfigurator(helmetConfigurator) {
+    if (helmetConfigurator !== undefined && !(helmetConfigurator instanceof Function)) {
+        throw new TypeError('Helmet configurator must be a function');
+    }
+    return helmetConfigurator;
+}
+exports.validateHelmetConfigurator = validateHelmetConfigurator;
 /**
  * Ingest, validate, sanitise and manipulate configuration parameters.
  *
@@ -432,6 +382,9 @@ function ingest(config = {}) {
             dirs: validateI18nDirs(i18n.dirs),
             locales: validateI18nLocales(i18n.locales),
         })),
+        // !!! DEPRECATION NOTICE !!!
+        // This will be removed in next major version
+        //
         // Public URL from which the app will be served
         mountUrl: validateMountUrl(config.mountUrl),
         // Session
@@ -456,6 +409,8 @@ function ingest(config = {}) {
         plugins: validatePlugins(config.plugins),
         // Events
         events: validateEvents(config.events),
+        // Helmet configuration
+        helmetConfigurator: validateHelmetConfigurator(config.helmetConfigurator),
     };
     // Freeze to modifications
     Object.freeze(parsed);

package/dist/lib/configure.d.ts

@@ -1,90 +1,19 @@
 /**
- * @typedef {import('express').RequestHandler} ExpressRequestHandler
+ * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
  */
 /**
- * @typedef {import('./index').MutableRouter} MutableRouter
+ * @typedef {import('../casa').ConfigurationOptions} ConfigureResult
  */
 /**
- * @typedef {import('./configuration-ingestor').ConfigurationOptions} ConfigurationOptions
- */
-/**
- * @typedef {object} ConfigureResult Result of a call to configure() function
- * @property {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 {ExpressRequestHandler[]} preMiddleware Middleware mounted before anything else
- * @property {ExpressRequestHandler[]} postMiddleware Middleware mounted after everything else
- * @property {ExpressRequestHandler[]} csrfMiddleware CSRF get/set middleware (useful for forms)
- * @property {ExpressRequestHandler} sessionMiddleware Session middleware
- * @property {ExpressRequestHandler[]} cookieParserMiddleware Cookie-parsing middleware
- * @property {ExpressRequestHandler[]} i18nMiddleware I18n preparation middleware
- * @property {ExpressRequestHandler} bodyParserMiddleware Body parsing middleware
- * @property {Function} mount Function used to mount all CASA artifacts onto an ExpressJS app
+ * @typedef {import('../casa').Mounter} Mounter
  */
 /**
  * Configure some middleware for use in creating a new CASA app.
  *
- * `mountUrl` is used to ensure the CSS content uses the correct reference to
- * static assets in the `govuk-frontend` module.
- *
  * @param {ConfigurationOptions} config Configuration options
  * @returns {ConfigureResult} Result
  */
 export default function configure(config?: ConfigurationOptions): ConfigureResult;
-export type ExpressRequestHandler = import('express').RequestHandler;
-export type MutableRouter = import('./index').MutableRouter;
-export type ConfigurationOptions = import('./configuration-ingestor').ConfigurationOptions;
-/**
- * Result of a call to configure() function
- */
-export type ConfigureResult = {
-    /**
-     * Nunjucks environment
-     */
-    nunjucksEnv: 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 anything else
-     */
-    preMiddleware: ExpressRequestHandler[];
-    /**
-     * Middleware mounted after everything else
-     */
-    postMiddleware: ExpressRequestHandler[];
-    /**
-     * CSRF get/set middleware (useful for forms)
-     */
-    csrfMiddleware: ExpressRequestHandler[];
-    /**
-     * Session middleware
-     */
-    sessionMiddleware: ExpressRequestHandler;
-    /**
-     * Cookie-parsing middleware
-     */
-    cookieParserMiddleware: ExpressRequestHandler[];
-    /**
-     * I18n preparation middleware
-     */
-    i18nMiddleware: ExpressRequestHandler[];
-    /**
-     * Body parsing middleware
-     */
-    bodyParserMiddleware: ExpressRequestHandler;
-    /**
-     * Function used to mount all CASA artifacts onto an ExpressJS app
-     */
-    mount: Function;
-};
+export type ConfigurationOptions = import('../casa').ConfigurationOptions;
+export type ConfigureResult = import('../casa').ConfigurationOptions;
+export type Mounter = import('../casa').Mounter;