@dwp/govuk-casa 8.0.0-alpha1 → 8.0.0

package/dist/lib/ValidationError.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import('./ValidatorFactory').ValidateContext} ValidateContext
+ */
 export default class ValidationError {
     /**
      * Make a ValidationError instance from a primitive object (or a function that
@@ -61,10 +64,11 @@ export default class ValidationError {
      * @param {ValidateContext} context See structure above
      * @returns {ValidationError} Chain
      */
-    withContext(context: any): ValidationError;
+    withContext(context: ValidateContext): ValidationError;
     variables: any;
-    field: any;
+    field: string | undefined;
     fieldHref: string | undefined;
     focusSuffix: any;
     validator: any;
 }
+export type ValidateContext = import('./ValidatorFactory').ValidateContext;

package/dist/lib/ValidationError.js

@@ -6,6 +6,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const lodash_1 = __importDefault(require("lodash"));
 const { isPlainObject } = lodash_1.default; // CommonJS
 const params = new WeakMap();
+/**
+ * @typedef {import('./ValidatorFactory').ValidateContext} ValidateContext
+ */
 class ValidationError {
     /**
      * Make a ValidationError instance from a primitive object (or a function that
@@ -111,11 +114,15 @@ class ValidationError {
         // the values that will be readable, and reflect any context that may have
         // been applied
         Object.keys(originals).forEach((o) => {
+            // ESLint disabled as `o` is an "own" property of `originals`, which is
+            // dev-controlled
+            /* eslint-disable security/detect-object-injection */
             Object.defineProperty(this, o, {
                 value: originals[o],
                 enumerable: true,
                 writable: true,
             });
+            /* eslint-enable security/detect-object-injection */
         });
     }
     /**

package/dist/lib/ValidatorFactory.d.ts

@@ -1,24 +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 bind and return this class'
-     * `validate()` function, so you can call it directly rather than calling the
-     * method. i.e.
+     * This is a convenience method that will return a consistently object
+     * structure containing validation and sanitisation methods.
      *
-     *  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
+     * @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): object;
+    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

@@ -4,24 +4,43 @@ var __importDefault = (this && this.__importDefault) || function (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
+/**
+ * @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 bind and return this class'
-     * `validate()` function, so you can call it directly rather than calling the
-     * method. i.e.
+     * This is a convenience method that will return a consistently object
+     * structure containing validation and sanitisation methods.
      *
-     *  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
+     * @param {object} config Validator config (custom to the validator being created)
+     * @returns {Validator} Validator object
      * @throws {TypeError} When configurarion is invalid.
      */
     static make(config = {}) {
@@ -31,7 +50,7 @@ class ValidatorFactory {
         const validator = Reflect.construct(this, [config]);
         /* eslint-disable-next-line sonarjs/prefer-object-literal */
         const instance = {};
-        instance.name = validator.name || validator.constructor.name;
+        instance.name = validator.name || 'unknown';
         instance.config = config;
         instance.validate = validator.validate.bind(instance);
         instance.sanitise = validator.sanitise.bind(instance);

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";