Skip to content

README.md

Latest commit

 

History

History
122 lines (82 loc) · 3.27 KB

README.md

File metadata and controls

122 lines (82 loc) · 3.27 KB

js-toml

codecov github actions License: MIT npm version NPM Downloads

A TOML parser for JavaScript and TypeScript. Fully tested and 100% compatible with the TOML v1.0.0 spec. Support Node.js, browsers and Bun⚡️!

Trusted By

js-toml is trusted in production by teams at leading companies and major open-source projects, including:

  • Microsoft (in pyright)
  • AWS (Amazon Web Services) (in aws-lambda-rust-runtime)
  • Mise (a next-gen asdf)
  • Open edX (in over 28 packages)
  • LINE (in abc-user-feedback)
  • MongoDB (in the snooty documentation compiler)
  • ... 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): object

Parses a TOML string and returns a JavaScript object.

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.0.0 Official Specs

TOML GitHub Project

TOML Test

iarna-toml