soml-lang 0.0.1 → 0.0.2

package/distribution/tree.d.ts

@@ -0,0 +1,153 @@
+/**
+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 = {
+    readonly line: number;
+    readonly column: number;
+};
+/**
+Where a node, token, or comment is in the source.
+*/
+export type SourceLocation = {
+    readonly start: Position;
+    readonly end: Position;
+};
+type Located<Type extends string> = {
+    readonly type: Type;
+    /**
+    The start and end, as UTF-16 offsets into the text.
+    */
+    readonly range: readonly [start: number, end: number];
+    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.
+*/
+export type Token = Located<'Punctuator' | 'BareKey' | 'String' | 'Integer' | 'Float' | 'Keyword' | 'Instant' | 'Duration'> & {
+    readonly value: string;
+};
+/**
+A comment. `value` is its text without its delimiters.
+*/
+export type Comment = Located<'Line' | 'Block'> & {
+    readonly value: string;
+};
+/**
+The root of a tree.
+*/
+export type DocumentNode = Located<'Document'> & {
+    readonly body: ObjectNode | ArrayNode;
+    /**
+    Every token, in source order, without comments.
+    */
+    readonly tokens: readonly Token[];
+    /**
+    Every comment, in source order.
+    */
+    readonly comments: readonly Comment[];
+};
+export type ObjectNode = Located<'Object'> & {
+    readonly members: readonly MemberNode[];
+    /**
+    `false` only for a top-level object written without braces.
+    */
+    readonly braced: boolean;
+};
+export type MemberNode = Located<'Member'> & {
+    readonly key: KeyNode;
+    readonly value: ValueNode;
+};
+export type ArrayNode = Located<'Array'> & {
+    readonly elements: readonly ValueNode[];
+};
+/**
+A key, with more than one segment when it is dotted.
+*/
+export type KeyNode = Located<'Key'> & {
+    readonly segments: readonly KeySegmentNode[];
+};
+export type KeySegmentNode = Located<'KeySegment'> & {
+    /**
+    The decoded key.
+    */
+    readonly value: string;
+    readonly style: 'bare' | 'literal' | 'escaped';
+};
+export type StringNode = Located<'String'> & {
+    /**
+    The decoded string.
+    */
+    readonly value: string;
+    readonly style: 'literal' | 'escaped';
+    /**
+    Whether it is a block string.
+    */
+    readonly block: boolean;
+};
+export type IntegerNode = Located<'Integer'> & {
+    readonly value: bigint;
+    readonly radix: 2 | 8 | 10 | 16;
+};
+export type FloatNode = Located<'Float'> & {
+    readonly value: number;
+};
+export type BooleanNode = Located<'Boolean'> & {
+    readonly value: boolean;
+};
+export type NullNode = Located<'Null'>;
+export type InstantNode = Located<'Instant'> & {
+    readonly value: Temporal.Instant;
+};
+export type DurationNode = Located<'Duration'> & {
+    readonly value: Temporal.Duration;
+};
+/**
+A node that is a value.
+*/
+export type ValueNode = ObjectNode | ArrayNode | StringNode | IntegerNode | FloatNode | BooleanNode | NullNode | InstantNode | DurationNode;
+/**
+Any node in a tree.
+*/
+export type Node = DocumentNode | MemberNode | KeyNode | KeySegmentNode | 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.
+
+@example
+```
+import {visitorKeys} from 'soml-lang';
+
+visitorKeys.Member;
+//=> ['key', 'value']
+
+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.
+
+Every node, token, and comment has a `range` and a `loc`.
+
+@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 declare function parseTree(text: string): DocumentNode;
+export {};

package/distribution/tree.js

@@ -0,0 +1,333 @@
+import { parse } from "./parse.js";
+import { isBareKeyCharacter, findNumberEnd, findLineEnd, findBlockStringEnd, } 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 */
+const TAB = 0x09;
+const LF = 0x0A;
+const SPACE = 0x20;
+const DOUBLE_QUOTE = 0x22;
+const HASH = 0x23;
+const SINGLE_QUOTE = 0x27;
+const ASTERISK = 0x2A;
+const COMMA = 0x2C;
+const DOT = 0x2E;
+const SLASH = 0x2F;
+const BACKSLASH = 0x5C;
+const OPEN_BRACKET = 0x5B;
+const CLOSE_BRACKET = 0x5D;
+const OPEN_BRACE = 0x7B;
+const CLOSE_BRACE = 0x7D;
+const WHITESPACE = new Set([SPACE, TAB, LF]);
+/*
+`infinity` and `-infinity` are read as numbers, because they are floats.
+*/
+const KEYWORDS = ['true', 'false', 'null'];
+const RADIX = { x: 16, o: 8, b: 2 };
+/**
+Parse a document into a syntax tree, for tools such as linters and formatters.
+
+Every node, token, and comment has a `range` and a `loc`.
+
+@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.
+    parse(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.
+*/
+function readScalar(raw) {
+    return parse(`[${raw}]`)[0];
+}
+class TreeBuilder {
+    #source;
+    #index = 0;
+    #tokens = [];
+    #comments = [];
+    #lineStarts = [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;
+        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;
+            }
+        }
+        return { line: low + 1, column: offset - lineStarts[low] };
+    }
+    #node(type, start, end, fields) {
+        return {
+            type,
+            ...fields,
+            range: [start, end],
+            loc: { start: this.#position(start), end: this.#position(end) },
+        };
+    }
+    #token(type, start, end) {
+        const token = this.#node(type, start, end, { value: this.#source.slice(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 (WHITESPACE.has(code)) {
+                this.#index++;
+            }
+            else if (code === HASH) {
+                this.#index = findLineEnd(source, start);
+                this.#comments.push(this.#node('Line', start, this.#index, { value: source.slice(start + 1, this.#index) }));
+            }
+            else if (code === SLASH && this.#code(start + 1) === ASTERISK) {
+                this.#index = source.indexOf('*/', start + 2) + 2;
+                this.#comments.push(this.#node('Block', start, this.#index, { value: source.slice(start + 2, this.#index - 2) }));
+            }
+            else {
+                return;
+            }
+        }
+    }
+    #bareObject() {
+        const members = [];
+        do {
+            members.push(this.#member());
+            this.#skipTrivia();
+        } while (this.#index < this.#source.length);
+        return this.#node('Object', members[0].range[0], members.at(-1).range[1], { members, braced: false });
+    }
+    #object() {
+        const start = this.#index;
+        const members = this.#items(CLOSE_BRACE, () => this.#member());
+        return this.#node('Object', start, this.#index, { members, braced: true });
+    }
+    #array() {
+        const start = this.#index;
+        const elements = this.#items(CLOSE_BRACKET, () => this.#value());
+        return this.#node('Array', start, this.#index, { elements });
+    }
+    /*
+    The items between an opening bracket and its `closing` bracket, which is consumed too. The parser has already checked the commas.
+    */
+    #items(closing, parseItem) {
+        const items = [];
+        this.#punctuator();
+        this.#skipTrivia();
+        while (this.#code() !== closing) {
+            items.push(parseItem());
+            this.#skipTrivia();
+            if (this.#code() !== COMMA) {
+                continue;
+            }
+            this.#punctuator();
+            this.#skipTrivia();
+        }
+        this.#punctuator();
+        return items;
+    }
+    #member() {
+        const key = this.#key();
+        this.#punctuator(); // `:`
+        this.#skipTrivia();
+        const value = this.#value();
+        return this.#node('Member', key.range[0], value.range[1], { key, value });
+    }
+    #key() {
+        const segments = [this.#keySegment()];
+        while (this.#code() === DOT) {
+            this.#punctuator();
+            segments.push(this.#keySegment());
+        }
+        return this.#node('Key', segments[0].range[0], segments.at(-1).range[1], { segments });
+    }
+    #keySegment() {
+        const start = this.#index;
+        const code = this.#code();
+        if (code === SINGLE_QUOTE || code === DOUBLE_QUOTE) {
+            const { value, style } = this.#singleLineString();
+            return this.#node('KeySegment', start, this.#index, { value, style });
+        }
+        while (isBareKeyCharacter(this.#code())) {
+            this.#index++;
+        }
+        const token = this.#token('BareKey', start, this.#index);
+        return this.#node('KeySegment', start, this.#index, { value: token.value, style: 'bare' });
+    }
+    #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 } = this.#singleLineString();
+            return this.#node('String', start, this.#index, { value, style, block: false });
+        }
+        const keyword = KEYWORDS.find(word => this.#source.startsWith(word, start) && !isBareKeyCharacter(this.#code(start + word.length)));
+        if (keyword !== undefined) {
+            this.#index += keyword.length;
+            this.#token('Keyword', start, this.#index);
+            return keyword === 'null'
+                ? this.#node('Null', start, this.#index, {})
+                : this.#node('Boolean', start, this.#index, { value: keyword === 'true' });
+        }
+        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' }
+            : { value: readScalar(token.value), style: 'escaped' };
+    }
+    /*
+    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 token = this.#token('String', start, this.#index);
+        return this.#node('String', start, this.#index, {
+            value: readScalar(token.value),
+            style: quote === SINGLE_QUOTE ? 'literal' : 'escaped',
+            block: true,
+        });
+    }
+    #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') {
+            this.#token('Integer', start, end);
+            return this.#node('Integer', start, end, { value, radix: RADIX[raw.charAt(1)] ?? 10 });
+        }
+        if (typeof value === 'number') {
+            this.#token('Float', start, end);
+            return this.#node('Float', start, end, { value });
+        }
+        const type = value instanceof Temporal.Instant ? 'Instant' : 'Duration';
+        this.#token(type, start, end);
+        return this.#node(type, start, end, { value });
+    }
+    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 this.#node('Document', 0, this.#source.length, {
+            body,
+            tokens: this.#tokens,
+            comments: this.#comments,
+        });
+    }
+}

package/package.json

@@ -1,26 +1,26 @@
 {
 	"name": "soml-lang",
-	"version": "0.0.1",
-	"description": "Reference parser and canonical serializer for SOML, a config format for humans",
+	"version": "0.0.2",
+	"description": "Reference parser, canonical serializer, and formatter for SOML, a config format for humans",
 	"license": "MIT",
 	"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",
+		"bench": "node bench/index.ts"
 	},
 	"files": [
-		"index.js",
-		"index.d.ts",
-		"source"
+		"distribution"
 	],
 	"keywords": [
 		"config",
@@ -35,6 +35,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 +52,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 +66,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"
+								]
+							}
+						]
+					}
+				]
 			}
 		}
 	]