@dwp/govuk-casa 8.15.0 → 9.1.0

package/dist/casa.d.ts

@@ -1,4 +1,4 @@
-export type PageField = import('./lib/field').PageField;
+export type PageField = import("./lib/field").PageField;
 export type ContextEventHandlerOptions = {
     /**
      * Context including changes
@@ -20,7 +20,8 @@ export type ContextEventHandlerOptions = {
 export type ContextEventHandler = (opts: ContextEventHandlerOptions) => void;
 export type ContextEventUserInfo = {
     /**
-     * Request phase at which event is triggered
+     * Request phase at which event is
+     * triggered
      */
     casaRequestPhase?: symbol | undefined;
 };
@@ -39,7 +40,8 @@ export type ContextEvent = {
     handler: ContextEventHandler;
 };
 /**
- * Page configuration. A Page is the interactive representation of a waypoint
+ * Page configuration. A Page is the interactive
+ *   representation of a waypoint
  */
 export type Page = {
     /**
@@ -51,11 +53,13 @@ export type Page = {
      */
     view: string;
     /**
-     * Page-specific hooks (optional, default [])
+     * Page-specific hooks (optional, default []).
+     * Default is `[]`
      */
     hooks?: PageHook[] | undefined;
     /**
-     * Fields to be managed on this page (optional, default [])
+     * Fields to be managed on this page
+     * (optional, default []). Default is `[]`
      */
     fields?: import("./lib/field.js").PageField[] | undefined;
 };
@@ -65,7 +69,8 @@ export type I18nOptions = {
      */
     dirs: string[];
     /**
-     * Supported locales
+     * Supported locales. Default is
+     * `['en', 'cy']`
      */
     locales?: string[] | undefined;
 };
@@ -78,11 +83,13 @@ export type GlobalHook = {
      */
     hook: string;
     /**
-     * Middleware function to insert at the hook point
+     * Middleware function to insert at the hook
+     * point
      */
     middleware: Function;
     /**
-     * Only run if route path matches this string/regexp
+     * Only run if route path matches
+     * this string/regexp. Default is `undefined`
      */
     path?: string | RegExp | undefined;
 };
@@ -95,29 +102,32 @@ export type PageHook = {
      */
     hook: string;
     /**
-     * Middleware function to insert at the hook point
+     * Middleware function to insert at the hook
+     * point
      */
     middleware: Function;
 };
 export type SessionOptions = {
     /**
-     * Session name
+     * Session name. Default is `casasession`
      */
     name?: string | undefined;
     /**
-     * Encryption secret
+     * Encryption secret. Default is `secret`
      */
     secret?: string | undefined;
     /**
-     * Session ttl (seconds)
+     * Session ttl (seconds). Default is `3600`
      */
     ttl?: number | undefined;
     /**
-     * Whether to use secure session cookies
+     * Whether to use secure session cookies.
+     * Default is `false`
      */
     secure?: boolean | undefined;
     /**
-     * SameSite (true = Strict)
+     * SameSite (true = Strict).
+     * Default is `true`
      */
     cookieSameSite?: string | boolean | undefined;
     /**
@@ -125,8 +135,8 @@ export type SessionOptions = {
      */
     store?: object | undefined;
     /**
-     * the URL path on which the session cookie
-     * is valid (defaults to '/')
+     * The URL path on which the session cookie is
+     * valid (defaults to '/')
      */
     cookiePath?: string | undefined;
 };
@@ -139,7 +149,8 @@ export type IPlugin = {
      */
     configure?: PluginConfigureFunction | undefined;
     /**
-     * Modify post-configuration artifacts
+     * Modify post-configuration
+     * artifacts
      */
     bootstrap?: PluginBootstrapFunction | undefined;
 };
@@ -149,15 +160,15 @@ export type HelmetConfigurator = (config: object) => object;
 /**
  * Mounting function.
  *
- * This will mount all of the routes and middleware in the correct order on
- * the given ExpressJS app.
+ * This will mount all of the 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".
  */
-export type Mounter = (app: import('express').Express, opts: {
+export type Mounter = (app: import("express").Express, opts: {
     route?: string | undefined;
-}) => import('express').Express;
+}) => import("express").Express;
 /**
  * Configuration options
  */
@@ -167,7 +178,7 @@ export type ConfigurationOptions = {
      */
     mountUrl?: string | undefined;
     /**
-     * Template directories
+     * Template directories. Default is `[]`
      */
     views?: string[] | undefined;
     /**
@@ -175,15 +186,15 @@ export type ConfigurationOptions = {
      */
     session?: SessionOptions | undefined;
     /**
-     * Pages the represent waypoints
+     * Pages the represent waypoints. Default is `[]`
      */
     pages?: Page[] | undefined;
     /**
-     * Hooks to apply
+     * Hooks to apply. Default is `[]`
      */
     hooks?: GlobalHook[] | undefined;
     /**
-     * Plugins
+     * Plugins. Default is `[]`
      */
     plugins?: IPlugin[] | undefined;
     /**
@@ -195,27 +206,33 @@ export type ConfigurationOptions = {
      */
     plan?: Plan | undefined;
     /**
-     * Handlers for JourneyContext events
+     * Handlers for JourneyContext events.
+     * Default is `[]`
      */
     events?: ContextEvent[] | undefined;
     /**
-     * Helmet configuration manipulator function
+     * Helmet configuration
+     * manipulator function
      */
     helmetConfigurator?: HelmetConfigurator | undefined;
     /**
-     * Max number of form parameters to ingest
+     * Max number of form parameters to
+     * ingest. Default is `25`
      */
     formMaxParams?: number | undefined;
     /**
-     * Max total form payload size to ingest
+     * Max total form payload size
+     * to ingest. Default is `"50KB"`
      */
     formMaxBytes?: string | number | undefined;
     /**
-     * Custom context ID generator
+     * Custom context ID
+     * generator
      */
     contextIdGenerator?: ContextIdGenerator | undefined;
     /**
-     * option to keep page errors active on GET request
+     * Option to keep page errors
+     * active on GET request
      */
     errorVisibility?: symbol | Function | undefined;
 };
@@ -226,7 +243,7 @@ export type ConfigureResult = {
     /**
      * Nunjucks environment
      */
-    nunjucksEnv: import('nunjucks').Environment;
+    nunjucksEnv: import("nunjucks").Environment;
     /**
      * Router handling all static assets
      */
@@ -240,71 +257,71 @@ export type ConfigureResult = {
      */
     journeyRouter: MutableRouter;
     /**
-     * Middleware mounted before everything
+     * Middleware
+     * mounted before everything
      */
-    preMiddleware: import('express').RequestHandler[];
+    preMiddleware: import("express").RequestHandler[];
     /**
-     * Middleware mounted after everything
+     * Middleware
+     * mounted after everything
      */
-    postMiddleware: import('express').RequestHandler[];
+    postMiddleware: import("express").RequestHandler[];
     /**
-     * CSRF get/set form middleware
+     * CSRF get/set
+     * form middleware
      */
-    csrfMiddleware: import('express').RequestHandler[];
+    csrfMiddleware: import("express").RequestHandler[];
     /**
-     * Session middleware
+     * Session
+     * middleware
      */
-    sessionMiddleware: import('express').RequestHandler;
+    sessionMiddleware: import("express").RequestHandler;
     /**
-     * Cookie-parsing middleware
+     *   Cookie-parsing middleware
      */
-    cookieParserMiddleware: import('express').RequestHandler[];
+    cookieParserMiddleware: import("express").RequestHandler[];
     /**
-     * I18n preparation middleware
+     * I18n
+     * preparation middleware
      */
-    i18nMiddleware: import('express').RequestHandler[];
+    i18nMiddleware: import("express").RequestHandler[];
     /**
-     * Body parsing middleware
+     * Body
+     * parsing middleware
      */
-    bodyParserMiddleware: import('express').RequestHandler;
+    bodyParserMiddleware: import("express").RequestHandler;
     /**
-     * Function used to mount all CASA artifacts onto an ExpressJS app
+     * Function used to mount all CASA artifacts onto an
+     * ExpressJS app
      */
     mount: Mounter;
     /**
-     * Ingested config supplied to `configure()`
+     * Ingested config supplied to
+     * `configure()`
      */
     config: ConfigurationOptions;
 };
 /**
- * Configuration for generating a ValidationError.
- * i.e. `new ValidationError(configObject)`
- * <br/><br/>
+ * Configuration for generating a ValidationError. i.e. `new
+ * ValidationError(configObject)` <br/><br/>
  *
- * The `fieldKeySuffix` is used to differentiate errors attached to
- * the same field name. For example, given these fields inputs ...
+ * The `fieldKeySuffix` is used to differentiate errors attached to the same
+ * field name. For example, given these fields inputs ...<pre> <input
+ * name="dateOfBirth[dd]" /> <input name="dateOfBirth[mm]" /> <input
+ * name="dateOfBirth[yyyy]" /> </pre>
  *
- * <pre>
- * &lt;input name="dateOfBirth[dd]" /&gt;
- * &lt;input name="dateOfBirth[mm]" /&gt;
- * &lt;input name="dateOfBirth[yyyy]" /&gt;
- * </pre>
+ * If we wanted to generate an error specifically for the `dd` element, then
+ * we'd include `{ fieldKeySuffix: '[dd]' }` in this config. <br/><br/>
  *
- * If we wanted to generate an error specifically for the `dd`
- * element, then we'd include `{ fieldKeySuffix: '[dd]' }` in this
- * config.
- * <br/><br/>
+ * We can also use `focusSuffix` to control which properties of an object field
+ * should be highlighted with a red border when in error. Looking again at the
+ * `dateOfBirth` example above, if we did not specify any `focusSuffix`, then
+ * all three inputs would be highlighted. However, if we use `{ focusSuffix:
+ * ['[dd]', '[yyyy]'] }` then only the `[dd]` and `[yyyy]` inputs would be
+ * highlighted. <br/><br/>
  *
- * We can also use `focusSuffix` to control which properties of an
- * object field should be highlighted with a red border when in error. Looking
- * again at the `dateOfBirth` example above, if we did not specify
- * any `focusSuffix`, then all three inputs would be highlighted.
- * However, if we use `{ focusSuffix: ['[dd]', '[yyyy]'] }` then only
- * the `[dd]` and `[yyyy]` inputs would be highlighted.
- * <br/><br/>
- *
- * The `fieldHref` and `field` properties are strictly for
- * internal use only and public access may be removed at any point.
+ * The `fieldHref` and `field` properties are strictly for internal use only and
+ * public access may be removed at any point.
  */
 export type ErrorMessageConfigObject = {
     /**
@@ -312,15 +329,18 @@ export type ErrorMessageConfigObject = {
      */
     summary: string;
     /**
-     * Inline message (@deprecated now uses summary everywhere)
+     * Inline message (@deprecated now uses summary
+     * everywhere)
      */
     inline?: string | undefined;
     /**
-     * String(s) to append to URL hash for focusing inputs
+     * String(s) to append to URL hash
+     * for focusing inputs
      */
     focusSuffix?: string | string[] | undefined;
     /**
-     * Object fields may use this to show errors per sub-property
+     * Object fields may use this to show errors
+     * per sub-property
      */
     fieldKeySuffix?: string | undefined;
     /**
@@ -332,7 +352,8 @@ export type ErrorMessageConfigObject = {
      */
     validator?: string | undefined;
     /**
-     * (internal) URL hash to link to field in UI, i.e `#f-..`
+     * (internal) URL hash to link to field in UI,
+     * i.e `#f-..`
      */
     fieldHref?: string | undefined;
     /**
@@ -380,7 +401,8 @@ export type Validator = {
      */
     validate: ValidateFunction;
     /**
-     * Sanitise a given value prior to validation
+     * Sanitise a given value prior to
+     * validation
      */
     sanitise: FieldProcessorFunction;
     /**
@@ -405,10 +427,6 @@ export type ValidatorConditionFunctionParams = {
      * Waypoint
      */
     waypoint: string;
-    /**
-     * [DEPRECATED] Waypoint (for backwards compatibility with v7)
-     */
-    waypointId: string;
     /**
      * Journey Context
      */
@@ -439,7 +457,8 @@ export type PlanRoute = {
 export type PlanRouteCondition = (route: PlanRoute, context: JourneyContext) => boolean;
 export type PlanTraverseOptions = {
     /**
-     * Waypoint from which to start (defaults to first in list)
+     * Waypoint from which to start (defaults to
+     * first in list)
      */
     startWaypoint?: string | undefined;
     /**
@@ -451,11 +470,13 @@ export type PlanTraverseOptions = {
      */
     history: Map<any, any>;
     /**
-     * If true, traversal will be stopped (useful for performance)
+     * If true, traversal will be stopped
+     * (useful for performance)
      */
     stopCondition?: Function | undefined;
     /**
-     * Multiple target routes found, this decides which to use
+     * Multiple target routes found, this
+     * decides which to use
      */
     arbiter?: string | PlanArbiter | undefined;
 };
@@ -469,7 +490,8 @@ export type PlanArbiterParams = {
      */
     journeyContext: JourneyContext;
     /**
-     * Original traverse options passed to `traverse()`
+     * Original traverse options
+     * passed to `traverse()`
      */
     traverseOptions: PlanTraverseOptions;
 };
@@ -500,7 +522,7 @@ export type ContextIdGeneratorParams = {
      * Arguments
      */
     args: {
-        req: import('express').Request;
+        req: import("express").Request;
         reservedIds: [string];
     };
 };
@@ -509,22 +531,23 @@ export type ContextIdGeneratorParams = {
  * any other context IDs in the given session.
  *
  * The resulting ID must match these criteria:
+ *
  * - A string
  * - Between 1 and 64 characters
  * - Contain only the characters a-z, 0-9, -
  */
 export type ContextIdGenerator = (params: ContextIdGeneratorParams) => string;
-import configure from './lib/configure.js';
-import validators from './lib/validators/index.js';
-import field from './lib/field.js';
-import Plan from './lib/Plan.js';
-import JourneyContext from './lib/JourneyContext.js';
-import ValidatorFactory from './lib/ValidatorFactory.js';
-import ValidationError from './lib/ValidationError.js';
-import MutableRouter from './lib/MutableRouter.js';
-import waypointUrl from './lib/waypoint-url.js';
-import endSession from './lib/end-session.js';
-import * as nunjucksFilters from './lib/nunjucks-filters.js';
-import * as constants from './lib/constants.js';
-import * as contextIdGenerators from './lib/context-id-generators.js';
+import configure from "./lib/configure.js";
+import validators from "./lib/validators/index.js";
+import field from "./lib/field.js";
+import Plan from "./lib/Plan.js";
+import JourneyContext from "./lib/JourneyContext.js";
+import ValidatorFactory from "./lib/ValidatorFactory.js";
+import ValidationError from "./lib/ValidationError.js";
+import MutableRouter from "./lib/MutableRouter.js";
+import waypointUrl from "./lib/waypoint-url.js";
+import endSession from "./lib/end-session.js";
+import * as nunjucksFilters from "./lib/nunjucks-filters.js";
+import * as constants from "./lib/constants.js";
+import * as contextIdGenerators from "./lib/context-id-generators.js";
 export { configure, validators, field, Plan, JourneyContext, ValidatorFactory, ValidationError, MutableRouter, waypointUrl, endSession, nunjucksFilters, constants, contextIdGenerators };