coerce-form-data

Zero-dependency form data coercion.

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'

License

MIT