soml-lang 0.0.2 → 0.0.4

package/distribution/stringify.js

@@ -1,4 +1,4 @@
-import { MAX_DEPTH, INT64_MIN, INT64_MAX, MIN_INSTANT, MAX_INSTANT, DURATION_UNITS, trimTrailingZeros, validateIntegersOption, requireTemporal, isBareKey, abbreviate, } from "./shared.js";
+import { MAX_DEPTH, INT64_MIN, INT64_MAX, MIN_INSTANT, MAX_INSTANT, DURATION_UNITS, trimTrailingZeros, getIntegersOption, requireTemporal, isBareKey, abbreviate, } from "./shared.js";
 const dateTime = Date.prototype.getTime;
 const durationField = (name) => Object.getOwnPropertyDescriptor(Temporal.Duration.prototype, name).get;
 const durationSizes = DURATION_UNITS.values().toArray();
@@ -19,26 +19,29 @@ const NEEDS_ESCAPED_STRING = /[\u{0}-\u{1F}'\u{7F}]/v;
 const NEEDS_ATTENTION = /[\u{0}-\u{1F}'\u{7F}\u{D800}-\u{DFFF}]/v;
 // eslint-disable-next-line no-control-regex, regexp/no-control-character -- Control characters are exactly what must be escaped.
 const ESCAPED_CHARACTER = /[\u{0}-\u{1F}"\\\u{7F}]/gv;
-const ESCAPES = {
-    '\\': '\\\\',
-    '"': String.raw `\"`,
-    '\n': String.raw `\n`,
-    '\t': String.raw `\t`,
-};
+// A map rather than an object, so that a property added to `Object.prototype` is never written as an escape.
+const ESCAPES = new Map([
+    ['\\', '\\\\'],
+    ['"', String.raw `\"`],
+    ['\n', String.raw `\n`],
+    ['\t', String.raw `\t`],
+]);
 /**
-Serialize an object or an array to canonical form.
+Serialize an object or an array to SOML. Nesting is written with braces and tabs, and the output ends with one line feed. Comments and block strings are never written.
 
-Canonical form is unique for a value: two equal values produce the same bytes, so the output can be hashed, signed, or compared. Members are sorted by key, and 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` 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.
 
-A `Date` is accepted and written as an instant. A member whose value is `undefined` is left out.
+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.
 
 @param value - A plain object or an array.
-@param options - How to write ints.
-@returns The canonical form, ending with one line feed.
-@throws {TypeError} When the value contains something that cannot be represented, such as `NaN`, a function, a class instance, an invalid `Date`, a `Temporal.Duration` with years, months, weeks, or days, a circular reference, or a string or key with a lone surrogate or a carriage return. Also when `options.integers` is not `'bigint'` or `'number'`.
-@throws {RangeError} When an int is outside the 64-bit range, an instant is outside the years 0001 to 9999, a duration is outside the 64-bit range of nanoseconds, or the value is nested more than 100 levels deep.
+@param options - How an int is represented in `value`, and whether to sort members.
+@returns The document, ending with one line feed.
+@throws {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 {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.
 
 @example
 ```
@@ -46,26 +49,97 @@ import {stringify} from 'soml-lang';
 
 stringify({name: 'api-gateway', replicas: 3n, timeout: 30});
 //=> "name: 'api-gateway'\nreplicas: 3\ntimeout: 30.0\n"
+
+stringify({port: 8080}, {integers: 'number'});
+//=> 'port: 8080\n'
+
+stringify({name: 'api', description: 'The edge service'}, {canonical: true});
+//=> "description: 'The edge service'\nname: 'api'\n"
 ```
 */
 // `object` rather than `Record<string, unknown>`, so that a value typed with an interface is accepted too. The value is checked at runtime.
-export function stringify(value, options = {}) {
-    const { integers = 'bigint' } = options;
-    validateIntegersOption(integers);
+export function stringify(value, options) {
     if (!Array.isArray(value) && !isPlainObject(value)) {
         throw new TypeError(`The top-level value must be an object or an array, because a document is a collection. Got ${describeType(value)}`);
     }
-    return new Writer(integers).writeDocument(value);
+    return new Writer(getStringifyOptions(options)).writeDocument(value);
+}
+/**
+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()` to write a whole document, and `edit()` to change a value in one.
+
+It takes the same values and options 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.
+
+@param value - A value of any type that `stringify()` accepts in a document.
+@param options - How an int is represented in `value`, and whether to sort members.
+@returns The value as it is written in a document.
+@throws {TypeError} For a value that cannot be represented, as for `stringify()`, and for `undefined`.
+@throws {RangeError} For a value out of range, as for `stringify()`.
+
+@example
+```
+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}'
+```
+*/
+export function stringifyValue(value, options) {
+    return new Writer(getStringifyOptions(options)).writeValue(value, 1, '');
+}
+/**
+One value as `stringifyValue()` writes it, for `edit()`. A container's own depth is `depth`, and its lines after the first are indented by `indent`, so the value fits where it is written. With `isOneLine`, a container is written on one line instead, as in `[1, {a: 2}]`, for a value inside a container that is on one line.
+
+@internal
+*/
+export function stringifyValueAt(value, { depth, indent, isOneLine, ...options }) {
+    return new Writer(options, isOneLine).writeValue(value, depth, indent);
+}
+/**
+The options of `stringify()`, `stringifyValue()`, and `edit()`, checked, with the defaults for those that are left out.
+
+@internal
+*/
+export function getStringifyOptions(options) {
+    const integers = getIntegersOption(options);
+    const { canonical = false } = (options ?? {});
+    if (typeof canonical !== 'boolean') {
+        throw new TypeError(`The \`canonical\` option must be a boolean, got ${canonical === null ? 'null' : typeof canonical}`);
+    }
+    return { integers, canonical };
 }
 /*
 Appends to one array of parts that is joined once at the end, so the time is linear in the output whatever the nesting. A scalar and its line are one part.
 */
 class Writer {
     #integers;
+    #isCanonical;
+    #isOneLine;
     #ancestors = new Set();
     #parts = [];
-    constructor(integers) {
+    constructor({ integers, canonical }, isOneLine = false) {
         this.#integers = integers;
+        this.#isCanonical = canonical;
+        this.#isOneLine = isOneLine;
+    }
+    /*
+    What comes before the item at `index` in a container whose items are indented by `indent`: a comma and a space after the first item on one line, and otherwise the indentation of a new line.
+    */
+    #itemPrefix(index, indent) {
+        if (this.#isOneLine) {
+            return index === 0 ? '' : ', ';
+        }
+        return indent;
     }
     /*
     Writes `prefix`, the value, and `suffix`. A container's own depth is `depth`, and its lines are indented by `indent`.
@@ -102,7 +176,7 @@ class Writer {
                 break;
             }
             default: {
-                throw new TypeError(`Cannot serialize ${describeType(value)}${key === undefined ? '' : ` at key "${abbreviate(key)}"`}`);
+                throw new TypeError(`Cannot serialize ${describeType(value)}${key === undefined ? '' : ` at key “${abbreviate(key)}”`}`);
             }
         }
         if (value === null) {
@@ -142,64 +216,81 @@ class Writer {
         this.#enter(value, depth);
         const parts = this.#parts;
         const innerIndent = `${indent}\t`;
+        const lineEnd = this.#isOneLine ? '' : '\n';
+        const closingIndent = this.#isOneLine ? '' : indent;
         if (Array.isArray(value)) {
-            if (value.length === 0) {
+            // The length is read once, as `JSON.stringify()` does, so a getter that adds items cannot make it go on forever.
+            const { length } = value;
+            if (length === 0) {
                 parts.push('[]');
             }
             else {
-                parts.push('[\n');
-                for (const [index, item] of value.entries()) {
+                parts.push(`[${lineEnd}`);
+                for (let index = 0; index < length; index++) {
+                    const item = value[index];
                     // A hole reads as `undefined`, and both would otherwise have to be guessed into something.
                     if (item === undefined) {
                         throw new TypeError(`Cannot serialize undefined in an array, at index ${index}`);
                     }
-                    this.#writeItem(innerIndent, item, depth + 1, innerIndent, ',\n');
+                    this.#writeItem(this.#itemPrefix(index, innerIndent), item, depth + 1, innerIndent, lineEnd);
                 }
-                parts.push(`${indent}]`);
+                parts.push(`${closingIndent}]`);
             }
         }
         else {
-            const members = sortedMembers(value);
+            const members = readMembers(value, this.#isCanonical);
             if (members.length === 0) {
                 parts.push('{}');
             }
             else {
-                parts.push('{\n');
-                for (const [key, member] of members) {
-                    this.#writeItem(`${innerIndent}${formatKey(key)}: `, member, depth + 1, innerIndent, ',\n', key);
-                }
-                parts.push(`${indent}}`);
+                parts.push(`{${lineEnd}`);
+                this.#writeMembers(members, depth + 1, innerIndent);
+                parts.push(`${closingIndent}}`);
             }
         }
         this.#ancestors.delete(value);
     }
+    #writeMembers(members, depth, indent) {
+        const lineEnd = this.#isOneLine ? '' : '\n';
+        for (const [index, [key, member]] of members.entries()) {
+            this.#writeItem(`${this.#itemPrefix(index, indent)}${formatKey(key)}: `, member, depth, indent, lineEnd, key);
+        }
+    }
+    writeValue(value, depth, indent) {
+        this.#writeItem('', value, depth, indent, '');
+        return this.#parts.join('');
+    }
     writeDocument(value) {
         if (Array.isArray(value)) {
             this.#writeContainer(value, 1, '');
             this.#parts.push('\n');
             return this.#parts.join('');
         }
-        this.#enter(value, 1);
-        const members = sortedMembers(value);
-        for (const [key, member] of members) {
-            this.#writeItem(`${formatKey(key)}: `, member, 2, '', '\n', key);
+        const members = readMembers(value, this.#isCanonical);
+        // A brace-less object needs at least one entry, so the empty object keeps its braces, like an array. It is written from the members already read, because reading them again would call each getter twice, and one that returns a value the second time would give a braced object that is not canonical.
+        if (members.length === 0) {
+            this.#parts.push('{}\n');
         }
-        this.#ancestors.delete(value);
-        // A brace-less object needs at least one entry, so the empty object keeps its braces.
-        return members.length === 0 ? '{}\n' : this.#parts.join('');
+        else {
+            this.#enter(value, 1);
+            this.#writeMembers(members, 2, '');
+        }
+        return this.#parts.join('');
     }
 }
 /*
-The members to write, sorted by key, with each value read once. A member whose value is `undefined` is left out, as `JSON.stringify` does.
+The members to write, with each value read once, sorted by key when `isCanonical` is true and otherwise in the object's own order. A member whose value is `undefined` is left out, as `JSON.stringify` does.
 */
-function sortedMembers(object) {
+function readMembers(object, isCanonical) {
     const keys = Object.keys(object);
-    // The default sort compares UTF-16 code units, which matches code point order unless a key has a code unit from U+D800 up.
-    if (keys.some(key => HIGH_CODE_UNIT.test(key))) {
-        keys.sort(compareCodePoints);
-    }
-    else {
-        keys.sort(); // The native string order is the point, and it is much faster than a comparator.
+    if (isCanonical) {
+        // The default sort compares UTF-16 code units, which matches code point order unless a key has a code unit from U+D800 up.
+        if (keys.some(key => HIGH_CODE_UNIT.test(key))) {
+            keys.sort(compareKeys);
+        }
+        else {
+            keys.sort(); // The native string order is the point, and it is much faster than a comparator.
+        }
     }
     const members = [];
     for (const key of keys) {
@@ -221,9 +312,6 @@ function describeType(value) {
     if (value === null) {
         return 'null';
     }
-    if (typeof value === 'number' && Number.isNaN(value)) {
-        return 'NaN, which is not representable';
-    }
     if (typeof value === 'function') {
         return 'a function';
     }
@@ -233,10 +321,25 @@ function describeType(value) {
     }
     return value === undefined ? 'undefined' : `a ${typeof value}`;
 }
-/*
-Members are sorted by the Unicode scalar values of their keys. `Array#sort` compares UTF-16 code units, which orders U+E000 to U+FFFF after every astral character, so the code units are compared with surrogates moved above that range.
+/**
+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.
+
+@param left - A key.
+@param right - Another key.
+@returns A negative number when `left` comes first, a positive number when `right` comes first, and `0` when they are equal.
+
+@example
+```
+import {compareKeys} from 'soml-lang';
+
+['b', 'a', '😀', 'ff'].toSorted(compareKeys);
+//=> ['a', 'b', 'ff', '😀']
+```
 */
-function compareCodePoints(left, right) {
+export function compareKeys(left, right) {
+    // The code units are compared with the surrogates moved above U+E000 to U+FFFF, which gives code point order.
     const length = Math.min(left.length, right.length);
     for (let index = 0; index < length; index++) {
         let leftCode = left.charCodeAt(index);
@@ -260,7 +363,7 @@ function toCodePointOrder(code) {
     }
     return code >= 0xD8_00 ? code + 0x20_00 : code;
 }
-function formatKey(key) {
+export function formatKey(key) {
     return isBareKey(key) ? key : formatString(key, 'key');
 }
 function formatString(string, kind) {
@@ -274,7 +377,7 @@ function formatString(string, kind) {
     if (string.includes('\r')) {
         throw new TypeError(`Cannot serialize a ${kind} containing a carriage return (U+000D), which is not representable`);
     }
-    return NEEDS_ESCAPED_STRING.test(string) ? `"${string.replaceAll(ESCAPED_CHARACTER, character => ESCAPES[character] ?? String.raw `\u{${character.codePointAt(0).toString(16)}}`)}"` : `'${string}'`;
+    return NEEDS_ESCAPED_STRING.test(string) ? `"${string.replaceAll(ESCAPED_CHARACTER, character => ESCAPES.get(character) ?? String.raw `\u{${character.codePointAt(0).toString(16)}}`)}"` : `'${string}'`;
 }
 function formatInteger(value) {
     if (value < INT64_MIN || value > INT64_MAX) {
@@ -345,15 +448,26 @@ function formatDuration(duration) {
         text += `${minutes}m`;
     }
     if (seconds > 0n || fraction > 0n) {
-        // The fraction is written like an instant's: nine digits with the trailing zeros removed.
-        text += fraction === 0n ? `${seconds}s` : `${seconds}.${trimTrailingZeros(String(fraction).padStart(9, '0'))}s`;
+        text += `${seconds}${formatFraction(fraction)}s`;
     }
     return text;
 }
+/*
+`Date#toISOString()` writes the date and the time of day exactly for every instant that a `Date` or a `Temporal.Instant` can hold, so a `Date` needs no `Temporal`. Only the fraction comes from the nanoseconds.
+*/
 function formatInstant(nanoseconds) {
-    const instant = new (requireTemporal().Instant)(nanoseconds);
+    // The fraction is never negative, so an instant before 1970 is a whole second plus a fraction, as it is written.
+    const fraction = ((nanoseconds % 1000000000n) + 1000000000n) % 1000000000n;
+    const milliseconds = Number((nanoseconds - fraction) / 1000000n);
+    const text = `${new Date(milliseconds).toISOString().slice(0, -'.000Z'.length)}${formatFraction(fraction)}Z`;
     if (nanoseconds < MIN_INSTANT || nanoseconds > MAX_INSTANT) {
-        throw new RangeError(`Cannot serialize the instant ${instant.toString()}, because it is outside the years 0001 to 9999`);
+        throw new RangeError(`Cannot serialize the instant ${text}, because it is outside the years 0001 to 9999`);
     }
-    return instant.toString();
+    return text;
+}
+/*
+The fraction of a second, from its nanoseconds, as canonical form writes it for an instant and a duration: nothing when it is zero, and otherwise a `.` and nine digits with the trailing zeros removed.
+*/
+function formatFraction(nanoseconds) {
+    return nanoseconds === 0n ? '' : `.${trimTrailingZeros(String(nanoseconds).padStart(9, '0'))}`;
 }

package/distribution/tree.d.ts

@@ -2,14 +2,26 @@
 A position in the source: a 1-based line, and a 0-based column in UTF-16 code units, as in ESTree.
 */
 export type Position = {
+    /**
+    The 1-based line.
+    */
     readonly line: number;
+    /**
+    The 0-based column, in UTF-16 code units.
+    */
     readonly column: number;
 };
 /**
 Where a node, token, or comment is in the source.
 */
 export type SourceLocation = {
+    /**
+    The position of the first character.
+    */
     readonly start: Position;
+    /**
+    The position after the last character.
+    */
     readonly end: Position;
 };
 type Located<Type extends string> = {
@@ -18,12 +30,15 @@ type Located<Type extends string> = {
     The start and end, as UTF-16 offsets into the text.
     */
     readonly range: readonly [start: number, end: number];
+    /**
+    The start and end, as lines and columns.
+    */
     readonly loc: SourceLocation;
 };
 /**
 A token. `value` is its source text.
 
-A `Punctuator` is one of `{`, `}`, `[`, `]`, `:`, `,`, and `.`. A `Keyword` is `true`, `false`, or `null`. `infinity` and `-infinity` are `Float` tokens.
+A `Punctuator` is one of `{`, `}`, `[`, `]`, `:`, and `,`. A `Keyword` is `true`, `false`, or `null`. `infinity` and `-infinity` are `Float` tokens, and a quoted key is a `String` token.
 */
 export type Token = Located<'Punctuator' | 'BareKey' | 'String' | 'Integer' | 'Float' | 'Keyword' | 'Instant' | 'Duration'> & {
     readonly value: string;
@@ -38,6 +53,9 @@ export type Comment = Located<'Line' | 'Block'> & {
 The root of a tree.
 */
 export type DocumentNode = Located<'Document'> & {
+    /**
+    The document's collection, an object or an array.
+    */
     readonly body: ObjectNode | ArrayNode;
     /**
     Every token, in source order, without comments.
@@ -48,60 +66,144 @@ export type DocumentNode = Located<'Document'> & {
     */
     readonly comments: readonly Comment[];
 };
+/**
+An object, written with braces or as a top-level object without them.
+*/
 export type ObjectNode = Located<'Object'> & {
+    /**
+    The members, in source order.
+    */
     readonly members: readonly MemberNode[];
     /**
     `false` only for a top-level object written without braces.
     */
     readonly braced: boolean;
 };
+/**
+A `key: value` member of an object.
+*/
 export type MemberNode = Located<'Member'> & {
+    /**
+    The key.
+    */
     readonly key: KeyNode;
+    /**
+    The value after the `:`.
+    */
     readonly value: ValueNode;
 };
+/**
+An array, with its items in `elements`.
+*/
 export type ArrayNode = Located<'Array'> & {
+    /**
+    The items, in source order.
+    */
     readonly elements: readonly ValueNode[];
 };
 /**
-A key, with more than one segment when it is dotted.
+A key.
 */
 export type KeyNode = Located<'Key'> & {
-    readonly segments: readonly KeySegmentNode[];
-};
-export type KeySegmentNode = Located<'KeySegment'> & {
     /**
     The decoded key.
     */
     readonly value: string;
+    /**
+    How the key is written: bare, as `'...'`, or as `"..."`.
+    */
     readonly style: 'bare' | 'literal' | 'escaped';
 };
+/**
+A string, written as `'...'`, `"..."`, or a block string.
+*/
 export type StringNode = Located<'String'> & {
     /**
     The decoded string.
     */
     readonly value: string;
+    /**
+    Whether the string is written with `'` (literal) or `"` (escaped).
+    */
     readonly style: 'literal' | 'escaped';
     /**
     Whether it is a block string.
     */
     readonly block: boolean;
 };
+/**
+An int, in any radix.
+*/
 export type IntegerNode = Located<'Integer'> & {
+    /**
+    The value, which is always a `bigint`.
+    */
     readonly value: bigint;
+    /**
+    The radix it is written in: `2` for `0b`, `8` for `0o`, `16` for `0x`, and otherwise `10`.
+    */
     readonly radix: 2 | 8 | 10 | 16;
 };
+/**
+A float, including `infinity` and `-infinity`.
+*/
 export type FloatNode = Located<'Float'> & {
+    /**
+    The value, including `Infinity` and `-Infinity`.
+    */
     readonly value: number;
 };
+/**
+`true` or `false`.
+*/
 export type BooleanNode = Located<'Boolean'> & {
+    /**
+    The value.
+    */
     readonly value: boolean;
 };
+/**
+The `null` keyword, which has no fields of its own.
+*/
 export type NullNode = Located<'Null'>;
+/**
+An instant, such as `2026-09-19T14:00:00Z`.
+*/
 export type InstantNode = Located<'Instant'> & {
+    /**
+    Made when it is first read, so that only reading it needs `Temporal`. Spreading or serializing the node reads it too.
+    */
     readonly value: Temporal.Instant;
 };
+/**
+One part of a duration, such as `30m` in `1h30m`.
+*/
+export type DurationPart = {
+    /**
+    The number as it is written, with any `_` and fraction, such as `1_000` or `1.5`.
+    */
+    readonly number: string;
+    /**
+    The unit.
+    */
+    readonly unit: 'h' | 'm' | 's' | 'ms' | 'us' | 'ns';
+};
+/**
+A duration, such as `1h30m`.
+*/
 export type DurationNode = Located<'Duration'> & {
+    /**
+    Made when it is first read, so that only reading it needs `Temporal`. Spreading or serializing the node reads it too.
+    */
     readonly value: Temporal.Duration;
+    /**
+    Whether it is written with a `-`, which negates the whole duration.
+    */
+    readonly negative: boolean;
+    /**
+    The parts as they are written, in order. So `-1h30m` is `negative` with the parts `1` `h` and `30` `m`.
+    */
+    readonly parts: readonly DurationPart[];
 };
 /**
 A node that is a value.
@@ -110,9 +212,9 @@ export type ValueNode = ObjectNode | ArrayNode | StringNode | IntegerNode | Floa
 /**
 Any node in a tree.
 */
-export type Node = DocumentNode | MemberNode | KeyNode | KeySegmentNode | ValueNode;
+export type Node = DocumentNode | MemberNode | KeyNode | ValueNode;
 /**
-The properties of each node type that hold its child nodes, in source order. For tools that walk the tree, such as an ESLint language plugin.
+The properties of each node type that hold its child nodes, in source order, for tools that walk the tree, such as an ESLint language plugin.
 
 @example
 ```
@@ -127,9 +229,9 @@ visitorKeys.Integer;
 */
 export declare const visitorKeys: Readonly<Record<Node['type'], readonly string[]>>;
 /**
-Parse a document into a syntax tree, for tools such as linters and formatters.
+Parse a document into a syntax tree, for tools such as linters and formatters. Returns a `Document` node, which also holds every token and comment.
 
-Every node, token, and comment has a `range` and a `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. A `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 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.
 
 @param text - The document.
 @returns The root node, which also holds every token and comment.