@dwp/govuk-casa 7.0.6 → 8.0.0-beta1

package/dist/lib/JourneyContext.d.ts

@@ -0,0 +1,297 @@
+/**
+ * @typedef {import('./configuration-ingestor').Page} Page
+ */
+/**
+ * @callback ContextEventHandler
+ * @param {JourneyContext} journeyContext Context including changes
+ * @param {JourneyContext} previousContext Context prior to changes
+ * @returns {void}
+ */
+/**
+ * @typedef {object} ContextEvent
+ * @property {string} waypoint Waypoint to watch for changes
+ * @property {string} [field] Field to watch for changes
+ * @property {ContextEventHandler} handler Handler to invoke when change happens
+ */
+export default class JourneyContext {
+    static DEFAULT_CONTEXT_ID: string;
+    /**
+     * Create a new JourneyContext using the plain object.
+     *
+     * @param {object} obj Object.
+     * @param {object} obj.data Data
+     * @param {object} obj.validation Validation state
+     * @param {object} obj.nav Navigation meta
+     * @param {object} obj.identity Identity meta
+     * @returns {JourneyContext} Instance.
+     */
+    static fromObject({ data, validation, nav, identity, }?: {
+        data: object;
+        validation: object;
+        nav: object;
+        identity: object;
+    }): JourneyContext;
+    /**
+     * Construct a new JourneyContext instance frmo another instance.
+     *
+     * @param {JourneyContext} context Context to copy from
+     * @returns {JourneyContext} Constructed JourneyContext instance
+     * @throws {TypeError} When context is not a valid type
+     */
+    static fromContext(context: JourneyContext): JourneyContext;
+    /**
+     * Initialise session with an empty entry for the "default" context.
+     *
+     * @param {object} session Request session
+     * @returns {void}
+     */
+    static initContextStore(session: object): void;
+    /**
+     * Validate the format of a context ID, i.e. "default" or a uuid
+     * eg 00000000-0000-0000-0000-000000000000
+     * eg 123e4567-e89b-12d3-a456-426614174000
+     *
+     * @param {string} id Context ID
+     * @returns {string} Original ID if it's valid
+     * @throws {TypeError} When id is not a valid type
+     * @throws {SyntaxError} When id is not a valid uuid format
+     */
+    static validateContextId(id: string): string;
+    /**
+     * Lookup context from session using the ID.
+     *
+     * @param {object} session Request session
+     * @param {string} id Context ID
+     * @returns {JourneyContext} The discovered JourneyContext instance
+     */
+    static getContextById(session: object, id: string): JourneyContext;
+    /**
+     * Lookup context from session using the name.
+     *
+     * @param {object} session Request session
+     * @param {string} name Context name
+     * @returns {JourneyContext} The discovered JourneyContext instance
+     */
+    static getContextByName(session: object, name: string): JourneyContext;
+    /**
+     * Lookup contexts from session using the tag.
+     *
+     * @param {object} session Request session
+     * @param {string} tag Context tag
+     * @returns {Array<JourneyContext>} The discovered JourneyContext instance
+     */
+    static getContextsByTag(session: object, tag: string): Array<JourneyContext>;
+    /**
+     * Return all contexts currently stored in the session.
+     *
+     * @param {object} session Request session
+     * @returns {Array} Array of contexts
+     */
+    static getContexts(session: object): any[];
+    /**
+     * Put context back into the session store.
+     *
+     * @param {object} session Request session
+     * @param {JourneyContext} context Context
+     * @returns {void}
+     * @throws {TypeError} When isession is not a valid type, or context has no ID
+     */
+    static putContext(session: object, context: JourneyContext): void;
+    /**
+     * Remove a context from the session store.
+     *
+     * @param {object} session Request session
+     * @param {JourneyContext} context Context
+     * @returns {void}
+     */
+    static removeContext(session: object, context: JourneyContext): void;
+    static removeContextById(session: any, id: any): void;
+    static removeContextByName(session: any, name: any): void;
+    static removeContextsByTag(session: any, tag: any): void;
+    static removeContexts(session: any): void;
+    static extractContextFromRequest(req: any): JourneyContext;
+    /**
+     * Constructor.
+     *
+     * `data` is the "single source of truth" for all data gathered during the
+     * user's journey. This is referred to as the "canonical data model".
+     *  Page-specific "views" of this data are generated at runtime in order to
+     * populate/validate specific form fields.
+     *
+     * `validation` holds the results of form field validation carried out when
+     * page forms are POSTed. These results are mapped directly to per-page,
+     * per-field.
+     *
+     * `nav` holds information about the current navigation state. Currently this
+     * comprises of the language in which the user is navigating the service.
+     *
+     * `identity` holds information that helps uniquely identify this context
+     * among a group of contexts stored in the session.
+     *
+     * @param {object} data Entire journey data.
+     * @param {object} validation Page errors (indexed by waypoint id).
+     * @param {object} nav Navigation context.
+     * @param {object} identity Some metadata for identifying this context among others.
+     */
+    constructor(data?: object, validation?: object, nav?: object, identity?: object);
+    /**
+     * Clone into an object that can be stringified.
+     *
+     * @returns {object} Plain object.
+     */
+    toObject(): object;
+    set data(arg: object);
+    get data(): object;
+    get validation(): object;
+    get nav(): object;
+    get identity(): object;
+    /**
+     * Get data context for a specific a specific page.
+     *
+     * @param  {string | Page} page Page waypoint ID, or Page object.
+     * @returns {object} Page data.
+     * @throws {TypeError} When page is invalid.
+     */
+    getDataForPage(page: string | Page): object;
+    getData(): object;
+    /**
+     * Overwrite the data context with a new object.
+     *
+     * @param {object} data Data that will overwrite all existing data.
+     * @returns {JourneyContext} Chain.
+     */
+    setData(data: object): JourneyContext;
+    /**
+     * Write field form data from a page HTML form, into the `data` model.
+     *
+     * By default this will store the data as-is, keyed against the page's
+     * waypoint ID. However, when passing a `Page` instance, its
+     * `fieldWriter()` method will be called to transform the provided formData
+     * before storing in `data`
+     *
+     * @param {string | Page} page Page waypoint ID, or Page object
+     * @param {object} webFormData Data to overwrite with
+     * @returns {JourneyContext} Chain
+     * @throws {TypeError} When page is invalid.
+     */
+    setDataForPage(page: string | Page, webFormData: object): JourneyContext;
+    /**
+     * Return validation errors for all pages.
+     *
+     * @returns {object} All page validation errors.
+     */
+    getValidationErrors(): object;
+    /**
+     * Removes any validation state for the given page. Clearing validation state
+     * completely will, by default, prevent onward traversal from this page. See
+     * the traversal logic in Plan class.
+     *
+     * @param {string} pageId Page ID.
+     * @returns {JourneyContext} Chain.
+     */
+    removeValidationStateForPage(pageId: string): JourneyContext;
+    /**
+     * Clear any validation errors for the given page. This effectively declares
+     * that this page has been successfully validated, and so can be traversed. If
+     * you want to remove any knowledge of validation success/failure, use
+     * `removeValidationStateForPage()` instead.
+     *
+     * @param {string} pageId Page ID.
+     * @returns {JourneyContext} Chain.
+     */
+    clearValidationErrorsForPage(pageId: string): JourneyContext;
+    /**
+     * Set validation errors for a page.
+     *
+     * @param {string} pageId Page ID.
+     * @param {ValidationError[]} errors Errors
+     * @returns {JourneyContext} Chain.
+     * @throws {SyntaxError} When errors are invalid.
+     */
+    setValidationErrorsForPage(pageId: string, errors?: ValidationError[]): JourneyContext;
+    /**
+     * Return the validation errors associated with the page's currently held data
+     * context (if any).
+     *
+     * @param {string} pageId Page ID.
+     * @returns {ValidationError[]} An array of errors
+     */
+    getValidationErrorsForPage(pageId: string): ValidationError[];
+    getValidationErrorsForPageByField(pageId: any): any;
+    /**
+     * Determine whether the specified page has any errors in its validation
+     * context.
+     *
+     * @param {string} pageId Page ID.
+     * @returns {boolean} Result.
+     */
+    hasValidationErrorsForPage(pageId: string): boolean;
+    /**
+     * Set language of the context.
+     *
+     * @param {string} language Language to set (ISO 639-1 2-letter code).
+     * @returns {JourneyContext} Chain.
+     */
+    setNavigationLanguage(language?: string): JourneyContext;
+    /**
+     * Convenience function to test if page is valid.
+     *
+     * @param {string} pageId Page ID.
+     * @returns {boolean} True if the page is valid.
+     */
+    isPageValid(pageId: string): boolean;
+    /**
+     * Remove information about these waypoints.
+     *
+     * @param {string[]} waypoints Waypoints to be removed
+     */
+    purge(waypoints?: string[]): void;
+    /**
+     * Remove validation state from these waypoints. This is useful to quickly
+     * force the user to revisit some waypoints.
+     *
+     * @param {string[]} waypoints Waypoints to be invalidated
+     * @returns {void}
+     */
+    invalidate(waypoints?: string[]): void;
+    /**
+     * Event listeners are transient. They are not stored in session, and generally
+     * only apply for the current request.
+     *
+     * They also only act on a fixed snapshot of this context's state, which is
+     * taken at the point of attaching the listeners (in the "data" middleware).
+     * This is important because JourneyContext.putContext()` could be called many
+     * times during a request, so the context will be constantly changing.
+     *
+     * @param {ContextEvent[]} events Event listeners
+     * @returns {JourneyContext} Chain
+     */
+    addEventListeners(events: ContextEvent[]): JourneyContext;
+    applyEventListeners({ event }: {
+        event: any;
+    }): JourneyContext;
+    /**
+     * Convenience method to determine if this is the default context.
+     *
+     * @returns {boolean} True if this is the "default" journey context
+     */
+    isDefault(): boolean;
+    #private;
+}
+export type Page = import('./configuration-ingestor').Page;
+export type ContextEventHandler = (journeyContext: JourneyContext, previousContext: JourneyContext) => void;
+export type ContextEvent = {
+    /**
+     * Waypoint to watch for changes
+     */
+    waypoint: string;
+    /**
+     * Field to watch for changes
+     */
+    field?: string | undefined;
+    /**
+     * Handler to invoke when change happens
+     */
+    handler: ContextEventHandler;
+};
+import ValidationError from "./ValidationError.js";