adaptform 2.0.5 → 2.1.0

package/README.md

@@ -1,420 +1,388 @@
 # AdaptForm
 
+[English](README.md) · [Русский](README.ru.md)
+
 [![npm version](https://img.shields.io/npm/v/adaptform.svg)](https://www.npmjs.com/package/adaptform)
 [![npm downloads](https://img.shields.io/npm/dm/adaptform.svg)](https://www.npmjs.com/package/adaptform)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/adaptform)](https://bundlephobia.com/package/adaptform)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-AdaptForm is a TypeScript-first form modeling framework inspired by Django Forms and Pydantic.
-
-Instead of describing validation schemas, you describe forms as classes with typed fields. Each field is responsible for
-its own state lifecycle, validation, transformation pipeline, and serialization logic.
+**[Open the interactive demo](https://arhimen.github.io/AdaptForm/)** · **[Read the 2.1.0 changelog](https://github.com/ArhiMEN/AdaptForm/blob/master/CHANGELOG.md)** · **[Browse the demo source](https://github.com/ArhiMEN/AdaptForm/tree/master/demo)**
 
-## AdaptForm provides:
+Maintainers: [automatic npm publication setup](docs/NPM_PUBLISH.md).
 
-- Typed form models
-- Field-level validation
-- Cross-field validation
-- Input transformation plugins
-- Nested forms and arrays
-- Automatic TypeScript inference
-- Framework-agnostic integration
+AdaptForm is a TypeScript-first form modeling library inspired by Django Forms and Pydantic. Define forms as classes with typed fields. Each field owns its value, casting, validation, transformation plugins, errors, and state.
 
 ## Features
 
-- Form-as-a-domain-model architecture
-- Field-level state + validation ownership
-- Cross-field validation support
-- Plugin-based transformation pipeline
-- Strong TypeScript inference
-- Nested forms & collections
-- Built-in serialization (JSON / FormData)
-- Optional date engine (Luxon)
-- Framework-agnostic design
-- Zero-core-dependencies
-
-## Philosophy
-
-Most form libraries treat forms as validation schemas:
-
-```TypeScript
-const schema = z.object({
-  login: z.string(),
-  password: z.string(),
-})
-````
-
-AdaptForm treats forms as stateful domain models:
-
-```TypeScript
-class LoginForm extends Form {
-  login = new Field(StringType)
-  password = new Field(StringType)
-}
-```
-
-field is not just a validator — it is a state container that owns:
-
-- value
-- validation
-- errors
-- transformation
-- plugins
-- type casting
-
-The form itself becomes a single source of truth.
-
-Simple Vue:
-
-## Without AdaptForm
-
-A typical Vue form consists of multiple disconnected parts:
-
-- reactive state
-- validation schema
-- error store
-- input masks
-- submission mapping
-
-## With AdaptForm
-
-Everything is unified into a single form model:
-
-```TypeScript
-class RegistrationForm extends Form {
-  phone = new Field(StringType)
-}
-````
+- Class-based form models with inferred TypeScript value types.
+- Field-level and cross-field validation.
+- Conditional required rules and custom synchronous validators.
+- String, number, decimal, boolean, and JavaScript Date field types.
+- Dynamic arrays of fields and arrays of nested forms.
+- Input transformation plugins, including `MaskPlugin`.
+- Server-error mapping with `ErrorsSchema`.
+- JSON and `FormData` serialization.
+- Optional Luxon integration through the `adaptform/luxon` entry point.
+- Framework-agnostic core with no required runtime dependencies.
 
 ## Installation
 
+Install the published npm package:
+
 ```bash
 npm install adaptform
 ```
 
-## Optional: Luxon integration
+Luxon integration is optional:
 
-```Bash
+```bash
 npm install luxon
 ```
 
-## Quick Start
+The [interactive demo](https://arhimen.github.io/AdaptForm/) runs from repository source, with automatic deployment from `v2.1.0` and `master`. Version `2.1.0` is prepared in the repository; npm continues to serve the last published version until the maintainer publishes the release.
 
-```TypeScript
-import {Form, Field, StringType, NumberType} from 'adaptform';
+The demo supports English and Russian with a persistent language selector: [English](https://arhimen.github.io/AdaptForm/?lang=en) · [Русский](https://arhimen.github.io/AdaptForm/?lang=ru). Switching languages preserves form data and validation state.
 
-class LoginForm extends Form {
-  login = new Field(StringType, null, {maxLength: 50});
-  password = new Field(StringType, null, {minLength: 8});
-  remember = new Field(BooleanType, false);
-}
+## Quick start
+
+```typescript
+import { BooleanType, Field, Form, StringType } from 'adaptform'
+
+class RegistrationForm extends Form {
+  name = new Field(StringType, null, {
+    isRequired: true,
+    minLength: 2,
+    maxLength: 50,
+  })
 
-const form = new LoginForm();
+  email = new Field(StringType, null, {
+    isRequired: true,
+    pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+  })
 
+  acceptedTerms = new Field(BooleanType, false, {
+    mustBeTrue: true,
+  })
+}
+
+const form = new RegistrationForm()
 form.fields = {
-  login: 'john_doe',
-  password: 'securepass123'
-};
+  name: 'Alex Morgan',
+  email: 'alex@example.com',
+  acceptedTerms: true,
+}
 
-console.log(form.isValid); // true
-console.log(form.fieldsValue); // { login: 'john_doe', password: 'securepass123', remember: false }
+if (form.isValid) {
+  console.log(form.fieldsValue)
+  console.log(form.toJSON())
+} else {
+  console.log(form.allErrors)
+}
 ```
 
-## Usage Examples
+`form.fields` assigns the supplied values and validates the completed form. Values for fields omitted from the assignment are left unchanged.
 
-## Field Types
+## Field types and options
 
-```TypeScript
-import {Field, StringType, NumberType, BooleanType, DecimalType, DateType} from 'adaptform';
+All field types are constructed using `new Field(TypeConstructor, defaultValue?, options?)`.
 
-// String with validation
-const name = new Field(StringType, null, {
-  minLength: 2,
-  maxLength: 50,
-  pattern: /^[a-zA-Z]+$/
-});
+### StringType
 
-// Number with range
-const age = new Field(NumberType, null, {
-  gt: 0,    // greater than
-  lt: 120   // less than
-});
-
-// Boolean with requirement
-const agreed = new Field(BooleanType, false, {
-  mustBeTrue: true,
+```typescript
+const username = new Field(StringType, null, {
+  isRequired: true,
+  minLength: 3,
+  maxLength: 32,
+  pattern: /^[a-z0-9_]+$/i,
   messages: {
-    mustBeTrue: 'You must agree to the terms'
-  }
-});
-```
-
-## Custom Validation
-
-```TypeScript
-const email = new Field(StringType, null, {
-  validate: (value) => {
-    return value.includes('@') || 'Invalid email format';
-  }
-});
-
-// Async validation with form context
-const passwordConfirmation = new Field(StringType, null, {
-  validate: (value, form) => {
-    return value === form?.password?.valueClear || 'Passwords do not match';
-  }
-});
+    isRequired: 'Enter a username.',
+    minLength: 'Use at least 3 characters.',
+    pattern: 'Use only letters, numbers, and underscores.',
+  },
+})
 ```
 
-## Conditional Required Fields
+Supported constraints: `isRequired`, `minLength`, `maxLength`, and `pattern`.
 
-```TypeScript
-class SignUpForm extends Form {
-  country = new Field(StringType, null);
+### NumberType
 
-  state = new Field(StringType, null, {
-    isRequired: (form) => form?.country?.valueClear === 'USA',
-    messages: {
-      isRequired: 'State is required for USA residents'
-    }
-  });
-}
+```typescript
+const age = new Field(NumberType, null, {
+  isRequired: true,
+  ge: 18,
+  le: 120,
+})
 ```
 
-## Input Masks
+Supported constraints: `gt`, `ge`, `lt`, and `le`. Values must be finite integers; blank strings and non-finite numbers are rejected.
 
-```TypeScript
-import {Field, StringType, MaskPlugin} from 'adaptform';
+### DecimalType
 
-const phone = new Field(StringType, null, {
-  plugins: [
-    new MaskPlugin({
-      maskFormat: '+7 (___) ___-__-__',
-      maskPlaceholder: '_',
-      digitPattern: /\d/
-    })
-  ]
-});
-
-phone.rawValue = '9991234567';
-console.log(phone.valueClear); // '+7 (999) 123-45-67'
+```typescript
+const price = new Field(DecimalType, null, {
+  decimalPlaces: 2,
+  maxDigits: 8,
+  ge: 0,
+})
 ```
 
-## Nested Forms
-
-```TypeScript
-import {ArrayField, Field, NumberType} from 'adaptform';
+Supports `gt`, `ge`, `lt`, `le`, `decimalPlaces`, and `maxDigits`. Numeric inputs with excess precision are rejected rather than silently rounded. String inputs may use a comma or a period as the decimal separator.
 
-const gameIds = new ArrayField(
-  (value?: number) => new Field(NumberType, value, {gt: 0}),
-  {minItems: 1}
-);
+### BooleanType
 
-gameIds.itemsValue = [1, 2, 3];
-gameIds.add(4);
-console.log(gameIds.itemsValue); // [1, 2, 3, 4]
+```typescript
+const accepted = new Field(BooleanType, false, {
+  mustBeTrue: true,
+})
 ```
 
-## Luxon Date Integration
-
-```Bash
-npm install luxon
-```
+Supports `mustBeTrue` and `mustBeFalse`.
 
-```TypeScript
-import {DateLuxonType} from 'adaptform/luxon';
-import {DateTime} from 'luxon';
+### DateType
 
-const birthdate = new Field(DateLuxonType, null, {
+```typescript
+const birthday = new Field(DateType, null, {
   isDatetime: false,
-  minDate: DateTime.fromISO('1900-01-01'),
-  maxDate: DateTime.now(),
-  inputFormat: 'dd.MM.yyyy',
-  messages: {
-    minDate: 'Date must be after 1900',
-    maxDate: 'Date cannot be in the future'
-  }
-});
-
-birthdate.rawValue = '15.06.1990';
-console.log(birthdate.valueClear); // Luxon DateTime object
+  minDate: new Date('1900-01-01T00:00:00.000Z'),
+  maxDate: new Date(),
+})
 ```
 
-## Form Submission
+Supports `minDate`, `maxDate`, and `isDatetime`. When `isDatetime` is false, comparisons use calendar dates; when true, timestamps are compared. Invalid dates are rejected.
 
-```TypeScript
-class ContactForm extends Form {
-  name = new Field(StringType, null, {maxLength: 100});
-  email = new Field(StringType, null, {
-    pattern: /^[^@]+@[^@.]+\.[^@.]+$/
-  });
-  message = new Field(StringType, null, {maxLength: 1000});
-}
+### Custom validation and messages
 
-const form = new ContactForm();
-form.fields = {
-  name: 'John',
-  email: 'john@example.com',
-  message: 'Hello!'
-};
-
-if (form.checkValid()) {
-  // Submit form
-  const formData = form.toFormData();
-  const json = form.toJSON();
-
-  await fetch('/api/contact', {
-    method: 'POST',
-    body: formData
-  });
-} else {
-  console.log(form.allErrors);
-  // {
-  //   name: [],
-  //   email: [],
-  //   message: []
-  // }
+Field options support `isRequired`, `messages`, and a synchronous `validate(value, form)` callback. A custom validator returns `true` for success, `false` for the configured validation message, or a string for a specific error.
+
+```typescript
+class PasswordForm extends Form {
+  password = new Field(StringType, null, { minLength: 8 })
+
+  confirmation = new Field(StringType, null, {
+    isRequired: true,
+    validate: (value, form) =>
+      value === form?.password.valueClear || 'Passwords do not match.',
+  })
 }
 ```
 
-## Global Errors
+Validators are synchronous; returning a Promise is not supported. For asynchronous checks such as server-side uniqueness, call the service separately and apply the response through the form's error API.
 
-```TypeScript
-class LoginForm extends Form {
-  login = new Field(StringType, null);
-  password = new Field(StringType, null);
-}
+## Validation lifecycle and state
 
-const form = new LoginForm();
+- Constructor defaults begin untouched.
+- Empty strings and whitespace-only strings count as empty values.
+- Global and sticky regular-expression flags do not make repeated string validation stateful.
+- `form.checkValid()` validates every field and returns `false` when a field is invalid or global server errors remain.
+- Reading `isValid` does not run validators. Fields without a non-null default start with `isValid === null`; non-null constructor defaults pass through casting and validation but still start untouched. After `reset()`, field validity is unset until validation runs again.
+- Bulk assignment validates after direct field values have been assigned, so conditional-required rules can inspect the complete form state.
+- If you change dependent fields one at a time, call `form.checkValid()` after the changes to recompute cross-field rules.
+- `field.setRawValue(value, false)` and `form.setFields(data, false)` allow advanced callers to defer validation. Call `checkValid()` before relying on the validity state.
+- `reset()` restores defaults, clears errors, and leaves validity unset until the next validation. Collection validity is false after reset until the collection is checked again.
+- Adding, removing, or clearing collection items refreshes collection validation. Invalid removal indices are ignored.
 
-// Add server-side errors
-form.errors = {
-  login: 'Account not found',
-  password: 'Invalid password'
-};
+## Dynamic collections
 
-// Or set global error
-form.setGlobalError('auth', 'Authentication failed');
-```
+### ArrayField
+
+Use `ArrayField` for a dynamic list of similarly typed fields.
 
-## Plugin System
+```typescript
+import { ArrayField, Field, StringType } from 'adaptform'
 
-### Built-in Plugins
+const tags = new ArrayField(
+  (value?: string) => new Field(StringType, value, {
+    isRequired: true,
+    minLength: 2,
+  }),
+  { minItems: 1, maxItems: 5 },
+)
 
-* **MaskPlugin** - Input masking (phone, date, credit card)
+tags.add('typescript')
+tags.add('forms')
+console.log(tags.itemsValue)
+console.log(tags.isValid)
+```
 
-* **FieldPlugin** - Base plugin for custom extensions
+Options include `isRequired`, `minItems`, `maxItems`, `messages`, and a synchronous `validate(values, form)` callback. `itemsValue` returns an array whose entries may be `null`.
 
-### Creating Custom Plugins
+### ArrayFormField
 
-```TypeScript
-import {BasePlugin} from 'adaptform';
-import type {FieldPlugin} from 'adaptform';
+Use `ArrayFormField` for a list of nested form instances.
 
-class UppercasePlugin extends BasePlugin implements FieldPlugin<string> {
-  toRawValue(value: string): string {
-    return value?.toUpperCase() || '';
-  }
+```typescript
+import { ArrayFormField, Field, Form, StringType } from 'adaptform'
 
-  toValueClear(value: string): string {
-    return value?.toLowerCase() || '';
-  }
+class AddressForm extends Form {
+  city = new Field(StringType, null, { isRequired: true })
+  postalCode = new Field(StringType, null, { isRequired: true })
 }
 
-const field = new Field(StringType, null, {
-  plugins: [new UppercasePlugin()]
-});
-```
+const addresses = new ArrayFormField(AddressForm, {
+  minForms: 1,
+  maxForms: 3,
+})
 
-## API Reference
+addresses.add({ city: 'Berlin', postalCode: '10115' })
+console.log(addresses.formsFieldsValue)
+```
 
-### Form
+Options include `isRequired`, `minForms`, `maxForms`, `messages`, and a synchronous `validate(forms, form)` callback.
 
-* `checkValid(form?)` - Validate all fields
+## Input masks
 
-* `fieldsValue` - Get all field values
+Plugins transform input before it is cast and validated. The built-in `MaskPlugin` supports fixed mask characters and digit or custom pattern placeholders.
 
-* `allErrors` - Get all validation errors
+```typescript
+import { Field, MaskPlugin, StringType } from 'adaptform'
 
-* `globalErrors` - Get global errors
+const phone = new Field(StringType, null, {
+  plugins: [
+    new MaskPlugin({
+      maskFormat: '+1 (___) ___-____',
+      maskPlaceholder: '_',
+      digitPattern: /\d/,
+    }),
+  ],
+})
 
-* `toFormData()` - Convert to FormData
+phone.rawValue = '4155550134'
+console.log(phone.rawValue)
+console.log(phone.valueClear)
+```
 
-* `toJSON()` - Convert to JSON
+## Server-side errors with ErrorsSchema
 
-* `reset()` - Reset all fields
+`ErrorsSchema` maps error keys returned by a backend to form fields. By default, unmatched keys fall back to their original names.
 
-### Field
+```typescript
+import { ErrorsSchema, Form, Field, StringType } from 'adaptform'
 
-* `rawValue` - Set raw input value
+class AccountForm extends Form {
+  email = new Field(StringType)
+  username = new Field(StringType)
+}
 
-* `valueClear` - Get cleaned/validated value
+const form = new AccountForm()
+form.errorsShema = new ErrorsSchema()
+  .staticKey('email_address', 'email')
+  .staticKey('user_name', 'username')
+  .fallback(key => key)
 
-* `isValid` - Check if field is valid
+form.errors = {
+  email_address: 'This email is already registered.',
+  user_name: 'This username is unavailable.',
+  request_id: 'The request could not be completed.',
+}
 
-* `error` - Get first error message
+console.log(form.allErrors)
+```
 
-* `errors` - Get all error messages
+Available schema methods:
 
-* `isTouched` - Check if field was modified
+- `staticKey(errorKey, fieldName)` maps an exact key.
+- `dynamicKey(pattern, mapping, options?)` maps keys using a regular expression and optional priority.
+- `fallback(handler)` handles keys that do not match configured rules.
+- `transformValue(transformer)` normalizes server error values before mapping.
+- `nest(prefix)` creates a schema for nested field paths.
+- `clone()` and `merge(other)` compose schemas.
+- `ErrorsSchema.fromObject(mapping)` creates a schema from a key-to-field map.
+- `ErrorsSchema.forArray(itemSchema, arrayFieldName, indexExtractor?)` maps array-item errors, including bracket and dotted index notation.
 
-* `isEmpty` - Check if field is empty
+Assigning a new `form.errors` object clears previously applied errors before applying the new payload. Unknown field keys become global errors.
 
-* `reset()` - Reset to default value
+## Serialization
 
-### ArrayField
+### JSON
 
-* `add(value?)` - Add new field
+`toJSON()` returns a JSON-compatible object. JavaScript `Date` instances are recursively converted to ISO 8601 strings, including dates nested in arrays and plain objects.
 
-* `remove(index)` - Remove field at index
+```typescript
+const payload = form.toJSON()
+await fetch('/api/profile', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload),
+})
+```
 
-* `clear()` - Remove all fields
+### FormData
 
-* `itemsValue` - Get array of values
+`toFormData()` omits `null` and `undefined` values, appends scalar values as strings, serializes dates as ISO 8601 strings, preserves `Blob` and `File` values, and JSON-encodes arrays and nested objects.
 
-* `items` - Get array of Field instances
+```typescript
+const body = form.toFormData()
+await fetch('/api/profile', {
+  method: 'POST',
+  body,
+})
+```
 
-### ArrayFormField
+Do not set the multipart `Content-Type` header manually; the browser supplies the boundary.
 
-* `add(data?)` - Add new form
+## Optional Luxon integration
 
-* `remove(index)` - Remove form at index
+Install Luxon separately, then import the additional date type from the dedicated subpath:
 
-* `clear()` - Remove all forms
+```bash
+npm install luxon
+```
 
-* `forms` - Get array of Form instances
+```typescript
+import { Field } from 'adaptform'
+import { DateLuxonType } from 'adaptform/luxon'
+import { DateTime } from 'luxon'
 
-* `formsFieldsValue` - Get array of form values
+const date = new Field(DateLuxonType, null, {
+  isDatetime: false,
+  minDate: DateTime.fromISO('1900-01-01'),
+  maxDate: DateTime.now(),
+  inputFormat: 'dd.MM.yyyy',
+})
+```
 
-## TypeScript Support
+## API overview
 
-```TypeScript
-import {Form, Field, StringType, NumberType} from 'adaptform';
+| Class | Main API |
+| --- | --- |
+| `Form` | `fields`, `setFields()`, `fieldsValue`, `checkValid()`, `isValid`, `allErrors`, `globalErrors`, `errors`, `setGlobalError()`, `clearGlobalErrors()`, `reset()`, `toJSON()`, `toFormData()` |
+| `Field` | `rawValue`, `setRawValue()`, `valueClear`, `errors`, `error`, `isValid`, `isTouched`, `isEmpty`, `checkValid()`, `reset()` |
+| `ArrayField` | `items`, `itemsValue`, `add()`, `remove()`, `clear()`, `checkValid()`, `reset()` |
+| `ArrayFormField` | `forms`, `formsFieldsValue`, `add()`, `remove()`, `clear()`, `checkValid()`, `reset()` |
+| `ErrorsSchema` | `staticKey()`, `dynamicKey()`, `fallback()`, `transformValue()`, `parseErrors()`, `parseErrorsDetailed()`, `nest()`, `clone()`, `merge()`, `forArray()`, `fromObject()` |
 
-class UserForm extends Form {
-  name = new Field(StringType, null);
-  age = new Field(NumberType, null);
-}
+## Development
 
-const form = new UserForm();
+Requirements: Node.js 22 (used by CI) and npm.
 
-// Full type inference
-type UserData = typeof form.fieldsValue;
-// { name: string | null; age: number | null; }
+```bash
+npm ci
+npm run lint
+npm test
+npm run build
+npx tsc --noEmit -p tsconfig.json
+npm run check:demo
+npm run build:demo
 ```
 
-## License
+To run the interactive demo locally:
+
+```bash
+npm run dev -- --config demo/vite.config.ts
+```
 
-MIT © [Stanislav Orlov](https://github.com/ArhiMEN)
+The demo is built by GitHub Actions from `v2.1.0` and `master`. GitHub Pages is configured to allow both branches to publish to the same demo URL; see [Demo and GitHub Pages notes](https://github.com/ArhiMEN/AdaptForm/blob/master/docs/DEMO.md).
 
 ## Links
 
-* [GitHub Repository](https://github.com/ArhiMEN/adaptform)
-* [npm Package](https://www.npmjs.com/package/adaptform)
-* [Bug Reports](https://github.com/ArhiMEN/adaptform/issues)
-* [Changelog](https://github.com/ArhiMEN/adaptform/blob/master/CHANGELOG.md)
+- **[Interactive demo](https://arhimen.github.io/AdaptForm/)**
+- [GitHub repository](https://github.com/ArhiMEN/AdaptForm)
+- [npm package](https://www.npmjs.com/package/adaptform)
+- [Issue tracker](https://github.com/ArhiMEN/AdaptForm/issues)
+- [Changelog](https://github.com/ArhiMEN/AdaptForm/blob/master/CHANGELOG.md)
+- [License](https://github.com/ArhiMEN/AdaptForm/blob/master/LICENSE.md)
 
-## Support
+## License
 
-If you find this project useful, please give it a star on GitHub!
+MIT © Stanislav Orlov