soml-lang 0.0.1 → 0.0.3

package/distribution/shared.d.ts

@@ -0,0 +1,102 @@
+export declare const TAB = 9;
+export declare const LF = 10;
+export declare const SPACE = 32;
+export declare const DOUBLE_QUOTE = 34;
+export declare const HASH = 35;
+export declare const SINGLE_QUOTE = 39;
+export declare const ASTERISK = 42;
+export declare const COMMA = 44;
+export declare const DASH = 45;
+export declare const DOT = 46;
+export declare const SLASH = 47;
+export declare const COLON = 58;
+export declare const OPEN_BRACKET = 91;
+export declare const BACKSLASH = 92;
+export declare const CLOSE_BRACKET = 93;
+export declare const OPEN_BRACE = 123;
+export declare const CLOSE_BRACE = 125;
+export declare const MAX_DEPTH = 100;
+export declare const INT64_MIN: bigint;
+export declare const INT64_MAX: bigint;
+export declare const MIN_INSTANT = -62135596800000000000n;
+export declare const MAX_INSTANT = 253402300799999999999n;
+export declare function requireTemporal(): typeof globalThis.Temporal;
+export declare const DURATION_UNITS: Map<string, bigint>;
+/**
+Remove the trailing zeros of a run of digits. A loop rather than a regular expression, which would be quadratic on a long run of zeros followed by another digit.
+*/
+export declare function trimTrailingZeros(digits: string): string;
+/**
+A duration as a `Temporal.Duration` in hours and smaller units, which hold any int64 count of nanoseconds exactly.
+*/
+export declare function createDuration(nanoseconds: bigint): Temporal.Duration;
+/**
+The `integers` option of `parse()`, `stringify()`, and `edit()`, checked, or its default when it is left out.
+*/
+export declare function getIntegersOption(options: unknown): 'bigint' | 'number';
+/**
+Whether a UTF-16 code unit can be part of a bare key. `NaN`, which `charCodeAt()` returns past the end of a string, cannot.
+*/
+export declare function isBareKeyCharacter(code: number): boolean;
+/**
+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.
+
+@param key - The decoded key.
+@returns Whether `key` can be a bare key.
+
+@example
+```
+import {isBareKey} from 'soml-lang';
+
+isBareKey('content-type');
+//=> true
+
+isBareKey('a.b');
+//=> false
+```
+*/
+export declare function isBareKey(key: string): boolean;
+/**
+A key as an error message shows it: bare when it can be, and otherwise quoted, and cut short when it is long.
+*/
+export declare function describeKey(key: string): string;
+/**
+The end of the number, instant, or duration token that starts at `start`, which is a digit, `-`, or the `i` of `infinity`.
+*/
+export declare function findNumberEnd(source: string, start: number): number;
+/**
+The offset of the line feed that ends the line containing `offset`, or the length of `source` on the last line.
+*/
+export declare function findLineEnd(source: string, offset: number): number;
+/**
+Find the closing delimiter of a block string: the first line from `offset` on that holds, after zero or more spaces and tabs, a run of exactly `length` of the `quote` character. A longer run is content. Returns where that line and its delimiter start, or `undefined` when no line closes the block.
+*/
+export declare function findBlockStringEnd(source: string, offset: number, quote: number, length: number): {
+    lineStart: number;
+    delimiterStart: number;
+} | undefined;
+/**
+Whether a UTF-16 code unit is a space or a tab, the whitespace within a line.
+*/
+export declare function isSpace(code: number): boolean;
+/**
+The index after the spaces and tabs from `index` on.
+*/
+export declare function skipSpaces(text: string, index: number): number;
+/**
+The index after the last character before `index` that is not a space or a tab.
+*/
+export declare function skipSpacesBack(text: string, index: number): number;
+/**
+Whether a line in a block string is blank: empty, or only spaces and tabs. A blank line becomes an empty line in the value.
+*/
+export declare function isBlankLine(line: string): boolean;
+/**
+Shorten text quoted in an error message, so a huge token does not make a huge message. The cut never splits a surrogate pair.
+*/
+export declare function abbreviate(text: string, maximumLength?: number): string;
+export declare function formatCodePoint(codePoint: number): string;
+/**
+Describe a character for an error message, such as `“$”` or `U+00A0 (NO-BREAK SPACE)`.
+*/
+export declare function describeCharacter(codePoint: number): string;

package/distribution/shared.js

@@ -0,0 +1,285 @@
+/*
+UTF-16 code units of the characters that the lexers look for.
+*/
+export const TAB = 0x09;
+export const LF = 0x0A;
+export const SPACE = 0x20;
+export const DOUBLE_QUOTE = 0x22;
+export const HASH = 0x23;
+export const SINGLE_QUOTE = 0x27;
+export const ASTERISK = 0x2A;
+export const COMMA = 0x2C;
+export const DASH = 0x2D;
+export const DOT = 0x2E;
+export const SLASH = 0x2F;
+export const COLON = 0x3A;
+export const OPEN_BRACKET = 0x5B;
+export const BACKSLASH = 0x5C;
+export const CLOSE_BRACKET = 0x5D;
+export const OPEN_BRACE = 0x7B;
+export const CLOSE_BRACE = 0x7D;
+/*
+The deepest nesting either direction accepts. A recursive-descent parser would otherwise end in an engine stack overflow.
+*/
+export const MAX_DEPTH = 100;
+export const INT64_MIN = -(2n ** 63n);
+export const INT64_MAX = (2n ** 63n) - 1n;
+/*
+The instant range is checked in UTC, so that every instant has a canonical form that can be read back.
+*/
+export const MIN_INSTANT = -62135596800000000000n; // 0001-01-01T00:00:00Z
+export const MAX_INSTANT = 253402300799999999999n; // 9999-12-31T23:59:59.999999999Z
+/*
+`Temporal` is built into Node.js 26 and later. Before that, only the values of instants and durations need it, so that everything else works without a polyfill, including `format()` and `parseTree()`. It is read at import, so a polyfill must be loaded before this package.
+*/
+const temporal = typeof Temporal === 'undefined' ? undefined : Temporal;
+export function requireTemporal() {
+    if (temporal === undefined) {
+        throw new Error('Instants and durations need `Temporal`. Use Node.js 26 or later, or load a polyfill such as `temporal-polyfill/global` before this package');
+    }
+    return temporal;
+}
+/*
+The duration units in their required order, with their length in nanoseconds.
+*/
+export const DURATION_UNITS = new Map([
+    ['h', 3600000000000n],
+    ['m', 60000000000n],
+    ['s', 1000000000n],
+    ['ms', 1000000n],
+    ['us', 1000n],
+    ['ns', 1n],
+]);
+/**
+Remove the trailing zeros of a run of digits. A loop rather than a regular expression, which would be quadratic on a long run of zeros followed by another digit.
+*/
+export function trimTrailingZeros(digits) {
+    let end = digits.length;
+    while (end > 0 && digits.charCodeAt(end - 1) === 0x30) {
+        end--;
+    }
+    return digits.slice(0, end);
+}
+/**
+A duration as a `Temporal.Duration` in hours and smaller units, which hold any int64 count of nanoseconds exactly.
+*/
+export function createDuration(nanoseconds) {
+    const sign = nanoseconds < 0n ? -1n : 1n;
+    let rest = nanoseconds * sign;
+    const parts = [];
+    for (const size of DURATION_UNITS.values()) {
+        parts.push(Number(sign * (rest / size)));
+        rest %= size;
+    }
+    const [hours, minutes, seconds, milliseconds, microseconds, nanosecondsPart] = parts;
+    return new (requireTemporal().Duration)(0, 0, 0, 0, hours, minutes, seconds, milliseconds, microseconds, nanosecondsPart);
+}
+/**
+The `integers` option of `parse()`, `stringify()`, and `edit()`, checked, or its default when it is left out.
+*/
+export function getIntegersOption(options) {
+    if (options === undefined) {
+        return 'bigint';
+    }
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError(`The options must be an object, got ${options === null ? 'null' : typeof options}`);
+    }
+    const { integers = 'bigint' } = options;
+    if (integers !== 'bigint' && integers !== 'number') {
+        throw new TypeError(`The \`integers\` option must be 'bigint' or 'number', got ${typeof integers === 'string' ? `'${abbreviate(integers)}'` : typeof integers}`);
+    }
+    return integers;
+}
+/*
+Names for the characters that are invisible or easy to mistake, so an error can say what it found.
+*/
+const CHARACTER_NAMES = new Map([
+    [0x06_1C, 'ARABIC LETTER MARK'],
+    [0x85, 'NEXT LINE'],
+    [0xA0, 'NO-BREAK SPACE'],
+    [0xAD, 'SOFT HYPHEN'],
+    [0x16_80, 'OGHAM SPACE MARK'],
+    [0x20_00, 'EN QUAD'],
+    [0x20_01, 'EM QUAD'],
+    [0x20_02, 'EN SPACE'],
+    [0x20_03, 'EM SPACE'],
+    [0x20_04, 'THREE-PER-EM SPACE'],
+    [0x20_05, 'FOUR-PER-EM SPACE'],
+    [0x20_06, 'SIX-PER-EM SPACE'],
+    [0x20_07, 'FIGURE SPACE'],
+    [0x20_08, 'PUNCTUATION SPACE'],
+    [0x20_09, 'THIN SPACE'],
+    [0x20_0A, 'HAIR SPACE'],
+    [0x20_0B, 'ZERO WIDTH SPACE'],
+    [0x20_0C, 'ZERO WIDTH NON-JOINER'],
+    [0x20_0D, 'ZERO WIDTH JOINER'],
+    [0x20_0E, 'LEFT-TO-RIGHT MARK'],
+    [0x20_0F, 'RIGHT-TO-LEFT MARK'],
+    [0x20_28, 'LINE SEPARATOR'],
+    [0x20_29, 'PARAGRAPH SEPARATOR'],
+    [0x20_2A, 'LEFT-TO-RIGHT EMBEDDING'],
+    [0x20_2B, 'RIGHT-TO-LEFT EMBEDDING'],
+    [0x20_2C, 'POP DIRECTIONAL FORMATTING'],
+    [0x20_2D, 'LEFT-TO-RIGHT OVERRIDE'],
+    [0x20_2E, 'RIGHT-TO-LEFT OVERRIDE'],
+    [0x20_2F, 'NARROW NO-BREAK SPACE'],
+    [0x20_5F, 'MEDIUM MATHEMATICAL SPACE'],
+    [0x20_60, 'WORD JOINER'],
+    [0x20_66, 'LEFT-TO-RIGHT ISOLATE'],
+    [0x20_67, 'RIGHT-TO-LEFT ISOLATE'],
+    [0x20_68, 'FIRST STRONG ISOLATE'],
+    [0x20_69, 'POP DIRECTIONAL ISOLATE'],
+    [0x30_00, 'IDEOGRAPHIC SPACE'],
+    [0xFE_FF, 'ZERO WIDTH NO-BREAK SPACE'],
+]);
+/*
+Letters, digits, `_`, and `-`, the characters of a bare key, as a lookup table by code unit.
+*/
+const bareKeyCharacters = new Uint8Array(128);
+for (const character of 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-') {
+    bareKeyCharacters[character.charCodeAt(0)] = 1;
+}
+/*
+A number, an instant, or a duration is lexed as one maximal run of these characters, and then validated as a whole. The validation is a hand-written scan rather than a regular expression, because a regular expression with a repeated group runs out of stack on a token of a few million characters.
+*/
+const numberCharacters = new Uint8Array(128);
+for (const character of 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.:+-') {
+    numberCharacters[character.charCodeAt(0)] = 1;
+}
+/**
+Whether a UTF-16 code unit can be part of a bare key. `NaN`, which `charCodeAt()` returns past the end of a string, cannot.
+*/
+export function isBareKeyCharacter(code) {
+    return code < 128 && bareKeyCharacters[code] === 1;
+}
+/**
+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.
+
+@param key - The decoded key.
+@returns Whether `key` can be a bare key.
+
+@example
+```
+import {isBareKey} from 'soml-lang';
+
+isBareKey('content-type');
+//=> true
+
+isBareKey('a.b');
+//=> false
+```
+*/
+export function isBareKey(key) {
+    if (key === '') {
+        return false;
+    }
+    for (let index = 0; index < key.length; index++) {
+        if (!isBareKeyCharacter(key.charCodeAt(index))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+A key as an error message shows it: bare when it can be, and otherwise quoted, and cut short when it is long.
+*/
+export function describeKey(key) {
+    return isBareKey(key) ? abbreviate(key) : JSON.stringify(abbreviate(key));
+}
+/**
+The end of the number, instant, or duration token that starts at `start`, which is a digit, `-`, or the `i` of `infinity`.
+*/
+export function findNumberEnd(source, start) {
+    let end = start + 1;
+    while (isNumberCharacter(source.charCodeAt(end))) {
+        end++;
+    }
+    return end;
+}
+function isNumberCharacter(code) {
+    return code < 128 && numberCharacters[code] === 1;
+}
+/**
+The offset of the line feed that ends the line containing `offset`, or the length of `source` on the last line.
+*/
+export function findLineEnd(source, offset) {
+    const end = source.indexOf('\n', offset);
+    return end === -1 ? source.length : end;
+}
+/**
+Find the closing delimiter of a block string: the first line from `offset` on that holds, after zero or more spaces and tabs, a run of exactly `length` of the `quote` character. A longer run is content. Returns where that line and its delimiter start, or `undefined` when no line closes the block.
+*/
+export function findBlockStringEnd(source, offset, quote, length) {
+    for (let lineStart = offset; lineStart < source.length; lineStart = findLineEnd(source, lineStart) + 1) {
+        const delimiterStart = skipSpaces(source, lineStart);
+        let runLength = 0;
+        while (source.charCodeAt(delimiterStart + runLength) === quote) {
+            runLength++;
+        }
+        if (runLength === length) {
+            return { lineStart, delimiterStart };
+        }
+    }
+    // Past the last line, either because the source ended with a line break or because the last line was content.
+    return undefined;
+}
+/**
+Whether a UTF-16 code unit is a space or a tab, the whitespace within a line.
+*/
+export function isSpace(code) {
+    return code === SPACE || code === TAB;
+}
+/*
+Whitespace within a line is scanned with loops rather than regular expressions such as `/[\t ]*:/`, because a regular expression that backtracks over a run of a few million spaces runs out of stack.
+*/
+/**
+The index after the spaces and tabs from `index` on.
+*/
+export function skipSpaces(text, index) {
+    while (isSpace(text.charCodeAt(index))) {
+        index++;
+    }
+    return index;
+}
+/**
+The index after the last character before `index` that is not a space or a tab.
+*/
+export function skipSpacesBack(text, index) {
+    while (index > 0 && isSpace(text.charCodeAt(index - 1))) {
+        index--;
+    }
+    return index;
+}
+/**
+Whether a line in a block string is blank: empty, or only spaces and tabs. A blank line becomes an empty line in the value.
+*/
+export function isBlankLine(line) {
+    return skipSpaces(line, 0) === line.length;
+}
+/**
+Shorten text quoted in an error message, so a huge token does not make a huge message. The cut never splits a surrogate pair.
+*/
+export function abbreviate(text, maximumLength = 40) {
+    if (text.length <= maximumLength) {
+        return text;
+    }
+    const lastCode = text.charCodeAt(maximumLength - 1);
+    const end = lastCode >= 0xD8_00 && lastCode <= 0xDB_FF ? maximumLength - 1 : maximumLength;
+    return `${text.slice(0, end)}…`;
+}
+export function formatCodePoint(codePoint) {
+    return `U+${codePoint.toString(16).toUpperCase().padStart(4, '0')}`;
+}
+/**
+Describe a character for an error message, such as `“$”` or `U+00A0 (NO-BREAK SPACE)`.
+*/
+export function describeCharacter(codePoint) {
+    const name = CHARACTER_NAMES.get(codePoint);
+    if (name !== undefined) {
+        const isWhitespace = /^[\p{White_Space}\u{200B}\u{FEFF}]$/v.test(String.fromCodePoint(codePoint));
+        return `${formatCodePoint(codePoint)} (${name}${isWhitespace ? '; only space, tab, and line feed are whitespace' : ''})`;
+    }
+    const character = String.fromCodePoint(codePoint);
+    // Control, format, private-use, unassigned, surrogate, separator, and default-ignorable characters are invisible or ambiguous, so they are shown by code point.
+    return codePoint !== 0x20 && /^[\p{Default_Ignorable_Code_Point}\p{Other}\p{Separator}]$/v.test(character) ? formatCodePoint(codePoint) : `“${character}”`;
+}

package/distribution/stringify.d.ts

@@ -0,0 +1,115 @@
+/**
+Options for `stringify()`.
+*/
+export type StringifyOptions = {
+    /**
+    How an int is represented in `value`.
+
+    - `'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.
+
+    @default 'bigint'
+    */
+    readonly integers?: 'bigint' | 'number';
+    /**
+    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.
+
+    @default false
+
+    @example
+    ```
+    import {stringify} from 'soml-lang';
+
+    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"
+    ```
+    */
+    readonly canonical?: boolean;
+};
+/**
+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` 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.
+
+@param value - A plain object or an array.
+@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
+```
+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"
+```
+*/
+export declare function stringify(value: object, options?: StringifyOptions): string;
+/**
+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 declare function stringifyValue(value: unknown, options?: StringifyOptions): string;
+/**
+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', '😀']
+```
+*/
+export declare function compareKeys(left: string, right: string): number;
+export declare function formatKey(key: string): string;