Transform basic plain-text lists or objects into arrays and objects.

• What is this?
• When should I use this?
• Install
• Use
• API
  • toJson(value[, options])
• Data
  • Comments
  • Whitespace
  • Empty lines
  • Key/value pairs
  • Values
  • Errors
• Types
• Compatibility
• Contribute
• Security
• License

This package takes a file (a sort of simple database), parses it, and returns clean data.

I found myself rewriting a simple transformation over and over to handle text files. One example is this source file in emoji-emotion This project fixes that for me. You can use it too if it matches your needs.

This package is ESM only. In Node.js (version 14.14+, 16.0+), install with npm:

npm install plain-text-data-to-json

In Deno with esm.sh:

import {toJson} from 'https://esm.sh/plain-text-data-to-json@2'

In browsers with esm.sh:

<script type="module">
  import {toJson} from 'https://esm.sh/plain-text-data-to-json@2?bundle'
</script>

If we have the following file input.txt:

% A comment

alpha
bravo
charlie

…and our module example.js looks as follows:

import fs from 'node:fs/promises'
import {toJson} from 'plain-text-data-to-json'

const document = String(await fs.readFile('input.txt'))

const data = toJson(document)

await fs.writeFile('output.json', JSON.stringify(data, null, 2) + '\n')

…then running node example.js yields in output.json:

[
  "alpha",
  "bravo",
  "charlie"
]

This package exports the identifier toJson. There is no default export.

Transform basic plain-text lists or objects into arrays and objects.

Configuration (optional).

Character to use as delimiter between key/value pairs (string, default: ':').

Character(s) to use for line comments, false turns off comments (string, Array<string>, or boolean, default: '%')

How relaxed to be ('fix' or boolean, default: false). When true, doesn’t throw for duplicate keys. When 'fix', doesn’t throw for key/value pairs and overwrites (see errors).

Whether to call console.log with info when forgiving ignores an error (boolean, default: true).

The term plain text might be confusing. It’s actually more of some (sparingly specified) standard.

Use a percentage sign (by default) to specify a comment. The comment will last until the end of line.

% This is a completely commented line.
unicorn % This is a partially commented line.

Yields:

['unicorn']

Initial or final white space (\s) is trimmed from values.

       unicorn     % some value

Yields:

['unicorn']

Empty lines are striped. This includes whitespace only lines.

    %%% this file contains a value. %%%

unicorn

Yields:

['unicorn']

If a line includes a colon (by default), the library returns an object.

unicorn : magic creature

Yields:

{unicorn: 'magic creature'}

All other lines are treated as array values.

unicorn

Yields:

["unicorn"]

Some errors are thrown when malformed “plain-text” is found, such as:

• when lines both with and without colons exist
• in arrays, when duplicate values exist (unless forgiving: true)
• in objects, when duplicate properties exist (unless forgiving: true)
• in objects, when duplicate properties with different values exist (unless forgiving: "fix")

This package is fully typed with TypeScript. It exports the additional type Options.

This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. It also works in Deno and modern browsers.

Yes please! See How to Contribute to Open Source.

This package is safe.

MIT © Titus Wormer