soml-lang 0.0.1

package/index.d.ts

@@ -0,0 +1,151 @@
+/**
+A value in a document.
+
+| Format | JavaScript |
+|---|---|
+| string | `string` |
+| int | `bigint`, or `number` with `integers: 'number'` |
+| float | `number` |
+| bool | `boolean` |
+| null | `null` |
+| instant | `Temporal.Instant` |
+| duration | `Temporal.Duration`, in hours and smaller units |
+| array | `Array` |
+| object | plain `Object` |
+*/
+export type Value<Integer extends bigint | number = bigint> =
+	| string
+	| Integer
+	| number
+	| boolean
+	| null // eslint-disable-line @typescript-eslint/no-restricted-types -- The format has a null value, and `parse()` returns `null` for it.
+	| Temporal.Instant
+	| Temporal.Duration
+	| Value<Integer>[] // eslint-disable-line @typescript-eslint/array-type
+	| ObjectValue<Integer>;
+
+/**
+An object in a document.
+*/
+export type ObjectValue<Integer extends bigint | number = bigint> = {[key: string]: Value<Integer>};
+
+/**
+A whole document, which is always an object or an array.
+*/
+export type Document<Integer extends bigint | number = bigint> = ObjectValue<Integer> | Array<Value<Integer>>;
+
+export type ParseOptions = {
+	/**
+	How an int is represented.
+
+	- `'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.
+
+	@default 'bigint'
+	*/
+	readonly integers?: 'bigint' | 'number';
+};
+
+export type StringifyOptions = {
+	/**
+	How an int is represented in the 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';
+};
+
+/**
+Parse a document.
+
+@param text - The document, as a string or as UTF-8 bytes.
+@returns The object or array the document contains.
+@throws {ParseError} When the document is not valid.
+@throws {TypeError} When `text` is not a string or a `Uint8Array`, or `options.integers` is not `'bigint'` or `'number'`.
+
+@example
+```
+import {parse} from 'soml';
+
+parse(`
+name: 'api-gateway'
+replicas: 3
+timeout: 30.0
+postgres.host: 'db.internal'
+`);
+//=> {name: 'api-gateway', replicas: 3n, timeout: 30, postgres: {host: 'db.internal'}}
+
+parse('replicas: 3', {integers: 'number'});
+//=> {replicas: 3}
+```
+*/
+export function parse(text: string | Uint8Array, options?: ParseOptions & {readonly integers?: 'bigint'}): Document;
+export function parse(text: string | Uint8Array, options: ParseOptions & {readonly integers: 'number'}): Document<number>;
+export function parse(text: string | Uint8Array, options?: ParseOptions): Document | Document<number>;
+
+/**
+Serialize an object or an array to canonical form.
+
+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.
+
+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.
+
+@param value - A plain object or an array.
+@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 1000 levels deep.
+
+@example
+```
+import {stringify} from 'soml';
+
+stringify({name: 'api-gateway', replicas: 3n, timeout: 30});
+//=> "name: 'api-gateway'\nreplicas: 3\ntimeout: 30.0\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: object, options?: StringifyOptions): string; // eslint-disable-line @typescript-eslint/no-restricted-types
+
+/**
+Thrown by `parse()` when the input is not a valid document.
+
+The `message` includes the position and a code frame. Use `reason` for the message alone.
+*/
+export class ParseError extends SyntaxError {
+	/**
+	Only `parse()` creates a `ParseError`.
+	*/
+	private constructor();
+
+	readonly name: 'ParseError';
+
+	/**
+	What is wrong, without the position.
+	*/
+	readonly reason: string;
+
+	/**
+	The 1-based line of the error.
+	*/
+	readonly line: number;
+
+	/**
+	The 1-based column of the error, counted in Unicode code points.
+	*/
+	readonly column: number;
+
+	/**
+	The 0-based UTF-16 index of the error in the decoded text.
+	*/
+	readonly offset: number;
+
+	/**
+	Up to three lines ending at the error, with a caret under the position. A long line is clipped around the position.
+	*/
+	readonly codeFrame: string;
+}

package/index.js

@@ -0,0 +1,3 @@
+export {parse} from './source/parse.js';
+export {stringify} from './source/stringify.js';
+export {ParseError} from './source/error.js';

package/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -0,0 +1,91 @@
+{
+	"name": "soml-lang",
+	"version": "0.0.1",
+	"description": "Reference parser and canonical serializer 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"
+	},
+	"sideEffects": false,
+	"engines": {
+		"node": ">=26"
+	},
+	"scripts": {
+		"test": "xo && node --test && tsc",
+		"bench": "node bench/index.js"
+	},
+	"files": [
+		"index.js",
+		"index.d.ts",
+		"source"
+	],
+	"keywords": [
+		"config",
+		"configuration",
+		"parse",
+		"parser",
+		"stringify",
+		"serialize",
+		"canonical",
+		"json",
+		"toml",
+		"yaml"
+	],
+	"devDependencies": {
+		"json5": "^2.2.3",
+		"smol-toml": "^1.9.0",
+		"typescript": "^6.0.3",
+		"xo": "^5.0.1"
+	},
+	"xo": [
+		{
+			"ignores": [
+				"test/conformance/**",
+				"test/fixtures/**"
+			]
+		},
+		{
+			"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"
+			}
+		},
+		{
+			"files": [
+				"test/**"
+			],
+			"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"
+			}
+		}
+	]
+}

package/readme.md

@@ -0,0 +1,224 @@
+# soml
+
+> The reference parser and canonical serializer for [SOML](../readme.md), a config format for humans
+
+> [!NOTE]
+> The format is a draft. See the [specification](../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 more than 800 cases, plus property tests and fuzzing
+
+## Install
+
+```sh
+npm install soml
+```
+
+Requires Node.js 26 or later, for `Temporal`.
+
+## Usage
+
+```js
+import {parse, stringify} from 'soml';
+
+const config = parse(`
+# The edge service.
+name: 'api-gateway'
+replicas: 3
+timeout: 30.0
+grace: 1m30s
+deployed-at: 2026-09-19T14:00:00Z
+postgres.host: 'db.internal'
+`);
+//=> {
+// 	name: 'api-gateway',
+// 	replicas: 3n,
+// 	timeout: 30,
+// 	grace: Temporal.Duration <PT1M30S>,
+// 	'deployed-at': Temporal.Instant <2026-09-19T14:00:00Z>,
+// 	postgres: {host: 'db.internal'},
+// }
+
+stringify(config);
+//=> `deployed-at: 2026-09-19T14:00:00Z
+// grace: 1m30s
+// name: 'api-gateway'
+// postgres: {
+// 	host: 'db.internal',
+// }
+// replicas: 3
+// timeout: 30.0
+// `
+```
+
+> [!IMPORTANT]
+> An int is a `bigint` and a float is a `number`, in both directions. So `stringify({port: 8080})` writes `port: 8080.0`, a float. Write `8080n`, or pass `{integers: 'number'}`.
+
+## Types
+
+| SOML | JavaScript | `integers: 'number'` |
+|---|---|---|
+| string | `string` | |
+| int | `bigint` | `number` |
+| float | `number` | |
+| bool | `boolean` | |
+| null | `null` | |
+| instant | [`Temporal.Instant`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant) | |
+| duration | [`Temporal.Duration`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration), in hours and smaller units | |
+| array | `Array` | |
+| object | plain `Object` | |
+
+The specification says that a reader which conflates `3` and `3.0` is not conforming, and that every 64-bit int must be exact. `bigint` for an int and `number` for a float is the one mapping onto JavaScript primitives that does both, so it is the default.
+
+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`.
+
+## API
+
+### parse(text, options?)
+
+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.
+
+#### text
+
+Type: `string | Uint8Array`
+
+The document. A `Uint8Array` is decoded as UTF-8, and invalid UTF-8 is reported with its position.
+
+#### options
+
+Type: `object`
+
+##### integers
+
+Type: `'bigint' | 'number'`\
+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.
+
+```js
+parse('port: 8080', {integers: 'number'});
+//=> {port: 8080}
+```
+
+### 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.
+
+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.
+
+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 1000 levels.
+
+#### options
+
+Type: `object`
+
+##### integers
+
+Type: `'bigint' | 'number'`\
+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.
+
+```js
+stringify({port: 8080});
+//=> 'port: 8080.0\n'
+
+stringify({port: 8080}, {integers: 'number'});
+//=> 'port: 8080\n'
+```
+
+### ParseError
+
+Thrown by `parse()`. Extends `SyntaxError`.
+
+```js
+import {parse, ParseError} from 'soml';
+
+try {
+	parse('name: api-gateway');
+} catch (error) {
+	if (error instanceof ParseError) {
+		console.log(error.message);
+	}
+}
+// Unexpected "api-gateway". A string value must be quoted, as in 'api-gateway' at line 1, column 7
+//
+// > 1 | name: api-gateway
+//     |       ^
+```
+
+#### reason
+
+Type: `string`
+
+What is wrong, without the position.
+
+#### line
+
+Type: `number`
+
+The 1-based line.
+
+#### column
+
+Type: `number`
+
+The 1-based column, counted in Unicode code points.
+
+#### offset
+
+Type: `number`
+
+The 0-based UTF-16 index in the decoded text.
+
+#### codeFrame
+
+Type: `string`
+
+Up to three lines ending at the error, with a caret under the position. A long line is clipped around the position.
+
+## Limits
+
+- **Nesting is limited to 1000 levels**, in `parse()` and in `stringify()`. A recursive parser would otherwise end with an engine stack overflow. A dotted key counts each segment.
+- **No formatter yet.** The specification defines a formatter that keeps comments, member order, and the author's spelling. This package only writes canonical form.
+
+## 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`.
+- `invalid/**/name.soml` must be rejected.
+
+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.
+
+## Benchmark
+
+```sh
+npm run bench
+```
+
+The same 2.6 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 |
+
+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.
+
+`JSON` is native code and a much smaller grammar, so it is the ceiling rather than a competitor.

package/source/error.js

@@ -0,0 +1,130 @@
+const CONTEXT_LINES = 2;
+const MAX_LINE_WIDTH = 100;
+
+// With the `v` flag, a surrogate in the class matches only when it is unpaired.
+const UNPRINTABLE = /[\p{Bidi_Control}\u{D800}-\u{DFFF}[\p{Control}--\t]]/gv;
+
+/**
+Thrown by `parse()` when the input is not a valid document.
+*/
+export class ParseError extends SyntaxError {
+	name = 'ParseError';
+
+	constructor(reason, source, offset) {
+		const sanitizedReason = sanitize(reason);
+		const {line, column} = locate(source, offset);
+		const codeFrame = createCodeFrame(source, offset, line);
+		super(`${sanitizedReason} at line ${line}, column ${column}\n\n${codeFrame}`);
+		this.reason = sanitizedReason;
+		this.line = line;
+		this.column = column;
+		this.offset = offset;
+		this.codeFrame = codeFrame;
+	}
+}
+
+/*
+Line and column are 1-based, and the column counts code points, so an emoji is one column.
+*/
+function locate(source, offset) {
+	let line = 1;
+	let lineStart = 0;
+
+	for (let index = source.indexOf('\n'); index !== -1 && index < offset; index = source.indexOf('\n', index + 1)) {
+		line++;
+		lineStart = index + 1;
+	}
+
+	return {line, column: countCodePoints(source.slice(lineStart, offset)) + 1};
+}
+
+function countCodePoints(string) {
+	let count = 0;
+
+	for (let index = 0; index < string.length; index++) {
+		const code = string.charCodeAt(index);
+
+		// A high surrogate followed by a low one is one code point.
+		if (code >= 0xD8_00 && code <= 0xDB_FF) {
+			const next = string.charCodeAt(index + 1);
+
+			if (next >= 0xDC_00 && next <= 0xDF_FF) {
+				index++;
+			}
+		}
+
+		count++;
+	}
+
+	return count;
+}
+
+function createCodeFrame(source, offset, line) {
+	// The error line and up to two lines before it, found by scanning back from the error, so that an error late in a long document does not split the whole document.
+	const lineStarts = [offset === 0 ? 0 : source.lastIndexOf('\n', offset - 1) + 1];
+
+	while (lineStarts.length <= CONTEXT_LINES && lineStarts[0] > 0) {
+		const searchFrom = lineStarts[0] - 2;
+		lineStarts.unshift(searchFrom < 0 ? 0 : source.lastIndexOf('\n', searchFrom) + 1);
+	}
+
+	const firstLine = line - lineStarts.length + 1;
+	const gutterWidth = String(line).length;
+	const output = [];
+
+	for (const [index, lineStart] of lineStarts.entries()) {
+		const number = firstLine + index;
+		const isErrorLine = number === line;
+		const lineEnd = source.indexOf('\n', lineStart);
+		const {text, pointerOffset} = clip(sanitize(source.slice(lineStart, lineEnd === -1 ? undefined : lineEnd)), isErrorLine ? offset - lineStart : 0);
+		const gutter = `${isErrorLine ? '>' : ' '} ${String(number).padStart(gutterWidth)} |`;
+		output.push(text === '' ? gutter : `${gutter} ${text}`);
+
+		if (isErrorLine) {
+			// Keep the tabs from the line, so the caret lines up whatever the tab width is.
+			const padding = text.slice(0, pointerOffset).replaceAll(/[^\t]/gv, ' ');
+			output.push(`  ${' '.repeat(gutterWidth)} | ${padding}^`);
+		}
+	}
+
+	return output.join('\n');
+}
+
+/*
+The rejected text can hold characters that a terminal acts on rather than shows: control characters such as an escape or a carriage return, bidirectional controls, and lone surrogates. Each becomes U+FFFD, which is also one code unit, so the caret still lines up. Tabs are kept.
+*/
+function sanitize(text) {
+	return text.replaceAll(UNPRINTABLE, '\u{FFFD}');
+}
+
+/*
+A long line, such as a minified document, is cut to a window around the pointer. The cut never splits a surrogate pair.
+*/
+function clip(text, pointerOffset) {
+	if (text.length <= MAX_LINE_WIDTH) {
+		return {text, pointerOffset};
+	}
+
+	let start = Math.max(0, Math.min(pointerOffset - (MAX_LINE_WIDTH / 2), text.length - MAX_LINE_WIDTH));
+	let end = start + MAX_LINE_WIDTH;
+
+	if (isLowSurrogate(text.charCodeAt(start))) {
+		start++;
+	}
+
+	if (isLowSurrogate(text.charCodeAt(end))) {
+		end--;
+	}
+
+	const prefix = start > 0 ? '…' : '';
+	const suffix = end < text.length ? '…' : '';
+
+	return {
+		text: `${prefix}${text.slice(start, end)}${suffix}`,
+		pointerOffset: pointerOffset - start + prefix.length,
+	};
+}
+
+function isLowSurrogate(code) {
+	return code >= 0xDC_00 && code <= 0xDF_FF;
+}