Converts raw form values (strings) into properly typed JavaScript values (numbers, booleans, dates, etc.) and back again. Supports recursive structures: arrays, objects, and arbitrary nesting.

Features

Zero dependencies
Recursive: arrays of objects, nested objects, arrays of arrays
Full TypeScript support with inferred return types
ESM and CommonJS builds
Reversible: coerce form strings to typed values and typed values back to form strings
Throws FormDataCoercionError on invalid values — no silent NaN or Invalid Date

Installation

npm install coerce-form-data
# or
pnpm add coerce-form-data
# or
yarn add coerce-form-data

Quick Start

import { coerceValue } from 'coerce-form-data'

// Scalar coercion
coerceValue('42', { type: 'number' })          // 42
coerceValue('true', { type: 'boolean' })       // true
coerceValue('2024-05-06', { type: 'date' })    // Date(2024, 4, 6)

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

// Object coercion
coerceValue(
  { name: 'Jane', age: '30', active: 'true' },
  {
    type: 'object',
    fields: {
      name: { type: 'string' },
      age: { type: 'number' },
      active: { type: 'boolean' },
    },
  },
)
// { name: 'Jane', age: 30, active: true }

// Deeply nested
coerceValue(
  { departments: [{ name: 'Eng', headcount: '50' }] },
  {
    type: 'object',
    fields: {
      departments: {
        type: 'array',
        item: {
          type: 'object',
          fields: {
            name: { type: 'string' },
            headcount: { type: 'number' },
          },
        },
      },
    },
  },
)
// { departments: [{ name: 'Eng', headcount: 50 }] }

Return types are automatically inferred from the field descriptors — no casts needed.

With composable-functions

Use composable-functions' inputFromForm to extract raw values from FormData (handling bracket notation, repeated keys, etc.), then pass the result to coerceValue for type coercion:

import { inputFromForm } from 'composable-functions'
import { coerceValue } from 'coerce-form-data'

const descriptor = {
  type: 'object',
  fields: {
    name: { type: 'string' },
    age: { type: 'number' },
  },
} as const

const raw = inputFromForm(formData)
const typed = coerceValue(raw, descriptor)
// { name: string, age: number }

API

`coerceValue(value, field?)`

Coerce a raw value into its typed representation. When no field descriptor is provided, the value is returned as-is.

// Scalars
coerceValue('42', { type: 'number' })               // 42
coerceValue('true', { type: 'boolean' })             // true
coerceValue('2024-05-06', { type: 'date' })          // Date(2024, 4, 6)
coerceValue('2024-05-06T14:30', { type: 'datetime' }) // Date(2024, 4, 6, 14, 30)
coerceValue('hello', { type: 'string' })             // 'hello'
coerceValue(file, { type: 'file' })                  // File (pass-through)

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

// Objects
coerceValue(
  { street: 'Main St', zip: '12345' },
  { type: 'object', fields: { street: { type: 'string' }, zip: { type: 'number' } } },
)
// { street: 'Main St', zip: 12345 }

Throws FormDataCoercionError for invalid values. For nested structures, the error includes a path indicating where the failure occurred.

`coerceToForm(value, field)`

The reverse of coerceValue. Converts a typed JavaScript value into the string (or boolean) that an HTML form input expects. Works recursively for arrays and objects.

// Scalars
coerceToForm(42, { type: 'number' })                              // '42'
coerceToForm(true, { type: 'boolean' })                           // true
coerceToForm(new Date('2024-05-06T12:00:00Z'), { type: 'date' }) // '2024-05-06'
coerceToForm(new Date(2024, 4, 6, 14, 30), { type: 'datetime' }) // '2024-05-06T14:30:00'
coerceToForm(file, { type: 'file' })                              // undefined

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

// Objects
coerceToForm(
  { name: 'Jane', age: 30 },
  { type: 'object', fields: { name: { type: 'string' }, age: { type: 'number' } } },
)
// { name: 'Jane', age: '30' }

`parseDate(value?)`

Formats a Date or ISO date-time string as a YYYY-MM-DD string suitable for <input type="date">. Uses local time for Date instances.

parseDate(new Date(2024, 4, 6))    // '2024-05-06'
parseDate('2024-05-06T12:00:00Z') // '2024-05-06'
parseDate(undefined)               // undefined

`parseDatetime(value?)`

Formats a Date as a YYYY-MM-DDTHH:mm:ss string suitable for <input type="datetime-local">. Uses local time.

parseDatetime(new Date(2024, 4, 6, 14, 30, 45)) // '2024-05-06T14:30:45'
parseDatetime('2024-05-06T14:30')                // '2024-05-06T14:30'
parseDatetime(undefined)                          // undefined

`FormDataCoercionError`

Thrown when a value cannot be coerced to the declared field type. Extends Error with value, fieldType, and path properties.

For nested structures, the path array indicates where the error occurred:

import { coerceValue, FormDataCoercionError } from 'coerce-form-data'

try {
  coerceValue(
    { departments: [{ name: 'Eng', headcount: 'bad' }] },
    {
      type: 'object',
      fields: {
        departments: {
          type: 'array',
          item: {
            type: 'object',
            fields: {
              name: { type: 'string' },
              headcount: { type: 'number' },
            },
          },
        },
      },
    },
  )
} catch (error) {
  if (error instanceof FormDataCoercionError) {
    error.value     // 'bad'
    error.fieldType // 'number'
    error.path      // ['departments', '0', 'headcount']
    error.message   // 'Cannot coerce "bad" to number at departments[0].headcount'
  }
}

Field Descriptors

FieldDescriptor is a recursive discriminated union:

// Scalar fields
type ScalarFieldDescriptor = {
  type: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'enum' | 'file' | null
  optional?: boolean
  nullable?: boolean
}

// Array fields — item describes each element
type ArrayFieldDescriptor = {
  type: 'array'
  item: FieldDescriptor
  optional?: boolean
  nullable?: boolean
}

// Object fields — fields describes the shape
type ObjectFieldDescriptor = {
  type: 'object'
  fields: Record<string, FieldDescriptor>
  optional?: boolean
  nullable?: boolean
}

type FieldDescriptor = ScalarFieldDescriptor | ArrayFieldDescriptor | ObjectFieldDescriptor

This mirrors schema-info's SchemaInfo discriminated union, so a SchemaInfo value is structurally compatible as a FieldDescriptor.

Coercion behavior by type

Type	Input	Output
`string`	`'hello'`	`'hello'`
`string`	falsy	`''`
`number`	`'42'`	`42`
`number`	falsy / invalid	throws `FormDataCoercionError`
`boolean`	`'on'`, `'true'`, truthy	`true`
`boolean`	`'false'`	`false`
`boolean`	`'null'` (required)	throws `FormDataCoercionError`
`boolean`	`'null'` (nullable)	`null`
`boolean`	`'null'` (optional)	`undefined`
`boolean`	falsy	`false`
`date`	`'2024-05-06'`	`Date(2024, 4, 6)`
`date`	falsy / invalid	throws `FormDataCoercionError`
`datetime`	`'2024-05-06T14:30'`	`Date(2024, 4, 6, 14, 30)`
`datetime`	falsy / invalid	throws `FormDataCoercionError`
`enum`	`'value'`	`'value'`
`enum`	falsy	`''`
`file`	`File` instance	`File` (pass-through)
`file`	falsy / non-File	throws `FormDataCoercionError`
`array`	`['1', '2']` with `item: { type: 'number' }`	`[1, 2]`
`array`	falsy	`[]`
`object`	`{ age: '30' }` with `fields: { age: { type: 'number' } }`	`{ age: 30 }`
`object`	falsy	recurse with `{}` (inner fields get defaults or throw)

Missing values

When a field value is missing (falsy), the optional and nullable flags control what is returned:

Flags	Missing value returns
(none)	Type-specific empty value (see table above), or throws for `number`/`date`/`datetime`
`optional: true`	`undefined`
`nullable: true`	`null`
both	`null` (nullable takes precedence)

These flags work at every nesting level. An optional array returns string[] | undefined. An array of optional strings returns (string | undefined)[].

Type Inference

All functions infer return types from the field descriptors you pass:

coerceValue('42', { type: 'number' })
//=> number

coerceValue('42', { type: 'number', optional: true })
//=> number | undefined

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

coerceValue({}, {
  type: 'object',
  fields: {
    name: { type: 'string' },
    age: { type: 'number' },
  },
})
//=> { readonly name: string; readonly age: number }

The utility types CoercedFieldValue and CoercedToFormValue are also exported for use in your own code.

Types

All types are exported:

import type {
  ScalarFieldType,      // 'string' | 'number' | 'boolean' | ...
  ScalarFieldDescriptor, // { type: ScalarFieldType | null, optional?, nullable? }
  ArrayFieldDescriptor,  // { type: 'array', item: FieldDescriptor, ... }
  ObjectFieldDescriptor, // { type: 'object', fields: Record<string, FieldDescriptor>, ... }
  FieldDescriptor,       // ScalarFieldDescriptor | ArrayFieldDescriptor | ObjectFieldDescriptor
  FormValue,             // Raw input value type
  CoercedFieldValue,     // Compute return type for coerceValue
  CoercedToFormValue,    // Compute return type for coerceToForm
} from 'coerce-form-data'