@dwp/govuk-casa/dist/lib/field.d.ts

A framework for building GOVUK Collect-And-Submit-Applications

/**
 * Factory for creating PageField instances.
 *
 * @memberof module:@dwp/govuk-casa
 * @param {string} name Field name
 * @param {object} [opts] Options
 * @param {boolean} [opts.optional] Whether this field is optional. Default is
 *   `false`
 * @param {boolean} [opts.persist] Whether this field will persist in
 *   `req.body`. Default is `true`
 * @returns {PageField} A PageField
 */
export default function field(name: string, opts?: {
    optional?: boolean | undefined;
    persist?: boolean | undefined;
}): PageField;
/**
 * This class is not exposed via the public API. Instances should instead be
 * instantiated through the `field()` factory function.
 *
 * @class
 */
export class PageField {
    /**
     * Create a field.
     *
     * @param {string} name Field name
     * @param {object} [opts] Options
     * @param {boolean} [opts.optional] Whether this field is optional. Default is
     *   `false`
     * @param {boolean} [opts.persist] Whether this field will persist in
     *   `req.body`. Default is `true`
     */
    constructor(name: string, { optional, persist }?: {
        optional?: boolean | undefined;
        persist?: boolean | undefined;
    });
    /**
     * Clone this field.
     *
     * @returns {PageField} Cloned field
     */
    clone(): PageField;
    /**
     * Extract this field's value from the given object.
     *
     * For complex fields, we may need to drill into an object to extract the
     * value.
     *
     * @param {object} obj Object from which to extract the value
     * @returns {any} Value extracted from object
     */
    getValue(obj?: object): any;
    /**
     * Store this field's value in the given object, using its name as the key.
     *
     * For complex fields, the field object will be created if it does not yet
     * exist, before then storing the property within that object.
     *
     * @param {object} obj Object from which to extract the value
     * @param {any} value Value to be stored
     * @returns {any} Value extracted from object
     */
    putValue(obj?: object, value?: any): any;
    get name(): string;
    get meta(): object;
    /**
     * Rename this field.
     *
     * @param {string} name New name to be applied
     * @returns {PageField} Chain
     * @throws {SyntaxError} When the name is invalid in some way
     */
    rename(name: string): PageField;
    /**
     * Get validators
     *
     * @returns {Validator[]} A list containing all validators.
     */
    getValidators(): Validator[];
    /**
     * Add value validators Some validators will include a `sanitise()` method
     * which will be run at the same time as other "processors".
     *
     * @param {Validator[]} items Validation functions
     * @returns {PageField} Chain
     */
    validators(items?: Validator[]): PageField;
    /**
     * Get processors
     *
     * @returns {FieldProcessorFunction[]} A list containing all processors.
     */
    getProcessors(): FieldProcessorFunction[];
    /**
     * Add value pre-processors This is most often used to sanitise values to a
     * particular data type.
     *
     * @param {FieldProcessorFunction[]} items Processor functions
     * @returns {PageField} Chain
     */
    processors(items?: FieldProcessorFunction[]): PageField;
    /**
     * Get conditions
     *
     * @returns {ValidatorConditionFunction[]} A list containing all conditions.
     */
    getConditions(): ValidatorConditionFunction[];
    /**
     * Add conditions All conditions must be met in order for this field to be
     * considered "actionable".
     *
     * @param {ValidatorConditionFunction[]} items Condition functions
     * @returns {PageField} Chain
     */
    conditions(items?: ValidatorConditionFunction[]): PageField;
    /**
     * Run all validators and return array of errors, if applicable.
     *
     * @param {ValidateContext} context Contextual validation information
     * @returns {ValidationError[]} Errors, or an empty array if all valid
     * @throws {TypeError} If validator does not return an array
     */
    runValidators(context?: ValidateContext): ValidationError[];
    /**
     * Apply all the processors to the given value.
     *
     * @param {any} value Value to process
     * @returns {any} Processed value
     */
    applyProcessors(value: any): any;
    /**
     * All conditions must return true to be considered a successful test.
     *
     * @param {ValidateContext} context Contextual validation information
     * @returns {boolean} True if all conditions pass
     */
    testConditions({ fieldValue, waypoint, journeyContext }: ValidateContext): boolean;
    /**
     * Add a single validator.
     *
     * @param {Validator} validator Validation function
     * @returns {PageField} Chain
     */
    validator(validator: Validator): PageField;
    /**
     * Add a single pre-processors
     *
     * @param {FieldProcessorFunction} processor Processor function
     * @returns {PageField} Chain
     */
    processor(processor: FieldProcessorFunction): PageField;
    /**
     * Add a single condition.
     *
     * @param {ValidatorConditionFunction} condition Condition function
     * @returns {PageField} Chain
     */
    condition(condition: ValidatorConditionFunction): PageField;
    /**
     * Alias for `conditions()`.
     *
     * @param {...ValidatorConditionFunction} args Condition functions
     * @returns {PageField} Chain
     */
    if(...args: ValidatorConditionFunction[]): PageField;
    #private;
}
export type JourneyContext = import("./index").JourneyContext;
export type Validator = import("../casa").Validator;
export type ValidateContext = import("../casa").ValidateContext;
export type ValidatorConditionFunction = import("../casa").ValidatorConditionFunction;
export type FieldProcessorFunction = import("../casa").FieldProcessorFunction;
export type ValidationError = import("./index").ValidationError;