Quick Start

Installation

bun add fatline

pnpm add fatline

npm install fatline

yarn add fatline

Basic Usage

import { serialize, deserialize } from 'fatline'

const data = {
  user: {
    id: '1',
    createdAt: new Date(),
    roles: new Set(['admin', 'user']),
    metadata: new Map([['theme', 'dark']]),
  }
}

// Serialize to JSON string
const json = serialize(data)

// Deserialize back to original types
const back = deserialize(json)

back.user.createdAt instanceof Date    // true
back.user.roles instanceof Set         // true
back.user.metadata instanceof Map      // true

Built-in Types

fatline automatically handles these types:

Type	Encoded As
`Date`	milliseconds timestamp
`BigInt`	string
`Map`	array of `[key, value]` entries
`Set`	array of values
`RegExp`	`[source, flags]`
`URL`	string
`Uint8Array`	base64 string
`ArrayBuffer`	base64 string
`undefined`	preserved (unlike JSON)
`NaN`, `Infinity`, `-Infinity`	preserved

Serialization Options

serialize(data, {
  // Paths to exclude from serialization
  exclude: ['user.password', 'internal'],

  // Transform values before serializing
  transform: {
    'user.secretKey': () => '[REDACTED]',
  },

  // How to handle circular references: 'error' | 'null' | 'ref'
  circular: 'error',

  // How to handle unknown types: 'error' | 'skip' | 'null'
  onUnknown: 'error',

  // Human-readable output for debugging
  debug: false,
})

Custom Types

import { registerType } from 'fatline'
import Decimal from 'decimal.js'

registerType({
  name: 'Decimal',
  test: (v): v is Decimal => v instanceof Decimal,
  encode: (v) => v.toString(),
  decode: (v) => new Decimal(v),
})

// Now Decimals serialize/deserialize automatically
serialize({ price: new Decimal('19.99') })