soml-lang 0.0.1 → 0.0.3

package/distribution/index.js

@@ -0,0 +1,10 @@
+// The types use the global `Temporal` types, which TypeScript has in the `esnext.temporal` lib, so a consumer whose `lib` is older gets them too.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference -- A lib can only be loaded with a directive, and `preserve` keeps it in the emitted types.
+/// <reference lib="esnext.temporal" preserve="true" />
+export { parse, } from "./parse.js";
+export { parseTree, visitorKeys, } from "./tree.js";
+export { format, formatEdits } from "./format.js";
+export { edit } from "./edit.js";
+export { stringify, stringifyValue, compareKeys, } from "./stringify.js";
+export { isBareKey } from "./shared.js";
+export { ParseError } from "./error.js";

package/distribution/parse.d.ts

@@ -0,0 +1,131 @@
+/**
+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 | Temporal.Instant | Temporal.Duration | Value<Integer>[] | 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>>;
+/**
+Options for `parse()`.
+*/
+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 ParsedValue = Value<bigint | number> | Time | ParsedValue[] | ParsedObject;
+type ParsedObject = {
+    [key: string]: ParsedValue;
+};
+/**
+Parse a document. Returns an object or an array, because a document is always a collection.
+
+@param text - The document, as a string or as UTF-8 bytes. Invalid UTF-8 is reported with its position.
+@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` is not an object or its `integers` is not `'bigint'` or `'number'`.
+
+@example
+```
+import {parse} from 'soml-lang';
+
+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('port: 8080', {integers: 'number'});
+//=> {port: 8080}
+```
+*/
+export declare function parse(text: string | Uint8Array, options?: ParseOptions & {
+    readonly integers?: 'bigint';
+}): Document;
+/**
+Parse a document. Returns an object or an array, because a document is always a collection.
+
+@param text - The document, as a string or as UTF-8 bytes. Invalid UTF-8 is reported with its position.
+@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` is not an object or its `integers` is not `'bigint'` or `'number'`.
+
+@example
+```
+import {parse} from 'soml-lang';
+
+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('port: 8080', {integers: 'number'});
+//=> {port: 8080}
+```
+*/
+export declare function parse(text: string | Uint8Array, options: ParseOptions & {
+    readonly integers: 'number';
+}): Document<number>;
+/**
+Parse a document. Returns an object or an array, because a document is always a collection.
+
+@param text - The document, as a string or as UTF-8 bytes. Invalid UTF-8 is reported with its position.
+@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` is not an object or its `integers` is not `'bigint'` or `'number'`.
+
+@example
+```
+import {parse} from 'soml-lang';
+
+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('port: 8080', {integers: 'number'});
+//=> {port: 8080}
+```
+*/
+export declare function parse(text: string | Uint8Array, options?: ParseOptions): Document | Document<number>;
+export declare class Time {
+    readonly type: 'Instant' | 'Duration';
+    readonly nanoseconds: bigint;
+    constructor(type: 'Instant' | 'Duration', nanoseconds: bigint);
+    toTemporal(): Temporal.Instant | Temporal.Duration;
+}
+export declare function parseWithTimes(text: string): ParsedObject | ParsedValue[];
+export {};