@vtaits/form-schema
TypeScript icon, indicating that this package has built-in type declarations

2.3.0-alpha.0 • Public • Published

NPM dependencies status

@vtaits/form-schema

A set of utilities for easy work with form values and errors:

  • Serialize form values before submit by schema
  • Parse initial values of form by schema
  • Map submission errors by schema

Installation

yarn add @vtaits/form-schema

or

npm install @vtaits/form-schema --save

Concept

There are next entities:

  • names - array of field names, required for serialization and parsing of initial values;

  • getFieldSchema - function that returns full schema of field by name (it can contain placeholder for input, options for select, label, help text etc.);

  • getFieldType - function that returns type declaration of field by full schema.

Type declaration

Type declaration is an object with next params:

  • serializer - function for serialize form values before submit. E.g. local value of select can be an object { value, label }, but only value should be submitted. Parameters:

    • values - all values of form;
    • name - name of current field;
    • fieldSchema - full schema of current field;
    • getFieldSchema - see above;
    • getFieldType - see above;
    • parents - stack of parent fields above current field with runtime values.

    Should return OBJECT of values. By default returns

    {
      [name]: values[name],
    }
    
  • parser - function for parse initial values of form before initialize. Parameters:

    • values - all values of form;
    • name - name of current field;
    • fieldSchema - full schema of current field;
    • getFieldSchema - see above;
    • getFieldType - see above;
    • parents - stack of parent fields above current field with raw values.

    Should return OBJECT of values or Promise with object of values (can be async). By default returns

    {
      [name]: values[name],
    }
    
  • validatorBeforeSubmit - function for collect validation errors of form before submit. Receives next arguments:

    • setError - a function for setting errors;
    • values - all values of the form;
    • name - name of current field;
    • fieldSchema - full schema of current field;
    • getFieldSchema - see above;
    • getFieldType - see above;
    • parents - stack of parent fields above current field with runtime values.

    Example:

    {
      validateBeforeSubmit: ({
        setError,
        values,
        name,
        fieldSchema: { required },
        parents,
      }) => {
        if (required && !values[name]) {
          setError(name, parents, 'This field is required');
        }
      },
    }
  • errorsMapper - function for map errors of field from backend format to format of field. Receives next arguments:

    • setError - a function for setting errors;
    • errors - errors object;
    • name - name of current field;
    • fieldSchema - full schema of current field;
    • getFieldSchema - see above;
    • getFieldType - see above;
    • values - serialized values of form using serializer functions of field;
    • rawValues - all values of form without processing;
    • parents - stack of parent fields above current field with runtime values.

    Should return OBJECT of values. By default returns

    {
      [name]: errors[name],
    }
    
  • createGetFieldSchema - function for create getFieldSchema for nested fields. Can be helpful for arrays of repeating fields etc. Parameters:

    • fieldSchema - schema of current field;
    • getFieldSchema - default getFieldSchema;
    • getFieldType - see above;
    • values - current values (values of form during render and serialization or raw values during parsing);
    • phase - one of next values: 'parse', 'serialize', 'render';
    • parents - stack of parent fields above current field, raw values for phase 'parse' and runtime values otherwise.

Usage

Serialization

import { serialize } from '@vtaits/form-schema';

// ...

serialize({
	values,
	names,
	getFieldSchema,
	getFieldType,
	parents,
});

Parsing

import { parse } from '@vtaits/form-schema';

// ...

parse({
	values,
	names,
	getFieldSchema,
	getFieldType,
	parents,
});

Validation before submit

import { validateBeforeSubmit } from '@vtaits/form-schema';

// ...

validateBeforeSubmit({
	setError,
	values,
	names,
	getFieldSchema,
	getFieldType,
	parents,
});

Mapping of errors of fields

import { setFieldErrors } from '@vtaits/form-schema';

// ...

setFieldErrors({
	setError,
	errors,
	names,
	getFieldSchema,
	getFieldType,
	values,
	rawValues,
	parents,
});
  • values - serialied values of form (result of serialize);
  • rawValues - raw values of form (before serialize).

Package Sidebar

Install

npm i @vtaits/form-schema

Weekly Downloads

98

Version

2.3.0-alpha.0

License

MIT

Unpacked Size

203 kB

Total Files

66

Last publish

Collaborators

  • vtaits