SerializationLast updated on
Last updated on
Locale-aware formatting of primitive values for rendering
Convert OpenForm primitive types (Money, Address, Phone, etc.) to locale-aware formatted strings for use in templates. This package powers automatic value formatting in all renderers.
Installation
npm install @open-form/serializationOr use via the SDK:
import { usaSerializers, createSerializer } from '@open-form/sdk'Example
import { usaSerializers } from '@open-form/serialization'
// Format a money value
usaSerializers.money.stringify({ amount: 1500.50, currency: 'USD' })
// "$1,500.50"
// Format an address
usaSerializers.address.stringify({
line1: '123 Main Street',
locality: 'San Francisco',
region: 'CA',
postalCode: '94105',
country: 'USA'
})
// "123 Main Street, San Francisco, CA 94105, USA"
// Format a phone number
usaSerializers.phone.stringify({ number: '+14155551234' })
// "+14155551234"
// Format a person's name
usaSerializers.person.stringify({ firstName: 'John', lastName: 'Smith' })
// "John Smith"Pre-built Registries
Two pre-configured serializer registries are available:
| Registry | Locale | Currency | Address Format |
|---|---|---|---|
usaSerializers | en-US | USD | US style (City, State ZIP) |
euSerializers | de-DE | EUR | EU style (PostalCode City) |
import { usaSerializers, euSerializers } from '@open-form/serialization'
const price = { amount: 1299.99, currency: 'EUR' }
usaSerializers.money.stringify(price) // "€1,299.99"
euSerializers.money.stringify(price) // "1.299,99 €"Creating Custom Serializers
Use createSerializer() to create a registry with custom configuration:
import { createSerializer } from '@open-form/serialization'
const customSerializers = createSerializer({
regionFormat: 'eu',
fallbacks: {
money: 'N/A',
address: '—',
phone: 'Not provided'
}
})
// Uses fallback when serialization fails
customSerializers.money.stringify(null) // "N/A"SerializerConfig
regionFormat?: "us" | "eu"
Regional format preference for addresses and numbers
fallbacks?: SerializerFallbacks
Fallback values when serialization fails
SerializerFallbacks
money?: string
Fallback for money values
address?: string
Fallback for address values
phone?: string
Fallback for phone values
person?: string
Fallback for person values
organization?: string
Fallback for organization values
party?: string
Fallback for party values
coordinate?: string
Fallback for coordinate values
bbox?: string
Fallback for bounding box values
duration?: string
Fallback for duration values
identification?: string
Fallback for identification values
attachment?: string
Fallback for attachment values
signature?: string
Fallback for signature values
Supported Types
The SerializerRegistry provides stringifiers for all OpenForm primitive types:
| Type | Input | Example Output |
|---|---|---|
money | Money | number | $1,500.00 |
address | Address | 123 Main St, City, ST 12345 |
phone | Phone | string | +15551234567 |
person | Person | Dr. John Smith Jr. |
organization | Organization | Acme Corp (Tax ID: 12-3456789) |
party | Party | Person or Organization format |
coordinate | Coordinate | 37.7749,-122.4194 |
bbox | Bbox | 37.7,-122.5,37.8,-122.4 |
duration | Duration | string | 1 year, 2 months, 3 days |
identification | Identification | PASSPORT: AB123456 |
attachment | Attachment | contract.pdf (application/pdf) |
signature | Signature | Signed 2024-01-15T10:30:00Z (drawn) |
SerializerRegistry
money: Stringifier<Money>
Formats monetary amounts with currency symbols
address: Stringifier<Address>
Formats postal addresses by region
phone: Stringifier<Phone>
Formats phone numbers in E.164 format
person: Stringifier<Person>
Formats person names with title/suffix
organization: Stringifier<Organization>
Formats organization name with tax ID
party: Stringifier<Party>
Delegates to person or organization
coordinate: Stringifier<Coordinate>
Formats lat/lng coordinates
bbox: Stringifier<Bbox>
Formats bounding boxes
duration: Stringifier<Duration>
Formats ISO 8601 durations
identification: Stringifier<Identification>
Formats ID documents
attachment: Stringifier<Attachment>
Formats attachment metadata
signature: Stringifier<Signature>
Formats signature information
Usage with Renderers
Renderers automatically use serializers to format field values based on their schema types. You can customize serialization by passing a SerializerRegistry via the renderer context:
import { open } from '@open-form/core'
import { textRenderer } from '@open-form/renderer-text'
import { euSerializers } from '@open-form/serialization'
const form = open.form({
name: 'invoice',
fields: {
total: { type: 'money' }
},
layers: {
text: { kind: 'inline', mimeType: 'text/plain', text: 'Total: {{total}}' }
}
})
// Fill form with data
const filled = form.fill({
fields: { total: { amount: 1000, currency: 'EUR' } }
})
// Use EU formatting
const output = await filled.render({
renderer: textRenderer({ serializers: euSerializers })
})
// "Total: 1.000,00 €"See Renderers for more details on the OpenFormRendererContext and how serializers integrate with rendering.
Related
- Renderers - How renderers use serialization
- Primitives - Primitive type definitions