soml-lang 0.0.1 → 0.0.3

package/distribution/tree.js

@@ -0,0 +1,468 @@
+import { parseWithTimes, } from "./parse.js";
+import { isBareKeyCharacter, isSpace, findNumberEnd, findLineEnd, findBlockStringEnd, LF, DOUBLE_QUOTE, HASH, SINGLE_QUOTE, ASTERISK, COMMA, DOT, SLASH, BACKSLASH, OPEN_BRACKET, CLOSE_BRACKET, OPEN_BRACE, CLOSE_BRACE, } from "./shared.js";
+/**
+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
+```
+import {visitorKeys} from 'soml-lang';
+
+visitorKeys.Member;
+//=> ['key', 'value']
+
+visitorKeys.Integer;
+//=> []
+```
+*/
+/* eslint-disable @typescript-eslint/naming-convention -- The keys are node types. */
+export const visitorKeys = Object.freeze({
+    Document: Object.freeze(['body']),
+    Object: Object.freeze(['members']),
+    Member: Object.freeze(['key', 'value']),
+    Array: Object.freeze(['elements']),
+    Key: Object.freeze(['segments']),
+    KeySegment: Object.freeze([]),
+    String: Object.freeze([]),
+    Integer: Object.freeze([]),
+    Float: Object.freeze([]),
+    Boolean: Object.freeze([]),
+    Null: Object.freeze([]),
+    Instant: Object.freeze([]),
+    Duration: Object.freeze([]),
+});
+/* eslint-enable @typescript-eslint/naming-convention */
+/*
+`infinity` and `-infinity` are read as numbers, because they are floats.
+*/
+const KEYWORDS = ['true', 'false', 'null'];
+// A map rather than an object, so that a property added to `Object.prototype` is never read as an entry.
+const RADIX = new Map([['x', 16], ['o', 8], ['b', 2]]);
+/**
+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`, 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 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.
+
+@param text - The document.
+@returns The root node, which also holds every token and comment.
+@throws {ParseError} When the document is not valid, the same as `parse()`.
+@throws {TypeError} When `text` is not a string.
+
+@example
+```
+import {parseTree} from 'soml-lang';
+
+const tree = parseTree('port: 8080 # The default');
+
+tree.body.members[0].value;
+//=> {type: 'Integer', value: 8080n, radix: 10, range: [6, 10], loc: {…}}
+
+tree.comments[0];
+//=> {type: 'Line', value: ' The default', range: [11, 24], loc: {…}}
+```
+*/
+export function parseTree(text) {
+    if (typeof text !== 'string') {
+        throw new TypeError(`Expected a string, got ${text === null ? 'null' : typeof text}`);
+    }
+    // Validates the whole document, so the builder below can assume valid input.
+    parseWithTimes(text);
+    return new TreeBuilder(text).build();
+}
+/*
+The value of one scalar, read by the parser itself so that the tree and `parse()` cannot disagree. A scalar's validity does not depend on its context, so it parses on its own inside an array. An instant or a duration is a `Time`.
+*/
+function readScalar(raw) {
+    return parseWithTimes(`[${raw}]`)[0];
+}
+/*
+Every node is an object literal with the same property order, `type`, its own fields, `range`, and `loc`, rather than one generic function that spreads the fields, which is several times slower. A node that is one token, such as a scalar or a key segment, shares the token's `range` and `loc`.
+*/
+class TreeBuilder {
+    #source;
+    #index = 0;
+    #tokens = [];
+    #comments = [];
+    #lineStarts = [0];
+    // The line of the last offset looked up. Offsets mostly arrive in order, so it is the best first guess for the next one.
+    #line = 0;
+    constructor(source) {
+        this.#source = source;
+        for (let index = source.indexOf('\n'); index !== -1; index = source.indexOf('\n', index + 1)) {
+            this.#lineStarts.push(index + 1);
+        }
+    }
+    #code(offset = this.#index) {
+        return this.#source.charCodeAt(offset);
+    }
+    /*
+    1-based line, and 0-based column in UTF-16 code units, as in ESTree.
+    */
+    #position(offset) {
+        const lineStarts = this.#lineStarts;
+        // The binary search runs only when the offset is not on the line of the last one or the line after it, which makes building the tree about twice as fast.
+        if (this.#isOnLine(offset, this.#line + 1)) {
+            this.#line++;
+        }
+        else if (!this.#isOnLine(offset, this.#line)) {
+            let low = 0;
+            let high = lineStarts.length - 1;
+            while (low < high) {
+                const middle = Math.ceil((low + high) / 2);
+                if (lineStarts[middle] <= offset) {
+                    low = middle;
+                }
+                else {
+                    high = middle - 1;
+                }
+            }
+            this.#line = low;
+        }
+        return { line: this.#line + 1, column: offset - lineStarts[this.#line] };
+    }
+    #isOnLine(offset, line) {
+        const lineStarts = this.#lineStarts;
+        return line < lineStarts.length && lineStarts[line] <= offset && (line + 1 === lineStarts.length || lineStarts[line + 1] > offset);
+    }
+    #location(start, end) {
+        return { start: this.#position(start), end: this.#position(end) };
+    }
+    #token(type, start, end) {
+        const token = {
+            type,
+            value: this.#source.slice(start, end),
+            range: [start, end],
+            loc: this.#location(start, end),
+        };
+        this.#tokens.push(token);
+        return token;
+    }
+    #punctuator() {
+        this.#index++;
+        return this.#token('Punctuator', this.#index - 1, this.#index);
+    }
+    #skipTrivia() {
+        const source = this.#source;
+        for (;;) {
+            const code = this.#code();
+            const start = this.#index;
+            if (code === LF || isSpace(code)) {
+                this.#index++;
+            }
+            else if (code === HASH) {
+                this.#index = findLineEnd(source, start);
+                this.#comment('Line', start, this.#index, source.slice(start + 1, this.#index));
+            }
+            else if (code === SLASH && this.#code(start + 1) === ASTERISK) {
+                this.#index = source.indexOf('*/', start + 2) + 2;
+                this.#comment('Block', start, this.#index, source.slice(start + 2, this.#index - 2));
+            }
+            else {
+                return;
+            }
+        }
+    }
+    #comment(type, start, end, value) {
+        this.#comments.push({
+            type,
+            value,
+            range: [start, end],
+            loc: this.#location(start, end),
+        });
+    }
+    #bareObject() {
+        const members = [];
+        do {
+            members.push(this.#member());
+            this.#skipTrivia();
+        } while (this.#index < this.#source.length);
+        const first = members[0];
+        const last = members.at(-1);
+        return {
+            type: 'Object',
+            members,
+            braced: false,
+            range: [first.range[0], last.range[1]],
+            loc: spanLocation(first, last),
+        };
+    }
+    #object() {
+        const { items: members, opening, closing } = this.#items(CLOSE_BRACE, () => this.#member());
+        return {
+            type: 'Object',
+            members,
+            braced: true,
+            range: [opening.range[0], closing.range[1]],
+            loc: spanLocation(opening, closing),
+        };
+    }
+    #array() {
+        const { items: elements, opening, closing } = this.#items(CLOSE_BRACKET, () => this.#value());
+        return {
+            type: 'Array',
+            elements,
+            range: [opening.range[0], closing.range[1]],
+            loc: spanLocation(opening, closing),
+        };
+    }
+    /*
+    The items between an opening bracket and its `closingCode` bracket, which is consumed too. Items are separated by a comma, a line break, or both, so a comma token may be absent. The parser has already checked the separators, including that a comma is on the line of the item before it.
+    */
+    #items(closingCode, parseItem) {
+        const items = [];
+        const opening = this.#punctuator();
+        this.#skipTrivia();
+        while (this.#code() !== closingCode) {
+            items.push(parseItem());
+            this.#skipTrivia();
+            if (this.#code() !== COMMA) {
+                continue;
+            }
+            this.#punctuator();
+            this.#skipTrivia();
+        }
+        return { items, opening, closing: this.#punctuator() };
+    }
+    #member() {
+        const key = this.#key();
+        this.#punctuator(); // `:`
+        this.#skipTrivia();
+        const value = this.#value();
+        return {
+            type: 'Member',
+            key,
+            value,
+            range: [key.range[0], value.range[1]],
+            loc: spanLocation(key, value),
+        };
+    }
+    #key() {
+        const segments = [this.#keySegment()];
+        while (this.#code() === DOT) {
+            this.#punctuator();
+            segments.push(this.#keySegment());
+        }
+        const first = segments[0];
+        const last = segments.at(-1);
+        return {
+            type: 'Key',
+            segments,
+            range: [first.range[0], last.range[1]],
+            loc: spanLocation(first, last),
+        };
+    }
+    #keySegment() {
+        const start = this.#index;
+        const code = this.#code();
+        if (code === SINGLE_QUOTE || code === DOUBLE_QUOTE) {
+            const { value, style, token: { range, loc } } = this.#singleLineString();
+            return {
+                type: 'KeySegment',
+                value,
+                style,
+                range,
+                loc,
+            };
+        }
+        while (isBareKeyCharacter(this.#code())) {
+            this.#index++;
+        }
+        const { value, range, loc } = this.#token('BareKey', start, this.#index);
+        return {
+            type: 'KeySegment',
+            value,
+            style: 'bare',
+            range,
+            loc,
+        };
+    }
+    #value() {
+        const code = this.#code();
+        if (code === OPEN_BRACE) {
+            return this.#object();
+        }
+        if (code === OPEN_BRACKET) {
+            return this.#array();
+        }
+        const start = this.#index;
+        if (code === SINGLE_QUOTE || code === DOUBLE_QUOTE) {
+            if (this.#code(start + 1) === code && this.#code(start + 2) === code) {
+                return this.#blockString(code);
+            }
+            const { value, style, token: { range, loc } } = this.#singleLineString();
+            return {
+                type: 'String',
+                value,
+                style,
+                block: false,
+                range,
+                loc,
+            };
+        }
+        // The document is valid, so a value that starts with a keyword is that keyword, as a number cannot start with a letter other than the `i` of `infinity`.
+        const keyword = KEYWORDS.find(word => this.#source.startsWith(word, start));
+        if (keyword !== undefined) {
+            this.#index += keyword.length;
+            const { range, loc } = this.#token('Keyword', start, this.#index);
+            if (keyword === 'null') {
+                return { type: 'Null', range, loc };
+            }
+            return {
+                type: 'Boolean',
+                value: keyword === 'true',
+                range,
+                loc,
+            };
+        }
+        return this.#numberOrTime();
+    }
+    /*
+    `'...'` ends at the next `'`. `"..."` ends at the next `"` that is not escaped, and `\` always starts a two-character escape or a `\u{…}`, which holds no quote.
+    */
+    #singleLineString() {
+        const source = this.#source;
+        const start = this.#index;
+        const quote = this.#code();
+        let end = start + 1;
+        if (quote === SINGLE_QUOTE) {
+            end = source.indexOf('\'', end);
+        }
+        else {
+            while (this.#code(end) !== DOUBLE_QUOTE) {
+                end += this.#code(end) === BACKSLASH ? 2 : 1;
+            }
+        }
+        this.#index = end + 1;
+        const token = this.#token('String', start, this.#index);
+        return quote === SINGLE_QUOTE
+            ? { value: source.slice(start + 1, end), style: 'literal', token }
+            : { value: readScalar(token.value), style: 'escaped', token };
+    }
+    /*
+    The block ends at the first line whose first non-whitespace content is a run of exactly as many quotes as the opening delimiter.
+    */
+    #blockString(quote) {
+        const source = this.#source;
+        const start = this.#index;
+        let delimiterLength = 0;
+        while (this.#code(start + delimiterLength) === quote) {
+            delimiterLength++;
+        }
+        const closing = findBlockStringEnd(source, source.indexOf('\n', start) + 1, quote, delimiterLength);
+        this.#index = closing.delimiterStart + delimiterLength;
+        const { value, range, loc } = this.#token('String', start, this.#index);
+        return {
+            type: 'String',
+            value: readScalar(value),
+            style: quote === SINGLE_QUOTE ? 'literal' : 'escaped',
+            block: true,
+            range,
+            loc,
+        };
+    }
+    #numberOrTime() {
+        const start = this.#index;
+        const end = findNumberEnd(this.#source, start);
+        this.#index = end;
+        const raw = this.#source.slice(start, end);
+        const value = readScalar(raw);
+        if (typeof value === 'bigint') {
+            const { range, loc } = this.#token('Integer', start, end);
+            return {
+                type: 'Integer',
+                value,
+                radix: RADIX.get(raw.charAt(1)) ?? 10,
+                range,
+                loc,
+            };
+        }
+        if (typeof value === 'number') {
+            const { range, loc } = this.#token('Float', start, end);
+            return {
+                type: 'Float',
+                value,
+                range,
+                loc,
+            };
+        }
+        const time = value;
+        const { range, loc } = this.#token(time.type, start, end);
+        let temporal;
+        if (time.type === 'Duration') {
+            // A getter, so that the `Temporal` object is made when `value` is first read.
+            const node = {
+                type: 'Duration',
+                get value() {
+                    temporal ??= time.toTemporal();
+                    return temporal;
+                },
+                negative: raw.startsWith('-'),
+                parts: readDurationParts(raw),
+                range,
+                loc,
+            };
+            return node;
+        }
+        // A getter, so that the `Temporal` object is made when `value` is first read.
+        const node = {
+            type: 'Instant',
+            get value() {
+                temporal ??= time.toTemporal();
+                return temporal;
+            },
+            range,
+            loc,
+        };
+        return node;
+    }
+    build() {
+        this.#skipTrivia();
+        const code = this.#code();
+        let body;
+        if (code === OPEN_BRACE) {
+            body = this.#object();
+        }
+        else if (code === OPEN_BRACKET) {
+            body = this.#array();
+        }
+        else {
+            body = this.#bareObject();
+        }
+        this.#skipTrivia();
+        return {
+            type: 'Document',
+            body,
+            tokens: this.#tokens,
+            comments: this.#comments,
+            range: [0, this.#source.length],
+            loc: this.#location(0, this.#source.length),
+        };
+    }
+}
+/*
+The location from the start of `first` to the end of `last`, which shares their positions rather than looking them up again. A node that ends far from where it starts, such as a large object, would otherwise move the line cache in `#position` back and forth.
+*/
+function spanLocation(first, last) {
+    return { start: first.loc.start, end: last.loc.end };
+}
+/*
+The parts of a duration that is already valid. A part is a number, which has no letters, and then a unit, which has only lowercase letters.
+*/
+function readDurationParts(raw) {
+    // From `a` to `z`.
+    const isUnitCharacter = (index) => raw.charCodeAt(index) >= 0x61 && raw.charCodeAt(index) <= 0x7A;
+    const parts = [];
+    let index = raw.startsWith('-') ? 1 : 0;
+    while (index < raw.length) {
+        let unitStart = index;
+        while (!isUnitCharacter(unitStart)) {
+            unitStart++;
+        }
+        let unitEnd = unitStart;
+        while (unitEnd < raw.length && isUnitCharacter(unitEnd)) {
+            unitEnd++;
+        }
+        parts.push({ number: raw.slice(index, unitStart), unit: raw.slice(unitStart, unitEnd) });
+        index = unitEnd;
+    }
+    return parts;
+}

package/package.json

@@ -1,26 +1,27 @@
 {
 	"name": "soml-lang",
-	"version": "0.0.1",
-	"description": "Reference parser and canonical serializer for SOML, a config format for humans",
+	"version": "0.0.3",
+	"description": "Reference parser, serializer, and formatter for SOML, a config format for humans",
 	"license": "MIT",
+	"repository": "som-lang/soml-javascript",
 	"author": "Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)",
 	"type": "module",
 	"exports": {
-		"types": "./index.d.ts",
-		"default": "./index.js"
+		"types": "./distribution/index.d.ts",
+		"default": "./distribution/index.js"
 	},
 	"sideEffects": false,
 	"engines": {
-		"node": ">=26"
+		"node": ">=22"
 	},
 	"scripts": {
-		"test": "xo && node --test && tsc",
-		"bench": "node bench/index.js"
+		"build": "tsc --project tsconfig.build.json",
+		"prepack": "npm run build",
+		"test": "xo && tsc && node --test 'test/*.ts'",
+		"bench": "node bench/index.ts"
 	},
 	"files": [
-		"index.js",
-		"index.d.ts",
-		"source"
+		"distribution"
 	],
 	"keywords": [
 		"config",
@@ -35,6 +36,8 @@
 		"yaml"
 	],
 	"devDependencies": {
+		"@sindresorhus/tsconfig": "^8.1.0",
+		"@types/node": "^26.6.4",
 		"json5": "^2.2.3",
 		"smol-toml": "^1.9.0",
 		"typescript": "^6.0.3",
@@ -50,19 +53,12 @@
 		{
 			"rules": {
 				"unicorn/prefer-code-point": "off",
-				"unicorn/consistent-class-member-order": "off",
-				"unicorn/consistent-boolean-name": "off",
-				"unicorn/prefer-simple-condition-first": "off",
-				"unicorn/prefer-ternary": "off",
-				"unicorn/prefer-continue": "off",
-				"unicorn/prefer-early-return": "off",
-				"unicorn/no-declarations-before-early-exit": "off",
-				"unicorn/prefer-global-number-constants": "off",
-				"unicorn/no-break-in-nested-loop": "off",
-				"unicorn/prefer-else-if": "off",
-				"jsdoc/require-param-description": "off",
-				"jsdoc/require-param-type": "off",
-				"jsdoc/require-param": "off"
+				"@typescript-eslint/switch-exhaustiveness-check": [
+					"error",
+					{
+						"considerDefaultExhaustiveForUnions": true
+					}
+				]
 			}
 		},
 		{
@@ -71,20 +67,24 @@
 			],
 			"rules": {
 				"node-test/no-conditional-assertion": "off",
-				"node-test/no-conditional-tests": "off",
 				"node-test/no-import-test-files": "off",
-				"node-test/no-compound-assertion": "off",
-				"node-test/prefer-assert-throws": "off",
 				"node-test/require-assertion": "off",
-				"no-bitwise": "off",
-				"unicorn/prefer-unicode-code-point-escapes": "off",
-				"@stylistic/object-curly-newline": "off",
-				"regexp/no-control-character": "off",
-				"no-control-regex": "off",
 				"unicorn/max-nested-calls": "off",
-				"unicorn/prefer-number-is-safe-integer": "off",
-				"unicorn/require-array-sort-compare": "off",
-				"unicorn/no-duplicate-loops": "off"
+				"@typescript-eslint/no-floating-promises": [
+					"error",
+					{
+						"allowForKnownSafeCalls": [
+							{
+								"from": "package",
+								"package": "node:test",
+								"name": [
+									"test",
+									"suite"
+								]
+							}
+						]
+					}
+				]
 			}
 		}
 	]