js-toml

A TOML parser for JavaScript and TypeScript. Fully tested and 100% compatible with the TOML v1.1.0 spec (every valid TOML v1.0.0 document parses identically; dump() keeps emitting TOML v1.0.0-compatible output for maximum downstream compatibility). Passes all 681 cases of the official toml-test suite. Support Node.js, browsers and Bun⚡️!

Trusted By

js-toml is used by leading companies and major open-source projects, including:

• MongoDB (in the snooty documentation compiler)
• LINE (in abc-user-feedback)
• cargo-lambda (in cargo-lambda-cdk, the CDK construct for deploying Rust on AWS Lambda)
• Mise (a next-gen asdf)
• Open edX (in over 28 packages)
• ... and many more.

Installation

npm install js-toml

or with yarn

yarn add js-toml

or with pnpm

pnpm add js-toml

even support bun!

bun add js-toml

Usage

Parsing TOML

import {load} from 'js-toml';

const toml = `
title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates
`;

const data = load(toml);
console.log(data);

Serializing to TOML

import {dump} from 'js-toml';

const toml = dump({
  title: 'TOML Example',
  owner: {
    name: 'Tom Preston-Werner',
    dob: new Date('1979-05-27T07:32:00-08:00'),
  },
});

console.log(toml);

API

load(toml: string, options?: LoadOptions): object

Parses a TOML string and returns a JavaScript object.

LoadOptions

| Option | Type | Default | Description | | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | maxDepth | number | 100 | Maximum nesting depth for arrays / inline tables and dotted-key / table-header segments. Input exceeding this is rejected with a SyntaxParseError instead of overflowing the call stack with a RangeError. |

Any invalid input, including input that exceeds maxDepth, is reported by throwing SyntaxParseError.

Dates and times

| TOML type | Example | You get | | ---------------- | ---------------------- | ---------------------------------- | | Offset date-time | 1979-05-27T07:32:00Z | TomlDate at that instant | | Local date-time | 1979-05-27T07:32:00 | TomlDate, wall clock read as UTC | | Local date | 1979-05-27 | TomlDate at midnight UTC | | Local time | 07:32:00 | TomlTime, a Date with no day |

A local date-time carries no offset, so read it with getUTCHours() and friends; getHours() would shift with the host timezone.

All four are Date subclasses, so instanceof Date reaches every one and toISOString() returns the form the document wrote rather than an instant with a Z it never carried. JSON.stringify follows, since toJSON delegates there. TomlDate adds kind, one of 'offset-date-time', 'local-date-time' or 'local-date'; TomlTime adds hour, minute, second and fraction, and keeps the source precision that a millisecond-based encoding rounds away.

Upgrading from 1.x: see the 2.0.1 notes.

dump(object: object, options?: DumpOptions): string

Serializes a JavaScript object into a TOML string. The input must be a plain object (i.e. a TOML table).

Supported value types: string, number, bigint, boolean, Date, array, plain object, and array-of-tables. Strings are always emitted as single-line basic strings; multiline string output is not currently supported.

DumpOptions

| Option | Type | Default | Description | | ----------------- | ------------------ | ------- | -------------------------------------------------------------------------------------------- | | newline | '\n' | '\r\n' | '\n' | Newline sequence used between lines. | | ignoreUndefined | boolean | false | If true, properties with unsupported values (undefined, Symbol, Function) are silently dropped instead of throwing. | | forceQuotes | boolean | false | If true, string keys are always quoted, even when they only contain bare-key characters. |

License

MIT

References

TOML v1.1.0 Official Specs

TOML GitHub Project

TOML Test

iarna-toml