jsonc-effect 0.2.0 → 0.3.0

package/index.d.ts

@@ -1,1983 +1,1933 @@
-/**
- * jsonc-effect
- *
- * Pure Effect-TS implementation of a JSONC (JSON with Comments) parser.
- * No external parser dependencies — scanner, parser, AST, and formatting
- * are all implemented natively in Effect.
- *
- * @packageDocumentation
- */
-
-import { Effect } from 'effect';
-import { Equals } from 'effect/Types';
-import { Option } from 'effect';
-import { Schema } from 'effect';
-import { Stream } from 'effect';
-import { YieldableError } from 'effect/Cause';
-
-/**
- * Apply an array of text edits to JSONC source text.
- *
- * This is a {@link https://effect.website/docs/function-dual | Function.dual}
- * that supports both data-first and data-last (pipeline) usage.
- *
- * @param text - The original JSONC source text.
- * @param edits - A read-only array of {@link JsoncEdit} objects, typically
- *   produced by {@link format} or {@link modify}.
- * @returns An `Effect` that succeeds with the edited string.
- *
- * @remarks
- * Edits are sorted in reverse offset order before application so that
- * earlier edits do not shift the offsets of later ones. The original `edits`
- * array is not mutated.
- *
- * @see {@link format} to compute formatting edits.
- * @see {@link modify} to compute structural edits (insert, replace, remove).
- *
- * @example Data-first usage
- * ```ts
- * import { Effect } from "effect";
- * import { format, applyEdits } from "jsonc-effect";
- *
- * const input = '{"a":1}';
- * const edits = Effect.runSync(format(input));
- * const result: string = Effect.runSync(applyEdits(input, edits));
- * ```
- *
- * @example Pipeline with modify
- * ```ts
- * import { Effect, pipe } from "effect";
- * import { modify, applyEdits } from "jsonc-effect";
- *
- * const input = '{ "a": 1 }';
- * const result = pipe(
- *   input,
- *   modify(["a"], 42),
- *   Effect.flatMap((edits) => applyEdits(input, edits)),
- *   Effect.runSync,
- * );
- * ```
- *
- * @public
- */
-export declare const applyEdits: {
-    (edits: ReadonlyArray<JsoncEdit>): (text: string) => Effect.Effect<string>;
-    (text: string, edits: ReadonlyArray<JsoncEdit>): Effect.Effect<string>;
-};
-
-/**
- * Create a stateful {@link JsoncScanner} for the given JSONC string.
- *
- * @param text - JSONC string to tokenize
- * @param ignoreTrivia - If `true`, the scanner automatically skips whitespace,
- *   line-break, and comment tokens so that only structural tokens are returned
- *   (default: `false`).
- * @returns A stateful {@link JsoncScanner} positioned before the first token.
- *
- * @remarks
- * When `ignoreTrivia` is `true` the scanner is suitable for building parsers
- * that only care about structural tokens (`OpenBrace`, `String`, `Number`,
- * etc.). Set it to `false` (the default) when you need to preserve comments
- * or whitespace — for example in a formatter or a comment-stripping pass.
- *
- * @see {@link JsoncScanner} — the interface returned by this factory
- * @see {@link parse} — higher-level API that uses a scanner internally
- *
- * @example
- * Tokenizing a JSONC string and printing each token:
- * ```ts
- * import type { JsoncSyntaxKind } from "jsonc-effect";
- * import { createScanner } from "jsonc-effect";
- *
- * const scanner = createScanner('{ "name": "jsonc" }', true);
- * let kind: JsoncSyntaxKind;
- * do {
- *   kind = scanner.scan();
- *   console.log(kind, scanner.getTokenValue());
- * } while (kind !== "EOF");
- * ```
- *
- * @privateRemarks
- * Ported from Microsoft's jsonc-parser (MIT), adapted to use string literal
- * token types instead of numeric enums.
- *
- * @public
- */
-export declare const createScanner: (text: string, ignoreTrivia?: boolean) => JsoncScanner;
-
-/**
- * Compare two JSONC strings for semantic equality.
- *
- * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
- * for both data-first and data-last (pipeline) usage.
- *
- * @param self - The first JSONC string.
- * @param that - The second JSONC string.
- *
- * @returns `Effect<boolean, JsoncParseError>` — `true` when both strings parse to
- *   semantically equivalent values, `false` otherwise. Fails with
- *   {@link JsoncParseError} if either string is malformed.
- *
- * @remarks
- * Both strings are parsed via {@link parse} and then deep-compared. The comparison
- * ignores comments, whitespace, formatting, and object key ordering. Array order
- * IS significant. Uses `Effect.all` internally, so the effect fails on the first
- * parse error encountered.
- *
- * @see {@link equalsValue} — compare a JSONC string against an existing JS value
- * @see {@link parse} — the underlying parser used for both strings
- *
- * @example Data-first comparison
- * ```ts
- * import { Effect } from "effect";
- * import { equals } from "jsonc-effect";
- *
- * const result = Effect.runSync(
- *   equals('{ "a": 1, "b": 2 }', '{"b":2,"a":1}')
- * );
- * // result is true
- * ```
- *
- * @example Key-order independence
- * ```ts
- * import { Effect } from "effect";
- * import { equals } from "jsonc-effect";
- *
- * // Object key order does not matter
- * const sameKeys = Effect.runSync(
- *   equals('{"z":1,"a":2}', '{"a":2,"z":1}')
- * );
- * // sameKeys is true
- *
- * // Array order DOES matter
- * const differentOrder = Effect.runSync(
- *   equals('[1, 2]', '[2, 1]')
- * );
- * // differentOrder is false
- * ```
- *
- * @example Error handling
- * ```ts
- * import { Effect, Either } from "effect";
- * import type { JsoncParseError } from "jsonc-effect";
- * import { equals } from "jsonc-effect";
- *
- * const result: Either.Either<boolean, JsoncParseError> = Effect.runSync(
- *   Effect.either(equals('{ invalid }', '{}'))
- * );
- * // result is Either.left(JsoncParseError)
- * ```
- *
- * @privateRemarks
- * Uses a simple recursive `deepEqual` helper rather than Effect's `Equal` module
- * because the parsed values are plain JS objects and arrays, not Effect data types.
- *
- * @public
- */
-export declare const equals: {
-    (that: string): (self: string) => Effect.Effect<boolean, JsoncParseError>;
-    (self: string, that: string): Effect.Effect<boolean, JsoncParseError>;
-};
-
-/**
- * Compare a JSONC string against a JavaScript value for semantic equality.
- *
- * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
- * for both data-first and data-last (pipeline) usage.
- *
- * @param self - The JSONC string to parse.
- * @param value - The JavaScript value to compare against.
- *
- * @returns `Effect<boolean, JsoncParseError>` — `true` when the parsed JSONC
- *   is semantically equivalent to the provided value, `false` otherwise.
- *   Fails with {@link JsoncParseError} if the string is malformed.
- *
- * @remarks
- * Only the JSONC string is parsed; the JS value is used as-is. This makes
- * `equalsValue` useful for assertions and testing where the expected value
- * is already a JS object. The comparison semantics are the same as
- * {@link equals}: comments, whitespace, formatting, and object key ordering
- * are ignored, while array order IS significant.
- *
- * @see {@link equals} — compare two JSONC strings against each other
- * @see {@link parse} — the underlying parser
- *
- * @example Basic comparison
- * ```ts
- * import { Effect } from "effect";
- * import { equalsValue } from "jsonc-effect";
- *
- * const result = Effect.runSync(
- *   equalsValue('{"port": 3000, "host": "localhost"}', { host: "localhost", port: 3000 })
- * );
- * // result is true
- * ```
- *
- * @example Pipeline usage for testing
- * ```ts
- * import { Effect, pipe } from "effect";
- * import { equalsValue } from "jsonc-effect";
- *
- * const jsonc = '{ "enabled": true, "count": 5 }';
- * const expected = { enabled: true, count: 5 };
- *
- * const result = Effect.runSync(
- *   pipe(jsonc, equalsValue(expected))
- * );
- * // result is true
- * ```
- *
- * @public
- */
-export declare const equalsValue: {
-    (value: unknown): (self: string) => Effect.Effect<boolean, JsoncParseError>;
-    (self: string, value: unknown): Effect.Effect<boolean, JsoncParseError>;
-};
-
-/**
- * Find an AST node at a specific JSON path.
- *
- * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
- * for both data-first and data-last (pipeline) usage.
- *
- * @param root - The AST root node obtained from {@link parseTree}.
- * @param path - An array of string keys and numeric indices describing the path to traverse.
- *
- * @returns `Effect<Option<JsoncNode>>` — the node at the given path, or `Option.none()` if the
- *   path does not exist in the tree.
- *
- * @remarks
- * String segments navigate object properties and number segments navigate array indices.
- * Returns `Option.none()` when any segment along the path cannot be resolved — for example,
- * accessing a property on a non-object node or an out-of-bounds array index.
- *
- * @see {@link parseTree} — produces the AST root this function operates on
- * @see {@link getNodeValue} — reconstructs a JS value from a found node
- * @see {@link JsoncNode} — the AST node type
- * @see {@link JsoncPath} — the path segment array type
- *
- * @example Data-first usage
- * ```ts
- * import { Effect, Option } from "effect";
- * import type { JsoncNode } from "jsonc-effect";
- * import { parseTree, findNode } from "jsonc-effect";
- *
- * const program = Effect.gen(function* () {
- *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "a": { "b": 1 } }');
- *   if (Option.isNone(root)) return Option.none();
- *   return yield* findNode(root.value, ["a", "b"]);
- * });
- *
- * const result = Effect.runSync(program);
- * // result is Option.some(node) where node.value === 1
- * ```
- *
- * @example Data-last pipeline usage
- * ```ts
- * import { Effect, Option, pipe } from "effect";
- * import type { JsoncNode } from "jsonc-effect";
- * import { parseTree, findNode } from "jsonc-effect";
- *
- * const program = Effect.gen(function* () {
- *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "x": [10, 20] }');
- *   if (Option.isNone(root)) return Option.none();
- *   return yield* pipe(root.value, findNode(["x", 1]));
- * });
- *
- * const result = Effect.runSync(program);
- * // result is Option.some(node) where node.value === 20
- * ```
- *
- * @privateRemarks
- * Wrapped in `Effect.sync`; the underlying traversal is fully synchronous.
- *
- * @public
- */
-export declare const findNode: {
-    (path: JsoncPath): (root: JsoncNode) => Effect.Effect<Option.Option<JsoncNode>>;
-    (root: JsoncNode, path: JsoncPath): Effect.Effect<Option.Option<JsoncNode>>;
-};
-
-/**
- * Find the innermost AST node covering a character offset.
- *
- * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
- * for both data-first and data-last (pipeline) usage.
- *
- * @param root - The AST root node obtained from {@link parseTree}.
- * @param offset - A zero-based character offset into the original JSONC string.
- *
- * @returns `Effect<Option<JsoncNode>>` — the most deeply nested node whose span
- *   includes the offset, or `Option.none()` if the offset is outside the tree.
- *
- * @remarks
- * This is useful for editor integrations such as hover information, go-to-definition,
- * and code completions where you need to identify the token under the cursor.
- *
- * @see {@link parseTree} — produces the AST root this function operates on
- * @see {@link getNodePath} — returns the JSON path to the node at an offset
- *
- * @example Finding a node at an offset
- * ```ts
- * import { Effect, Option } from "effect";
- * import type { JsoncNode } from "jsonc-effect";
- * import { parseTree, findNodeAtOffset } from "jsonc-effect";
- *
- * const program = Effect.gen(function* () {
- *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "key": "value" }');
- *   if (Option.isNone(root)) return Option.none();
- *   // Offset 10 is inside the "value" string literal
- *   return yield* findNodeAtOffset(root.value, 10);
- * });
- *
- * const result = Effect.runSync(program);
- * // result is Option.some(node) where node.type === "string"
- * ```
- *
- * @privateRemarks
- * Wrapped in `Effect.sync`; the underlying traversal is fully synchronous.
- *
- * @public
- */
-export declare const findNodeAtOffset: {
-    (offset: number): (root: JsoncNode) => Effect.Effect<Option.Option<JsoncNode>>;
-    (root: JsoncNode, offset: number): Effect.Effect<Option.Option<JsoncNode>>;
-};
-
-/**
- * Compute formatting edits for a JSONC document.
- *
- * Returns an array of {@link JsoncEdit} objects describing text replacements
- * that, when applied, produce a well-formatted document. The input text is
- * never mutated — apply the returned edits with {@link applyEdits}.
- *
- * @param text - The JSONC source text to format.
- * @param range - Optional sub-range to format. When provided, only edits
- *   within the range are returned.
- * @param options - Partial {@link JsoncFormattingOptions} controlling indent
- *   size, tabs vs. spaces, EOL style, and final-newline insertion.
- * @returns An `Effect` that succeeds with a read-only array of
- *   {@link JsoncEdit} objects.
- *
- * @remarks
- * This function is non-mutating by design. It computes a minimal set of
- * whitespace edits; structural changes (inserting or removing properties)
- * are handled by {@link modify}. The `range` parameter allows formatting a
- * subset of the document without touching surrounding text.
- *
- * @see {@link applyEdits} to apply the returned edits to the source text.
- * @see {@link formatAndApply} for a one-step format-and-apply convenience.
- * @see {@link JsoncFormattingOptions} for available formatting controls.
- *
- * @example
- * ```ts
- * import { Effect } from "effect";
- * import type { JsoncEdit } from "jsonc-effect";
- * import { format, applyEdits } from "jsonc-effect";
- *
- * const input = '{"a":1, "b" :2}';
- * const edits: ReadonlyArray<JsoncEdit> = Effect.runSync(format(input));
- * const formatted: string = Effect.runSync(applyEdits(input, edits));
- * ```
- *
- * @privateRemarks
- * Uses {@link createScanner} internally to tokenize the input and compute
- * whitespace adjustments between consecutive non-trivia tokens.
- *
- * @public
- */
-export declare const format: (text: string, range?: JsoncRange | undefined, options?: Partial<JsoncFormattingOptions> | undefined) => Effect.Effect<readonly JsoncEdit[], never, never>;
-
-/**
- * Format a JSONC document in one step by computing edits and immediately
- * applying them.
- *
- * This is a convenience that combines {@link format} and {@link applyEdits}
- * into a single call.
- *
- * @param text - The JSONC source text to format.
- * @param range - Optional sub-range to restrict formatting to.
- * @param options - Partial {@link JsoncFormattingOptions} controlling indent
- *   size, tabs vs. spaces, EOL style, and final-newline insertion.
- * @returns An `Effect` that succeeds with the fully formatted string.
- *
- * @see {@link format} to obtain the edits without applying them.
- * @see {@link applyEdits} to apply edits separately.
- *
- * @example
- * ```ts
- * import { Effect } from "effect";
- * import { formatAndApply } from "jsonc-effect";
- *
- * const input = '{"a":1, "b" :2}';
- * const formatted: string = Effect.runSync(formatAndApply(input));
- * ```
- *
- * @public
- */
-export declare const formatAndApply: (text: string, range?: JsoncRange | undefined, options?: Partial<JsoncFormattingOptions> | undefined) => Effect.Effect<string, never, never>;
-
-/**
- * Get the JSON path to the node at a specific character offset.
- *
- * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
- * for both data-first and data-last (pipeline) usage.
- *
- * @param root - The AST root node obtained from {@link parseTree}.
- * @param targetOffset - A zero-based character offset into the original JSONC string.
- *
- * @returns `Effect<Option<JsoncPath>>` — an array of path segments (string keys
- *   and numeric indices) leading to the innermost node at the offset, or
- *   `Option.none()` if the offset is outside the tree.
- *
- * @remarks
- * Returns the path segments leading to the innermost node that spans the given
- * offset. This is the inverse of {@link findNode} — given an offset you get the path,
- * and given a path you get the node.
- *
- * @see {@link findNodeAtOffset} — returns the node itself rather than its path
- * @see {@link JsoncPath} — the path segment array type
- *
- * @example Getting the path at an offset
- * ```ts
- * import { Effect, Option } from "effect";
- * import type { JsoncNode, JsoncPath } from "jsonc-effect";
- * import { parseTree, getNodePath } from "jsonc-effect";
- *
- * const program = Effect.gen(function* () {
- *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "a": { "b": 42 } }');
- *   if (Option.isNone(root)) return Option.none();
- *   // Offset 15 points inside the value 42
- *   return yield* getNodePath(root.value, 15);
- * });
- *
- * const result: Option.Option<JsoncPath> = Effect.runSync(program);
- * // result is Option.some(["a", "b"])
- * ```
- *
- * @public
- */
-export declare const getNodePath: {
-    (targetOffset: number): (root: JsoncNode) => Effect.Effect<Option.Option<JsoncPath>>;
-    (root: JsoncNode, targetOffset: number): Effect.Effect<Option.Option<JsoncPath>>;
-};
-
-/**
- * Reconstruct a plain JavaScript value from an AST subtree.
- *
- * @param node - The AST node to evaluate, typically obtained via {@link findNode} or
- *   as the root from {@link parseTree}.
- *
- * @returns `Effect<unknown>` — the reconstructed JS value (object, array, string,
- *   number, boolean, or null).
- *
- * @remarks
- * Recursively evaluates the node tree to produce a plain JavaScript value.
- * This is the inverse of {@link parseTree}: where `parseTree` turns a JSONC string
- * into an AST, `getNodeValue` turns an AST subtree back into a JS value.
- *
- * @see {@link parseTree} — produces the AST that this function evaluates
- * @see {@link findNode} — locates a subtree to pass to this function
- *
- * @example Extracting the value of a found node
- * ```ts
- * import { Effect, Option } from "effect";
- * import type { JsoncNode } from "jsonc-effect";
- * import { parseTree, findNode, getNodeValue } from "jsonc-effect";
- *
- * const program = Effect.gen(function* () {
- *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "items": [1, 2, 3] }');
- *   if (Option.isNone(root)) return undefined;
- *   const node: Option.Option<JsoncNode> = yield* findNode(root.value, ["items"]);
- *   if (Option.isNone(node)) return undefined;
- *   return yield* getNodeValue(node.value);
- * });
- *
- * const result = Effect.runSync(program);
- * // result is [1, 2, 3]
- * ```
- *
- * @privateRemarks
- * Useful after {@link findNode} to extract a subtree's value without manual
- * AST traversal.
- *
- * @public
- */
-export declare const getNodeValue: (node: JsoncNode) => Effect.Effect<unknown, never, never>;
-
-/**
- * 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
- */
-export declare class JsoncEdit extends JsoncEdit_base {
-}
-
-declare const JsoncEdit_base: Schema.Class<JsoncEdit, {
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-    content: typeof Schema.String;
-}, Schema.Struct.Encoded<{
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-    content: typeof Schema.String;
-}>, never, {
-    readonly content: string;
-} & {
-    readonly length: number;
-} & {
-    readonly offset: number;
-}, {}, {}>;
-
-/**
- * Union of all JSONC error types, useful for exhaustive error handling
- * with `Effect.catchTags`.
- *
- * @see {@link JsoncParseError}
- * @see {@link JsoncNodeNotFoundError}
- * @see {@link JsoncModificationError}
- *
- * @example
- * ```ts
- * import { Effect } from "effect";
- * import type { JsoncError } from "jsonc-effect";
- * import { parse, parseTree, findNode, modify } from "jsonc-effect";
- *
- * const program = parse("{}").pipe(
- *   Effect.catchTags({
- *     JsoncParseError: (e) => Effect.succeed("parse failed"),
- *     JsoncModificationError: (e) => Effect.succeed("modify failed"),
- *     JsoncNodeNotFoundError: (e) => Effect.succeed("node not found"),
- *   }),
- * );
- * ```
- *
- * @public
- */
-export declare type JsoncError = JsoncParseError | JsoncNodeNotFoundError | JsoncModificationError;
-
-/**
- * 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
- */
-export declare class JsoncFormattingOptions extends JsoncFormattingOptions_base {
-}
-
-declare const JsoncFormattingOptions_base: Schema.Class<JsoncFormattingOptions, {
-    tabSize: Schema.optionalWith<typeof Schema.Number, {
-        default: () => number;
-    }>;
-    insertSpaces: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => true;
-    }>;
-    eol: Schema.optionalWith<typeof Schema.String, {
-        default: () => string;
-    }>;
-    insertFinalNewline: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
-    }>;
-    keepLines: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
-    }>;
-}, Schema.Struct.Encoded<{
-    tabSize: Schema.optionalWith<typeof Schema.Number, {
-        default: () => number;
-    }>;
-    insertSpaces: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => true;
-    }>;
-    eol: Schema.optionalWith<typeof Schema.String, {
-        default: () => string;
-    }>;
-    insertFinalNewline: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
-    }>;
-    keepLines: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
-    }>;
-}>, never, {
-    readonly eol?: string;
-} & {
-    readonly insertFinalNewline?: boolean;
-} & {
-    readonly insertSpaces?: boolean;
-} & {
-    readonly keepLines?: boolean;
-} & {
-    readonly tabSize?: number;
-}, {}, {}>;
-
-/**
- * Pre-built `Schema<unknown, string>` that decodes a JSONC string into an
- * unknown JavaScript value using default parse options.
- *
- * This is the first stage of a typical parsing pipeline:
- *
- * ```
- * JSONC string  --JsoncFromString-->  unknown  --YourSchema-->  A
- * ```
- *
- * @remarks
- * Default parse options are used (comments allowed, trailing commas
- * allowed). The encode direction uses `JSON.stringify` with 2-space
- * indentation, which means comments present in the original JSONC
- * input are not preserved during a round-trip encode.
- *
- * For custom parse options, use {@link makeJsoncFromString} instead.
- *
- * @see {@link makeJsoncFromString} to create a schema with custom options.
- * @see {@link makeJsoncSchema} to compose JSONC parsing with a domain schema
- *   in one step.
- *
- * @example Decode a JSONC string
- * ```ts
- * import { Schema } from "effect";
- * import { JsoncFromString } from "jsonc-effect";
- *
- * const value: unknown = Schema.decodeUnknownSync(JsoncFromString)(
- *   '{ "key": 42 // comment\n}',
- * );
- * ```
- *
- * @example Compose with a domain schema
- * ```ts
- * import { Schema } from "effect";
- * import { JsoncFromString } from "jsonc-effect";
- *
- * const MyConfig = Schema.Struct({
- *   name: Schema.String,
- *   version: Schema.Number,
- * });
- *
- * const MyConfigFromJsonc = Schema.compose(JsoncFromString, MyConfig);
- * const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(
- *   '{ "name": "app", "version": 1 }',
- * );
- * ```
- *
- * @public
- */
-export declare const JsoncFromString: Schema.Schema<unknown, string>;
-
-/**
- * Error raised when {@link modify} produces invalid edits or encounters
- * an unsupported modification scenario.
- *
- * @remarks
- * Contains the `path` where modification was attempted and a `reason`
- * string explaining why it failed.
- *
- * @see {@link modify} — may fail with this error
- *
- * @example
- * ```ts
- * import { Effect } from "effect";
- * import { modify } from "jsonc-effect";
- *
- * const program = modify("{}", ["deep", "path"], 42).pipe(
- *   Effect.catchTag("JsoncModificationError", (e) => {
- *     console.error(`Failed at [${e.path.join(", ")}]: ${e.reason}`);
- *     return Effect.succeed([]);
- *   }),
- * );
- * ```
- *
- * @public
- */
-export declare class JsoncModificationError extends JsoncModificationErrorBase<{
-    readonly path: ReadonlyArray<string | number>;
-    readonly reason: string;
-}> {
-    get message(): string;
-}
-
-/**
- * Base class for {@link JsoncModificationError}.
- *
- * @privateRemarks
- * Uses the same `*Base` pattern as {@link JsoncParseErrorBase} to work
- * around api-extractor's inability to roll up the complex type produced
- * by `Data.TaggedError` into a single `.d.ts` declaration.
- *
- * @internal
- */
-export declare const JsoncModificationErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
-    readonly _tag: "JsoncModificationError";
-} & Readonly<A>;
-
-/**
- * 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} 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
- */
-export declare class JsoncNode extends JsoncNode_base {
-}
-
-declare const JsoncNode_base: Schema.Class<JsoncNode, {
-    type: Schema.Literal<["object", "array", "property", "string", "number", "boolean", "null"]>;
-    value: Schema.optional<typeof Schema.Unknown>;
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-    colonOffset: Schema.optional<typeof Schema.Number>;
-    children: Schema.optional<Schema.Array$<Schema.suspend<JsoncNode, JsoncNode, never>>>;
-}, Schema.Struct.Encoded<{
-    type: Schema.Literal<["object", "array", "property", "string", "number", "boolean", "null"]>;
-    value: Schema.optional<typeof Schema.Unknown>;
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-    colonOffset: Schema.optional<typeof Schema.Number>;
-    children: Schema.optional<Schema.Array$<Schema.suspend<JsoncNode, JsoncNode, never>>>;
-}>, never, {
-    readonly children?: readonly JsoncNode[] | undefined;
-} & {
-    readonly colonOffset?: number | undefined;
-} & {
-    readonly value?: unknown;
-} & {
-    readonly length: number;
-} & {
-    readonly offset: number;
-} & {
-    readonly type: "array" | "boolean" | "null" | "number" | "object" | "property" | "string";
-}, {}, {}>;
-
-/**
- * Error raised when AST navigation fails to find a node at the given path.
- *
- * @remarks
- * Contains the `path` that was searched and the `rootNodeType` of the tree
- * that was traversed.
- *
- * @see {@link findNode} — may fail with this error
- *
- * @example
- * ```ts
- * import { Effect } from "effect";
- * import { parseTree, findNode } from "jsonc-effect";
- *
- * const program = parseTree('{ "a": 1 }').pipe(
- *   Effect.flatMap((root) => findNode(root, ["missing", "path"])),
- *   Effect.catchTag("JsoncNodeNotFoundError", (e) => {
- *     console.error(`Not found: [${e.path.join(", ")}] in ${e.rootNodeType}`);
- *     return Effect.succeed(undefined);
- *   }),
- * );
- * ```
- *
- * @public
- */
-export declare class JsoncNodeNotFoundError extends JsoncNodeNotFoundErrorBase<{
-    readonly path: ReadonlyArray<string | number>;
-    readonly rootNodeType: string;
-}> {
-    get message(): string;
-}
-
-/**
- * Base class for {@link JsoncNodeNotFoundError}.
- *
- * @privateRemarks
- * Uses the same `*Base` pattern as {@link JsoncParseErrorBase} to work
- * around api-extractor's inability to roll up the complex type produced
- * by `Data.TaggedError` into a single `.d.ts` declaration.
- *
- * @internal
- */
-export declare const JsoncNodeNotFoundErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
-    readonly _tag: "JsoncNodeNotFoundError";
-} & Readonly<A>;
-
-/**
- * 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
- */
-export declare const JsoncNodeType: Schema.Literal<["object", "array", "property", "string", "number", "boolean", "null"]>;
-
-/**
- * The union of all JSONC AST node type string literals.
- *
- * @see {@link JsoncNodeType}
- *
- * @public
- */
-export declare type JsoncNodeType = Schema.Schema.Type<typeof JsoncNodeType>;
-
-/**
- * Error raised when JSONC parsing encounters one or more syntax errors.
- *
- * @remarks
- * Contains the full source `text`, the `options` used for parsing, and an
- * `errors` array of {@link JsoncParseErrorDetail} instances with precise
- * position information for each problem found.
- *
- * @see {@link parse} — may fail with this error
- * @see {@link parseTree} — may fail with this error
- *
- * @example Catching with `Effect.catchTag`
- * ```ts
- * import { Effect } from "effect";
- * import { parse } from "jsonc-effect";
- *
- * const program = parse("{ invalid }").pipe(
- *   Effect.catchTag("JsoncParseError", (e) => {
- *     console.error(e.errors); // Array of JsoncParseErrorDetail
- *     return Effect.succeed({});
- *   }),
- * );
- * ```
- *
- * @example Inspecting error details
- * ```ts
- * import { Effect } from "effect";
- * import { parse } from "jsonc-effect";
- *
- * const program = parse("{ invalid }").pipe(
- *   Effect.catchTag("JsoncParseError", (e) => {
- *     for (const detail of e.errors) {
- *       console.error(
- *         `[${detail.code}] ${detail.message} at line ${detail.startLine}:${detail.startCharacter}`,
- *       );
- *     }
- *     return Effect.succeed({});
- *   }),
- * );
- * ```
- *
- * @public
- */
-export declare class JsoncParseError extends JsoncParseErrorBase<{
-    readonly errors: ReadonlyArray<JsoncParseErrorDetail>;
-    readonly text: string;
-    readonly options?: Partial<JsoncParseOptions>;
-}> {
-    get message(): string;
-}
-
-/**
- * Base class for {@link JsoncParseError}.
- *
- * @privateRemarks
- * The `*Base` pattern is required because `Data.TaggedError` produces complex
- * type signatures involving intersection types and branded generics that
- * api-extractor cannot roll up into a single `.d.ts` bundle. By exporting
- * the base separately as `@internal`, the public `JsoncParseError` class
- * extends it with concrete fields, giving api-extractor a simple class
- * declaration to work with.
- *
- * @internal
- */
-export declare const JsoncParseErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
-    readonly _tag: "JsoncParseError";
-} & Readonly<A>;
-
-/**
- * Error codes representing specific JSONC parse failures.
- *
- * @remarks
- * Each code maps to a distinct syntactic error the parser can encounter,
- * from invalid symbols and number formats to missing delimiters and
- * unexpected end-of-input conditions.
- *
- * @see {@link JsoncParseErrorDetail} — carries one of these codes alongside
- *   position information
- *
- * @public
- */
-export declare const JsoncParseErrorCode: Schema.Literal<["InvalidSymbol", "InvalidNumberFormat", "PropertyNameExpected", "ValueExpected", "ColonExpected", "CommaExpected", "CloseBraceExpected", "CloseBracketExpected", "EndOfFileExpected", "InvalidCommentToken", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter"]>;
-
-/**
- * The union of all JSONC parse error code string literals.
- *
- * @see {@link JsoncParseErrorCode}
- *
- * @public
- */
-export declare type JsoncParseErrorCode = Schema.Schema.Type<typeof JsoncParseErrorCode>;
-
-/**
- * Detail for a single parse error, including the error code, a human-readable
- * message, and the exact position within the source document.
- *
- * @remarks
- * - `code` — a {@link JsoncParseErrorCode} identifying the error kind.
- * - `message` — a descriptive message suitable for display.
- * - `offset` — zero-based character offset where the error occurred.
- * - `length` — character length of the problematic span.
- * - `startLine` — zero-based line number of the error.
- * - `startCharacter` — zero-based column within `startLine`.
- *
- * @see {@link JsoncParseError} — aggregates an array of these details
- *
- * @example
- * ```ts
- * import { JsoncParseErrorDetail } from "jsonc-effect";
- *
- * const detail = new JsoncParseErrorDetail({
- *   code: "ValueExpected",
- *   message: "Value expected",
- *   offset: 5,
- *   length: 1,
- *   startLine: 0,
- *   startCharacter: 5,
- * });
- *
- * console.log(detail.code); // "ValueExpected"
- * console.log(detail.offset); // 5
- * ```
- *
- * @public
- */
-export declare class JsoncParseErrorDetail extends JsoncParseErrorDetail_base {
-}
-
-declare const JsoncParseErrorDetail_base: Schema.Class<JsoncParseErrorDetail, {
-    code: Schema.Literal<["InvalidSymbol", "InvalidNumberFormat", "PropertyNameExpected", "ValueExpected", "ColonExpected", "CommaExpected", "CloseBraceExpected", "CloseBracketExpected", "EndOfFileExpected", "InvalidCommentToken", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter"]>;
-    message: typeof Schema.String;
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-    startLine: typeof Schema.Number;
-    startCharacter: typeof Schema.Number;
-}, Schema.Struct.Encoded<{
-    code: Schema.Literal<["InvalidSymbol", "InvalidNumberFormat", "PropertyNameExpected", "ValueExpected", "ColonExpected", "CommaExpected", "CloseBraceExpected", "CloseBracketExpected", "EndOfFileExpected", "InvalidCommentToken", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter"]>;
-    message: typeof Schema.String;
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-    startLine: typeof Schema.Number;
-    startCharacter: typeof Schema.Number;
-}>, never, {
-    readonly code: "CloseBraceExpected" | "CloseBracketExpected" | "ColonExpected" | "CommaExpected" | "EndOfFileExpected" | "InvalidCharacter" | "InvalidCommentToken" | "InvalidEscapeCharacter" | "InvalidNumberFormat" | "InvalidSymbol" | "InvalidUnicode" | "PropertyNameExpected" | "UnexpectedEndOfComment" | "UnexpectedEndOfNumber" | "UnexpectedEndOfString" | "ValueExpected";
-} & {
-    readonly length: number;
-} & {
-    readonly message: string;
-} & {
-    readonly offset: number;
-} & {
-    readonly startCharacter: number;
-} & {
-    readonly startLine: 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
- */
-export declare class JsoncParseOptions extends JsoncParseOptions_base {
-}
-
-declare const JsoncParseOptions_base: Schema.Class<JsoncParseOptions, {
-    disallowComments: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
-    }>;
-    allowTrailingComma: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => true;
-    }>;
-    allowEmptyContent: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
-    }>;
-}, Schema.Struct.Encoded<{
-    disallowComments: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
-    }>;
-    allowTrailingComma: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => true;
-    }>;
-    allowEmptyContent: Schema.optionalWith<typeof Schema.Boolean, {
-        default: () => false;
-    }>;
-}>, never, {
-    readonly allowEmptyContent?: boolean;
-} & {
-    readonly allowTrailingComma?: boolean;
-} & {
-    readonly disallowComments?: boolean;
-}, {}, {}>;
-
-/**
- * An ordered sequence of {@link JsoncSegment} 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
- */
-export declare const JsoncPath: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
-
-/**
- * An array of path segments — `ReadonlyArray<string | number>`.
- *
- * @see {@link JsoncPath}
- *
- * @public
- */
-export declare type JsoncPath = Schema.Schema.Type<typeof JsoncPath>;
-
-/**
- * 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
- */
-export declare class JsoncRange extends JsoncRange_base {
-}
-
-declare const JsoncRange_base: Schema.Class<JsoncRange, {
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-}, Schema.Struct.Encoded<{
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-}>, never, {
-    readonly length: number;
-} & {
-    readonly offset: number;
-}, {}, {}>;
-
-/**
- * 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
- */
-export declare const JsoncScanError: Schema.Literal<["None", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter", "InvalidSymbol"]>;
-
-/**
- * The union of all JSONC scan error string literals.
- *
- * @see {@link JsoncScanError}
- *
- * @public
- */
-export declare type JsoncScanError = Schema.Schema.Type<typeof JsoncScanError>;
-
-/**
- * Stateful cursor over JSONC text that produces tokens on demand.
- *
- * @remarks
- * The scanner is the lowest-level API in jsonc-effect. It exposes an
- * imperative scan-loop pattern: call {@link JsoncScanner.scan | scan()} in a
- * loop until it returns `"EOF"`, inspecting the current token with the
- * getter methods after each call.
- *
- * Unlike the rest of the library, the scanner is **mutable** — each call to
- * `scan()` advances an internal cursor and updates all token-related state.
- *
- * @see {@link createScanner} — factory function that produces a `JsoncScanner`
- * @see {@link JsoncSyntaxKind} — string literal union of all token types
- *
- * @example
- * Collecting all structural tokens from a JSONC string:
- * ```ts
- * import type { JsoncSyntaxKind } from "jsonc-effect";
- * import { createScanner } from "jsonc-effect";
- *
- * const scanner = createScanner('{ "key": 42 }', true);
- * const tokens: JsoncSyntaxKind[] = [];
- * let kind: JsoncSyntaxKind;
- * do {
- *   kind = scanner.scan();
- *   tokens.push(kind);
- * } while (kind !== "EOF");
- * console.log(tokens);
- * // ["OpenBrace", "String", "Colon", "Number", "CloseBrace", "EOF"]
- * ```
- *
- * @privateRemarks
- * The scanner is the only mutable/stateful part of the library. All other
- * APIs are pure Effect pipelines built on top of it.
- *
- * @public
- */
-export declare interface JsoncScanner {
-    /** Advance the cursor to the next token and return its {@link JsoncSyntaxKind}. */
-    scan(): JsoncSyntaxKind;
-    /** Return the {@link JsoncSyntaxKind} of the current token without advancing. */
-    getToken(): JsoncSyntaxKind;
-    /** Return the string value of the current token (e.g. the unescaped content of a string literal). */
-    getTokenValue(): string;
-    /** Return the zero-based character offset where the current token begins. */
-    getTokenOffset(): number;
-    /** Return the character length of the current token. */
-    getTokenLength(): number;
-    /** Return the zero-based line number where the current token starts. */
-    getTokenStartLine(): number;
-    /** Return the zero-based character position within the line where the current token starts. */
-    getTokenStartCharacter(): number;
-    /** Return the {@link JsoncScanError} for the current token, or `"None"` if no error. */
-    getTokenError(): JsoncScanError;
-    /** Return the current cursor position (byte offset into the source text). */
-    getPosition(): number;
-    /** Set the cursor position, resetting the current token state. */
-    setPosition(pos: number): void;
-}
-
-/**
- * A single segment of a {@link JsoncPath}: 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
- */
-export declare const JsoncSegment: Schema.Union<[typeof Schema.String, typeof Schema.Number]>;
-
-/**
- * A single path segment type — `string | number`.
- *
- * @see {@link JsoncSegment}
- *
- * @public
- */
-export declare type JsoncSegment = Schema.Schema.Type<typeof JsoncSegment>;
-
-/**
- * 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
- */
-export declare const JsoncSyntaxKind: Schema.Literal<["OpenBrace", "CloseBrace", "OpenBracket", "CloseBracket", "Comma", "Colon", "Null", "True", "False", "String", "Number", "LineComment", "BlockComment", "LineBreak", "Trivia", "Unknown", "EOF"]>;
-
-/**
- * The union of all JSONC token kind string literals.
- *
- * @see {@link JsoncSyntaxKind}
- *
- * @public
- */
-export declare type JsoncSyntaxKind = Schema.Schema.Type<typeof JsoncSyntaxKind>;
-
-/**
- * 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} 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} 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
- */
-export declare class JsoncToken extends JsoncToken_base {
-}
-
-declare const JsoncToken_base: Schema.Class<JsoncToken, {
-    kind: Schema.Literal<["OpenBrace", "CloseBrace", "OpenBracket", "CloseBracket", "Comma", "Colon", "Null", "True", "False", "String", "Number", "LineComment", "BlockComment", "LineBreak", "Trivia", "Unknown", "EOF"]>;
-    value: typeof Schema.String;
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-    startLine: typeof Schema.Number;
-    startCharacter: typeof Schema.Number;
-    error: Schema.Literal<["None", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter", "InvalidSymbol"]>;
-}, Schema.Struct.Encoded<{
-    kind: Schema.Literal<["OpenBrace", "CloseBrace", "OpenBracket", "CloseBracket", "Comma", "Colon", "Null", "True", "False", "String", "Number", "LineComment", "BlockComment", "LineBreak", "Trivia", "Unknown", "EOF"]>;
-    value: typeof Schema.String;
-    offset: typeof Schema.Number;
-    length: typeof Schema.Number;
-    startLine: typeof Schema.Number;
-    startCharacter: typeof Schema.Number;
-    error: Schema.Literal<["None", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter", "InvalidSymbol"]>;
-}>, never, {
-    readonly error: "InvalidCharacter" | "InvalidEscapeCharacter" | "InvalidSymbol" | "InvalidUnicode" | "None" | "UnexpectedEndOfComment" | "UnexpectedEndOfNumber" | "UnexpectedEndOfString";
-} & {
-    readonly kind: "BlockComment" | "CloseBrace" | "CloseBracket" | "Colon" | "Comma" | "EOF" | "False" | "LineBreak" | "LineComment" | "Null" | "Number" | "OpenBrace" | "OpenBracket" | "String" | "Trivia" | "True" | "Unknown";
-} & {
-    readonly length: number;
-} & {
-    readonly offset: number;
-} & {
-    readonly startCharacter: number;
-} & {
-    readonly startLine: number;
-} & {
-    readonly value: string;
-}, {}, {}>;
-
-/**
- * Discriminated union of JSONC visitor events.
- *
- * Each variant carries an `_tag` discriminant, an `offset`, and a `length`
- * describing where the event occurred in the source text. Some variants
- * include additional fields such as `path`, `value`, or `property`.
- *
- * @remarks
- * The nine event types are:
- *
- * - **ObjectBegin** — opening `{` of an object, includes `path`.
- * - **ObjectEnd** — closing `}` of an object.
- * - **ObjectProperty** — a property key, includes `property` and `path`.
- * - **ArrayBegin** — opening `[` of an array, includes `path`.
- * - **ArrayEnd** — closing `]` of an array.
- * - **LiteralValue** — a string, number, boolean, or null literal,
- *   includes `value` and `path`.
- * - **Separator** — a `,` or `:` character.
- * - **Comment** — a line or block comment.
- * - **Error** — a parse error, includes a {@link JsoncParseErrorCode} `code`.
- *
- * Use the `_tag` field to discriminate between variants in `switch`
- * statements or {@link https://effect.website/docs/stream/operations | Stream}
- * filter predicates.
- *
- * @see {@link visit} to produce a stream of these events.
- * @see {@link visitCollect} to collect matching events in one step.
- *
- * @example Filtering events by tag
- * ```ts
- * import { Chunk, Effect, Stream } from "effect";
- * import type { JsoncVisitorEvent } from "jsonc-effect";
- * import { visit } from "jsonc-effect";
- *
- * const literals = Effect.runSync(
- *   visit('{ "a": 1 }').pipe(
- *     Stream.filter(
- *       (e): e is Extract<JsoncVisitorEvent, { _tag: "LiteralValue" }> =>
- *         e._tag === "LiteralValue",
- *     ),
- *     Stream.runCollect,
- *     Effect.map(Chunk.toReadonlyArray),
- *   ),
- * );
- * ```
- *
- * @public
- */
-export declare type JsoncVisitorEvent = {
-    readonly _tag: "ObjectBegin";
-    readonly offset: number;
-    readonly length: number;
-    readonly path: ReadonlyArray<string | number>;
-} | {
-    readonly _tag: "ObjectEnd";
-    readonly offset: number;
-    readonly length: number;
-} | {
-    readonly _tag: "ObjectProperty";
-    readonly property: string;
-    readonly offset: number;
-    readonly length: number;
-    readonly path: ReadonlyArray<string | number>;
-} | {
-    readonly _tag: "ArrayBegin";
-    readonly offset: number;
-    readonly length: number;
-    readonly path: ReadonlyArray<string | number>;
-} | {
-    readonly _tag: "ArrayEnd";
-    readonly offset: number;
-    readonly length: number;
-} | {
-    readonly _tag: "LiteralValue";
-    readonly value: unknown;
-    readonly offset: number;
-    readonly length: number;
-    readonly path: ReadonlyArray<string | number>;
-} | {
-    readonly _tag: "Separator";
-    readonly character: string;
-    readonly offset: number;
-    readonly length: number;
-} | {
-    readonly _tag: "Comment";
-    readonly offset: number;
-    readonly length: number;
-} | {
-    readonly _tag: "Error";
-    readonly code: JsoncParseErrorCode;
-    readonly offset: number;
-    readonly length: number;
-};
-
-/**
- * Create a `Schema<unknown, string>` that decodes JSONC with custom
- * parse options.
- *
- * @param options - Partial {@link JsoncParseOptions} controlling comment
- *   handling and trailing-comma tolerance.
- * @returns A `Schema<unknown, string>` configured with the given options.
- *
- * @remarks
- * The encode direction uses `JSON.stringify` with 2-space indentation,
- * which produces standard JSON. Comments present in the original JSONC
- * input are not preserved during a round-trip encode.
- *
- * @see {@link JsoncFromString} for a zero-config default instance.
- * @see {@link makeJsoncSchema} to compose JSONC parsing with a domain
- *   schema in one step.
- *
- * @example Strict mode (no comments, no trailing commas)
- * ```ts
- * import { Schema } from "effect";
- * import { makeJsoncFromString } from "jsonc-effect";
- *
- * const StrictJsoncFromString = makeJsoncFromString({
- *   disallowComments: true,
- *   allowTrailingComma: false,
- * });
- *
- * const value: unknown = Schema.decodeUnknownSync(StrictJsoncFromString)(
- *   '{ "key": 42 }',
- * );
- * ```
- *
- * @privateRemarks
- * Internally delegates to `Schema.transformOrFail` to wire up the decode
- * and encode directions.
- *
- * @public
- */
-export declare function makeJsoncFromString(options?: Partial<JsoncParseOptions>): Schema.Schema<unknown, string>;
-
-/**
- * Create a composed `Schema<A, string>` that parses a JSONC string and
- * validates the result against a target domain schema in one step.
- *
- * @param targetSchema - The domain schema to validate the parsed value
- *   against. Its input type `I` must be assignable from `unknown`.
- * @param options - Optional partial {@link JsoncParseOptions} forwarded to
- *   the underlying JSONC parser.
- * @returns A `Schema<A, string>` that goes directly from a JSONC string
- *   to a fully validated domain value of type `A`.
- *
- * @remarks
- * Internally composes two schema stages:
- *
- * 1. JSONC string to `unknown` (via {@link makeJsoncFromString}).
- * 2. `unknown` to `A` (via the provided `targetSchema`).
- *
- * This avoids the need to manually call `Schema.compose`.
- *
- * @see {@link makeJsoncFromString} for the first stage of the pipeline.
- *
- * @example Typed configuration from JSONC
- * ```ts
- * import { Schema } from "effect";
- * import { makeJsoncSchema } from "jsonc-effect";
- *
- * const MyConfig = Schema.Struct({
- *   name: Schema.String,
- *   version: Schema.Number,
- * });
- *
- * const MyConfigFromJsonc = makeJsoncSchema(MyConfig);
- * const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(
- *   '{ "name": "app", "version": 1 }',
- * );
- * ```
- *
- * @example With custom parse options
- * ```ts
- * import { Schema } from "effect";
- * import { makeJsoncSchema } from "jsonc-effect";
- *
- * const MyConfig = Schema.Struct({ debug: Schema.Boolean });
- *
- * const StrictConfig = makeJsoncSchema(MyConfig, {
- *   disallowComments: true,
- *   allowTrailingComma: false,
- * });
- *
- * const config = Schema.decodeUnknownSync(StrictConfig)(
- *   '{ "debug": true }',
- * );
- * ```
- *
- * @privateRemarks
- * Uses `Schema.compose` internally to chain the JSONC-from-string schema
- * with the provided target schema.
- *
- * @public
- */
-export declare const makeJsoncSchema: <A, I>(targetSchema: Schema.Schema<A, I, never>, options?: Partial<JsoncParseOptions> | undefined) => Schema.Schema<A, string, never>;
-
-/**
- * Compute edits to insert, replace, or remove a value at a JSON path.
- *
- * This is a {@link https://effect.website/docs/function-dual | Function.dual}
- * that supports both data-first and data-last (pipeline) usage.
- *
- * @param text - The JSONC source text to modify.
- * @param path - A {@link JsoncPath} (array of string keys and numeric indices)
- *   identifying the target location in the JSON structure.
- * @param value - The value to set. Pass `undefined` to remove the
- *   property or array element at the given path.
- * @param options - Optional object with `formattingOptions` controlling
- *   indent size, tabs vs. spaces, and EOL style for generated text.
- * @returns An `Effect` that succeeds with a read-only array of
- *   {@link JsoncEdit} objects, or fails with a
- *   {@link JsoncModificationError} if the path cannot be navigated.
- *
- * @remarks
- * Setting `value` to `undefined` removes the targeted property or element,
- * including its surrounding comma. When inserting a new property into an
- * object, it is appended after the last existing property.
- *
- * @see {@link applyEdits} to apply the returned edits to the source text.
- * @see {@link JsoncModificationError} for the error type on navigation failure.
- *
- * @example Update an existing property
- * ```ts
- * import { Effect } from "effect";
- * import { modify, applyEdits } from "jsonc-effect";
- *
- * const input = '{ "a": 1 }';
- * const edits = Effect.runSync(modify(input, ["a"], 2));
- * const result: string = Effect.runSync(applyEdits(input, edits));
- * ```
- *
- * @example Insert a new property
- * ```ts
- * import { Effect } from "effect";
- * import { modify, applyEdits } from "jsonc-effect";
- *
- * const input = '{ "a": 1 }';
- * const edits = Effect.runSync(modify(input, ["b"], "hello"));
- * const result: string = Effect.runSync(applyEdits(input, edits));
- * ```
- *
- * @example Remove a property
- * ```ts
- * import { Effect } from "effect";
- * import { modify, applyEdits } from "jsonc-effect";
- *
- * const input = '{ "a": 1, "b": 2 }';
- * const edits = Effect.runSync(modify(input, ["a"], undefined));
- * const result: string = Effect.runSync(applyEdits(input, edits));
- * ```
- *
- * @example Pipeline (data-last) usage
- * ```ts
- * import { Effect, pipe } from "effect";
- * import { modify, applyEdits } from "jsonc-effect";
- *
- * const input = '{ "a": 1 }';
- * const result = pipe(
- *   input,
- *   modify(["a"], 42),
- *   Effect.flatMap((edits) => applyEdits(input, edits)),
- *   Effect.runSync,
- * );
- * ```
- *
- * @privateRemarks
- * Uses its own scanner-based navigation to locate the target path rather
- * than building a full AST via `parseTree`. This keeps the implementation
- * lightweight and avoids an intermediate allocation.
- *
- * @public
- */
-export declare const modify: {
-    (path: JsoncPath, value: unknown, options?: {
-        formattingOptions?: Partial<JsoncFormattingOptions>;
-    }): (text: string) => Effect.Effect<ReadonlyArray<JsoncEdit>, JsoncModificationError>;
-    (text: string, path: JsoncPath, value: unknown, options?: {
-        formattingOptions?: Partial<JsoncFormattingOptions>;
-    }): Effect.Effect<ReadonlyArray<JsoncEdit>, JsoncModificationError>;
-};
-
-/**
- * Parse a JSONC string into a JavaScript value.
- *
- * @param text - JSONC string to parse
- * @param options - Optional {@link JsoncParseOptions} controlling comment and
- *   trailing-comma handling.
- * @returns `Effect<unknown, JsoncParseError>` — succeeds with the parsed value
- *   or fails with a {@link JsoncParseError} containing every error encountered.
- *
- * @remarks
- * The return type is `unknown` (not `any`) so consumers are forced to narrow
- * the result, which is safer in Effect pipelines. By default
- * `allowTrailingComma` is `true`, matching common JSONC conventions used in
- * VS Code settings and `tsconfig.json`.
- *
- * @see {@link parseTree} — parse into an AST instead of a plain value
- * @see {@link JsoncParseOptions} — available parse options
- * @see {@link JsoncParseError} — the tagged error type on the failure channel
- *
- * @example
- * Basic parsing:
- * ```ts
- * import { Effect } from "effect";
- * import { parse } from "jsonc-effect";
- *
- * const value = Effect.runSync(parse('{ "key": 42 }'));
- * console.log(value); // { key: 42 }
- * ```
- *
- * @example
- * Parsing with options:
- * ```ts
- * import { Effect } from "effect";
- * import { parse } from "jsonc-effect";
- *
- * const value = Effect.runSync(
- *   parse('{ "key": 42 }', { disallowComments: true }),
- * );
- * ```
- *
- * @example
- * Error handling with `catchTag`:
- * ```ts
- * import { Effect } from "effect";
- * import { parse } from "jsonc-effect";
- *
- * const program = parse("{ bad }").pipe(
- *   Effect.catchTag("JsoncParseError", (err) =>
- *     Effect.succeed({ fallback: true, errors: err.errors }),
- *   ),
- * );
- *
- * const result = Effect.runSync(program);
- * console.log(result);
- * ```
- *
- * @example
- * Using `Effect.gen`:
- * ```ts
- * import { Effect } from "effect";
- * import { parse } from "jsonc-effect";
- *
- * const program = Effect.gen(function* () {
- *   const config = yield* parse('{ "port": 3000 }');
- *   return config;
- * });
- *
- * const result = Effect.runSync(program);
- * console.log(result); // { port: 3000 }
- * ```
- *
- * @privateRemarks
- * Uses {@link createScanner} internally with a recursive descent parser.
- * The scanner is created with `ignoreTrivia = false` so the parser can
- * report comment-related errors when `disallowComments` is set.
- *
- * @public
- */
-export declare const parse: {
-    (text: string): Effect.Effect<unknown, JsoncParseError>;
-    (text: string, options: Partial<JsoncParseOptions>): Effect.Effect<unknown, JsoncParseError>;
-};
-
-/**
- * Parse a JSONC string into an immutable AST.
- *
- * @param text - JSONC string to parse
- * @param options - Optional {@link JsoncParseOptions} controlling comment and
- *   trailing-comma handling.
- * @returns `Effect<Option<JsoncNode>, JsoncParseError>` — succeeds with
- *   `Option.some(root)` for non-empty documents or `Option.none()` when the
- *   input is empty (and `allowEmptyContent` is set).
- *
- * @remarks
- * The returned AST is immutable and does **not** contain parent pointers, which
- * keeps nodes safe to share across fibers. Use the AST navigation helpers
- * ({@link findNode}, {@link getNodeValue}) to traverse and extract values from
- * the tree.
- *
- * `Option.none()` is returned only when the document contains no value tokens
- * and `allowEmptyContent` is enabled; otherwise an empty document produces a
- * {@link JsoncParseError}.
- *
- * @see {@link parse} — parse into a plain JavaScript value instead of an AST
- * @see {@link findNode} — locate a node by JSON path segments
- * @see {@link getNodeValue} — extract the JavaScript value from a subtree
- * @see {@link JsoncNode} — the AST node type
- *
- * @example
- * Parsing a JSONC string and navigating the tree:
- * ```ts
- * import { Effect, Option } from "effect";
- * import { parseTree } from "jsonc-effect";
- *
- * const program = Effect.gen(function* () {
- *   const maybeRoot = yield* parseTree('{ "a": [1, 2, 3] }');
- *   if (Option.isSome(maybeRoot)) {
- *     const root = maybeRoot.value;
- *     console.log(root.type); // "object"
- *     console.log(root.children?.length); // 1
- *   }
- * });
- *
- * Effect.runSync(program);
- * ```
- *
- * @privateRemarks
- * Internally the parser builds a mutable tree using `MutableJsoncNode` and
- * casts to the readonly `JsoncNode` on output.
- *
- * @public
- */
-export declare const parseTree: {
-    (text: string): Effect.Effect<Option.Option<JsoncNode>, JsoncParseError>;
-    (text: string, options: Partial<JsoncParseOptions>): Effect.Effect<Option.Option<JsoncNode>, JsoncParseError>;
-};
-
-/**
- * Remove all comments from JSONC text, producing valid JSON.
- *
- * @param text - JSONC string to strip comments from
- * @param replaceCh - Optional single character used to replace each character of
- *   every comment. When provided, the output has the **same length** as the
- *   input so that all offsets are preserved (line breaks inside block comments
- *   are kept as-is).
- * @returns `Effect<string>` — the text with all comments removed (or replaced).
- *
- * @remarks
- * When `replaceCh` is omitted the comment text is simply deleted, which means
- * character offsets in the output no longer match the original document. Pass a
- * space (`" "`) as `replaceCh` to keep offsets stable — this is useful when you
- * need to correlate positions between the original JSONC and the stripped JSON.
- *
- * @see {@link parse} — parse JSONC directly without a stripping step
- *
- * @example
- * Basic comment stripping:
- * ```ts
- * import { Effect } from "effect";
- * import { stripComments } from "jsonc-effect";
- *
- * const json = Effect.runSync(
- *   stripComments('{ "a": 1 // comment\n}'),
- * );
- * console.log(json); // '{ "a": 1 \n}'
- * ```
- *
- * @example
- * Using a replacement character to preserve offsets:
- * ```ts
- * import { Effect } from "effect";
- * import { stripComments } from "jsonc-effect";
- *
- * const json = Effect.runSync(
- *   stripComments('{ "a": 1 // comment\n}', " "),
- * );
- * console.log(json.length === '{ "a": 1 // comment\n}'.length); // true
- * ```
- *
- * @public
- */
-export declare const stripComments: {
-    (text: string): Effect.Effect<string>;
-    (text: string, replaceCh: string): Effect.Effect<string>;
-};
-
-/**
- * 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
- */
-export declare const visit: (text: string, options?: Partial<JsoncParseOptions> | undefined) => Stream.Stream<JsoncVisitorEvent, never, never>;
-
-/**
- * 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
- */
-export declare const visitCollect: <A extends JsoncVisitorEvent>(text: string, predicate: (event: JsoncVisitorEvent) => event is A, options?: Partial<JsoncParseOptions> | undefined) => Effect.Effect<readonly A[], never, never>;
-
-export { }
+import { Effect, Option, Schema, Stream } from "effect";
+
+//#region src/schemas.d.ts
+/**
+ * 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
+ */
+declare const JsoncSyntaxKind: Schema.Literal<["OpenBrace", "CloseBrace", "OpenBracket", "CloseBracket", "Comma", "Colon", "Null", "True", "False", "String", "Number", "LineComment", "BlockComment", "LineBreak", "Trivia", "Unknown", "EOF"]>;
+/**
+ * The union of all JSONC token kind string literals.
+ *
+ * @see {@link (JsoncSyntaxKind:variable)}
+ *
+ * @public
+ */
+type JsoncSyntaxKind = Schema.Schema.Type<typeof JsoncSyntaxKind>;
+/**
+ * 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
+ */
+declare const JsoncScanError: Schema.Literal<["None", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter", "InvalidSymbol"]>;
+/**
+ * The union of all JSONC scan error string literals.
+ *
+ * @see {@link (JsoncScanError:variable)}
+ *
+ * @public
+ */
+type JsoncScanError = Schema.Schema.Type<typeof JsoncScanError>;
+declare const JsoncToken_base: Schema.Class<JsoncToken, {
+  kind: Schema.Literal<["OpenBrace", "CloseBrace", "OpenBracket", "CloseBracket", "Comma", "Colon", "Null", "True", "False", "String", "Number", "LineComment", "BlockComment", "LineBreak", "Trivia", "Unknown", "EOF"]>;
+  value: typeof Schema.String;
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+  startLine: typeof Schema.Number;
+  startCharacter: typeof Schema.Number;
+  error: Schema.Literal<["None", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter", "InvalidSymbol"]>;
+}, Schema.Struct.Encoded<{
+  kind: Schema.Literal<["OpenBrace", "CloseBrace", "OpenBracket", "CloseBracket", "Comma", "Colon", "Null", "True", "False", "String", "Number", "LineComment", "BlockComment", "LineBreak", "Trivia", "Unknown", "EOF"]>;
+  value: typeof Schema.String;
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+  startLine: typeof Schema.Number;
+  startCharacter: typeof Schema.Number;
+  error: Schema.Literal<["None", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter", "InvalidSymbol"]>;
+}>, never, {
+  readonly error: "InvalidCharacter" | "InvalidEscapeCharacter" | "InvalidSymbol" | "InvalidUnicode" | "None" | "UnexpectedEndOfComment" | "UnexpectedEndOfNumber" | "UnexpectedEndOfString";
+} & {
+  readonly kind: "BlockComment" | "CloseBrace" | "CloseBracket" | "Colon" | "Comma" | "EOF" | "False" | "LineBreak" | "LineComment" | "Null" | "Number" | "OpenBrace" | "OpenBracket" | "String" | "Trivia" | "True" | "Unknown";
+} & {
+  readonly length: number;
+} & {
+  readonly offset: number;
+} & {
+  readonly startCharacter: number;
+} & {
+  readonly startLine: number;
+} & {
+  readonly value: string;
+}, {}, {}>;
+/**
+ * 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
+ */
+declare class JsoncToken extends JsoncToken_base {}
+/**
+ * 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
+ */
+declare const JsoncNodeType: Schema.Literal<["object", "array", "property", "string", "number", "boolean", "null"]>;
+/**
+ * The union of all JSONC AST node type string literals.
+ *
+ * @see {@link (JsoncNodeType:variable)}
+ *
+ * @public
+ */
+type JsoncNodeType = Schema.Schema.Type<typeof JsoncNodeType>;
+declare const JsoncNode_base: Schema.Class<JsoncNode, {
+  type: Schema.Literal<["object", "array", "property", "string", "number", "boolean", "null"]>;
+  value: Schema.optional<typeof Schema.Unknown>;
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+  colonOffset: Schema.optional<typeof Schema.Number>;
+  children: Schema.optional<Schema.Array$<Schema.suspend<JsoncNode, JsoncNode, never>>>;
+}, Schema.Struct.Encoded<{
+  type: Schema.Literal<["object", "array", "property", "string", "number", "boolean", "null"]>;
+  value: Schema.optional<typeof Schema.Unknown>;
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+  colonOffset: Schema.optional<typeof Schema.Number>;
+  children: Schema.optional<Schema.Array$<Schema.suspend<JsoncNode, JsoncNode, never>>>;
+}>, never, {
+  readonly children?: readonly JsoncNode[] | undefined;
+} & {
+  readonly colonOffset?: number | undefined;
+} & {
+  readonly value?: unknown;
+} & {
+  readonly length: number;
+} & {
+  readonly offset: number;
+} & {
+  readonly type: "array" | "boolean" | "null" | "number" | "object" | "property" | "string";
+}, {}, {}>;
+/**
+ * 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
+ */
+declare class JsoncNode extends JsoncNode_base {}
+/**
+ * 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
+ */
+declare const JsoncSegment: Schema.Union<[typeof Schema.String, typeof Schema.Number]>;
+/**
+ * A single path segment type — `string | number`.
+ *
+ * @see {@link (JsoncSegment:variable)}
+ *
+ * @public
+ */
+type JsoncSegment = Schema.Schema.Type<typeof JsoncSegment>;
+/**
+ * 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
+ */
+declare const JsoncPath: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
+/**
+ * An array of path segments — `ReadonlyArray<string | number>`.
+ *
+ * @see {@link (JsoncPath:variable)}
+ *
+ * @public
+ */
+type JsoncPath = Schema.Schema.Type<typeof JsoncPath>;
+declare const JsoncEdit_base: Schema.Class<JsoncEdit, {
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+  content: typeof Schema.String;
+}, Schema.Struct.Encoded<{
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+  content: typeof Schema.String;
+}>, never, {
+  readonly content: string;
+} & {
+  readonly length: number;
+} & {
+  readonly offset: number;
+}, {}, {}>;
+/**
+ * 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
+ */
+declare class JsoncEdit extends JsoncEdit_base {}
+declare const JsoncRange_base: Schema.Class<JsoncRange, {
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+}, Schema.Struct.Encoded<{
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+}>, never, {
+  readonly length: number;
+} & {
+  readonly offset: number;
+}, {}, {}>;
+/**
+ * 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
+ */
+declare class JsoncRange extends JsoncRange_base {}
+declare const JsoncParseOptions_base: Schema.Class<JsoncParseOptions, {
+  disallowComments: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  allowTrailingComma: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => true;
+  }>;
+  allowEmptyContent: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+}, Schema.Struct.Encoded<{
+  disallowComments: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  allowTrailingComma: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => true;
+  }>;
+  allowEmptyContent: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+}>, never, {
+  readonly allowEmptyContent?: boolean | undefined;
+} & {
+  readonly allowTrailingComma?: boolean | undefined;
+} & {
+  readonly disallowComments?: boolean | undefined;
+}, {}, {}>;
+/**
+ * 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
+ */
+declare class JsoncParseOptions extends JsoncParseOptions_base {}
+declare const JsoncFormattingOptions_base: Schema.Class<JsoncFormattingOptions, {
+  tabSize: Schema.optionalWith<typeof Schema.Number, {
+    default: () => number;
+  }>;
+  insertSpaces: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => true;
+  }>;
+  eol: Schema.optionalWith<typeof Schema.String, {
+    default: () => string;
+  }>;
+  insertFinalNewline: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  keepLines: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+}, Schema.Struct.Encoded<{
+  tabSize: Schema.optionalWith<typeof Schema.Number, {
+    default: () => number;
+  }>;
+  insertSpaces: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => true;
+  }>;
+  eol: Schema.optionalWith<typeof Schema.String, {
+    default: () => string;
+  }>;
+  insertFinalNewline: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  keepLines: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+}>, never, {
+  readonly eol?: string | undefined;
+} & {
+  readonly insertFinalNewline?: boolean | undefined;
+} & {
+  readonly insertSpaces?: boolean | undefined;
+} & {
+  readonly keepLines?: boolean | undefined;
+} & {
+  readonly tabSize?: number | undefined;
+}, {}, {}>;
+/**
+ * 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
+ */
+declare class JsoncFormattingOptions extends JsoncFormattingOptions_base {}
+//#endregion
+//#region src/ast.d.ts
+/**
+ * Find an AST node at a specific JSON path.
+ *
+ * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+ * for both data-first and data-last (pipeline) usage.
+ *
+ * @param root - The AST root node obtained from {@link parseTree}.
+ * @param path - An array of string keys and numeric indices describing the path to traverse.
+ *
+ * @returns `Effect<Option<JsoncNode>>` — the node at the given path, or `Option.none()` if the
+ *   path does not exist in the tree.
+ *
+ * @remarks
+ * String segments navigate object properties and number segments navigate array indices.
+ * Returns `Option.none()` when any segment along the path cannot be resolved — for example,
+ * accessing a property on a non-object node or an out-of-bounds array index.
+ *
+ * @see {@link parseTree} — produces the AST root this function operates on
+ * @see {@link getNodeValue} — reconstructs a JS value from a found node
+ * @see {@link JsoncNode} — the AST node type
+ * @see {@link (JsoncPath:type)} — the path segment array type
+ *
+ * @example Data-first usage
+ * ```ts
+ * import { Effect, Option } from "effect";
+ * import type { JsoncNode } from "jsonc-effect";
+ * import { parseTree, findNode } from "jsonc-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "a": { "b": 1 } }');
+ *   if (Option.isNone(root)) return Option.none();
+ *   return yield* findNode(root.value, ["a", "b"]);
+ * });
+ *
+ * const result = Effect.runSync(program);
+ * // result is Option.some(node) where node.value === 1
+ * ```
+ *
+ * @example Data-last pipeline usage
+ * ```ts
+ * import { Effect, Option, pipe } from "effect";
+ * import type { JsoncNode } from "jsonc-effect";
+ * import { parseTree, findNode } from "jsonc-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "x": [10, 20] }');
+ *   if (Option.isNone(root)) return Option.none();
+ *   return yield* pipe(root.value, findNode(["x", 1]));
+ * });
+ *
+ * const result = Effect.runSync(program);
+ * // result is Option.some(node) where node.value === 20
+ * ```
+ *
+ * @privateRemarks
+ * Wrapped in `Effect.sync`; the underlying traversal is fully synchronous.
+ *
+ * @public
+ */
+declare const findNode: {
+  (path: JsoncPath): (root: JsoncNode) => Effect.Effect<Option.Option<JsoncNode>>;
+  (root: JsoncNode, path: JsoncPath): Effect.Effect<Option.Option<JsoncNode>>;
+};
+/**
+ * Find the innermost AST node covering a character offset.
+ *
+ * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+ * for both data-first and data-last (pipeline) usage.
+ *
+ * @param root - The AST root node obtained from {@link parseTree}.
+ * @param offset - A zero-based character offset into the original JSONC string.
+ *
+ * @returns `Effect<Option<JsoncNode>>` — the most deeply nested node whose span
+ *   includes the offset, or `Option.none()` if the offset is outside the tree.
+ *
+ * @remarks
+ * This is useful for editor integrations such as hover information, go-to-definition,
+ * and code completions where you need to identify the token under the cursor.
+ *
+ * @see {@link parseTree} — produces the AST root this function operates on
+ * @see {@link getNodePath} — returns the JSON path to the node at an offset
+ *
+ * @example Finding a node at an offset
+ * ```ts
+ * import { Effect, Option } from "effect";
+ * import type { JsoncNode } from "jsonc-effect";
+ * import { parseTree, findNodeAtOffset } from "jsonc-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "key": "value" }');
+ *   if (Option.isNone(root)) return Option.none();
+ *   // Offset 10 is inside the "value" string literal
+ *   return yield* findNodeAtOffset(root.value, 10);
+ * });
+ *
+ * const result = Effect.runSync(program);
+ * // result is Option.some(node) where node.type === "string"
+ * ```
+ *
+ * @privateRemarks
+ * Wrapped in `Effect.sync`; the underlying traversal is fully synchronous.
+ *
+ * @public
+ */
+declare const findNodeAtOffset: {
+  (offset: number): (root: JsoncNode) => Effect.Effect<Option.Option<JsoncNode>>;
+  (root: JsoncNode, offset: number): Effect.Effect<Option.Option<JsoncNode>>;
+};
+/**
+ * Get the JSON path to the node at a specific character offset.
+ *
+ * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+ * for both data-first and data-last (pipeline) usage.
+ *
+ * @param root - The AST root node obtained from {@link parseTree}.
+ * @param targetOffset - A zero-based character offset into the original JSONC string.
+ *
+ * @returns `Effect<Option<JsoncPath>>` — an array of path segments (string keys
+ *   and numeric indices) leading to the innermost node at the offset, or
+ *   `Option.none()` if the offset is outside the tree.
+ *
+ * @remarks
+ * Returns the path segments leading to the innermost node that spans the given
+ * offset. This is the inverse of {@link findNode} — given an offset you get the path,
+ * and given a path you get the node.
+ *
+ * @see {@link findNodeAtOffset} — returns the node itself rather than its path
+ * @see {@link (JsoncPath:type)} — the path segment array type
+ *
+ * @example Getting the path at an offset
+ * ```ts
+ * import { Effect, Option } from "effect";
+ * import type { JsoncNode, JsoncPath } from "jsonc-effect";
+ * import { parseTree, getNodePath } from "jsonc-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "a": { "b": 42 } }');
+ *   if (Option.isNone(root)) return Option.none();
+ *   // Offset 15 points inside the value 42
+ *   return yield* getNodePath(root.value, 15);
+ * });
+ *
+ * const result: Option.Option<JsoncPath> = Effect.runSync(program);
+ * // result is Option.some(["a", "b"])
+ * ```
+ *
+ * @public
+ */
+declare const getNodePath: {
+  (targetOffset: number): (root: JsoncNode) => Effect.Effect<Option.Option<JsoncPath>>;
+  (root: JsoncNode, targetOffset: number): Effect.Effect<Option.Option<JsoncPath>>;
+};
+/**
+ * Reconstruct a plain JavaScript value from an AST subtree.
+ *
+ * @param node - The AST node to evaluate, typically obtained via {@link findNode} or
+ *   as the root from {@link parseTree}.
+ *
+ * @returns `Effect<unknown>` — the reconstructed JS value (object, array, string,
+ *   number, boolean, or null).
+ *
+ * @remarks
+ * Recursively evaluates the node tree to produce a plain JavaScript value.
+ * This is the inverse of {@link parseTree}: where `parseTree` turns a JSONC string
+ * into an AST, `getNodeValue` turns an AST subtree back into a JS value.
+ *
+ * @see {@link parseTree} — produces the AST that this function evaluates
+ * @see {@link findNode} — locates a subtree to pass to this function
+ *
+ * @example Extracting the value of a found node
+ * ```ts
+ * import { Effect, Option } from "effect";
+ * import type { JsoncNode } from "jsonc-effect";
+ * import { parseTree, findNode, getNodeValue } from "jsonc-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root: Option.Option<JsoncNode> = yield* parseTree('{ "items": [1, 2, 3] }');
+ *   if (Option.isNone(root)) return undefined;
+ *   const node: Option.Option<JsoncNode> = yield* findNode(root.value, ["items"]);
+ *   if (Option.isNone(node)) return undefined;
+ *   return yield* getNodeValue(node.value);
+ * });
+ *
+ * const result = Effect.runSync(program);
+ * // result is [1, 2, 3]
+ * ```
+ *
+ * @privateRemarks
+ * Useful after {@link findNode} to extract a subtree's value without manual
+ * AST traversal.
+ *
+ * @public
+ */
+declare const getNodeValue: (node: JsoncNode) => Effect.Effect<unknown>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error codes representing specific JSONC parse failures.
+ *
+ * @remarks
+ * Each code maps to a distinct syntactic error the parser can encounter,
+ * from invalid symbols and number formats to missing delimiters and
+ * unexpected end-of-input conditions.
+ *
+ * @see {@link JsoncParseErrorDetail} — carries one of these codes alongside
+ *   position information
+ *
+ * @public
+ */
+declare const JsoncParseErrorCode: Schema.Literal<["InvalidSymbol", "InvalidNumberFormat", "PropertyNameExpected", "ValueExpected", "ColonExpected", "CommaExpected", "CloseBraceExpected", "CloseBracketExpected", "EndOfFileExpected", "InvalidCommentToken", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter"]>;
+/**
+ * The union of all JSONC parse error code string literals.
+ *
+ * @see {@link (JsoncParseErrorCode:variable)}
+ *
+ * @public
+ */
+type JsoncParseErrorCode = Schema.Schema.Type<typeof JsoncParseErrorCode>;
+declare const JsoncParseErrorDetail_base: Schema.Class<JsoncParseErrorDetail, {
+  code: Schema.Literal<["InvalidSymbol", "InvalidNumberFormat", "PropertyNameExpected", "ValueExpected", "ColonExpected", "CommaExpected", "CloseBraceExpected", "CloseBracketExpected", "EndOfFileExpected", "InvalidCommentToken", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter"]>;
+  message: typeof Schema.String;
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+  startLine: typeof Schema.Number;
+  startCharacter: typeof Schema.Number;
+}, Schema.Struct.Encoded<{
+  code: Schema.Literal<["InvalidSymbol", "InvalidNumberFormat", "PropertyNameExpected", "ValueExpected", "ColonExpected", "CommaExpected", "CloseBraceExpected", "CloseBracketExpected", "EndOfFileExpected", "InvalidCommentToken", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter"]>;
+  message: typeof Schema.String;
+  offset: typeof Schema.Number;
+  length: typeof Schema.Number;
+  startLine: typeof Schema.Number;
+  startCharacter: typeof Schema.Number;
+}>, never, {
+  readonly code: "CloseBraceExpected" | "CloseBracketExpected" | "ColonExpected" | "CommaExpected" | "EndOfFileExpected" | "InvalidCharacter" | "InvalidCommentToken" | "InvalidEscapeCharacter" | "InvalidNumberFormat" | "InvalidSymbol" | "InvalidUnicode" | "PropertyNameExpected" | "UnexpectedEndOfComment" | "UnexpectedEndOfNumber" | "UnexpectedEndOfString" | "ValueExpected";
+} & {
+  readonly length: number;
+} & {
+  readonly message: string;
+} & {
+  readonly offset: number;
+} & {
+  readonly startCharacter: number;
+} & {
+  readonly startLine: number;
+}, {}, {}>;
+/**
+ * Detail for a single parse error, including the error code, a human-readable
+ * message, and the exact position within the source document.
+ *
+ * @remarks
+ * - `code` — a {@link (JsoncParseErrorCode:type)} identifying the error kind.
+ * - `message` — a descriptive message suitable for display.
+ * - `offset` — zero-based character offset where the error occurred.
+ * - `length` — character length of the problematic span.
+ * - `startLine` — zero-based line number of the error.
+ * - `startCharacter` — zero-based column within `startLine`.
+ *
+ * @see {@link JsoncParseError} — aggregates an array of these details
+ *
+ * @example
+ * ```ts
+ * import { JsoncParseErrorDetail } from "jsonc-effect";
+ *
+ * const detail = new JsoncParseErrorDetail({
+ *   code: "ValueExpected",
+ *   message: "Value expected",
+ *   offset: 5,
+ *   length: 1,
+ *   startLine: 0,
+ *   startCharacter: 5,
+ * });
+ *
+ * console.log(detail.code); // "ValueExpected"
+ * console.log(detail.offset); // 5
+ * ```
+ *
+ * @public
+ */
+declare class JsoncParseErrorDetail extends JsoncParseErrorDetail_base {}
+/**
+ * Base class for {@link JsoncParseError}; not intended to be constructed or
+ * caught directly — use `JsoncParseError` instead.
+ *
+ * @privateRemarks
+ * The `*Base` pattern is required because `Data.TaggedError` produces complex
+ * type signatures involving intersection types and branded generics that
+ * api-extractor cannot roll up into a single `.d.ts` bundle. Exporting the
+ * base separately lets the public `JsoncParseError` class extend it with
+ * concrete fields, giving api-extractor a simple class declaration to work
+ * with. It is tagged `@public` (rather than `@internal`) because it appears
+ * in `JsoncParseError`'s heritage clause in the public `.d.ts`, and API
+ * Extractor requires release tags to be compatible across a signature.
+ *
+ * @public
+ */
+declare const JsoncParseErrorBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "JsoncParseError";
+} & Readonly<A>;
+/**
+ * Error raised when JSONC parsing encounters one or more syntax errors.
+ *
+ * @remarks
+ * Contains the full source `text`, the `options` used for parsing, and an
+ * `errors` array of {@link JsoncParseErrorDetail} instances with precise
+ * position information for each problem found.
+ *
+ * @see {@link parse} — may fail with this error
+ * @see {@link parseTree} — may fail with this error
+ *
+ * @example Catching with `Effect.catchTag`
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse } from "jsonc-effect";
+ *
+ * const program = parse("{ invalid }").pipe(
+ *   Effect.catchTag("JsoncParseError", (e) => {
+ *     console.error(e.errors); // Array of JsoncParseErrorDetail
+ *     return Effect.succeed({});
+ *   }),
+ * );
+ * ```
+ *
+ * @example Inspecting error details
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse } from "jsonc-effect";
+ *
+ * const program = parse("{ invalid }").pipe(
+ *   Effect.catchTag("JsoncParseError", (e) => {
+ *     for (const detail of e.errors) {
+ *       console.error(
+ *         `[${detail.code}] ${detail.message} at line ${detail.startLine}:${detail.startCharacter}`,
+ *       );
+ *     }
+ *     return Effect.succeed({});
+ *   }),
+ * );
+ * ```
+ *
+ * @public
+ */
+declare class JsoncParseError extends JsoncParseErrorBase<{
+  readonly errors: ReadonlyArray<JsoncParseErrorDetail>;
+  readonly text: string;
+  readonly options?: Partial<JsoncParseOptions>;
+}> {
+  get message(): string;
+}
+/**
+ * Base class for {@link JsoncNodeNotFoundError}; not intended to be
+ * constructed or caught directly — use `JsoncNodeNotFoundError` instead.
+ *
+ * @privateRemarks
+ * Uses the same `*Base` pattern as {@link JsoncParseErrorBase} to work
+ * around api-extractor's inability to roll up the complex type produced
+ * by `Data.TaggedError` into a single `.d.ts` declaration. Tagged `@public`
+ * for the same heritage-clause-compatibility reason as `JsoncParseErrorBase`.
+ *
+ * @public
+ */
+declare const JsoncNodeNotFoundErrorBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "JsoncNodeNotFoundError";
+} & Readonly<A>;
+/**
+ * Error raised when AST navigation fails to find a node at the given path.
+ *
+ * @remarks
+ * Contains the `path` that was searched and the `rootNodeType` of the tree
+ * that was traversed.
+ *
+ * @see {@link findNode} — may fail with this error
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parseTree, findNode } from "jsonc-effect";
+ *
+ * const program = parseTree('{ "a": 1 }').pipe(
+ *   Effect.flatMap((root) => findNode(root, ["missing", "path"])),
+ *   Effect.catchTag("JsoncNodeNotFoundError", (e) => {
+ *     console.error(`Not found: [${e.path.join(", ")}] in ${e.rootNodeType}`);
+ *     return Effect.succeed(undefined);
+ *   }),
+ * );
+ * ```
+ *
+ * @public
+ */
+declare class JsoncNodeNotFoundError extends JsoncNodeNotFoundErrorBase<{
+  readonly path: ReadonlyArray<string | number>;
+  readonly rootNodeType: string;
+}> {
+  get message(): string;
+}
+/**
+ * Base class for {@link JsoncModificationError}; not intended to be
+ * constructed or caught directly — use `JsoncModificationError` instead.
+ *
+ * @privateRemarks
+ * Uses the same `*Base` pattern as {@link JsoncParseErrorBase} to work
+ * around api-extractor's inability to roll up the complex type produced
+ * by `Data.TaggedError` into a single `.d.ts` declaration. Tagged `@public`
+ * for the same heritage-clause-compatibility reason as `JsoncParseErrorBase`.
+ *
+ * @public
+ */
+declare const JsoncModificationErrorBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "JsoncModificationError";
+} & Readonly<A>;
+/**
+ * Error raised when {@link modify} produces invalid edits or encounters
+ * an unsupported modification scenario.
+ *
+ * @remarks
+ * Contains the `path` where modification was attempted and a `reason`
+ * string explaining why it failed.
+ *
+ * @see {@link modify} — may fail with this error
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { modify } from "jsonc-effect";
+ *
+ * const program = modify("{}", ["deep", "path"], 42).pipe(
+ *   Effect.catchTag("JsoncModificationError", (e) => {
+ *     console.error(`Failed at [${e.path.join(", ")}]: ${e.reason}`);
+ *     return Effect.succeed([]);
+ *   }),
+ * );
+ * ```
+ *
+ * @public
+ */
+declare class JsoncModificationError extends JsoncModificationErrorBase<{
+  readonly path: ReadonlyArray<string | number>;
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+/**
+ * Union of all JSONC error types, useful for exhaustive error handling
+ * with `Effect.catchTags`.
+ *
+ * @see {@link JsoncParseError}
+ * @see {@link JsoncNodeNotFoundError}
+ * @see {@link JsoncModificationError}
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import type { JsoncError } from "jsonc-effect";
+ * import { parse, parseTree, findNode, modify } from "jsonc-effect";
+ *
+ * const program = parse("{}").pipe(
+ *   Effect.catchTags({
+ *     JsoncParseError: (e) => Effect.succeed("parse failed"),
+ *     JsoncModificationError: (e) => Effect.succeed("modify failed"),
+ *     JsoncNodeNotFoundError: (e) => Effect.succeed("node not found"),
+ *   }),
+ * );
+ * ```
+ *
+ * @public
+ */
+type JsoncError = JsoncParseError | JsoncNodeNotFoundError | JsoncModificationError;
+//#endregion
+//#region src/equality.d.ts
+/**
+ * Compare two JSONC strings for semantic equality.
+ *
+ * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+ * for both data-first and data-last (pipeline) usage.
+ *
+ * @param self - The first JSONC string.
+ * @param that - The second JSONC string.
+ *
+ * @returns `Effect<boolean, JsoncParseError>` — `true` when both strings parse to
+ *   semantically equivalent values, `false` otherwise. Fails with
+ *   {@link JsoncParseError} if either string is malformed.
+ *
+ * @remarks
+ * Both strings are parsed via {@link parse} and then deep-compared. The comparison
+ * ignores comments, whitespace, formatting, and object key ordering. Array order
+ * IS significant. Uses `Effect.all` internally, so the effect fails on the first
+ * parse error encountered.
+ *
+ * @see {@link equalsValue} — compare a JSONC string against an existing JS value
+ * @see {@link parse} — the underlying parser used for both strings
+ *
+ * @example Data-first comparison
+ * ```ts
+ * import { Effect } from "effect";
+ * import { equals } from "jsonc-effect";
+ *
+ * const result = Effect.runSync(
+ *   equals('{ "a": 1, "b": 2 }', '{"b":2,"a":1}')
+ * );
+ * // result is true
+ * ```
+ *
+ * @example Key-order independence
+ * ```ts
+ * import { Effect } from "effect";
+ * import { equals } from "jsonc-effect";
+ *
+ * // Object key order does not matter
+ * const sameKeys = Effect.runSync(
+ *   equals('{"z":1,"a":2}', '{"a":2,"z":1}')
+ * );
+ * // sameKeys is true
+ *
+ * // Array order DOES matter
+ * const differentOrder = Effect.runSync(
+ *   equals('[1, 2]', '[2, 1]')
+ * );
+ * // differentOrder is false
+ * ```
+ *
+ * @example Error handling
+ * ```ts
+ * import { Effect, Either } from "effect";
+ * import type { JsoncParseError } from "jsonc-effect";
+ * import { equals } from "jsonc-effect";
+ *
+ * const result: Either.Either<boolean, JsoncParseError> = Effect.runSync(
+ *   Effect.either(equals('{ invalid }', '{}'))
+ * );
+ * // result is Either.left(JsoncParseError)
+ * ```
+ *
+ * @privateRemarks
+ * Uses a simple recursive `deepEqual` helper rather than Effect's `Equal` module
+ * because the parsed values are plain JS objects and arrays, not Effect data types.
+ *
+ * @public
+ */
+declare const equals: {
+  (that: string): (self: string) => Effect.Effect<boolean, JsoncParseError>;
+  (self: string, that: string): Effect.Effect<boolean, JsoncParseError>;
+};
+/**
+ * Compare a JSONC string against a JavaScript value for semantic equality.
+ *
+ * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+ * for both data-first and data-last (pipeline) usage.
+ *
+ * @param self - The JSONC string to parse.
+ * @param value - The JavaScript value to compare against.
+ *
+ * @returns `Effect<boolean, JsoncParseError>` — `true` when the parsed JSONC
+ *   is semantically equivalent to the provided value, `false` otherwise.
+ *   Fails with {@link JsoncParseError} if the string is malformed.
+ *
+ * @remarks
+ * Only the JSONC string is parsed; the JS value is used as-is. This makes
+ * `equalsValue` useful for assertions and testing where the expected value
+ * is already a JS object. The comparison semantics are the same as
+ * {@link equals}: comments, whitespace, formatting, and object key ordering
+ * are ignored, while array order IS significant.
+ *
+ * @see {@link equals} — compare two JSONC strings against each other
+ * @see {@link parse} — the underlying parser
+ *
+ * @example Basic comparison
+ * ```ts
+ * import { Effect } from "effect";
+ * import { equalsValue } from "jsonc-effect";
+ *
+ * const result = Effect.runSync(
+ *   equalsValue('{"port": 3000, "host": "localhost"}', { host: "localhost", port: 3000 })
+ * );
+ * // result is true
+ * ```
+ *
+ * @example Pipeline usage for testing
+ * ```ts
+ * import { Effect, pipe } from "effect";
+ * import { equalsValue } from "jsonc-effect";
+ *
+ * const jsonc = '{ "enabled": true, "count": 5 }';
+ * const expected = { enabled: true, count: 5 };
+ *
+ * const result = Effect.runSync(
+ *   pipe(jsonc, equalsValue(expected))
+ * );
+ * // result is true
+ * ```
+ *
+ * @public
+ */
+declare const equalsValue: {
+  (value: unknown): (self: string) => Effect.Effect<boolean, JsoncParseError>;
+  (self: string, value: unknown): Effect.Effect<boolean, JsoncParseError>;
+};
+//#endregion
+//#region src/format.d.ts
+/**
+ * Compute formatting edits for a JSONC document.
+ *
+ * Returns an array of {@link JsoncEdit} objects describing text replacements
+ * that, when applied, produce a well-formatted document. The input text is
+ * never mutated — apply the returned edits with {@link applyEdits}.
+ *
+ * @param text - The JSONC source text to format.
+ * @param range - Optional sub-range to format. When provided, only edits
+ *   within the range are returned.
+ * @param options - Partial {@link JsoncFormattingOptions} controlling indent
+ *   size, tabs vs. spaces, EOL style, and final-newline insertion.
+ * @returns An `Effect` that succeeds with a read-only array of
+ *   {@link JsoncEdit} objects.
+ *
+ * @remarks
+ * This function is non-mutating by design. It computes a minimal set of
+ * whitespace edits; structural changes (inserting or removing properties)
+ * are handled by {@link modify}. The `range` parameter allows formatting a
+ * subset of the document without touching surrounding text.
+ *
+ * @see {@link applyEdits} to apply the returned edits to the source text.
+ * @see {@link formatAndApply} for a one-step format-and-apply convenience.
+ * @see {@link JsoncFormattingOptions} for available formatting controls.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import type { JsoncEdit } from "jsonc-effect";
+ * import { format, applyEdits } from "jsonc-effect";
+ *
+ * const input = '{"a":1, "b" :2}';
+ * const edits: ReadonlyArray<JsoncEdit> = Effect.runSync(format(input));
+ * const formatted: string = Effect.runSync(applyEdits(input, edits));
+ * ```
+ *
+ * @privateRemarks
+ * Uses {@link createScanner} internally to tokenize the input and compute
+ * whitespace adjustments between consecutive non-trivia tokens.
+ *
+ * @public
+ */
+declare const format: (text: string, range?: JsoncRange, options?: Partial<JsoncFormattingOptions>) => Effect.Effect<ReadonlyArray<JsoncEdit>>;
+/**
+ * Apply an array of text edits to JSONC source text.
+ *
+ * This is a {@link https://effect.website/docs/function-dual | Function.dual}
+ * that supports both data-first and data-last (pipeline) usage.
+ *
+ * @param text - The original JSONC source text.
+ * @param edits - A read-only array of {@link JsoncEdit} objects, typically
+ *   produced by {@link format} or {@link modify}.
+ * @returns An `Effect` that succeeds with the edited string.
+ *
+ * @remarks
+ * Edits are sorted in reverse offset order before application so that
+ * earlier edits do not shift the offsets of later ones. The original `edits`
+ * array is not mutated.
+ *
+ * @see {@link format} to compute formatting edits.
+ * @see {@link modify} to compute structural edits (insert, replace, remove).
+ *
+ * @example Data-first usage
+ * ```ts
+ * import { Effect } from "effect";
+ * import { format, applyEdits } from "jsonc-effect";
+ *
+ * const input = '{"a":1}';
+ * const edits = Effect.runSync(format(input));
+ * const result: string = Effect.runSync(applyEdits(input, edits));
+ * ```
+ *
+ * @example Pipeline with modify
+ * ```ts
+ * import { Effect, pipe } from "effect";
+ * import { modify, applyEdits } from "jsonc-effect";
+ *
+ * const input = '{ "a": 1 }';
+ * const result = pipe(
+ *   input,
+ *   modify(["a"], 42),
+ *   Effect.flatMap((edits) => applyEdits(input, edits)),
+ *   Effect.runSync,
+ * );
+ * ```
+ *
+ * @public
+ */
+declare const applyEdits: {
+  (edits: ReadonlyArray<JsoncEdit>): (text: string) => Effect.Effect<string>;
+  (text: string, edits: ReadonlyArray<JsoncEdit>): Effect.Effect<string>;
+};
+/**
+ * Format a JSONC document in one step by computing edits and immediately
+ * applying them.
+ *
+ * This is a convenience that combines {@link format} and {@link applyEdits}
+ * into a single call.
+ *
+ * @param text - The JSONC source text to format.
+ * @param range - Optional sub-range to restrict formatting to.
+ * @param options - Partial {@link JsoncFormattingOptions} controlling indent
+ *   size, tabs vs. spaces, EOL style, and final-newline insertion.
+ * @returns An `Effect` that succeeds with the fully formatted string.
+ *
+ * @see {@link format} to obtain the edits without applying them.
+ * @see {@link applyEdits} to apply edits separately.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { formatAndApply } from "jsonc-effect";
+ *
+ * const input = '{"a":1, "b" :2}';
+ * const formatted: string = Effect.runSync(formatAndApply(input));
+ * ```
+ *
+ * @public
+ */
+declare const formatAndApply: (text: string, range?: JsoncRange, options?: Partial<JsoncFormattingOptions>) => Effect.Effect<string>;
+/**
+ * Compute edits to insert, replace, or remove a value at a JSON path.
+ *
+ * This is a {@link https://effect.website/docs/function-dual | Function.dual}
+ * that supports both data-first and data-last (pipeline) usage.
+ *
+ * @param text - The JSONC source text to modify.
+ * @param path - A {@link (JsoncPath:type)} (array of string keys and numeric indices)
+ *   identifying the target location in the JSON structure.
+ * @param value - The value to set. Pass `undefined` to remove the
+ *   property or array element at the given path.
+ * @param options - Optional object with `formattingOptions` controlling
+ *   indent size, tabs vs. spaces, and EOL style for generated text.
+ * @returns An `Effect` that succeeds with a read-only array of
+ *   {@link JsoncEdit} objects, or fails with a
+ *   {@link JsoncModificationError} if the path cannot be navigated.
+ *
+ * @remarks
+ * Setting `value` to `undefined` removes the targeted property or element,
+ * including its surrounding comma. When inserting a new property into an
+ * object, it is appended after the last existing property.
+ *
+ * @see {@link applyEdits} to apply the returned edits to the source text.
+ * @see {@link JsoncModificationError} for the error type on navigation failure.
+ *
+ * @example Update an existing property
+ * ```ts
+ * import { Effect } from "effect";
+ * import { modify, applyEdits } from "jsonc-effect";
+ *
+ * const input = '{ "a": 1 }';
+ * const edits = Effect.runSync(modify(input, ["a"], 2));
+ * const result: string = Effect.runSync(applyEdits(input, edits));
+ * ```
+ *
+ * @example Insert a new property
+ * ```ts
+ * import { Effect } from "effect";
+ * import { modify, applyEdits } from "jsonc-effect";
+ *
+ * const input = '{ "a": 1 }';
+ * const edits = Effect.runSync(modify(input, ["b"], "hello"));
+ * const result: string = Effect.runSync(applyEdits(input, edits));
+ * ```
+ *
+ * @example Remove a property
+ * ```ts
+ * import { Effect } from "effect";
+ * import { modify, applyEdits } from "jsonc-effect";
+ *
+ * const input = '{ "a": 1, "b": 2 }';
+ * const edits = Effect.runSync(modify(input, ["a"], undefined));
+ * const result: string = Effect.runSync(applyEdits(input, edits));
+ * ```
+ *
+ * @example Pipeline (data-last) usage
+ * ```ts
+ * import { Effect, pipe } from "effect";
+ * import { modify, applyEdits } from "jsonc-effect";
+ *
+ * const input = '{ "a": 1 }';
+ * const result = pipe(
+ *   input,
+ *   modify(["a"], 42),
+ *   Effect.flatMap((edits) => applyEdits(input, edits)),
+ *   Effect.runSync,
+ * );
+ * ```
+ *
+ * @privateRemarks
+ * Uses its own scanner-based navigation to locate the target path rather
+ * than building a full AST via `parseTree`. This keeps the implementation
+ * lightweight and avoids an intermediate allocation.
+ *
+ * @public
+ */
+declare const modify: {
+  (path: JsoncPath, value: unknown, options?: {
+    formattingOptions?: Partial<JsoncFormattingOptions>;
+  }): (text: string) => Effect.Effect<ReadonlyArray<JsoncEdit>, JsoncModificationError>;
+  (text: string, path: JsoncPath, value: unknown, options?: {
+    formattingOptions?: Partial<JsoncFormattingOptions>;
+  }): Effect.Effect<ReadonlyArray<JsoncEdit>, JsoncModificationError>;
+};
+//#endregion
+//#region src/parse.d.ts
+/**
+ * Parse a JSONC string into a JavaScript value.
+ *
+ * @param text - JSONC string to parse
+ * @param options - Optional {@link JsoncParseOptions} controlling comment and
+ *   trailing-comma handling.
+ * @returns `Effect<unknown, JsoncParseError>` — succeeds with the parsed value
+ *   or fails with a {@link JsoncParseError} containing every error encountered.
+ *
+ * @remarks
+ * The return type is `unknown` (not `any`) so consumers are forced to narrow
+ * the result, which is safer in Effect pipelines. By default
+ * `allowTrailingComma` is `true`, matching common JSONC conventions used in
+ * VS Code settings and `tsconfig.json`.
+ *
+ * @see {@link parseTree} — parse into an AST instead of a plain value
+ * @see {@link JsoncParseOptions} — available parse options
+ * @see {@link JsoncParseError} — the tagged error type on the failure channel
+ *
+ * @example
+ * Basic parsing:
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse } from "jsonc-effect";
+ *
+ * const value = Effect.runSync(parse('{ "key": 42 }'));
+ * console.log(value); // { key: 42 }
+ * ```
+ *
+ * @example
+ * Parsing with options:
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse } from "jsonc-effect";
+ *
+ * const value = Effect.runSync(
+ *   parse('{ "key": 42 }', { disallowComments: true }),
+ * );
+ * ```
+ *
+ * @example
+ * Error handling with `catchTag`:
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse } from "jsonc-effect";
+ *
+ * const program = parse("{ bad }").pipe(
+ *   Effect.catchTag("JsoncParseError", (err) =>
+ *     Effect.succeed({ fallback: true, errors: err.errors }),
+ *   ),
+ * );
+ *
+ * const result = Effect.runSync(program);
+ * console.log(result);
+ * ```
+ *
+ * @example
+ * Using `Effect.gen`:
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse } from "jsonc-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const config = yield* parse('{ "port": 3000 }');
+ *   return config;
+ * });
+ *
+ * const result = Effect.runSync(program);
+ * console.log(result); // { port: 3000 }
+ * ```
+ *
+ * @privateRemarks
+ * Uses {@link createScanner} internally with a recursive descent parser.
+ * The scanner is created with `ignoreTrivia = false` so the parser can
+ * report comment-related errors when `disallowComments` is set.
+ *
+ * @public
+ */
+declare const parse: {
+  (text: string): Effect.Effect<unknown, JsoncParseError>;
+  (text: string, options: Partial<JsoncParseOptions>): Effect.Effect<unknown, JsoncParseError>;
+};
+/**
+ * Parse a JSONC string into an immutable AST.
+ *
+ * @param text - JSONC string to parse
+ * @param options - Optional {@link JsoncParseOptions} controlling comment and
+ *   trailing-comma handling.
+ * @returns `Effect<Option<JsoncNode>, JsoncParseError>` — succeeds with
+ *   `Option.some(root)` for non-empty documents or `Option.none()` when the
+ *   input is empty (and `allowEmptyContent` is set).
+ *
+ * @remarks
+ * The returned AST is immutable and does **not** contain parent pointers, which
+ * keeps nodes safe to share across fibers. Use the AST navigation helpers
+ * ({@link findNode}, {@link getNodeValue}) to traverse and extract values from
+ * the tree.
+ *
+ * `Option.none()` is returned only when the document contains no value tokens
+ * and `allowEmptyContent` is enabled; otherwise an empty document produces a
+ * {@link JsoncParseError}.
+ *
+ * @see {@link parse} — parse into a plain JavaScript value instead of an AST
+ * @see {@link findNode} — locate a node by JSON path segments
+ * @see {@link getNodeValue} — extract the JavaScript value from a subtree
+ * @see {@link JsoncNode} — the AST node type
+ *
+ * @example
+ * Parsing a JSONC string and navigating the tree:
+ * ```ts
+ * import { Effect, Option } from "effect";
+ * import { parseTree } from "jsonc-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const maybeRoot = yield* parseTree('{ "a": [1, 2, 3] }');
+ *   if (Option.isSome(maybeRoot)) {
+ *     const root = maybeRoot.value;
+ *     console.log(root.type); // "object"
+ *     console.log(root.children?.length); // 1
+ *   }
+ * });
+ *
+ * Effect.runSync(program);
+ * ```
+ *
+ * @privateRemarks
+ * Internally the parser builds a mutable tree using `MutableJsoncNode` and
+ * casts to the readonly `JsoncNode` on output.
+ *
+ * @public
+ */
+declare const parseTree: {
+  (text: string): Effect.Effect<Option.Option<JsoncNode>, JsoncParseError>;
+  (text: string, options: Partial<JsoncParseOptions>): Effect.Effect<Option.Option<JsoncNode>, JsoncParseError>;
+};
+/**
+ * Remove all comments from JSONC text, producing valid JSON.
+ *
+ * @param text - JSONC string to strip comments from
+ * @param replaceCh - Optional single character used to replace each character of
+ *   every comment. When provided, the output has the **same length** as the
+ *   input so that all offsets are preserved (line breaks inside block comments
+ *   are kept as-is).
+ * @returns `Effect<string>` — the text with all comments removed (or replaced).
+ *
+ * @remarks
+ * When `replaceCh` is omitted the comment text is simply deleted, which means
+ * character offsets in the output no longer match the original document. Pass a
+ * space (`" "`) as `replaceCh` to keep offsets stable — this is useful when you
+ * need to correlate positions between the original JSONC and the stripped JSON.
+ *
+ * @see {@link parse} — parse JSONC directly without a stripping step
+ *
+ * @example
+ * Basic comment stripping:
+ * ```ts
+ * import { Effect } from "effect";
+ * import { stripComments } from "jsonc-effect";
+ *
+ * const json = Effect.runSync(
+ *   stripComments('{ "a": 1 // comment\n}'),
+ * );
+ * console.log(json); // '{ "a": 1 \n}'
+ * ```
+ *
+ * @example
+ * Using a replacement character to preserve offsets:
+ * ```ts
+ * import { Effect } from "effect";
+ * import { stripComments } from "jsonc-effect";
+ *
+ * const json = Effect.runSync(
+ *   stripComments('{ "a": 1 // comment\n}', " "),
+ * );
+ * console.log(json.length === '{ "a": 1 // comment\n}'.length); // true
+ * ```
+ *
+ * @public
+ */
+declare const stripComments: {
+  (text: string): Effect.Effect<string>;
+  (text: string, replaceCh: string): Effect.Effect<string>;
+};
+//#endregion
+//#region src/scanner.d.ts
+/**
+ * Stateful cursor over JSONC text that produces tokens on demand.
+ *
+ * @remarks
+ * The scanner is the lowest-level API in jsonc-effect. It exposes an
+ * imperative scan-loop pattern: call {@link JsoncScanner.scan | scan()} in a
+ * loop until it returns `"EOF"`, inspecting the current token with the
+ * getter methods after each call.
+ *
+ * Unlike the rest of the library, the scanner is **mutable** — each call to
+ * `scan()` advances an internal cursor and updates all token-related state.
+ *
+ * @see {@link createScanner} — factory function that produces a `JsoncScanner`
+ * @see {@link (JsoncSyntaxKind:type)} — string literal union of all token types
+ *
+ * @example
+ * Collecting all structural tokens from a JSONC string:
+ * ```ts
+ * import type { JsoncSyntaxKind } from "jsonc-effect";
+ * import { createScanner } from "jsonc-effect";
+ *
+ * const scanner = createScanner('{ "key": 42 }', true);
+ * const tokens: JsoncSyntaxKind[] = [];
+ * let kind: JsoncSyntaxKind;
+ * do {
+ *   kind = scanner.scan();
+ *   tokens.push(kind);
+ * } while (kind !== "EOF");
+ * console.log(tokens);
+ * // ["OpenBrace", "String", "Colon", "Number", "CloseBrace", "EOF"]
+ * ```
+ *
+ * @privateRemarks
+ * The scanner is the only mutable/stateful part of the library. All other
+ * APIs are pure Effect pipelines built on top of it.
+ *
+ * @public
+ */
+interface JsoncScanner {
+  /** Advance the cursor to the next token and return its {@link (JsoncSyntaxKind:type)}. */
+  scan(): JsoncSyntaxKind;
+  /** Return the {@link (JsoncSyntaxKind:type)} of the current token without advancing. */
+  getToken(): JsoncSyntaxKind;
+  /** Return the string value of the current token (e.g. the unescaped content of a string literal). */
+  getTokenValue(): string;
+  /** Return the zero-based character offset where the current token begins. */
+  getTokenOffset(): number;
+  /** Return the character length of the current token. */
+  getTokenLength(): number;
+  /** Return the zero-based line number where the current token starts. */
+  getTokenStartLine(): number;
+  /** Return the zero-based character position within the line where the current token starts. */
+  getTokenStartCharacter(): number;
+  /** Return the {@link (JsoncScanError:type)} for the current token, or `"None"` if no error. */
+  getTokenError(): JsoncScanError;
+  /** Return the current cursor position (byte offset into the source text). */
+  getPosition(): number;
+  /** Set the cursor position, resetting the current token state. */
+  setPosition(pos: number): void;
+}
+/**
+ * Create a stateful {@link JsoncScanner} for the given JSONC string.
+ *
+ * @param text - JSONC string to tokenize
+ * @param ignoreTrivia - If `true`, the scanner automatically skips whitespace,
+ *   line-break, and comment tokens so that only structural tokens are returned
+ *   (default: `false`).
+ * @returns A stateful {@link JsoncScanner} positioned before the first token.
+ *
+ * @remarks
+ * When `ignoreTrivia` is `true` the scanner is suitable for building parsers
+ * that only care about structural tokens (`OpenBrace`, `String`, `Number`,
+ * etc.). Set it to `false` (the default) when you need to preserve comments
+ * or whitespace — for example in a formatter or a comment-stripping pass.
+ *
+ * @see {@link JsoncScanner} — the interface returned by this factory
+ * @see {@link parse} — higher-level API that uses a scanner internally
+ *
+ * @example
+ * Tokenizing a JSONC string and printing each token:
+ * ```ts
+ * import type { JsoncSyntaxKind } from "jsonc-effect";
+ * import { createScanner } from "jsonc-effect";
+ *
+ * const scanner = createScanner('{ "name": "jsonc" }', true);
+ * let kind: JsoncSyntaxKind;
+ * do {
+ *   kind = scanner.scan();
+ *   console.log(kind, scanner.getTokenValue());
+ * } while (kind !== "EOF");
+ * ```
+ *
+ * @privateRemarks
+ * Ported from Microsoft's jsonc-parser (MIT), adapted to use string literal
+ * token types instead of numeric enums.
+ *
+ * @public
+ */
+declare const createScanner: (text: string, ignoreTrivia?: boolean) => JsoncScanner;
+//#endregion
+//#region src/schema-integration.d.ts
+/**
+ * Pre-built `Schema<unknown, string>` that decodes a JSONC string into an
+ * unknown JavaScript value using default parse options.
+ *
+ * This is the first stage of a typical parsing pipeline:
+ *
+ * ```
+ * JSONC string  --JsoncFromString-->  unknown  --YourSchema-->  A
+ * ```
+ *
+ * @remarks
+ * Default parse options are used (comments allowed, trailing commas
+ * allowed). The encode direction uses `JSON.stringify` with 2-space
+ * indentation, which means comments present in the original JSONC
+ * input are not preserved during a round-trip encode.
+ *
+ * For custom parse options, use {@link makeJsoncFromString} instead.
+ *
+ * @see {@link makeJsoncFromString} to create a schema with custom options.
+ * @see {@link makeJsoncSchema} to compose JSONC parsing with a domain schema
+ *   in one step.
+ *
+ * @example Decode a JSONC string
+ * ```ts
+ * import { Schema } from "effect";
+ * import { JsoncFromString } from "jsonc-effect";
+ *
+ * const value: unknown = Schema.decodeUnknownSync(JsoncFromString)(
+ *   '{ "key": 42 // comment\n}',
+ * );
+ * ```
+ *
+ * @example Compose with a domain schema
+ * ```ts
+ * import { Schema } from "effect";
+ * import { JsoncFromString } from "jsonc-effect";
+ *
+ * const MyConfig = Schema.Struct({
+ *   name: Schema.String,
+ *   version: Schema.Number,
+ * });
+ *
+ * const MyConfigFromJsonc = Schema.compose(JsoncFromString, MyConfig);
+ * const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(
+ *   '{ "name": "app", "version": 1 }',
+ * );
+ * ```
+ *
+ * @public
+ */
+declare const JsoncFromString: Schema.Schema<unknown, string>;
+/**
+ * Create a `Schema<unknown, string>` that decodes JSONC with custom
+ * parse options.
+ *
+ * @param options - Partial {@link JsoncParseOptions} controlling comment
+ *   handling and trailing-comma tolerance.
+ * @returns A `Schema<unknown, string>` configured with the given options.
+ *
+ * @remarks
+ * The encode direction uses `JSON.stringify` with 2-space indentation,
+ * which produces standard JSON. Comments present in the original JSONC
+ * input are not preserved during a round-trip encode.
+ *
+ * @see {@link JsoncFromString} for a zero-config default instance.
+ * @see {@link makeJsoncSchema} to compose JSONC parsing with a domain
+ *   schema in one step.
+ *
+ * @example Strict mode (no comments, no trailing commas)
+ * ```ts
+ * import { Schema } from "effect";
+ * import { makeJsoncFromString } from "jsonc-effect";
+ *
+ * const StrictJsoncFromString = makeJsoncFromString({
+ *   disallowComments: true,
+ *   allowTrailingComma: false,
+ * });
+ *
+ * const value: unknown = Schema.decodeUnknownSync(StrictJsoncFromString)(
+ *   '{ "key": 42 }',
+ * );
+ * ```
+ *
+ * @privateRemarks
+ * Internally delegates to `Schema.transformOrFail` to wire up the decode
+ * and encode directions.
+ *
+ * @public
+ */
+declare function makeJsoncFromString(options?: Partial<JsoncParseOptions>): Schema.Schema<unknown, string>;
+/**
+ * Create a composed `Schema<A, string>` that parses a JSONC string and
+ * validates the result against a target domain schema in one step.
+ *
+ * @param targetSchema - The domain schema to validate the parsed value
+ *   against. Its input type `I` must be assignable from `unknown`.
+ * @param options - Optional partial {@link JsoncParseOptions} forwarded to
+ *   the underlying JSONC parser.
+ * @returns A `Schema<A, string>` that goes directly from a JSONC string
+ *   to a fully validated domain value of type `A`.
+ *
+ * @remarks
+ * Internally composes two schema stages:
+ *
+ * 1. JSONC string to `unknown` (via {@link makeJsoncFromString}).
+ * 2. `unknown` to `A` (via the provided `targetSchema`).
+ *
+ * This avoids the need to manually call `Schema.compose`.
+ *
+ * @see {@link makeJsoncFromString} for the first stage of the pipeline.
+ *
+ * @example Typed configuration from JSONC
+ * ```ts
+ * import { Schema } from "effect";
+ * import { makeJsoncSchema } from "jsonc-effect";
+ *
+ * const MyConfig = Schema.Struct({
+ *   name: Schema.String,
+ *   version: Schema.Number,
+ * });
+ *
+ * const MyConfigFromJsonc = makeJsoncSchema(MyConfig);
+ * const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(
+ *   '{ "name": "app", "version": 1 }',
+ * );
+ * ```
+ *
+ * @example With custom parse options
+ * ```ts
+ * import { Schema } from "effect";
+ * import { makeJsoncSchema } from "jsonc-effect";
+ *
+ * const MyConfig = Schema.Struct({ debug: Schema.Boolean });
+ *
+ * const StrictConfig = makeJsoncSchema(MyConfig, {
+ *   disallowComments: true,
+ *   allowTrailingComma: false,
+ * });
+ *
+ * const config = Schema.decodeUnknownSync(StrictConfig)(
+ *   '{ "debug": true }',
+ * );
+ * ```
+ *
+ * @privateRemarks
+ * Uses `Schema.compose` internally to chain the JSONC-from-string schema
+ * with the provided target schema.
+ *
+ * @public
+ */
+declare const makeJsoncSchema: <A, I>(targetSchema: Schema.Schema<A, I>, options?: Partial<JsoncParseOptions>) => Schema.Schema<A, string>;
+//#endregion
+//#region src/visitor.d.ts
+/**
+ * Discriminated union of JSONC visitor events.
+ *
+ * Each variant carries an `_tag` discriminant, an `offset`, and a `length`
+ * describing where the event occurred in the source text. Some variants
+ * include additional fields such as `path`, `value`, or `property`.
+ *
+ * @remarks
+ * The nine event types are:
+ *
+ * - **ObjectBegin** — opening `{` of an object, includes `path`.
+ * - **ObjectEnd** — closing `}` of an object.
+ * - **ObjectProperty** — a property key, includes `property` and `path`.
+ * - **ArrayBegin** — opening `[` of an array, includes `path`.
+ * - **ArrayEnd** — closing `]` of an array.
+ * - **LiteralValue** — a string, number, boolean, or null literal,
+ *   includes `value` and `path`.
+ * - **Separator** — a `,` or `:` character.
+ * - **Comment** — a line or block comment.
+ * - **Error** — a parse error, includes a {@link (JsoncParseErrorCode:type)} `code`.
+ *
+ * Use the `_tag` field to discriminate between variants in `switch`
+ * statements or {@link https://effect.website/docs/stream/operations | Stream}
+ * filter predicates.
+ *
+ * @see {@link visit} to produce a stream of these events.
+ * @see {@link visitCollect} to collect matching events in one step.
+ *
+ * @example Filtering events by tag
+ * ```ts
+ * import { Chunk, Effect, Stream } from "effect";
+ * import type { JsoncVisitorEvent } from "jsonc-effect";
+ * import { visit } from "jsonc-effect";
+ *
+ * const literals = Effect.runSync(
+ *   visit('{ "a": 1 }').pipe(
+ *     Stream.filter(
+ *       (e): e is Extract<JsoncVisitorEvent, { _tag: "LiteralValue" }> =>
+ *         e._tag === "LiteralValue",
+ *     ),
+ *     Stream.runCollect,
+ *     Effect.map(Chunk.toReadonlyArray),
+ *   ),
+ * );
+ * ```
+ *
+ * @public
+ */
+type JsoncVisitorEvent = {
+  readonly _tag: "ObjectBegin";
+  readonly offset: number;
+  readonly length: number;
+  readonly path: ReadonlyArray<string | number>;
+} | {
+  readonly _tag: "ObjectEnd";
+  readonly offset: number;
+  readonly length: number;
+} | {
+  readonly _tag: "ObjectProperty";
+  readonly property: string;
+  readonly offset: number;
+  readonly length: number;
+  readonly path: ReadonlyArray<string | number>;
+} | {
+  readonly _tag: "ArrayBegin";
+  readonly offset: number;
+  readonly length: number;
+  readonly path: ReadonlyArray<string | number>;
+} | {
+  readonly _tag: "ArrayEnd";
+  readonly offset: number;
+  readonly length: number;
+} | {
+  readonly _tag: "LiteralValue";
+  readonly value: unknown;
+  readonly offset: number;
+  readonly length: number;
+  readonly path: ReadonlyArray<string | number>;
+} | {
+  readonly _tag: "Separator";
+  readonly character: string;
+  readonly offset: number;
+  readonly length: number;
+} | {
+  readonly _tag: "Comment";
+  readonly offset: number;
+  readonly length: number;
+} | {
+  readonly _tag: "Error";
+  readonly code: JsoncParseErrorCode;
+  readonly offset: number;
+  readonly length: number;
+};
+/**
+ * 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
+ */
+declare const visit: (text: string, options?: Partial<JsoncParseOptions>) => Stream.Stream<JsoncVisitorEvent>;
+/**
+ * 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
+ */
+declare const visitCollect: <A extends JsoncVisitorEvent>(text: string, predicate: (event: JsoncVisitorEvent) => event is A, options?: Partial<JsoncParseOptions>) => Effect.Effect<ReadonlyArray<A>>;
+//#endregion
+export { JsoncEdit, type JsoncError, JsoncFormattingOptions, JsoncFromString, JsoncModificationError, JsoncModificationErrorBase, JsoncNode, JsoncNodeNotFoundError, JsoncNodeNotFoundErrorBase, type JsoncNodeType, JsoncParseError, JsoncParseErrorBase, type JsoncParseErrorCode, JsoncParseErrorDetail, JsoncParseOptions, type JsoncPath, JsoncRange, type JsoncScanError, type JsoncScanner, type JsoncSegment, type JsoncSyntaxKind, JsoncToken, type JsoncVisitorEvent, applyEdits, createScanner, equals, equalsValue, findNode, findNodeAtOffset, format, formatAndApply, getNodePath, getNodeValue, makeJsoncFromString, makeJsoncSchema, modify, parse, parseTree, stripComments, visit, visitCollect };
+//# sourceMappingURL=index.d.ts.map