jsonc-effect 0.1.0 → 0.2.0

package/index.d.ts

@@ -16,8 +16,49 @@ import { Stream } from 'effect';
 import { YieldableError } from 'effect/Cause';
 
 /**
- * Apply an array of edits to JSONC source text.
- * Edits are applied in reverse offset order to avoid offset shifting.
+ * 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>;
@@ -25,35 +66,232 @@ export declare const applyEdits: {
 };
 
 /**
- * Create a JSONC scanner.
+ * 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.
  *
- * @param text - The JSONC string to scan
- * @param ignoreTrivia - If true, skip whitespace, line breaks, and comments
- * @returns A JsoncScanner for iterating over tokens
+ * @public
  */
 export declare const createScanner: (text: string, ignoreTrivia?: boolean) => JsoncScanner;
 
 /**
- * Find a node at a specific path in the AST.
+ * Compare two JSONC strings for semantic equality.
  *
- * Traverses the AST following property names (strings) and
- * array indices (numbers) in the path.
+ * Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+ * for both data-first and data-last (pipeline) usage.
  *
- * @example
+ * @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, Option, pipe } from "effect";
- * import { parseTree, findNode } from "@spencerbeggs/jsonc-effect";
+ * 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.
  *
- * // Data-first
- * const node = Effect.gen(function* () {
- *   const root = yield* parseTree('{ "a": { "b": 1 } }');
+ * 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"]);
  * });
  *
- * // Data-last (pipeline)
- * const node2 = pipe(root, findNode(["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>>;
@@ -61,16 +299,45 @@ export declare const findNode: {
 };
 
 /**
- * Find the innermost node covering a character offset.
+ * Find the innermost AST node covering a character offset.
  *
- * @example
+ * 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, pipe } from "effect";
- * import { parseTree, findNodeAtOffset } from "@spencerbeggs/jsonc-effect";
+ * 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);
+ * });
  *
- * // Data-last (pipeline)
- * const node = pipe(root, findNodeAtOffset(5));
+ * 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>>;
@@ -80,36 +347,115 @@ export declare const findNodeAtOffset: {
 /**
  * Compute formatting edits for a JSONC document.
  *
- * Does NOT mutate the input — returns an array of edits to apply
- * with applyEdits().
+ * 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 { format, applyEdits } from "@spencerbeggs/jsonc-effect";
+ * import type { JsoncEdit } from "jsonc-effect";
+ * import { format, applyEdits } from "jsonc-effect";
  *
- * const edits = Effect.runSync(format('{"a":1}'));
- * const formatted = Effect.runSync(applyEdits('{"a":1}', edits));
+ * 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 (format + apply).
+ * 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 offset.
+ * Get the JSON path to the node at a specific character offset.
  *
- * @example
+ * 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, pipe } from "effect";
- * import { parseTree, getNodePath } from "@spencerbeggs/jsonc-effect";
+ * import { Effect, Option } from "effect";
+ * import type { JsoncNode, JsoncPath } from "jsonc-effect";
+ * import { parseTree, getNodePath } from "jsonc-effect";
  *
- * // Data-last (pipeline)
- * const path = pipe(root, getNodePath(5));
+ * 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>>;
@@ -117,13 +463,78 @@ export declare const getNodePath: {
 };
 
 /**
- * Evaluate a node subtree into a plain JavaScript value.
- * Reconstructs objects and arrays from the AST.
+ * 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 text edit to apply to a JSONC document.
+ * 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 {
 }
@@ -145,14 +556,20 @@ declare const JsoncEdit_base: Schema.Class<JsoncEdit, {
 }, {}, {}>;
 
 /**
- * Union of all JSONC error types for exhaustive error handling.
+ * 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 { parse, type JsoncError } from "jsonc-effect";
+ * import type { JsoncError } from "jsonc-effect";
+ * import { parse, parseTree, findNode, modify } from "jsonc-effect";
  *
- * const program = someJsoncOperation.pipe(
+ * const program = parse("{}").pipe(
  *   Effect.catchTags({
  *     JsoncParseError: (e) => Effect.succeed("parse failed"),
  *     JsoncModificationError: (e) => Effect.succeed("modify failed"),
@@ -160,11 +577,44 @@ declare const JsoncEdit_base: Schema.Class<JsoncEdit, {
  *   }),
  * );
  * ```
+ *
+ * @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 {
 }
@@ -214,24 +664,66 @@ declare const JsoncFormattingOptions_base: Schema.Class<JsoncFormattingOptions,
 }, {}, {}>;
 
 /**
- * Schema that transforms a JSONC string into an unknown JavaScript value.
+ * 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 parsing pipeline:
- *   JSONC string → unknown → (your typed schema)
+ * This is the first stage of a typical parsing pipeline:
  *
- * @example
- * ```typescript
- * import { Schema } from "effect"
- * import { JsoncFromString } from "jsonc-effect"
+ * ```
+ * 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.
  *
- * const MyConfigFromJsonc = Schema.compose(JsoncFromString, MyConfigSchema)
- * const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(jsoncText)
+ * 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 modify() produces invalid edits.
+ * 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
@@ -240,11 +732,13 @@ export declare const JsoncFromString: Schema.Schema<unknown, string>;
  *
  * const program = modify("{}", ["deep", "path"], 42).pipe(
  *   Effect.catchTag("JsoncModificationError", (e) => {
- *     console.error(e.path, e.reason);
+ *     console.error(`Failed at [${e.path.join(", ")}]: ${e.reason}`);
  *     return Effect.succeed([]);
  *   }),
  * );
  * ```
+ *
+ * @public
  */
 export declare class JsoncModificationError extends JsoncModificationErrorBase<{
     readonly path: ReadonlyArray<string | number>;
@@ -253,14 +747,65 @@ export declare class JsoncModificationError extends JsoncModificationErrorBase<{
     get message(): string;
 }
 
-/** @internal */
+/**
+ * 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.
- * Parent field is intentionally omitted to avoid circular references.
+ * 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 {
 }
@@ -295,6 +840,28 @@ declare const JsoncNode_base: Schema.Class<JsoncNode, {
 
 /**
  * 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>;
@@ -303,34 +870,86 @@ export declare class JsoncNodeNotFoundError extends JsoncNodeNotFoundErrorBase<{
     get message(): string;
 }
 
-/** @internal */
+/**
+ * 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>;
 
 /**
- * AST node types.
+ * 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 syntax errors.
- * Contains an array of error details with position information.
+ * 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
+ * @example Inspecting error details
  * ```ts
  * import { Effect } from "effect";
- * import { parse, JsoncParseError } from "jsonc-effect";
+ * import { parse } from "jsonc-effect";
  *
  * const program = parse("{ invalid }").pipe(
  *   Effect.catchTag("JsoncParseError", (e) => {
- *     console.error(e.errors); // Array of JsoncParseErrorDetail
+ *     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>;
@@ -340,20 +959,79 @@ export declare class JsoncParseError extends JsoncParseErrorBase<{
     get message(): string;
 }
 
-/** @internal */
+/**
+ * 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 for JSONC parse errors.
+ * 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 with location information.
+ * 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 {
 }
@@ -388,6 +1066,35 @@ declare const JsoncParseErrorDetail_base: Schema.Class<JsoncParseErrorDetail, {
 
 /**
  * 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 {
 }
@@ -421,14 +1128,48 @@ declare const JsoncParseOptions_base: Schema.Class<JsoncParseOptions, {
 }, {}, {}>;
 
 /**
- * A path to a location in a JSONC document.
+ * 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.
+ * 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 {
 }
@@ -446,55 +1187,180 @@ declare const JsoncRange_base: Schema.Class<JsoncRange, {
 }, {}, {}>;
 
 /**
- * Scan error codes produced by the scanner.
+ * 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>;
 
 /**
- * JSONC Scanner interface — a stateful cursor over input text.
+ * 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 to the next token and return its kind */
+    /** Advance the cursor to the next token and return its {@link JsoncSyntaxKind}. */
     scan(): JsoncSyntaxKind;
-    /** Get the current token kind */
+    /** Return the {@link JsoncSyntaxKind} of the current token without advancing. */
     getToken(): JsoncSyntaxKind;
-    /** Get the string value of the current token */
+    /** Return the string value of the current token (e.g. the unescaped content of a string literal). */
     getTokenValue(): string;
-    /** Get the character offset of the current token */
+    /** Return the zero-based character offset where the current token begins. */
     getTokenOffset(): number;
-    /** Get the length of the current token */
+    /** Return the character length of the current token. */
     getTokenLength(): number;
-    /** Get the line number of the current token start */
+    /** Return the zero-based line number where the current token starts. */
     getTokenStartLine(): number;
-    /** Get the character position within the line */
+    /** Return the zero-based character position within the line where the current token starts. */
     getTokenStartCharacter(): number;
-    /** Get the scan error for the current token */
+    /** Return the {@link JsoncScanError} for the current token, or `"None"` if no error. */
     getTokenError(): JsoncScanError;
-    /** Get the current scanner position */
+    /** Return the current cursor position (byte offset into the source text). */
     getPosition(): number;
-    /** Set the scanner position */
+    /** Set the cursor position, resetting the current token state. */
     setPosition(pos: number): void;
 }
 
 /**
- * A path segment: string for object keys, number for array indices.
+ * 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.
- * Uses string literals instead of numeric enums for self-documenting debug output.
+ *
+ * @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.
+ * 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 {
 }
@@ -533,6 +1399,51 @@ declare const JsoncToken_base: Schema.Class<JsoncToken, {
 
 /**
  * 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";
@@ -581,66 +1492,182 @@ export declare type JsoncVisitorEvent = {
 };
 
 /**
- * Create a JSONC-to-unknown Schema with custom parse options.
+ * 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` which produces standard
- * JSON. Comments present in the original JSONC input are not preserved
- * during round-trip encode/decode.
+ * 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.
  *
- * @example
- * ```typescript
- * import { makeJsoncFromString } from "jsonc-effect"
+ * @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";
  *
- * // Strict mode: no comments allowed
  * 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 that parses JSONC and validates against
- * a target schema in one step.
+ * Create a composed `Schema<A, string>` that parses a JSONC string and
+ * validates the result against a target domain schema in one step.
  *
- * @example
- * ```typescript
- * import { Schema } from "effect"
- * import { makeJsoncSchema } from "jsonc-effect"
+ * @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 }',
+ * );
+ * ```
  *
- * const MyConfigFromJsonc = makeJsoncSchema(MyConfig)
- * const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(jsoncText)
+ * @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.
- * Setting value to undefined removes the property/element.
  *
- * @example
+ * 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, pipe } from "effect";
- * import { modify, applyEdits } from "@spencerbeggs/jsonc-effect";
+ * 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";
  *
- * // Data-first
- * const edits = Effect.runSync(modify('{ "a": 1 }', ["a"], 2));
+ * 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";
  *
- * // Data-last (pipeline)
+ * const input = '{ "a": 1 }';
  * const result = pipe(
- *   '{ "a": 1 }',
- *   modify(["a"], 2),
- *   Effect.flatMap((edits) => applyEdits('{ "a": 1 }', edits)),
+ *   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?: {
@@ -654,21 +1681,80 @@ export declare const modify: {
 /**
  * Parse a JSONC string into a JavaScript value.
  *
- * @param text - The JSONC string to parse
- * @param options - Optional parse options
- * @returns An Effect that produces the parsed value or fails with JsoncParseError
+ * @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 "@spencerbeggs/jsonc-effect";
+ * import { parse } from "jsonc-effect";
  *
- * // Basic usage
  * 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;
+ * });
  *
- * // With options
- * const strict = Effect.runSync(parse('{ "key": 42 }', { disallowComments: true }));
+ * 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>;
@@ -676,22 +1762,53 @@ export declare const parse: {
 };
 
 /**
- * Parse a JSONC string into an AST.
+ * 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.
  *
- * @param text - The JSONC string to parse
- * @param options - Optional parse options
- * @returns An Effect that produces Option.some(node) or Option.none() for empty content
+ * `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 "@spencerbeggs/jsonc-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
+ *   }
+ * });
  *
- * const result = Effect.runSync(parseTree('{ "a": 1 }'));
- * if (Option.isSome(result)) {
- *   console.log(result.value.type); // "object"
- * }
+ * 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>;
@@ -701,18 +1818,46 @@ export declare const parseTree: {
 /**
  * Remove all comments from JSONC text, producing valid JSON.
  *
- * @param text - The JSONC string to strip comments from
- * @param replaceCh - Optional character to replace comments with (preserves offsets)
- * @returns An Effect that produces the text with comments removed
+ * @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 "@spencerbeggs/jsonc-effect";
+ * import { stripComments } from "jsonc-effect";
  *
- * const json = Effect.runSync(stripComments('{ "a": 1 // comment\n}'));
- * // '{ "a": 1           \n}'
+ * 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>;
@@ -720,31 +1865,118 @@ export declare const stripComments: {
 };
 
 /**
- * Create a Stream of visitor events from JSONC text.
+ * Create a lazy `Stream` of {@link JsoncVisitorEvent} from JSONC text.
  *
- * Uses a lazy generator internally — events are produced on demand
- * as the stream is consumed, not pre-collected into memory.
+ * 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.
  *
- * @example
+ * @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 "@spencerbeggs/jsonc-effect";
+ * import { visit } from "jsonc-effect";
  *
- * // Collect all events
  * const all = Effect.runSync(
- *   visit('{ "a": 1 }').pipe(Stream.runCollect, Effect.map(Chunk.toReadonlyArray)),
+ *   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";
  *
- * // Take only the first 3 events (lazy — won't scan entire document)
- * const first3 = Effect.runSync(
- *   visit(largeDoc).pipe(Stream.take(3), Stream.runCollect, Effect.map(Chunk.toReadonlyArray)),
+ * 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 predicate.
+ * 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>;