Add improved docs

Author: wooorm

index.js

@@ -1,18 +1,32 @@
-const own = {}.hasOwnProperty
-
 /**
- * @typedef ToJsonOptions
- * @property {boolean} [log=true]
+ * @typedef Options
+ *   Configuration.
  * @property {string} [delimiter=':']
- * @property {string[]|string|false} [comment='%']
+ *   Character to use as delimiter between key/value pairs.
+ * @property {Array<string>|string|false} [comment='%']
+ *   Character(s) to use for line comments, `false` turns off comments.
  * @property {boolean|'fix'} [forgiving]
+ *   How relaxed to be.
+ *   When `true`, doesn’t throw for duplicate keys.
+ *   When `'fix'`, doesn’t throw for key/value pairs and overwrites.
+ * @property {boolean} [log=true]
+ *   Whether to log when `forgiving` ignores an error.
  */
 
 /**
- * Transform a string into an array or object of values.
+ * @typedef {Options} ToJsonOptions
+ *   Deprecated: please use `Options`.
+ */
+
+const own = {}.hasOwnProperty
+
+/**
+ * Transform basic plain-text lists or objects into arrays and objects.
  *
  * @param {string} value
- * @param {ToJsonOptions} [options={}]
+ *   Value to parse.
+ * @param {Options} [options]
+ *   Configuration (optional).
  */
 export function toJson(value, options = {}) {
   const log =
@@ -31,11 +45,9 @@ export function toJson(value, options = {}) {
     .split('\n')
     .map((line) => {
       let commentIndex = -1
-      /** @type {number} */
-      let index
 
       while (++commentIndex < comments.length) {
-        index = line.indexOf(comments[commentIndex])
+        const index = line.indexOf(comments[commentIndex])
         if (index !== -1) line = line.slice(0, index)
       }
 
@@ -47,6 +59,7 @@ export function toJson(value, options = {}) {
     // Transform `value` to a property--value tuple.
     function (value) {
       const values = value.split(delimiter)
+      /** @type {[string, undefined|string]} */
       // @ts-expect-error: always one.
       const result = [values.shift().trim()]
 
@@ -124,8 +137,8 @@ export function toJson(value, options = {}) {
 
 /**
  * Sort on the first (`0`) index.
- * @param {Array<string>} a
- * @param {Array<string>} b
+ * @param {[string, undefined|string]} a
+ * @param {[string, undefined|string]} b
  */
 function sortOnFirstIndex(a, b) {
   // @ts-expect-error: never empty

readme.md

@@ -5,73 +5,136 @@
 [![Downloads][downloads-badge]][downloads]
 [![Size][size-badge]][size]
 
-Transform a “database” / basic (word, phrase) list from plain text to JSON.
+Transform basic plain-text lists or objects into arrays and objects.
+
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`toJson(value[, options])`](#tojsonvalue-options)
+*   [Data](#data)
+    *   [Comments](#comments)
+    *   [Whitespace](#whitespace)
+    *   [Empty lines](#empty-lines)
+    *   [Key/value pairs](#keyvalue-pairs)
+    *   [Values](#values)
+    *   [Errors](#errors)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Contribute](#contribute)
+*   [Security](#security)
+*   [License](#license)
+
+## What is this?
+
+This package takes a file (a sort of simple database), parses it, and returns
+clean data.
+
+## When should I use this?
+
+I found myself rewriting a simple transformation over and over to handle text
+files.
+One example is this source file in [`emoji-emotion`][emoji-emotion-example]
+This project fixes that for me.
+You can use it too if it matches your needs.
 
 ## Install
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
-
-[npm][]:
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
 ```sh
 npm install plain-text-data-to-json
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {toJson} from 'https://esm.sh/plain-text-data-to-json@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {toJson} from 'https://esm.sh/plain-text-data-to-json@2?bundle'
+</script>
+```
+
 ## Use
 
+If we have the following file `input.txt`:
+
+```txt
+% A comment
+
+alpha
+bravo
+charlie
+```
+
+…and our module `example.js` looks as follows:
+
 ```js
-import fs from 'fs'
+import fs from 'node:fs/promises'
 import {toJson} from 'plain-text-data-to-json'
 
-var doc = fs.readFileSync('input.txt', 'utf8')
+const document = String(await fs.readFile('input.txt'))
+
+const data = toJson(document)
 
-var data = toJson(doc)
+await fs.writeFile('output.json', JSON.stringify(data, null, 2) + '\n')
+```
+
+…then running `node example.js` yields in `output.json`:
 
-fs.writeFileSync('output.json', JSON.stringify(data, null, 2) + '\n')
+```json
+[
+  "alpha",
+  "bravo",
+  "charlie"
+]
 ```
 
 ## API
 
-This package exports the following identifiers: `toJson`.
+This package exports the identifier `toJson`.
 There is no default export.
 
 ### `toJson(value[, options])`
 
-Transforms the given value (string) to JSON.
-Don’t like the default comment and property-value pair delimiters?
-Specify your own:
+Transform basic plain-text lists or objects into arrays and objects.
 
 ##### `options`
 
-###### `options.comment`
-
-Character(s) to use for line-comments, `false` turns off comments (`string`,
-`Array<string>`, or `boolean`, default: `'%'`)
+Configuration (optional).
 
 ###### `options.delimiter`
 
-Character to use as delimiter between property-value pairs (`string`, default:
-`':'`)
+Character to use as delimiter between key/value pairs (`string`, default:
+`':'`).
+
+###### `options.comment`
+
+Character(s) to use for line comments, `false` turns off comments (`string`,
+`Array<string>`, or `boolean`, default: `'%'`)
 
 ###### `options.forgiving`
 
 How relaxed to be (`'fix'` or `boolean`, default: `false`).
 When `true`, doesn’t throw for duplicate keys.
-When `'fix'`, doesn’t throw for property-value pairs and overwrites (see
+When `'fix'`, doesn’t throw for key/value pairs and overwrites (see
 [errors][]).
 
 ###### `options.log`
 
-Whether to log when `forgiving` ignores an error (`boolean`, default: `true`).
+Whether to call `console.log` with info when `forgiving` ignores an error
+(`boolean`, default: `true`).
 
-## Why
-
-I found myself rewriting a simple transformation over and over.
-This (verbosely named) project fixes that.
-It might not be useful, or too simple for others, but suites my use cases.
-
-## “Plain text”
+## Data
 
 The term plain text might be confusing.
 It’s actually more of some (sparingly specified) standard.
@@ -109,7 +172,7 @@ Yields:
 ### Empty lines
 
 Empty lines are striped.
-This includes blank (whitespace only) lines.
+This includes whitespace only lines.
 
 ```txt
     %%% this file contains a value. %%%
@@ -123,7 +186,7 @@ Yields:
 ['unicorn']
 ```
 
-### Property-value pairs
+### Key/value pairs
 
 If a line includes a colon (by default), the library returns an object.
 
@@ -155,12 +218,32 @@ Yields:
 
 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
+*   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"`)
 
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type `Options`.
+
+## Compatibility
+
+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.
+
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
+## Security
+
+This package is safe.
+
 ## License
 
 [MIT][license] © [Titus Wormer][author]
@@ -185,8 +268,18 @@ Some errors are thrown when malformed “plain-text” is found, such as:
 
 [npm]: https://docs.npmjs.com/cli/install
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
+[contribute]: https://opensource.guide/how-to-contribute/
+
 [license]: license
 
 [author]: https://wooorm.com
 
 [errors]: #errors
+
+[emoji-emotion-example]: https://github.com/words/emoji-emotion/blob/main/faces.txt