soml-lang 0.0.2 → 0.0.3

package/readme.md

@@ -1,16 +1,17 @@
 # soml
 
-> The reference parser, canonical serializer, and formatter for [SOML](../soml/readme.md), a config format for humans
+> The reference parser, serializer with canonical form, and formatter for [SOML](https://soml.sh), a config format for humans
 
 > [!NOTE]
-> The format is a draft. See the [specification](../soml/spec.md).
+> The format is a draft. See the [specification](https://github.com/soml-lang/soml/blob/main/spec.md).
 
 - Strict: every rule in the specification is enforced, and every error says what is wrong and where
 - Exact: an int is a `bigint`, so every 64-bit int survives, and `3` and `3.0` stay different
-- Canonical: `stringify()` writes the one canonical form, so equal values give equal bytes
-- Safe: no prototype pollution, define semantics for every object member even with a frozen or modified `Object.prototype`, no stack overflow on deep input or on huge tokens, and `parse()` takes linear time on every input shape
-- Fast: parses about 1.7 times as fast as smol-toml and 7 times as fast as json5
-- Tested by a language-neutral [conformance suite](test/conformance) of almost 900 cases, plus property tests and fuzzing
+- Canonical: `stringify()` keeps the member order of its input for people to read, and with `canonical: true` it writes the one canonical form, so equal values give equal bytes
+- Lossless: `format()` and `edit()` keep comments, member order, and the spelling of every value they do not change
+- Safe: no prototype pollution, every object member is created as an own property even when `Object.prototype` is frozen or changed, no stack overflow on deep input or on huge tokens, and `parse()`, `parseTree()`, `format()`, `edit()`, and `stringify()` take linear time on every input shape
+- Fast: parses about 1.5 times as fast as smol-toml and 7 times as fast as json5
+- Tested by a language-neutral [conformance suite](test/conformance) of more than 900 cases, plus property tests and fuzzing
 
 ## Install
 
@@ -18,13 +19,15 @@
 npm install soml-lang
 ```
 
-Requires Node.js 22 or later. Instants and durations use `Temporal`, which Node.js 26 and later have built in. On older versions, everything else works, but an instant, a duration, or a `Date` throws. To use them, load a [`Temporal` polyfill](https://github.com/fullcalendar/temporal-polyfill) before you import this package:
+Requires Node.js 22 or later. Instants and durations use `Temporal`, which Node.js 26 and later have built in. On older versions, everything else works, including `format()`, `parseTree()`, and `edit()` on a document with instants and durations, but `parse()` of an instant or a duration, and reading the `value` of an `Instant` or `Duration` node throw. Spreading or serializing such a node reads its `value` too. To use them, load a [`Temporal` polyfill](https://github.com/fullcalendar/temporal-polyfill) before you import this package:
 
 ```js
 import 'temporal-polyfill/global';
 import {parse} from 'soml-lang';
 ```
 
+The types use the global `Temporal` types, so they need TypeScript 6 or later. They load its `esnext.temporal` lib themselves, so your `lib` setting does not need to include it.
+
 ## Usage
 
 ```js
@@ -43,20 +46,20 @@ postgres.host: 'db.internal'
 // 	name: 'api-gateway',
 // 	replicas: 3n,
 // 	timeout: 30,
-// 	grace: Temporal.Duration <PT1M30S>,
-// 	'deployed-at': Temporal.Instant <2026-09-19T14:00:00Z>,
+// 	grace: Temporal.Duration.from('PT1M30S'),
+// 	'deployed-at': Temporal.Instant.from('2026-09-19T14:00:00Z'),
 // 	postgres: {host: 'db.internal'},
 // }
 
 stringify(config);
-//=> `deployed-at: 2026-09-19T14:00:00Z
+//=> `name: 'api-gateway'
+// replicas: 3
+// timeout: 30.0
 // grace: 1m30s
-// name: 'api-gateway'
+// deployed-at: 2026-09-19T14:00:00Z
 // postgres: {
-// 	host: 'db.internal',
+// 	host: 'db.internal'
 // }
-// replicas: 3
-// timeout: 30.0
 // `
 ```
 
@@ -82,7 +85,7 @@ The specification says that a reader which conflates `3` and `3.0` is not confor
 With this mapping, two things always hold:
 
 - `parse(stringify(value))` deep-equals `value`, for a value made of the types `parse()` returns. (A `Date` comes back as a `Temporal.Instant`, a `Temporal.Duration` as the same length in hours and smaller units, `-0` as `0`, and an object with a null prototype as a plain object.)
-- `stringify(parse(text))` is the canonical form of `text`, and `stringify(parse(canonical)) === canonical`.
+- `stringify(parse(text), {canonical: true})` is the canonical form of `text`, and `stringify(parse(canonical), {canonical: true}) === canonical`. Without the option, the output differs from canonical form only in member order: members are in the order of `text`, except that integer-like keys, such as `404`, come first, in numeric order, as JavaScript enumerates them.
 
 ## API
 
@@ -90,7 +93,19 @@ With this mapping, two things always hold:
 
 Parse a document. Returns an object or an array, because a document is always a collection.
 
-Throws a [`ParseError`](#parseerror) when `text` is not a valid document, and a `TypeError` when `text` is not a string or a `Uint8Array`, or an option is invalid.
+Throws a [`ParseError`](#parseerror) when `text` is not a valid document, and a `TypeError` when `text` is not a string or a `Uint8Array`, or `options` is not an object or its `integers` is not `'bigint'` or `'number'`.
+
+```js
+import {parse} from 'soml-lang';
+
+parse(`
+name: 'api-gateway'
+replicas: 3
+timeout: 30.0
+postgres.host: 'db.internal'
+`);
+//=> {name: 'api-gateway', replicas: 3n, timeout: 30, postgres: {host: 'db.internal'}}
+```
 
 #### text
 
@@ -109,7 +124,8 @@ Default: `'bigint'`
 
 How an int is represented.
 
-With `'number'`, an int is a `number`, and an int outside `Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER` throws a `ParseError` rather than being rounded. `3` and `3.0` both become `3`, so this mode is convenient but not conforming.
+- `'bigint'`: Every int is a `bigint`, and every float is a `number`, so `3` and `3.0` stay different, and every 64-bit int is exact. This is the only conforming mode.
+- `'number'`: Every int is a `number`. An int outside `Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER` throws a `ParseError` rather than being rounded. `3` and `3.0` both become `3`, so `stringify()` cannot tell them apart afterwards.
 
 ```js
 parse('port: 8080', {integers: 'number'});
@@ -134,7 +150,7 @@ tree.comments[0];
 //=> {type: 'Line', value: ' The default', range: [11, 24], loc: {…}}
 ```
 
-Every node, token, and comment has a `range`, which is `[start, end]` as UTF-16 offsets into `text`, and a `loc`, which is `{start: {line, column}, end: {line, column}}`, with a 1-based line and a 0-based column in UTF-16 code units, as in [ESTree](https://github.com/estree/estree). A [`ParseError`](#parseerror) counts its column differently, for people to read, so use its `offset` to find the position in the tree.
+Every node, token, and comment has a `range`, which is `[start, end]` as UTF-16 offsets into `text`, and a `loc`, which is `{start: {line, column}, end: {line, column}}`, with a 1-based line and a 0-based column in UTF-16 code units, as in [ESTree](https://github.com/estree/estree). A [`ParseError`](#parseerror) counts its column differently, for people to read, so use its `offset` to find the position in the tree. A scalar node or a key segment shares its `range` and `loc` with its token, and other nodes, except `Document`, share the positions in `loc` with their first and last token, so treat them as read-only.
 
 | Node | Fields |
 |---|---|
@@ -149,10 +165,10 @@ Every node, token, and comment has a `range`, which is `[start, end]` as UTF-16
 | `Float` | `value`, including `Infinity` and `-Infinity` |
 | `Boolean` | `value` |
 | `Null` | |
-| `Instant` | `value`, a `Temporal.Instant` |
-| `Duration` | `value`, a `Temporal.Duration` |
+| `Instant` | `value`, a `Temporal.Instant`, made when it is first read, also by spreading or serializing the node |
+| `Duration` | `value`, a `Temporal.Duration`, made when it is first read, also by spreading or serializing the node; `negative`, whether it is written with a `-`; `parts`, each `{number, unit}` as written, so `-1h1.5m` has the parts `{number: '1', unit: 'h'}` and `{number: '1.5', unit: 'm'}` |
 
-A token is `{type, value, range, loc}`, where `type` is `'Punctuator'` (for `{`, `}`, `[`, `]`, `:`, `,`, and `.`), `'BareKey'`, `'String'`, `'Integer'`, `'Float'`, `'Keyword'` (for `true`, `false`, and `null`), `'Instant'`, or `'Duration'`, and `value` is its source text. A comment is `{type, value, range, loc}`, where `type` is `'Line'` or `'Block'`, and `value` is the text without `#`, or without `/*` and `*/`.
+A token is `{type, value, range, loc}`, where `type` is `'Punctuator'` (for `{`, `}`, `[`, `]`, `:`, `,`, and `.`), `'BareKey'`, `'String'`, `'Integer'`, `'Float'`, `'Keyword'` (for `true`, `false`, and `null`), `'Instant'`, or `'Duration'`, and `value` is its source text. `infinity` and `-infinity` are `'Float'` tokens, and a quoted key segment is a `'String'` token. A comment is `{type, value, range, loc}`, where `type` is `'Line'` or `'Block'`, and `value` is the text without `#`, or without `/*` and `*/`.
 
 ### visitorKeys
 
@@ -172,33 +188,148 @@ visitorKeys.Integer;
 
 Format a document. Returns the document with its layout normalized, ending with one line feed.
 
-The layout follows the [formatter](../soml/spec.md#formatting) in the specification: one tab per level, every member and item on its own line, a trailing comma after every member and item inside `{}` and `[]`, one space after `:`, and no trailing whitespace or runs of blank lines. Comments, member order, dotted keys, block strings, and the spelling of every value stay as they are, so the value never changes.
+The layout follows the [formatter](https://github.com/soml-lang/soml/blob/main/spec.md#formatting) in the specification: one tab per level, every member and item on its own line with no commas, and no trailing whitespace or runs of blank lines. An object or an array whose brackets are on one line stays on one line, as in `ports: [80, 443]`, with a comma and a space between its members or items. To give a one-line container one member or item per line, put a line break anywhere inside it. Comments, member order, dotted keys, block strings, and the spelling of every value stay as they are, so the value never changes. The one change inside a block comment is the same layout rule: trailing whitespace is removed, and runs of blank lines collapse to one.
 
 Throws the same [`ParseError`](#parseerror) as `parse()`, and a `TypeError` when `text` is not a string.
 
 ```js
 import {format} from 'soml-lang';
 
-format('pool: {min: 2, max: 16} # Connections');
-//=> 'pool: {\n\tmin: 2,\n\tmax: 16,\n} # Connections\n'
+format('pool: {min: 2,   max: 16,} # Connections');
+//=> 'pool: {min: 2, max: 16} # Connections\n'
+
+format('pool: {\nmin: 2, max: 16}');
+//=> 'pool: {\n\tmin: 2\n\tmax: 16\n}\n'
 ```
 
-Where the specification does not say, the formatter decides:
+In detail, as the specification states:
 
-- A comment at the end of a line stays at the end of that line, after the inserted comma. A block comment that a value follows on the same line, as in `[1, /* note */ 2]`, stays in front of that value.
-- A value on the line after its `key:` moves up to that line, unless a comment comes between them.
-- A block string moves with its closing delimiter, and its lines are not otherwise changed.
+- A block comment that a value follows on the same line, as in `1, /* note */ 2`, stays in front of that value when each item goes on its own line.
+- One space follows each `:`, as in canonical form.
+- A value on the line after its `key:` moves up to that line, unless a comment comes between them. Then it stays on its own line, one level deeper than the key, and the blank lines between them are removed.
+- A block string begins on the line after its key, and its delimiters and content have the indentation of that line. Its lines are not otherwise changed.
 - There are no blank lines at the start of the file or directly inside brackets.
 
-In the rare comma-first style, a comment after a comma on its own line moves to its own line when the item before it already ends with a comment.
+### formatEdits(text)
+
+The changes that [`format()`](#formattext) makes to a document, as edits of its text: an array of `{range: [start, end], text}`, with UTF-16 offsets into `text`. For an editor or a linter, which shows or applies each change where it is, rather than replacing the whole document.
+
+The edits are sorted, do not overlap, and change only spaces, tabs, line feeds, and commas, as `format()` does. Each one is as small as possible, so it leaves out the characters at its ends that stay the same. Applying all of them gives the same text as `format()`, and a document that is already formatted gives no edits.
+
+Throws the same errors as `format()`.
+
+```js
+import {formatEdits} from 'soml-lang';
+
+formatEdits('a: [1,\n2]\n');
+//=> [{range: [4, 4], text: '\n\t'}, {range: [5, 7], text: '\n\t'}, {range: [8, 8], text: '\n'}]
+```
+
+### edit(text, path, value, options?)
+
+Change one value in a document, and keep everything else as it is written: comments, member order, layout, and the spelling of every other value. For tools that update a config file, such as a dependency bumper or a `set` command.
+
+The value at `path` is replaced, or added when it does not exist yet, and an `undefined` value removes it. Only the changed part of the text is rewritten, and an edit to a formatted document leaves it formatted.
+
+```js
+import {edit} from 'soml-lang';
+
+edit('name: \'api\' # The service\nport: 8080\n', ['port'], 9090n);
+//=> "name: 'api' # The service\nport: 9090\n"
+
+edit('postgres.host: \'db\'\n', ['postgres', 'port'], 5432n);
+//=> "postgres.host: 'db'\npostgres.port: 5432\n"
+
+edit('a: 1\nb: 2\n', ['a'], undefined);
+//=> 'b: 2\n'
+```
+
+- A new value is written as `stringify()` writes it, at the indentation of its line. So `0xFF` that is replaced by `255n` becomes `255`, and `8080` becomes `8080.0` unless you pass `8080n` or the `integers: 'number'` option. The members of a new object keep their order, unless you pass the `canonical: true` option. In a container that is on one line, it is written on one line too, so `[1, 2]` with a new item `{a: 3n}` becomes `[1, 2, {a: 3}]`.
+- A new member goes after the last member of its object, or after the last member that shares its dotted prefix, as `postgres.port` after `postgres.host`. Missing objects on the way are created.
+- A new item can be added at the end of an array, with the index that is its length.
+- A new member or item goes on its own line without a comma, after the comments that the one before it owns (see below), and the commas of the other members and items stay as they are. When something follows the member or item before it on the same line, such as the closing bracket of the one-line container `{a: 1}`, it goes on that line after a comma, as in `{a: 1, b: 2}`. In an empty `[]` or `{}`, it goes on a line of its own, unless that container is inside a container on one line, so `a: [1, []]` becomes `a: [1, [2]]`.
+- A removed member or item takes the comments it owns, which are the ones that `format()` keeps with it: the comments after it on its line, also after its comma when nothing else follows there, and the block comments before it on its line, after the comma or bracket before it. So removing `2` from `[1, /* note */ 2]` gives `[1]`. A comment on a line of its own belongs to no member or item, so it stays. A removed member or item also removes its lines when nothing else is on them. A line that a block comment after it continues onto counts as one of its lines. Removing every item of a container closes it up to `[]` or `{}`, unless a comment is left inside.
+- A removed member or item takes its comma with it. When the removed items are the last ones and have no comma after them, they take the comma directly before them instead, when only spaces, tabs, and the comments they own are between, so `[1, 2]` becomes `[1]`.
+- Removing the last member under a dotted prefix, such as `a.b` when it is the only member that starts with `a.`, leaves `a: {}`, because the object `a` still exists. Removing the only member of a document without braces leaves `{}`.
+
+Comments inside a value that is replaced or removed are removed with it. In a layout that `format()` never writes, an edit can leave odd spacing, such as a new item after a closing block string delimiter on its line that is indented differently from its neighbors. The document is always valid and has the right value. Removing a value that does not exist changes nothing and is not an error: a missing member, a missing object or array on the way, or an index at or past the end of its array. So removing the same path twice is safe, and `edit(text, path, undefined) === text` tells whether something was removed.
+
+The result is parsed before it is returned, so a bug in `edit()` throws an `Error` rather than returning a broken document.
+
+Throws the same [`ParseError`](#parseerror) as `parse()` when `text` is not a valid document. Throws a `TypeError` when `text` is not a string, when `path` is not a non-empty array of keys and array indexes, when it leads through a value that is not an object or an array, or when it has a key where an array is or an index where an object is. Throws a `RangeError` when a value is set at an index past the end of its array, or at an index under a value that does not exist, or when the change would nest the document more than 100 levels deep. A `value` that cannot be represented or is out of range, and invalid `options`, throw as they do in `stringify()`.
+
+#### text
+
+Type: `string`
+
+The document.
+
+#### path
+
+Type: `Array<string | number>`
+
+The keys and array indexes that lead to the value, such as `['servers', 0, 'port']`. A dotted key is followed like the objects it builds, so `['postgres', 'host']` finds `postgres.host: 'db'`.
+
+#### value
+
+Type: `unknown`
+
+The new value, of the types that [`stringify()`](#stringifyvalue-options) accepts, or `undefined` to remove the value.
+
+#### options
+
+Type: `object`
+
+##### integers
+
+Type: `'bigint' | 'number'`\
+Default: `'bigint'`
+
+How an int is represented in `value`, as for [`stringify()`](#stringifyvalue-options).
+
+```js
+edit('port: 8080', ['port'], 9090, {integers: 'number'});
+//=> 'port: 9090'
+```
+
+##### canonical
+
+Type: `boolean`\
+Default: `false`
+
+Sort the members of every object in `value` by key, as for [`stringify()`](#stringifyvalue-options).
+
+```js
+edit('a: 1\n', ['b'], {y: 1n, x: 2n}, {canonical: true});
+//=> 'a: 1\nb: {\n\tx: 2\n\ty: 1\n}\n'
+```
 
 ### stringify(value, options?)
 
-Serialize an object or an array to canonical form. Members are sorted by key, nesting is written with braces and tabs, and the output ends with one line feed. Comments, dotted keys, and block strings are never written.
+Serialize an object or an array to SOML. Nesting is written with braces and tabs, and the output ends with one line feed. Comments, dotted keys, and block strings are never written.
+
+Members keep the order of `value`, which reads better in a file for people, and every other rule of canonical form is followed. With the [`canonical: true`](#canonical-1) option, members are sorted by key, and the output is canonical form: two equal values produce the same bytes, so it can be hashed, signed, or compared.
+
+JavaScript puts integer-like keys, such as `404` or `10`, before every other key, in numeric order, so their order in `value` cannot be kept.
+
+A `bigint` is written as an int and a `number` as a float, so `{port: 8080}` becomes `port: 8080.0`. Use `8080n`, or the `integers: 'number'` option.
+
+Besides the types that `parse()` returns, a `Date` is accepted and written as an instant, a `Temporal.Duration` is accepted when it has no years, months, weeks, or days, because those are not a fixed length, and a member whose value is `undefined` is left out, as `JSON.stringify` does.
+
+Throws a `TypeError` for a value that cannot be represented: `NaN`, a function, a symbol value, an object that is neither a plain object nor an array (such as a class instance or a `Map`), `undefined` in an array, a circular reference, a non-collection at the top level, an invalid `Date`, a `Temporal.Duration` with years, months, weeks, or days, an object that only claims to be a `Date`, a `Temporal.Instant`, or a `Temporal.Duration`, and a string or key with a lone surrogate or a carriage return. Also when `options` is not an object, its `integers` is not `'bigint'` or `'number'`, or its `canonical` is not a boolean. Throws a `RangeError` for an int outside the 64-bit range, an instant outside the years 0001 to 9999, a duration outside the 64-bit range of nanoseconds, and nesting deeper than 100 levels.
 
-Besides the types above, a `Date` is accepted and written as an instant, a `Temporal.Duration` is accepted when it has no years, months, weeks, or days, because those are not a fixed length, and a member whose value is `undefined` is left out, as `JSON.stringify` does.
+```js
+import {stringify} from 'soml-lang';
+
+stringify({name: 'api-gateway', replicas: 3n, timeout: 30});
+//=> "name: 'api-gateway'\nreplicas: 3\ntimeout: 30.0\n"
+```
 
-Throws a `TypeError` for a value that cannot be represented: `NaN`, a function, a symbol, a class instance, `undefined` in an array, a circular reference, a non-collection at the top level, an invalid `Date`, a `Temporal.Duration` with years, months, weeks, or days, an object that only claims to be a `Date`, a `Temporal.Instant`, or a `Temporal.Duration`, and a string or key with a lone surrogate or a carriage return. Throws a `RangeError` for an int outside the 64-bit range, an instant outside the years 0001 to 9999, a duration outside the 64-bit range of nanoseconds, and nesting deeper than 100 levels.
+#### value
+
+Type: `object`
+
+A plain object or an array.
 
 #### options
 
@@ -211,7 +342,8 @@ Default: `'bigint'`
 
 How an int is represented in `value`.
 
-With `'number'`, a `number` that is a safe integer is written as an int, and any other `number` as a float. A `bigint` is always written as an int.
+- `'bigint'`: A `bigint` is written as an int, and a `number` is always written as a float, so `8080` becomes `8080.0`.
+- `'number'`: A `number` that is a safe integer is written as an int, and any other `number` as a float. A `bigint` is still written as an int.
 
 ```js
 stringify({port: 8080});
@@ -221,9 +353,81 @@ stringify({port: 8080}, {integers: 'number'});
 //=> 'port: 8080\n'
 ```
 
+##### canonical
+
+Type: `boolean`\
+Default: `false`
+
+Write exact canonical form, with the members of every object sorted by key, for hashing, signing, or comparing.
+
+By default, members keep the order of `value`, which reads better in a file for people, and every other rule of canonical form is followed. JavaScript puts integer-like keys, such as `404` or `10`, before every other key, in numeric order, so their order in `value` cannot be kept.
+
+```js
+stringify({name: 'api', description: 'The edge service'});
+//=> "name: 'api'\ndescription: 'The edge service'\n"
+
+stringify({name: 'api', description: 'The edge service'}, {canonical: true});
+//=> "description: 'The edge service'\nname: 'api'\n"
+```
+
+### stringifyValue(value, options?)
+
+Serialize one value as it is written in a document: a scalar on one line, and an object or an array in braces or brackets over several lines, with each level indented by one more tab. There is no line feed at the end.
+
+For showing a value, as in a message, or for writing it into a template. Use [`stringify()`](#stringifyvalue-options) to write a whole document, and [`edit()`](#edittext-path-value-options) to change a value in one.
+
+It takes the same values and [options](#options-2) as `stringify()`, and any of them at the top level, so `1.5` gives `'1.5'` and `'it\'s'` gives `"it's"`. Members keep their order, as in `stringify()`, unless the `canonical: true` option sorts them. It throws as `stringify()` does, and a `TypeError` for `undefined`.
+
+```js
+import {stringifyValue} from 'soml-lang';
+
+stringifyValue(0.1 + 0.2);
+//=> '0.30000000000000004'
+
+stringifyValue(8080n);
+//=> '8080'
+
+stringifyValue({b: 1n, a: [true]});
+//=> '{\n\tb: 1\n\ta: [\n\t\ttrue\n\t]\n}'
+
+stringifyValue({b: 1n, a: [true]}, {canonical: true});
+//=> '{\n\ta: [\n\t\ttrue\n\t]\n\tb: 1\n}'
+```
+
+### compareKeys(left, right)
+
+Compare two keys in canonical order, which is by their Unicode scalar values, as `stringify()` sorts members with the `canonical: true` option. For a sort, such as in a lint rule that keeps the members of an object in canonical order.
+
+The default `Array#sort()` compares UTF-16 code units, which puts U+E000 to U+FFFF after every character above U+FFFF, so it differs from canonical order for keys that hold such characters.
+
+Returns a negative number when `left` comes first, a positive number when `right` comes first, and `0` when they are equal.
+
+```js
+import {compareKeys} from 'soml-lang';
+
+['b', 'a', '😀', 'ff'].toSorted(compareKeys);
+//=> ['a', 'b', 'ff', '😀']
+```
+
+### isBareKey(key)
+
+Whether a key can be written without quotes, as a bare key: one or more ASCII letters, digits, `_`, or `-`, in any order, so `404` and `-x` are bare keys too. `stringify()` writes such a key bare and quotes every other key.
+
+```js
+import {isBareKey} from 'soml-lang';
+
+isBareKey('content-type');
+//=> true
+
+isBareKey('a.b');
+//=> false
+```
+
 ### ParseError
 
-Thrown by `parse()`. Extends `SyntaxError`.
+Thrown when the input is not a valid document, by `parse()`, `parseTree()`, `format()`, and `edit()`. Extends `SyntaxError`.
+
+The `message` includes the position and a code frame. Use `reason` for the message alone.
 
 ```js
 import {parse, ParseError} from 'soml-lang';
@@ -235,7 +439,7 @@ try {
 		console.log(error.message);
 	}
 }
-// Unexpected "api-gateway". A string value must be quoted, as in 'api-gateway' at line 1, column 7
+// Unexpected “api-gateway”. A string value must be quoted, as in 'api-gateway' at line 1, column 7
 //
 // > 1 | name: api-gateway
 //     |       ^
@@ -251,19 +455,19 @@ What is wrong, without the position.
 
 Type: `number`
 
-The 1-based line.
+The 1-based line of the error.
 
 #### column
 
 Type: `number`
 
-The 1-based column, counted in Unicode code points.
+The 1-based column of the error, counted in Unicode code points.
 
 #### offset
 
 Type: `number`
 
-The 0-based UTF-16 index in the decoded text.
+The 0-based UTF-16 index of the error in the decoded text.
 
 #### codeFrame
 
@@ -273,16 +477,17 @@ Up to three lines ending at the error, with a caret under the position. A long l
 
 ## Limits
 
-- **Nesting is limited to 100 levels**, in `parse()` and in `stringify()`, as the spec requires: every document up to 100 levels is accepted, and every deeper one is rejected. The document's own collection is level 1, and a dotted key counts each segment.
+- **Nesting is limited to 100 levels**, as the spec requires: every document up to 100 levels is accepted, by `parse()`, `parseTree()`, `format()`, and `edit()`, and every deeper one is rejected. `stringify()` refuses a deeper value, and `edit()` refuses a change that would make one. The document's own collection is level 1, and a dotted key counts the objects it builds, so `a.b.c: 1` has a depth of 3, the same as `a: {b: {c: 1}}`.
 
 ## Conformance suite
 
 [`test/conformance`](test/conformance) holds the cases as plain files, so that another implementation can run them:
 
-- `valid/**/name.soml` must parse to the value in `name.json`, and serialize to exactly `name.canonical.soml`.
+- `valid/**/name.soml` must parse to the value in `name.json`, and serialize in canonical form, with members sorted by key, to exactly `name.canonical.soml`. An implementation that has a formatter must also format it to exactly `name.formatted.soml`.
 - `invalid/**/name.soml` must be rejected.
+- `edit/name.json` holds a formatted `document`, a `path`, a tagged `value`, which is left out for a removal, and the `expected` document. An implementation that has an editor must give exactly `expected` when it sets `path` to `value`, or removes it. A case with `error: true` instead of `expected` has a path that does not fit the document, and the change must fail.
 
-The expected values are tagged JSON, as in [toml-test](https://github.com/toml-lang/toml-test): `{"type": "int", "value": "3"}`. The types are `string`, `int`, `float`, `bool`, `null`, `instant`, and `duration`. A float's value is its canonical spelling, including `infinity` and `-infinity`, an instant's is its canonical UTC form, and a duration's is its length in nanoseconds as a decimal int. Case names differ in more than letter case, so the suite checks out on case-insensitive file systems.
+The expected values are tagged JSON, as in [toml-test](https://github.com/toml-lang/toml-test): `{"type": "int", "value": "3"}`. The types are `string`, `int`, `float`, `bool`, `null`, `instant`, and `duration`. A float's value is its canonical spelling, including `infinity` and `-infinity`, an instant's is its canonical UTC form, and a duration's is its length in nanoseconds as a decimal int. Case names differ in more than letter case, and none is a name that Windows reserves, such as `nul`, so the suite checks out on every file system.
 
 ## Benchmark
 
@@ -290,15 +495,17 @@ The expected values are tagged JSON, as in [toml-test](https://github.com/toml-l
 npm run bench
 ```
 
-The same 2.6 MB of config-shaped data on an Apple M-series machine with Node.js 26:
+The same 2.5 MB of config-shaped data on an Apple M-series machine with Node.js 26:
 
 | | parse | stringify |
 |---|---|---|
-| `JSON` | 570 MB/s | 650 MB/s |
-| this package | 155 MB/s | 118 MB/s |
-| smol-toml | 91 MB/s | 133 MB/s |
-| json5 | 22 MB/s | 80 MB/s |
+| `JSON` | 600 MB/s | 730 MB/s |
+| this package | 145 MB/s | 120 MB/s |
+| smol-toml | 100 MB/s | 135 MB/s |
+| json5 | 22 MB/s | 85 MB/s |
+
+A hand-written style document (comments, dotted keys, block strings, hex ints, instants) parses at about 110 MB/s, and minified one-line input at about 120 MB/s. The `stringify` figure is with `canonical: true`, which sorts every object's keys, a step smol-toml does not need. The default keeps member order and skips that step, so it is faster.
 
-A hand-written style document (comments, dotted keys, block strings, hex ints, instants) parses at about 120 MB/s, and so does minified one-line input. `stringify` sorts every object's keys, which smol-toml does not need to do.
+`parseTree()` runs at about 35 MB/s, and `format()` at about 20 to 25 MB/s, also on an already formatted document. Both are slower than `parse()`, because the tree has a node and a location for every token.
 
 `JSON` is native code and a much smaller grammar, so it is the ceiling rather than a competitor.