jsonc-effect 0.2.1 → 0.3.0

package/schemas.js

@@ -0,0 +1,325 @@
+import { Schema } from "effect";
+
+//#region src/schemas.ts
+/**
+* JSONC Schema definitions for tokens, AST nodes, and options.
+*
+* @packageDocumentation
+*/
+/**
+* Token types produced by the JSONC scanner.
+*
+* @remarks
+* Uses string literals instead of numeric enums so that token kinds are
+* self-documenting in debug output, log messages, and test assertions.
+* This avoids the "reverse-mapping" confusion of TypeScript numeric enums
+* and makes pattern-matching with `Schema.Literal` straightforward.
+*
+* @see {@link createScanner} — creates a scanner that emits these token types
+*
+* @public
+*/
+const JsoncSyntaxKind = Schema.Literal("OpenBrace", "CloseBrace", "OpenBracket", "CloseBracket", "Comma", "Colon", "Null", "True", "False", "String", "Number", "LineComment", "BlockComment", "LineBreak", "Trivia", "Unknown", "EOF");
+/**
+* Scanner error codes produced by the JSONC scanner.
+*
+* @remarks
+* `"None"` indicates a successful scan with no errors. All other values
+* describe a specific lexical error encountered while tokenizing input.
+*
+* @see {@link JsoncScanner} — the scanner interface that reports these errors
+*
+* @public
+*/
+const JsoncScanError = Schema.Literal("None", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter", "InvalidSymbol");
+/**
+* A single token produced by the JSONC scanner, carrying its kind, textual
+* value, position within the source, and any scan error.
+*
+* @remarks
+* - `kind` — the {@link (JsoncSyntaxKind:type)} discriminator for this token.
+* - `value` — the raw text slice from the source document.
+* - `offset` — zero-based character offset from the start of the document.
+* - `length` — character length of this token in the source.
+* - `startLine` — zero-based line number where the token begins.
+* - `startCharacter` — zero-based column within `startLine`.
+* - `error` — a {@link (JsoncScanError:type)} code; `"None"` when the token is valid.
+*
+* @see {@link createScanner} — produces a stream of `JsoncToken` instances
+*
+* @example
+* ```ts
+* import { JsoncToken } from "jsonc-effect";
+*
+* const token = new JsoncToken({
+*   kind: "String",
+*   value: '"hello"',
+*   offset: 0,
+*   length: 7,
+*   startLine: 0,
+*   startCharacter: 0,
+*   error: "None",
+* });
+*
+* console.log(token.kind); // "String"
+* console.log(token.value); // '"hello"'
+* ```
+*
+* @privateRemarks
+* `Schema.Class` gives `JsoncToken` structural equality via `Data.Class`
+* under the hood, so two tokens with identical fields are considered equal
+* by `Equal.equals`. This is essential for test assertions and Effect's
+* structural comparison semantics.
+*
+* @public
+*/
+var JsoncToken = class extends Schema.Class("JsoncToken")({
+	kind: JsoncSyntaxKind,
+	value: Schema.String,
+	offset: Schema.Number,
+	length: Schema.Number,
+	startLine: Schema.Number,
+	startCharacter: Schema.Number,
+	error: JsoncScanError
+}) {};
+/**
+* Discriminator values for JSONC AST node types.
+*
+* @remarks
+* These correspond to the JSON value types (`"string"`, `"number"`,
+* `"boolean"`, `"null"`) plus structural types (`"object"`, `"array"`)
+* and the special `"property"` type representing a key-value pair inside
+* an object.
+*
+* @see {@link JsoncNode} — the AST node that carries this discriminator
+*
+* @public
+*/
+const JsoncNodeType = Schema.Literal("object", "array", "property", "string", "number", "boolean", "null");
+/**
+* AST node representing a parsed JSONC element, produced by {@link parseTree}.
+*
+* @remarks
+* The `parent` field present in Microsoft's `jsonc-parser` is intentionally
+* omitted here to avoid circular references, which would break structural
+* equality, serialization, and Effect's `Schema.encode`/`Schema.decode`
+* pipelines. Child relationships are expressed via the `children` array,
+* and the recursive type is handled with `Schema.suspend`.
+*
+* - `type` — the {@link (JsoncNodeType:type)} discriminator.
+* - `value` — the decoded JavaScript value for leaf nodes (`string`,
+*   `number`, `boolean`, `null`); `undefined` for structural nodes.
+* - `offset` — zero-based character offset of this node in the source.
+* - `length` — character length of this node in the source.
+* - `colonOffset` — for `"property"` nodes, the offset of the `:` separator.
+* - `children` — child nodes; present for `"object"`, `"array"`, and
+*   `"property"` nodes.
+*
+* @see {@link parseTree} — produces the root `JsoncNode`
+* @see {@link findNode} — locates a descendant by path
+*
+* @example
+* ```ts
+* import { Effect } from "effect";
+* import { parseTree } from "jsonc-effect";
+*
+* const program = parseTree('{ "key": [1, 2] }').pipe(
+*   Effect.map((root) => {
+*     // root.type === "object"
+*     const property = root.children?.[0]; // "property" node
+*     const array = property?.children?.[1]; // "array" node
+*     console.log(array?.children?.length); // 2
+*   }),
+* );
+* ```
+*
+* @privateRemarks
+* Unlike the `*Base` pattern needed for `Data.TaggedError` subclasses,
+* `Schema.Class` works directly for data types — api-extractor can roll up
+* the generated `.d.ts` without issues. The `Schema.suspend` call for
+* `children` is required to break the circular type reference at the schema
+* level while still allowing recursive decode/encode.
+*
+* @public
+*/
+var JsoncNode = class JsoncNode extends Schema.Class("JsoncNode")({
+	type: JsoncNodeType,
+	value: Schema.optional(Schema.Unknown),
+	offset: Schema.Number,
+	length: Schema.Number,
+	colonOffset: Schema.optional(Schema.Number),
+	children: Schema.optional(Schema.Array(Schema.suspend(() => JsoncNode)))
+}) {};
+/**
+* A single segment of a {@link (JsoncPath:type)}: a `string` for object property
+* keys or a `number` for array indices.
+*
+* @see {@link findNode} — resolves a path to an AST node
+* @see {@link modify} — applies a value change at a path
+*
+* @example
+* ```ts
+* import type { JsoncSegment } from "jsonc-effect";
+*
+* const objectKey: JsoncSegment = "compilerOptions";
+* const arrayIndex: JsoncSegment = 0;
+* ```
+*
+* @public
+*/
+const JsoncSegment = Schema.Union(Schema.String, Schema.Number);
+/**
+* An ordered sequence of {@link (JsoncSegment:type)} values describing a location
+* within a JSONC document tree.
+*
+* @see {@link findNode} — resolves a `JsoncPath` to an AST node
+* @see {@link modify} — applies a modification at a `JsoncPath`
+*
+* @example
+* ```ts
+* import type { JsoncPath } from "jsonc-effect";
+*
+* // Path to the "strict" property inside "compilerOptions"
+* const path: JsoncPath = ["compilerOptions", "strict"];
+*
+* // Path to the second element of the "include" array
+* const arrayPath: JsoncPath = ["include", 1];
+* ```
+*
+* @public
+*/
+const JsoncPath = Schema.Array(JsoncSegment);
+/**
+* A non-mutating text edit describing a replacement within a JSONC document.
+*
+* @remarks
+* Edits use zero-based `offset` and `length` to identify the span of text
+* to replace, and `content` for the replacement string. To insert without
+* removing text, set `length` to `0`. To delete without inserting, set
+* `content` to `""`.
+*
+* Edits returned by {@link format} and {@link modify} should be applied
+* via {@link applyEdits}, which processes them in reverse order so that
+* earlier offsets remain valid.
+*
+* @see {@link format} — produces edits for formatting
+* @see {@link modify} — produces edits for value changes
+* @see {@link applyEdits} — applies an array of edits to a source string
+*
+* @example
+* ```ts
+* import { JsoncEdit } from "jsonc-effect";
+*
+* // An edit that inserts ", true" at offset 10
+* const edit = new JsoncEdit({ offset: 10, length: 0, content: ", true" });
+*
+* console.log(edit.offset); // 10
+* console.log(edit.length); // 0
+* console.log(edit.content); // ", true"
+* ```
+*
+* @public
+*/
+var JsoncEdit = class extends Schema.Class("JsoncEdit")({
+	offset: Schema.Number,
+	length: Schema.Number,
+	content: Schema.String
+}) {};
+/**
+* A range within a JSONC document, expressed as a zero-based character
+* offset and a length in characters.
+*
+* @remarks
+* Both `offset` and `length` are measured in UTF-16 code units (JavaScript
+* string indices). Pass a `JsoncRange` to {@link format} to restrict
+* formatting to a specific region of the document rather than the whole file.
+*
+* @see {@link format} — accepts an optional `JsoncRange` parameter
+*
+* @public
+*/
+var JsoncRange = class extends Schema.Class("JsoncRange")({
+	offset: Schema.Number,
+	length: Schema.Number
+}) {};
+/**
+* Options controlling JSONC parse behavior.
+*
+* @remarks
+* - `disallowComments` — when `true`, line and block comments are treated
+*   as parse errors. Defaults to `false`.
+* - `allowTrailingComma` — when `true`, trailing commas after the last
+*   element in arrays and objects are permitted. Defaults to `true`, which
+*   differs from Microsoft's `jsonc-parser` (where the default is `false`).
+* - `allowEmptyContent` — when `true`, an empty string parses as
+*   `undefined` rather than producing an error. Defaults to `false`.
+*
+* @see {@link parse} — parses JSONC text into a JavaScript value
+* @see {@link parseTree} — parses JSONC text into an AST
+*
+* @example
+* ```ts
+* import { Effect } from "effect";
+* import { parse, JsoncParseOptions } from "jsonc-effect";
+*
+* const options = new JsoncParseOptions({
+*   disallowComments: true,
+*   allowTrailingComma: false,
+* });
+*
+* const program = parse('{ "key": "value" }', options).pipe(
+*   Effect.map((value) => console.log(value)),
+* );
+* ```
+*
+* @public
+*/
+var JsoncParseOptions = class extends Schema.Class("JsoncParseOptions")({
+	disallowComments: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	allowTrailingComma: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	allowEmptyContent: Schema.optionalWith(Schema.Boolean, { default: () => false })
+}) {};
+/**
+* Options controlling JSONC formatting behavior.
+*
+* @remarks
+* - `tabSize` — number of spaces per indentation level. Defaults to `2`.
+* - `insertSpaces` — when `true`, use spaces for indentation; when `false`,
+*   use tab characters. Defaults to `true`.
+* - `eol` — the end-of-line sequence. Defaults to `"\n"`.
+* - `insertFinalNewline` — when `true`, ensure the formatted output ends
+*   with a newline. Defaults to `false`.
+* - `keepLines` — when `true`, preserve existing line breaks in the source
+*   rather than reflowing. Defaults to `false`.
+*
+* @see {@link format} — uses these options to produce formatting edits
+* @see {@link formatAndApply} — formats and applies edits in one step
+*
+* @example
+* ```ts
+* import { Effect } from "effect";
+* import { formatAndApply, JsoncFormattingOptions } from "jsonc-effect";
+*
+* const options = new JsoncFormattingOptions({
+*   tabSize: 4,
+*   insertSpaces: true,
+*   insertFinalNewline: true,
+* });
+*
+* const program = formatAndApply('{"key":"value"}', options).pipe(
+*   Effect.map((formatted) => console.log(formatted)),
+* );
+* ```
+*
+* @public
+*/
+var JsoncFormattingOptions = class extends Schema.Class("JsoncFormattingOptions")({
+	tabSize: Schema.optionalWith(Schema.Number, { default: () => 2 }),
+	insertSpaces: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	eol: Schema.optionalWith(Schema.String, { default: () => "\n" }),
+	insertFinalNewline: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	keepLines: Schema.optionalWith(Schema.Boolean, { default: () => false })
+}) {};
+
+//#endregion
+export { JsoncEdit, JsoncFormattingOptions, JsoncNode, JsoncNodeType, JsoncParseOptions, JsoncRange, JsoncScanError, JsoncSegment, JsoncSyntaxKind, JsoncToken };

package/tsdoc-metadata.json

@@ -1,11 +1,11 @@
-// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
-// It should be published with your NPM package.  It should not be tracked by Git.
-{
-  "tsdocVersion": "0.12",
-  "toolPackages": [
-    {
-      "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.57.7"
-    }
-  ]
-}
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}

package/visitor.js

@@ -0,0 +1,355 @@
+import { createScanner } from "./scanner.js";
+import { Chunk, Effect, Stream } from "effect";
+
+//#region src/visitor.ts
+/**
+* SAX-style visitor API for JSONC documents.
+*
+* Emits typed events as an Effect Stream, enabling memory-efficient
+* processing of large JSONC documents via lazy evaluation.
+*
+* @packageDocumentation
+*/
+/**
+* Create a lazy `Stream` of {@link JsoncVisitorEvent} from JSONC text.
+*
+* Events are produced on demand as the stream is consumed, not
+* pre-collected into memory. This makes `visit` suitable for large
+* documents and supports early termination via `Stream.take` or
+* `Stream.takeWhile` without scanning the entire input.
+*
+* @param text - The JSONC source text to visit.
+* @param options - Optional partial {@link JsoncParseOptions} controlling
+*   comment handling and trailing-comma tolerance.
+* @returns A `Stream` of {@link JsoncVisitorEvent} objects.
+*
+* @remarks
+* The stream is backed by a lazy generator — no work is performed until
+* the stream is consumed. Because evaluation is demand-driven, combining
+* `visit` with `Stream.take` allows efficient partial scans of large
+* documents without allocating a full AST.
+*
+* @see {@link visitCollect} for a one-step filter-and-collect convenience.
+* @see {@link JsoncVisitorEvent} for the event type definitions.
+*
+* @example Collect all events
+* ```ts
+* import { Chunk, Effect, Stream } from "effect";
+* import { visit } from "jsonc-effect";
+*
+* const all = Effect.runSync(
+*   visit('{ "a": 1 }').pipe(
+*     Stream.runCollect,
+*     Effect.map(Chunk.toReadonlyArray),
+*   ),
+* );
+* ```
+*
+* @example Filter and take the first match
+* ```ts
+* import { Chunk, Effect, Stream } from "effect";
+* import { visit } from "jsonc-effect";
+*
+* const firstLiteral = Effect.runSync(
+*   visit('{ "a": 1, "b": 2 }').pipe(
+*     Stream.filter((e) => e._tag === "LiteralValue"),
+*     Stream.take(1),
+*     Stream.runCollect,
+*     Effect.map(Chunk.toReadonlyArray),
+*   ),
+* );
+* ```
+*
+* @example Extract property names
+* ```ts
+* import { Chunk, Effect, Stream } from "effect";
+* import { visit } from "jsonc-effect";
+*
+* const propertyNames = Effect.runSync(
+*   visit('{ "name": "Alice", "age": 30 }').pipe(
+*     Stream.filter((e) => e._tag === "ObjectProperty"),
+*     Stream.map((e) => (e as { property: string }).property),
+*     Stream.runCollect,
+*     Effect.map(Chunk.toReadonlyArray),
+*   ),
+* );
+* ```
+*
+* @privateRemarks
+* Internally wraps a generator function with `Stream.fromIterable`,
+* preserving laziness. The generator yields events as it encounters
+* tokens from the scanner.
+*
+* @public
+*/
+const visit = (text, options) => Stream.fromIterable(visitGen(text, options));
+/**
+* Visit JSONC text and collect all events matching a type-guard predicate.
+*
+* This is a convenience that composes {@link visit}, `Stream.filter`, and
+* `Stream.runCollect` into a single call.
+*
+* @param text - The JSONC source text to visit.
+* @param predicate - A type-guard function that narrows
+*   {@link JsoncVisitorEvent} to the desired subtype `A`.
+* @param options - Optional partial {@link JsoncParseOptions}.
+* @returns An `Effect` that succeeds with a read-only array of the
+*   matched events.
+*
+* @remarks
+* Equivalent to:
+* ```
+* visit(text, options) |> Stream.filter(predicate) |> Stream.runCollect
+* ```
+* Use this when you need all matching events and do not require
+* intermediate stream transformations.
+*
+* @see {@link visit} for full stream-level control.
+*
+* @example Collecting literal values
+* ```ts
+* import { Effect } from "effect";
+* import type { JsoncVisitorEvent } from "jsonc-effect";
+* import { visitCollect } from "jsonc-effect";
+*
+* const literals = Effect.runSync(
+*   visitCollect(
+*     '{ "a": 1, "b": true }',
+*     (e): e is Extract<JsoncVisitorEvent, { _tag: "LiteralValue" }> =>
+*       e._tag === "LiteralValue",
+*   ),
+* );
+* ```
+*
+* @public
+*/
+const visitCollect = (text, predicate, options) => visit(text, options).pipe(Stream.filter(predicate), Stream.runCollect, Effect.map(Chunk.toReadonlyArray));
+function* visitGen(text, options) {
+	const scanner = createScanner(text, false);
+	const disallowComments = options?.disallowComments ?? false;
+	const path = [];
+	function* scanNext() {
+		for (;;) {
+			const t = scanner.scan();
+			const scanError = scanner.getTokenError();
+			if (scanError !== "None") {
+				let code;
+				switch (scanError) {
+					case "InvalidUnicode":
+						code = "InvalidUnicode";
+						break;
+					case "InvalidEscapeCharacter":
+						code = "InvalidEscapeCharacter";
+						break;
+					case "UnexpectedEndOfNumber":
+						code = "InvalidNumberFormat";
+						break;
+					case "UnexpectedEndOfComment":
+						code = "UnexpectedEndOfComment";
+						break;
+					case "UnexpectedEndOfString":
+						code = "UnexpectedEndOfString";
+						break;
+					case "InvalidCharacter":
+						code = "InvalidCharacter";
+						break;
+					default: code = "InvalidSymbol";
+				}
+				yield {
+					_tag: "Error",
+					code,
+					offset: scanner.getTokenOffset(),
+					length: scanner.getTokenLength()
+				};
+			}
+			switch (t) {
+				case "LineComment":
+				case "BlockComment":
+					if (disallowComments) yield {
+						_tag: "Error",
+						code: "InvalidCommentToken",
+						offset: scanner.getTokenOffset(),
+						length: scanner.getTokenLength()
+					};
+					else yield {
+						_tag: "Comment",
+						offset: scanner.getTokenOffset(),
+						length: scanner.getTokenLength()
+					};
+					break;
+				case "Trivia":
+				case "LineBreak": break;
+				default: return t;
+			}
+		}
+	}
+	function getLiteralValue(kind, tokenValue) {
+		switch (kind) {
+			case "String": return tokenValue;
+			case "Number": return Number.parseFloat(tokenValue);
+			case "True": return true;
+			case "False": return false;
+			case "Null": return null;
+			default: return;
+		}
+	}
+	function* visitValue() {
+		const t = scanner.getToken();
+		switch (t) {
+			case "OpenBrace": return yield* visitObject();
+			case "OpenBracket": return yield* visitArray();
+			case "String":
+			case "Number":
+			case "True":
+			case "False":
+			case "Null":
+				yield {
+					_tag: "LiteralValue",
+					value: getLiteralValue(t, scanner.getTokenValue()),
+					offset: scanner.getTokenOffset(),
+					length: scanner.getTokenLength(),
+					path: [...path]
+				};
+				yield* scanNext();
+				return true;
+			default:
+				yield {
+					_tag: "Error",
+					code: "ValueExpected",
+					offset: scanner.getTokenOffset(),
+					length: scanner.getTokenLength()
+				};
+				return false;
+		}
+	}
+	function* visitObject() {
+		yield {
+			_tag: "ObjectBegin",
+			offset: scanner.getTokenOffset(),
+			length: scanner.getTokenLength(),
+			path: [...path]
+		};
+		yield* scanNext();
+		let needsComma = false;
+		while (scanner.getToken() !== "CloseBrace" && scanner.getToken() !== "EOF") {
+			if (scanner.getToken() === "Comma") {
+				yield {
+					_tag: "Separator",
+					character: ",",
+					offset: scanner.getTokenOffset(),
+					length: scanner.getTokenLength()
+				};
+				yield* scanNext();
+				if (scanner.getToken() === "CloseBrace") break;
+			} else if (needsComma) yield {
+				_tag: "Error",
+				code: "CommaExpected",
+				offset: scanner.getTokenOffset(),
+				length: scanner.getTokenLength()
+			};
+			if (scanner.getToken() !== "String") {
+				yield {
+					_tag: "Error",
+					code: "PropertyNameExpected",
+					offset: scanner.getTokenOffset(),
+					length: scanner.getTokenLength()
+				};
+				yield* scanNext();
+				continue;
+			}
+			const key = scanner.getTokenValue();
+			yield {
+				_tag: "ObjectProperty",
+				property: key,
+				offset: scanner.getTokenOffset(),
+				length: scanner.getTokenLength(),
+				path: [...path]
+			};
+			path.push(key);
+			yield* scanNext();
+			if (scanner.getToken() === "Colon") {
+				yield {
+					_tag: "Separator",
+					character: ":",
+					offset: scanner.getTokenOffset(),
+					length: scanner.getTokenLength()
+				};
+				yield* scanNext();
+			} else yield {
+				_tag: "Error",
+				code: "ColonExpected",
+				offset: scanner.getTokenOffset(),
+				length: scanner.getTokenLength()
+			};
+			yield* visitValue();
+			path.pop();
+			needsComma = true;
+		}
+		if (scanner.getToken() === "CloseBrace") {
+			yield {
+				_tag: "ObjectEnd",
+				offset: scanner.getTokenOffset(),
+				length: scanner.getTokenLength()
+			};
+			yield* scanNext();
+		} else yield {
+			_tag: "Error",
+			code: "CloseBraceExpected",
+			offset: scanner.getTokenOffset(),
+			length: scanner.getTokenLength()
+		};
+		return true;
+	}
+	function* visitArray() {
+		yield {
+			_tag: "ArrayBegin",
+			offset: scanner.getTokenOffset(),
+			length: scanner.getTokenLength(),
+			path: [...path]
+		};
+		yield* scanNext();
+		let index = 0;
+		let needsComma = false;
+		while (scanner.getToken() !== "CloseBracket" && scanner.getToken() !== "EOF") {
+			if (scanner.getToken() === "Comma") {
+				yield {
+					_tag: "Separator",
+					character: ",",
+					offset: scanner.getTokenOffset(),
+					length: scanner.getTokenLength()
+				};
+				yield* scanNext();
+				if (scanner.getToken() === "CloseBracket") break;
+			} else if (needsComma) yield {
+				_tag: "Error",
+				code: "CommaExpected",
+				offset: scanner.getTokenOffset(),
+				length: scanner.getTokenLength()
+			};
+			path.push(index);
+			yield* visitValue();
+			path.pop();
+			index++;
+			needsComma = true;
+		}
+		if (scanner.getToken() === "CloseBracket") {
+			yield {
+				_tag: "ArrayEnd",
+				offset: scanner.getTokenOffset(),
+				length: scanner.getTokenLength()
+			};
+			yield* scanNext();
+		} else yield {
+			_tag: "Error",
+			code: "CloseBracketExpected",
+			offset: scanner.getTokenOffset(),
+			length: scanner.getTokenLength()
+		};
+		return true;
+	}
+	yield* scanNext();
+	if (scanner.getToken() !== "EOF") yield* visitValue();
+}
+
+//#endregion
+export { visit, visitCollect };