npm package: @origints/toml
Description: TOML parsing and manipulation for Origins with full lineage tracking
Latest version: 0.3.2

# @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

```bash
npm install @origints/toml @origints/core
```

---

## Usage with Planner

### Extract values from a TOML config file

```ts
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

```ts
// 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

```ts
// 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()`:

```ts
// 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

```ts
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:

```ts
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