v3.0.0

Breaking Changes

Recursive FieldDescriptor — The flat FieldType union ('string-array', 'number-array', 'date-array', 'datetime-array') is replaced by a recursive discriminated union supporting type: 'array' (with item) and type: 'object' (with fields). This mirrors schema-info's SchemaInfo structure so the types are structurally compatible.

// Before
coerceValue(['1', '2'], { type: 'number-array' })

// After
coerceValue(['1', '2'], { type: 'array', item: { type: 'number' } })

Removed coerceFormData — Use composable-functions' inputFromForm to extract raw values from FormData, then pass the result to the now-recursive coerceValue for type coercion.

FieldType renamed to ScalarFieldType — The old FieldType union (which included flat array types) is replaced by ScalarFieldType covering only scalar types.

fieldName replaced by path on FormDataCoercionError — Nested errors now include a path: string[] property formatted as departments[0].headcount in the error message.

Removed types — FormDataLike, FormRecord, FieldDescriptors, CoercedFormData are removed along with coerceFormData.

New Features

• Object coercion — coerceValue and coerceToForm now handle type: 'object' with recursive fields descriptors
• Nested structures — Arrays of objects, objects with array fields, arrays of arrays, and arbitrary depth nesting
• Recursive type inference — CoercedFieldValue and CoercedToFormValue resolve recursively, so { type: 'array', item: { type: 'object', fields: { name: { type: 'string' } } } } infers as { readonly name: string }[]
• Error paths — FormDataCoercionError.path traces the exact location of nested failures

What's Changed

• Replace flat array types with recursive FieldDescriptor by @danielweinmann in #9

Full Changelog: v2.1.0...v3.0.0

v2.1.0

What's Changed

• Add 'file' FieldType for File/Blob pass-through by @danielweinmann in #8

Full Changelog: v2.0.0...v2.1.0

v2.0.0

Breaking Changes

• Throw on invalid values: number, date, and datetime fields now throw FormDataCoercionError instead of returning null, NaN, or Invalid Date. Boolean fields throw for the string 'null' unless nullable or optional is set. Add optional: true or nullable: true to fields that relied on null returns.
• parseDate uses local time: parseDate now uses getFullYear/getMonth/getDate instead of toISOString() (UTC), consistent with parseDatetime and coerceDate.

New Features

• Typed return values: coerceFormData, coerceValue, and coerceToForm infer return types from field descriptors via TypeScript generics — no casts needed
• FormDataCoercionError: Custom error class with value, fieldType, and fieldName properties for structured error handling
• FormDataLike type: coerceFormData now accepts any object with .get() and .getAll() methods (FormData, URLSearchParams, or custom implementations)
• Utility types: Export CoercedFieldValue, CoercedFormData, CoercedToFormValue, and FormDataLike

What's Changed

• v2: Throw on invalid values, add typed return values by @danielweinmann in #4
• BREAKING: Fix parseDate to use local time instead of UTC by @danielweinmann in #5
• Add fieldName to FormDataCoercionError for better debugging by @danielweinmann in #6
• Accept any FormDataLike source instead of only FormData by @danielweinmann in #7

Full Changelog: v1.2.0...v2.0.0

v1.2.0

What's Changed

• Add array field types for multi-value form fields by @danielweinmann in #3

Full Changelog: v1.1.0...v1.2.0

v1.1.0

What's Changed

• Add datetime field type for datetime-local input support by @danielweinmann in #2

Full Changelog: v1.0.0...v1.1.0

v1.0.0

coerce-form-data

Zero-dependency form data coercion using web standard APIs.

Converts raw form values (strings from HTML forms or FormData objects) into properly typed JavaScript values (numbers, booleans, dates, etc.) and back again.

Highlights

• Zero dependencies — uses only web standard APIs
• Full TypeScript support with strict typing
• ESM and CommonJS builds
• Reversible coercion — form strings to typed values and typed values back to form strings
• Supports string, number, boolean, date, and enum field types
• Works with web standard FormData and plain objects
• Handles optional and nullable fields

What's Changed

• Add CI workflow by @danielweinmann in #1

Full Changelog: https://github.com/seasonedcc/coerce-form-data/commits/v1.0.0