@dwp/govuk-casa 7.0.6 → 8.0.0-alpha1

package/dist/lib/ValidatorFactory.js

@@ -0,0 +1,87 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable class-methods-use-this */
+// const { isPlainObject } = require('../Util.js');
+const lodash_1 = __importDefault(require("lodash"));
+const { isPlainObject } = lodash_1.default; // CommonJS
+class ValidatorFactory {
+    /**
+     * This is a convenience method that will bind and return this class'
+     * `validate()` function, so you can call it directly rather than calling the
+     * method. i.e.
+     *
+     *  MyValidator.make()('value to validate')
+     *    versus
+     *  (new MyValidator()).validate('value to validate')
+     *
+     * It also attaches the `sanitise()` method as a static property to that
+     * function.
+     *
+     * @param {object} config Validator config
+     * @returns {object} Validator object
+     * @throws {TypeError} When configurarion is invalid.
+     */
+    static make(config = {}) {
+        if (!isPlainObject(config)) {
+            throw new TypeError('Configuration must be an object');
+        }
+        const validator = Reflect.construct(this, [config]);
+        /* eslint-disable-next-line sonarjs/prefer-object-literal */
+        const instance = {};
+        instance.name = validator.name || validator.constructor.name;
+        instance.config = config;
+        instance.validate = validator.validate.bind(instance);
+        instance.sanitise = validator.sanitise.bind(instance);
+        Object.freeze(instance);
+        return instance;
+    }
+    static coerceToValidatorObject(input) {
+        let validator = Object.create(null);
+        validator.validate = () => (Promise.reject(new Error('validate() method has not been defined')));
+        validator.sanitise = (val) => (val);
+        validator.config = Object.create(null);
+        // An uninstantied Validator subclass
+        if (typeof input === 'function' && Reflect.getPrototypeOf(input) === ValidatorFactory) {
+            validator = input.make();
+        }
+        else if (typeof input === 'function') {
+            // A plain function is assumed to be just the validation logic. We do not
+            // bind the function to `validator` here because it may already be bound to
+            // another context in userland.
+            validator.name = input.name || input.constructor.name || 'unknown';
+            validator.validate = input;
+        }
+        else if (isPlainObject(input)) {
+            // A plain object
+            validator = {
+                validate: input.validate || validator.validate,
+                sanitise: input.sanitise || validator.sanitise,
+                config: input.config || validator.config,
+                name: input.name || validator.name,
+            };
+        }
+        else {
+            // An unsupported scenario
+            throw new TypeError(`Cannot coerce input to a validator object (typeof = ${typeof input})`);
+        }
+        return validator;
+    }
+    constructor(config = {}) {
+        if (new.target === ValidatorFactory) {
+            throw new TypeError('Cannot instantiate the abstract class, ValidatorFactory');
+        }
+        this.config = config;
+    }
+    /* eslint-disable-next-line no-unused-vars */
+    validate(fieldValue, context) {
+        throw new Error('validate() method has not been implemented');
+    }
+    /* eslint-disable-next-line no-unused-vars */
+    sanitise(fieldValue) {
+        return fieldValue;
+    }
+}
+exports.default = ValidatorFactory;

package/dist/lib/configure.d.ts

@@ -0,0 +1,205 @@
+/**
+ *
+ * @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 setting (true (Strict), false (no value), Strict, Lax, None, default true)
+ * @property {object} [store] Session store (default MemoryStore)
+ */
+/**
+ * @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] Hook only triggered if route path matches this string/regexp (optional, default /./)
+ */
+/**
+ * @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
+ * @property {PageField[]} fields Fields to be managed on this page
+ */
+/**
+ * @typedef {Object} ConfigureResult Result of a call to configure() function
+ * @property {nunjucks.Environment} nunjucksEnv Nunjucks environment to attach to other ExpressJS app instances
+ * @property {MutableRouter} staticRouter ExpressJS Router instance which serves all static assets
+ * @property {MutableRouter} ancillaryRouter ExpressJS app instance which serves all ancillary routes
+ * @property {MutableRouter} journeyRouter ExpressJS app instance which serves page routes for each waypoint in a user's journey
+ * @property {express.RequestHandler[]} preMiddleware Middleware mounted before anything else
+ * @property {express.RequestHandler[]} postMiddleware Middleware mounted after everything else
+ * @property {express.RequestHandler[]} csrfMiddleware Collection of middleware useful for pages containing forms
+ * @property {express.RequestHandler} sessionMiddleware Session middleware
+ * @property {express.RequestHandler[]} cookieParserMiddleware Cookie-parsing middleware (configured to match that of session middleware)
+ * @property {express.RequestHandler[]} i18nMiddleware I18n preparation middleware
+ * @property {express.RequestHandler} bodyParserMiddleware Body parsing middleware
+ * @property {express.RequestHandler[]} csrfMiddleware CSRF middleware
+ * @property {function} mount Function used to mount all CASA artifacts onto an ExpressJS app instance
+ */
+/**
+ * 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 {Object} config Configuration options
+ * @param {string} [config.mountUrl=/] URL path used to serve static assets from and generate links (optional, default /)
+ * @param {string} [config.serviceName=common.serviceName] Service name (i18n key) to display in header (optional, default common:serviceName)
+ * @param {string[]} [config.views=[]] Array of directories in which Nunjucks templates will be searched for (optional, default [])
+ * @param {SessionOptions} [config.session] Session configuration
+ * @param {Page[]} [config.pages=[]] Pages the represent waypoints in the Plan (optional, default [])
+ * @param {GlobalHook[]} [config.hooks=[]] Hooks to apply (optional, default [])
+ * @param {Object[]} [config.plugins=[]] Plugins(optional, default [])
+ * @param {I18nOptions[]} [config.i18n] I18n configuration
+ * @param {Plan} config.plan CASA Plan
+ * @param {ContextEvent[]} [config.events=[]] Handlers for JourneyContext events
+ * @returns {ConfigureResult} Result
+ */
+export default function configure(config?: {
+    mountUrl?: string | undefined;
+    serviceName?: string | undefined;
+    views?: string[] | undefined;
+    session?: SessionOptions | undefined;
+    pages?: Page[] | undefined;
+    hooks?: GlobalHook[] | undefined;
+    plugins?: Object[] | undefined;
+    i18n?: any[] | undefined;
+    plan: any;
+    events?: any[] | undefined;
+}): ConfigureResult;
+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 setting (true (Strict), false (no value), Strict, Lax, None, default true)
+     */
+    cookieSameSite?: string | boolean | undefined;
+    /**
+     * Session store (default MemoryStore)
+     */
+    store?: object | undefined;
+};
+/**
+ * Hook configuration
+ */
+export type GlobalHook = {
+    /**
+     * Hook name in format `<router>.<hook>`
+     */
+    hook: string;
+    /**
+     * Middleware function to insert at the hook point
+     */
+    middleware: Function;
+    /**
+     * Hook only triggered if route path matches this string/regexp (optional, default /./)
+     */
+    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
+     */
+    hooks: PageHook[];
+    /**
+     * Fields to be managed on this page
+     */
+    fields: any[];
+};
+/**
+ * Result of a call to configure() function
+ */
+export type ConfigureResult = {
+    /**
+     * Nunjucks environment to attach to other ExpressJS app instances
+     */
+    nunjucksEnv: any;
+    /**
+     * ExpressJS Router instance which serves all static assets
+     */
+    staticRouter: any;
+    /**
+     * ExpressJS app instance which serves all ancillary routes
+     */
+    ancillaryRouter: any;
+    /**
+     * ExpressJS app instance which serves page routes for each waypoint in a user's journey
+     */
+    journeyRouter: any;
+    /**
+     * Middleware mounted before anything else
+     */
+    preMiddleware: any[];
+    /**
+     * Middleware mounted after everything else
+     */
+    postMiddleware: any[];
+    /**
+     * Collection of middleware useful for pages containing forms
+     */
+    csrfMiddleware: any[];
+    /**
+     * Session middleware
+     */
+    sessionMiddleware: any;
+    /**
+     * Cookie-parsing middleware (configured to match that of session middleware)
+     */
+    cookieParserMiddleware: any[];
+    /**
+     * I18n preparation middleware
+     */
+    i18nMiddleware: any[];
+    /**
+     * Body parsing middleware
+     */
+    bodyParserMiddleware: any;
+    /**
+     * Function used to mount all CASA artifacts onto an ExpressJS app instance
+     */
+    mount: Function;
+};

package/dist/lib/configure.js

@@ -0,0 +1,215 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const dirname_cjs_1 = __importDefault(require("./dirname.cjs"));
+const express_session_1 = require("express-session");
+const path_1 = require("path");
+const module_1 = require("module");
+const nunjucks_js_1 = __importDefault(require("./nunjucks.js"));
+const static_js_1 = __importDefault(require("../routes/static.js"));
+const ancillary_js_1 = __importDefault(require("../routes/ancillary.js"));
+const journey_js_1 = __importDefault(require("../routes/journey.js"));
+const pre_js_1 = __importDefault(require("../middleware/pre.js"));
+const post_js_1 = __importDefault(require("../middleware/post.js"));
+const session_js_1 = __importDefault(require("../middleware/session.js"));
+const cookie_parser_1 = __importDefault(require("cookie-parser"));
+const i18n_js_1 = __importDefault(require("../middleware/i18n.js"));
+const data_js_1 = __importDefault(require("../middleware/data.js"));
+const body_parser_js_1 = __importDefault(require("../middleware/body-parser.js"));
+const csrf_js_1 = __importDefault(require("../middleware/csrf.js"));
+/**
+ *
+ * @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 setting (true (Strict), false (no value), Strict, Lax, None, default true)
+ * @property {object} [store] Session store (default MemoryStore)
+ */
+/**
+ * @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] Hook only triggered if route path matches this string/regexp (optional, default /./)
+ */
+/**
+ * @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
+ * @property {PageField[]} fields Fields to be managed on this page
+ */
+/**
+ * @typedef {Object} ConfigureResult Result of a call to configure() function
+ * @property {nunjucks.Environment} nunjucksEnv Nunjucks environment to attach to other ExpressJS app instances
+ * @property {MutableRouter} staticRouter ExpressJS Router instance which serves all static assets
+ * @property {MutableRouter} ancillaryRouter ExpressJS app instance which serves all ancillary routes
+ * @property {MutableRouter} journeyRouter ExpressJS app instance which serves page routes for each waypoint in a user's journey
+ * @property {express.RequestHandler[]} preMiddleware Middleware mounted before anything else
+ * @property {express.RequestHandler[]} postMiddleware Middleware mounted after everything else
+ * @property {express.RequestHandler[]} csrfMiddleware Collection of middleware useful for pages containing forms
+ * @property {express.RequestHandler} sessionMiddleware Session middleware
+ * @property {express.RequestHandler[]} cookieParserMiddleware Cookie-parsing middleware (configured to match that of session middleware)
+ * @property {express.RequestHandler[]} i18nMiddleware I18n preparation middleware
+ * @property {express.RequestHandler} bodyParserMiddleware Body parsing middleware
+ * @property {express.RequestHandler[]} csrfMiddleware CSRF middleware
+ * @property {function} mount Function used to mount all CASA artifacts onto an ExpressJS app instance
+ */
+/**
+ * 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 {Object} config Configuration options
+ * @param {string} [config.mountUrl=/] URL path used to serve static assets from and generate links (optional, default /)
+ * @param {string} [config.serviceName=common.serviceName] Service name (i18n key) to display in header (optional, default common:serviceName)
+ * @param {string[]} [config.views=[]] Array of directories in which Nunjucks templates will be searched for (optional, default [])
+ * @param {SessionOptions} [config.session] Session configuration
+ * @param {Page[]} [config.pages=[]] Pages the represent waypoints in the Plan (optional, default [])
+ * @param {GlobalHook[]} [config.hooks=[]] Hooks to apply (optional, default [])
+ * @param {Object[]} [config.plugins=[]] Plugins(optional, default [])
+ * @param {I18nOptions[]} [config.i18n] I18n configuration
+ * @param {Plan} config.plan CASA Plan
+ * @param {ContextEvent[]} [config.events=[]] Handlers for JourneyContext events
+ * @returns {ConfigureResult} Result
+ */
+function configure(config = {}) {
+    var _a, _b;
+    // Pass the raw config through each plugin's configure phase so they can
+    // optionally modify it
+    ((_a = config.plugins) !== null && _a !== void 0 ? _a : []).forEach((plugin) => {
+        plugin.configure(config);
+    });
+    // Extract config
+    // TODO: Validate/sanitise and deep-freeze object
+    const { mountUrl = '/', serviceName = 'common:serviceName', views = [], session = {
+        secret: 'secret',
+        name: 'casasession',
+        secure: false,
+        ttl: 60 * 60,
+        cookieSameSite: true,
+        store: undefined,
+    }, pages = [], plan = null, hooks = [], plugins = [], events = [], i18n = {
+        dirs: [],
+        locales: ['en', 'cy'],
+    }, } = config;
+    // Prepare a Nunjucks environment for rendering all templates.
+    // Resolve priority: userland templates > CASA templates > GOVUK templates > Plugin templates
+    const nunjucksEnv = (0, nunjucks_js_1.default)({
+        mountUrl,
+        views: [
+            ...views,
+            (0, path_1.resolve)(dirname_cjs_1.default, '../../views'),
+            (0, path_1.resolve)((0, module_1.createRequire)(dirname_cjs_1.default).resolve('govuk-frontend'), '../../'),
+        ],
+    });
+    // Prepare mandatory middleware
+    // These _must_ be added to the ExpressJS application at the start and end
+    // of all other middleware respectively.
+    const preMiddleware = (0, pre_js_1.default)();
+    const postMiddleware = (0, post_js_1.default)();
+    // Prepare common middleware mounted prior to the ancillaryRouter
+    const cookieParserMiddleware = (0, cookie_parser_1.default)(session.secret);
+    const sessionMiddleware = (0, session_js_1.default)({
+        cookieParserMiddleware,
+        secure: session.secure,
+        secret: session.secret,
+        name: session.name,
+        ttl: session.ttl,
+        cookieSameSite: session.cookieSameSite,
+        mountUrl,
+        store: (_b = session.store) !== null && _b !== void 0 ? _b : new express_session_1.MemoryStore(),
+    });
+    const i18nMiddleware = (0, i18n_js_1.default)({
+        directories: [
+            // Order is important; latter directories take precedence
+            (0, path_1.resolve)(dirname_cjs_1.default, '../../locales/'),
+            ...i18n.dirs,
+        ],
+        languages: i18n.locales,
+    });
+    const dataMiddleware = (0, data_js_1.default)({
+        plan,
+        mountUrl,
+        serviceName,
+        events,
+    });
+    // Prepare form middleware and its constiuent parts
+    // These are used for any forms, including waypoint page forms.
+    const bodyParserMiddleware = (0, body_parser_js_1.default)();
+    const csrfMiddleware = (0, csrf_js_1.default)();
+    // Setup router to serve up bundled static assets
+    const staticRouter = (0, static_js_1.default)({
+        mountUrl,
+    });
+    // Setup ancillary router default stand-alone pages.
+    const ancillaryRouter = (0, ancillary_js_1.default)({
+        sessionTtl: session.ttl,
+    });
+    // Setup waypoint router, which includes routes for every defined waypoint
+    const journeyRouter = (0, journey_js_1.default)({
+        globalHooks: hooks,
+        pages,
+        plan,
+        csrfMiddleware,
+        mountUrl,
+    });
+    // Mount function
+    // This will mount all of these routes and middleware in the correct order on
+    // the given ExpressJS app.
+    // Once this is called, you will not be able to modify any of the routers as
+    // they will be "sealed".
+    const mount = (app) => {
+        nunjucksEnv.express(app);
+        app.set('view engine', 'njk');
+        app.use(preMiddleware);
+        app.use(staticRouter.seal());
+        app.use(sessionMiddleware); // A session is useful to all pages, so assume it is always mounted after static routes
+        app.use(i18nMiddleware);
+        app.use(bodyParserMiddleware);
+        app.use(dataMiddleware);
+        app.use(ancillaryRouter.seal());
+        app.use(journeyRouter.seal());
+        app.use(postMiddleware);
+        return app;
+    };
+    // Prepare configuration result
+    const configOutput = {
+        // Nunjucks environment, so it can be attached to other ExpressJS instances
+        // using `nunjucksEnv.express(myApp); myApp.set('view engine', 'njk');`.
+        nunjucksEnv,
+        // Mandatory middleware. User must add these to their ExpressJS app.
+        preMiddleware,
+        postMiddleware,
+        // Mandatory routers that consumer must mount onto their own ExpressJS parent app
+        staticRouter,
+        ancillaryRouter,
+        journeyRouter,
+        // Form middleware. Should be used wherever form pages are built.
+        csrfMiddleware,
+        // Other middleware
+        // These may be used by the application author to build other custom routes
+        cookieParserMiddleware,
+        sessionMiddleware,
+        bodyParserMiddleware,
+        csrfMiddleware,
+        i18nMiddleware,
+        dataMiddleware,
+        // Mount function
+        mount,
+    };
+    // Bootstrap all plugins
+    plugins.filter(p => p.bootstrap).forEach((plugin) => plugin === null || plugin === void 0 ? void 0 : plugin.bootstrap(configOutput));
+    // Finished configuration
+    return configOutput;
+}
+exports.default = configure;

package/dist/lib/dirname.cjs

@@ -0,0 +1 @@
+module.exports = __dirname;

package/dist/lib/end-session.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A convenience for ending the current session, but retaining some data in it,
+ * like the current language.
+ *
+ * Note: this will not remove the session from server-side storage, which will
+ * instead be left up to the storage mechanism to clean up.
+ *
+ * @param {Object} req HTTP request
+ * @param {Function} next Chain
+ * @returns {void}
+ */
+export default function endSession(req: Object, next: Function): void;

package/dist/lib/end-session.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * A convenience for ending the current session, but retaining some data in it,
+ * like the current language.
+ *
+ * Note: this will not remove the session from server-side storage, which will
+ * instead be left up to the storage mechanism to clean up.
+ *
+ * @param {Object} req HTTP request
+ * @param {Function} next Chain
+ * @returns {void}
+ */
+function endSession(req, next) {
+    const language = req.session.language;
+    req.session.regenerate((err) => {
+        if (err) {
+            return next(err);
+        }
+        req.session.language = language;
+        req.session.save(next);
+    });
+}
+exports.default = endSession;

package/dist/lib/field.d.ts

@@ -0,0 +1,79 @@
+export default function field(...args: any[]): PageField;
+export class PageField {
+    constructor(name: any, { optional, persist }?: any);
+    /**
+     * For complex fields, we need may need to drill into an object to extract the
+     * value.
+     *
+     * @param {Object} obj Object from which to extract the value
+     * @returns {any}
+     */
+    getValue(obj?: Object): any;
+    putValue(obj: any, value: any): PageField;
+    get name(): string;
+    get meta(): Object;
+    validators(...items: any[]): PageField | Validator[];
+    processors(...items: any[]): Function[] | PageField;
+    conditions(...items: any[]): Function[] | PageField;
+    /**
+     * Run all validators and return array of errors, if applicable.
+     *
+     * @param {any} value Value to validate
+     * @param {ValidateContext} context Contextual information
+     * @returns {ValidationError[]} Errors, or an empty array if all valid
+     */
+    runValidators(value: any, context: ValidateContext): any[];
+    applyProcessors(value: any): any;
+    /**
+     * Apply all conditions to get the resulting boolean
+     *
+     * @param {Object} params Parameters
+     * @param {string} fieldValue Field value
+     * @param {string} waypoint Waypoint
+     * @param {object} journeyContext JourneyContext
+     * @returns {boolean}
+     */
+    testConditions({ fieldValue, waypoint, journeyContext }: Object): boolean;
+    validator(...args: any[]): PageField | Validator[];
+    processor(...args: any[]): Function[] | PageField;
+    condition(...args: any[]): Function[] | PageField;
+    if(...args: any[]): Function[] | PageField;
+    #private;
+}
+export type Validator = {
+    /**
+     * Validation function
+     */
+    validate: ValidateFunction;
+    /**
+     * Sanitise a given value to make it suitable for this validator
+     */
+    sanitise: SanitiseFunction;
+    /**
+     * Configuration
+     */
+    config: Object;
+    /**
+     * Validator name
+     */
+    name: string;
+};
+export type ValidateFunction = (value: any, context: ValidateContext) => any[];
+export type SanitiseFunction = (value: any) => any;
+/**
+ * Context passed to validate function
+ */
+export type ValidateContext = {
+    /**
+     * Journey context
+     */
+    journeyContext: any;
+    /**
+     * Waypoint
+     */
+    waypoint: string;
+    /**
+     * Name of field being processed
+     */
+    fieldName: string;
+};