soml-lang 0.0.2 → 0.0.3

package/distribution/parse.d.ts

@@ -24,6 +24,9 @@ export type ObjectValue<Integer extends bigint | number = bigint> = {
 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.
@@ -35,13 +38,17 @@ export type ParseOptions = {
     */
     readonly integers?: 'bigint' | 'number';
 };
+export type ParsedValue = Value<bigint | number> | Time | ParsedValue[] | ParsedObject;
+type ParsedObject = {
+    [key: string]: ParsedValue;
+};
 /**
-Parse a 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.
+@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.integers` is not `'bigint'` or `'number'`.
+@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
 ```
@@ -55,14 +62,70 @@ postgres.host: 'db.internal'
 `);
 //=> {name: 'api-gateway', replicas: 3n, timeout: 30, postgres: {host: 'db.internal'}}
 
-parse('replicas: 3', {integers: 'number'});
-//=> {replicas: 3}
+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 {};