Formatter

Serialize data to multiple output formats including TOON, JSON, YAML, and Markdown

The Formatter module provides utilities for serializing data to various output formats. It supports TOON (the default format), JSON, YAML, Markdown tables, and JSONL.

Types

Format

Supported output formats for the format() function.

type Format = 'toon' | 'json' | 'yaml' | 'md' | 'jsonl'

toon · 'toon'

TOON format (default) - a concise, human-readable format

json · 'json'

Pretty-printed JSON with 2-space indentation

yaml · 'yaml'

YAML format

md · 'md'

Markdown format with tables for structured data

jsonl · 'jsonl'

JSON Lines format (one JSON object per line)

Functions

format

Serializes a value to the specified format. Defaults to TOON.

value · unknown · required

The value to serialize. Can be any JavaScript value including objects, arrays, primitives, or null/undefined.

fmt · Format · default: "'toon'"

The output format. Defaults to 'toon'.

return · string

The serialized string representation of the value

Usage: Basic Formatting

import { format } from 'incur'

const data = {
  name: 'Alice',
  age: 30,
  active: true
}

// TOON format (default)
const toon = format(data)
// name: Alice
// age: 30
// active: true

// JSON format
const json = format(data, 'json')
// {
//   "name": "Alice",
//   "age": 30,
//   "active": true
// }

// YAML format
const yaml = format(data, 'yaml')
// name: Alice
// age: 30
// active: true

Usage: Markdown Tables

import { format } from 'incur'

// Flat object becomes a key-value table
const config = { host: 'localhost', port: 3000 }
const md = format(config, 'md')
// | Key  | Value     |
// |------|-----------|  
// | host | localhost |
// | port | 3000      |

// Array of objects becomes a columnar table
const users = [
  { name: 'Alice', role: 'admin' },
  { name: 'Bob', role: 'user' }
]
const table = format(users, 'md')
// | name  | role  |
// |-------|-------|
// | Alice | admin |
// | Bob   | user  |

Usage: Scalar Values

import { format } from 'incur'

// Scalars return as strings
format('hello')  // 'hello'
format(42)       // '42'
format(true)     // 'true'
format(null)     // ''
format(undefined) // ''

Usage: CLI Output

import { format } from 'incur'

function output(data: unknown, fmt: Format = 'toon') {
  console.log(format(data, fmt))
}

// User can control output format
const result = { success: true, count: 42 }
output(result, 'json')  // Pretty JSON
output(result, 'yaml')  // YAML
output(result, 'md')    // Markdown table

Usage: Nested Objects

import { format } from 'incur'

const nested = {
  server: {
    host: 'localhost',
    port: 3000
  },
  database: {
    host: 'db.example.com',
    port: 5432
  }
}

const md = format(nested, 'md')
// ## server
//
// | Key  | Value     |
// |------|-----------|  
// | host | localhost |
// | port | 3000      |
//
// ## database
//
// | Key  | Value          |
// |------|----------------|
// | host | db.example.com |
// | port | 5432           |