@dwp/govuk-casa 7.0.7 → 7.0.8

package/dist/lib/ValidatorFactory.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @typedef {import('./index').ProcessorFunction} ProcessorFunction
+ */
+/**
+ * @typedef {import('./index').JourneyContext} JourneyContext
+ */
+/**
+ * @typedef {import('./index').ValidationError} ValidationError
+ */
+/**
+ * @typedef {object} Validator
+ * @property {ValidateFunction} validate Validation function
+ * @property {ProcessorFunction} sanitise Sanitise a given value prior to validation
+ * @property {object} config Configuration
+ * @property {string} name Validator name
+ */
+/**
+ * @callback ValidateFunction
+ * @param {any} value
+ * @param {ValidateContext} context
+ * @returns {ValidationError[]}
+ */
+/**
+ * @typedef {object} ValidateContext Context passed to validate function
+ * @property {JourneyContext} journeyContext Journey context
+ * @property {string} waypoint Waypoint
+ * @property {string} fieldName Name of field being processed
+ */
+export default class ValidatorFactory {
+    /**
+     * This is a convenience method that will return a consistently object
+     * structure containing validation and sanitisation methods.
+     *
+     * @param {object} config Validator config (custom to the validator being created)
+     * @returns {Validator} Validator object
+     * @throws {TypeError} When configurarion is invalid.
+     */
+    static make(config?: object): Validator;
+    static coerceToValidatorObject(input: any): any;
+    constructor(config?: {});
+    config: {};
+    validate(fieldValue: any, context: any): void;
+    sanitise(fieldValue: any): any;
+}
+export type ProcessorFunction = import('./index').ProcessorFunction;
+export type JourneyContext = import('./index').JourneyContext;
+export type ValidationError = import('./index').ValidationError;
+export type Validator = {
+    /**
+     * Validation function
+     */
+    validate: ValidateFunction;
+    /**
+     * Sanitise a given value prior to validation
+     */
+    sanitise: any;
+    /**
+     * Configuration
+     */
+    config: object;
+    /**
+     * Validator name
+     */
+    name: string;
+};
+export type ValidateFunction = (value: any, context: ValidateContext) => ValidationError[];
+/**
+ * Context passed to validate function
+ */
+export type ValidateContext = {
+    /**
+     * Journey context
+     */
+    journeyContext: JourneyContext;
+    /**
+     * Waypoint
+     */
+    waypoint: string;
+    /**
+     * Name of field being processed
+     */
+    fieldName: string;
+};

package/dist/lib/ValidatorFactory.js

@@ -0,0 +1,106 @@
+"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 lodash_1 = __importDefault(require("lodash"));
+const { isPlainObject } = lodash_1.default; // CommonJS
+/**
+ * @typedef {import('./index').ProcessorFunction} ProcessorFunction
+ */
+/**
+ * @typedef {import('./index').JourneyContext} JourneyContext
+ */
+/**
+ * @typedef {import('./index').ValidationError} ValidationError
+ */
+/**
+ * @typedef {object} Validator
+ * @property {ValidateFunction} validate Validation function
+ * @property {ProcessorFunction} sanitise Sanitise a given value prior to validation
+ * @property {object} config Configuration
+ * @property {string} name Validator name
+ */
+/**
+ * @callback ValidateFunction
+ * @param {any} value
+ * @param {ValidateContext} context
+ * @returns {ValidationError[]}
+ */
+/**
+ * @typedef {object} ValidateContext Context passed to validate function
+ * @property {JourneyContext} journeyContext Journey context
+ * @property {string} waypoint Waypoint
+ * @property {string} fieldName Name of field being processed
+ */
+class ValidatorFactory {
+    /**
+     * This is a convenience method that will return a consistently object
+     * structure containing validation and sanitisation methods.
+     *
+     * @param {object} config Validator config (custom to the validator being created)
+     * @returns {Validator} 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 || 'unknown';
+        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/configuration-ingestor.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Validates and sanitises i18n obejct.
+ *
+ * @param {object} i18n Object to validate.
+ * @param {Function} cb Callback function that receives the validated value.
+ * @throws {TypeError} For invalid object.
+ * @returns {object} Sanitised i18n object.
+ */
+export function validateI18nObject(i18n: object, cb?: Function): object;
+/**
+ * Validates and sanitises i18n directory.
+ *
+ * @param {Array} dirs Array of directories.
+ * @throws {SyntaxError} For invalid directories.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of directories.
+ */
+export function validateI18nDirs(dirs: any[]): any[];
+/**
+ * Validates and sanitises i18n locales.
+ *
+ * @param {Array} locales Array of locales.
+ * @throws {SyntaxError} For invalid locales.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of locales.
+ */
+export function validateI18nLocales(locales: any[]): any[];
+/**
+ * Validates and sanitises mount url.
+ *
+ * @param {string} mountUrl URL from which Express app will be served.
+ * @param {string} name Name of the URL type (Mount URL, or Proxy Mount URL).
+ * @throws {SyntaxError} For invalid URL.
+ * @returns {string} Sanitised URL.
+ */
+export function validateMountUrl(mountUrl: string, name?: string): string;
+/**
+ * Validates and sanitises sessions object.
+ *
+ * @param {object} session Object to validate.
+ * @param {Function} cb Callback function that receives the validated value.
+ * @throws {TypeError} For invalid object.
+ * @returns {object} Sanitised sessions object.
+ */
+export function validateSessionObject(session: object, cb?: Function): object;
+/**
+ * Validates and sanitises view directory.
+ *
+ * @param {Array} dirs Array of directories.
+ * @throws {SyntaxError} For invalid directories.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of directories.
+ */
+export function validateViews(dirs: any[]): any[];
+/**
+ * Validates and sanitises sessions secret.
+ *
+ * @param {string} secret Session secret.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {string} Secret.
+ */
+export function validateSessionSecret(secret: string): string;
+/**
+ * Validates and sanitises sessions ttl.
+ *
+ * @param {number} ttl Session ttl (seconds).
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {number} Ttl.
+ */
+export function validateSessionTtl(ttl: number): number;
+/**
+ * Validates and sanitises sessions name.
+ *
+ * @param {string} name Session name.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {string} Name.
+ */
+export function validateSessionName(name: string): string;
+/**
+ * Validates and sanitises sessions secure flag.
+ *
+ * @param {boolean} secure Session secure flag.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {string} Name.
+ */
+export function validateSessionSecure(secure: boolean): string;
+/**
+ * Validates and sanitises sessions store.
+ *
+ * @param {Function} store Session store.
+ * @returns {Function} Store.
+ */
+export function validateSessionStore(store: Function): Function;
+/**
+ * Validates and sanitises sessions cookie url path.
+ *
+ * @param {string} cookiePath Session cookie url path.
+ * @param {string} defaultPath Default path if none specified.
+ * @returns {string} Cookie path.
+ */
+export function validateSessionCookiePath(cookiePath: string, defaultPath?: string): string;
+/**
+ * Validates and sanitises sessions cookie "sameSite" flag. One of:
+ * true (Strict)
+ * false (will not set the flag at all)
+ * Strict
+ * Lax
+ * None
+ *
+ * @param {any} cookieSameSite Session cookie "sameSite" flag
+ * @param {any} defaultFlag Default path if none specified
+ * @returns {boolean} cookie path
+ * @throws {TypeError} When invalid arguments are provided
+ */
+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 validatePlan(plan: any): any;
+export function validateGlobalHooks(hooks: any): any[];
+export function validatePlugins(plugins: any): any;
+export function validateEvents(events: any): any;
+/**
+ * Ingest, validate, sanitise and manipulate configuration parameters.
+ *
+ * @param {ConfigurationOptions} config Config to ingest.
+ * @throws {Error|SyntaxError|TypeError} For invalid config values.
+ * @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";