confbox

confbox provides utilities for the following formats:

• JSON: Standard JSON parsing and serialization.
• JSON5: JSON with extended syntax.
• JSONC: JSON with comments.
• YAML: YAML parsing and serialization.
• TOML: TOML parsing and serialization.
• INI: INI file parsing and serialization (Note: style/indentation not preserved).

You can install confbox using your preferred package manager. It is zero-dependency and tree-shakable.

# Auto-detect package manager
npx nypm install confbox

# npm
npm install confbox

# yarn
yarn add confbox

# pnpm
pnpm add confbox

# bun
bun install confbox

# deno
deno install npm:confbox

Import the parsing and serialization utilities from confbox depending on your environment.

// ESM (Node.js, Bun, Deno)
import {
  parseJSON5,
  stringifyJSON5,
  parseJSONC,
  stringifyJSONC,
  parseYAML,
  stringifyYAML,
  parseJSON,
  stringifyJSON,
  parseTOML,
  stringifyTOML,
  parseINI,
  stringifyINI,
} from "confbox";

// CDN (Deno and Browsers)
import {
  parseJSON5,
  stringifyJSON5,
  parseJSONC,
  stringifyJSONC,
  parseYAML,
  stringifyYAML,
  parseJSON,
  stringifyJSON,
  parseTOML,
  stringifyTOML,
  parseINI,
  stringifyINI,
} from "https://esm.sh/confbox";

Use the stringify* functions to convert JavaScript objects into configuration strings.

Note on JSON: For stringifyJSON, indentation status is auto-detected and preserved if the value was originally produced by parseJSON.

Note on INI: For parseINI and stringifyINI, style and indentation are not currently preserved.

// Examples of stringifying
stringifyINI(value, options?)
stringifyJSON(value, options?)
stringifyJSON5(value, options?)
stringifyJSONC(value, options?)
stringifyTOML(value)
stringifyYAML(value, options?)

Use the parse* functions to convert configuration strings into JavaScript objects. Most functions accept an optional options object.

// Examples of parsing
parseINI(text, options?)
parseJSON(text, options?)
parseJSON5(text, options?)
parseJSONC(text, options?)
parseTOML(text)
parseYAML(text, options?)

Use parseINI to parse INI configuration strings and stringifyINI to convert objects to INI format. Configuration is handled via INIParseOptions and INIStringifyOptions.

import { parseINI, stringifyINI } from 'confbox';

const obj = parseINI('[section]\nkey = value');
const str = stringifyINI(obj);

Use parseJSONC<T>(text, options?) to convert a JSONC (JSON with comments) string into a JavaScript object. The parser is designed to be fault-tolerant.

Important Notes:

• Comments and trailing commas are not preserved in the resulting object.
• You can configure whether to allow trailing commas via the allowTrailingComma option.
• The function uses stripBOM internally to handle Byte Order Marks.

import { parseJSONC } from 'confbox/jsonc';

const jsonc = `{
  // This is a comment
  "name": "confbox",
  "version": "0.3.1",
}`;

const obj = parseJSONC(jsonc, { allowTrailingComma: true });
console.log(obj.name); // "confbox"

Use parseYAML to convert YAML strings to JavaScript objects and stringifyYAML to convert objects to YAML strings. Use YAMLParseOptions and YAMLStringifyOptions for configuration.

import { parseYAML, stringifyYAML } from 'confbox';

const obj = parseYAML('key: value');
const str = stringifyYAML(obj);

Use parseTOML to parse TOML strings and stringifyTOML to convert JavaScript objects into TOML strings.

import { parseTOML, stringifyTOML } from 'confbox';

const obj = parseTOML('key = "value"');
const str = stringifyTOML(obj);

Use parseTOML<T>(text) to convert a TOML-formatted string into a JavaScript object.

Note: Comments and indentation are not preserved after parsing.

import { parseTOML } from 'confbox/toml';

const tomlString = `
[server]
port = 8080
`;

const config = parseTOML<{ server: { port: number } }>(tomlString);
console.log(config.server.port); // 8080

Use parseJSONC to parse JSON with comments (JSONC) and stringifyJSONC to convert an object to a JSONC string. Configuration is handled via JSONCParseOptions.

import { parseJSONC, stringifyJSONC } from 'confbox';

const obj = parseJSONC('{ "key": "value" // comment }');
const str = stringifyJSONC(obj);

Use stringifyJSON5() to convert a JavaScript value into a JSON5 formatted string. This is useful for writing configuration files that allow comments and trailing commas.

import { stringifyJSON5 } from 'confbox';

const obj = { name: 'confbox', version: 0.3.1 };
const str = stringifyJSON5(obj, { space: 2 });

console.log(str);