@origints/toml

TOML parsing and manipulation for Origins with full lineage tracking.

Features

• Full TOML 1.0 spec support
• Source position tracking for all nodes
• Type-safe navigation with Result types
• Proper datetime type handling (offset, local date/time)
• JSON conversion with customizable options
• Integrates with Origins transform registry

Installation

npm install @origints/toml @origints/core

Usage with Planner

Extract values from a TOML config file

import { Planner, loadFile, run } from '@origints/core'
import { parseToml } from '@origints/toml'

const plan = new Planner()
  .in(loadFile('config.toml'))
  .mapIn(parseToml())
  .emit((out, $) =>
    out
      .add('host', $.get('server').get('host').string())
      .add('port', $.get('server').get('port').number())
      .add('debug', $.get('server').get('debug').boolean())
  )
  .compile()

const result = await run(plan, { readFile, registry })
// result.value: { host: 'localhost', port: 8080, debug: false }

Extract nested tables

// config.toml:
// [database]
// host = "localhost"
// port = 5432
// [database.pool]
// min = 5
// max = 20

const plan = new Planner()
  .in(loadFile('config.toml'))
  .mapIn(parseToml())
  .emit((out, $) =>
    out
      .add('dbHost', $.get('database').get('host').string())
      .add('dbPort', $.get('database').get('port').number())
      .add('poolMin', $.get('database').get('pool').get('min').number())
      .add('poolMax', $.get('database').get('pool').get('max').number())
  )
  .compile()

Extract arrays

// config.toml:
// [[servers]]
// name = "alpha"
// ip = "10.0.0.1"
// [[servers]]
// name = "beta"
// ip = "10.0.0.2"

const plan = new Planner()
  .in(loadFile('config.toml'))
  .mapIn(parseToml())
  .emit((out, $) =>
    out.add(
      'serverNames',
      $.get('servers').array(s => s.get('name').string())
    )
  )
  .compile()

const result = await run(plan, { readFile, registry })
// result.value: { serverNames: ['alpha', 'beta'] }

Convenience collection methods

For simple arrays of scalars, use strings() or numbers() instead of array():

// config.toml:
// tags = ["dev", "staging", "prod"]
// ports = [3000, 3001, 3002]

const plan = new Planner()
  .in(loadFile('config.toml'))
  .mapIn(parseToml())
  .emit((out, $) =>
    out
      .add('tags', $.get('tags').strings())
      .add('ports', $.get('ports').numbers())
  )
  .compile()

const result = await run(plan, { readFile, registry })
// result.value: { tags: ['dev', 'staging', 'prod'], ports: [3000, 3001, 3002] }

Combine TOML config with another source

const plan = new Planner()
  .in(loadFile('config.toml'))
  .mapIn(parseToml())
  .emit((out, $) =>
    out
      .add('host', $.get('server').get('host').string())
      .add('port', $.get('server').get('port').number())
  )
  .in(loadFile('overrides.toml'))
  .mapIn(parseToml())
  .emit((out, $) =>
    out.addIfEmpty('host', $.get('server').get('host').string())
  )
  .compile()

Standalone usage (without Planner)

For quick scripts or debugging, use the transform implementation directly:

import { parseTomlImpl, toJson, TomlNode } from '@origints/toml'

const node = parseTomlImpl.execute(tomlString) as TomlNode

// Navigate with Result types
const host = node.get('server')
if (host.ok) {
  console.log(host.value.get('host').value.asString().value)
}

// Or convert to JSON
const json = toJson(node)
if (json.ok) {
  console.log(json.value)
}

API

| Export | Description | | ---------------------------------- | ----------------------------------------------------- | | parseToml(options?) | Create a transform AST for use with Planner.mapIn() | | parseTomlImpl | Sync transform implementation (string input) | | parseTomlAsyncImpl | Async transform implementation (string or stream) | | registerTomlTransforms(registry) | Register all TOML transforms with a registry | | TomlNode | Navigable wrapper around parsed TOML | | toJson(node, options?) | Convert TomlNode to JSON | | toJsonValue(node) | Convert TomlNode to JSON with defaults | | ok, fail, formatTomlPath | Result helpers |

License

MIT