jsonc-effect 0.1.0

package/index.d.ts

@@ -0,0 +1,751 @@
+/**
+ * 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 edits to JSONC source text.
+ * Edits are applied in reverse offset order to avoid offset shifting.
+ */
+export declare const applyEdits: {
+    (edits: ReadonlyArray<JsoncEdit>): (text: string) => Effect.Effect<string>;
+    (text: string, edits: ReadonlyArray<JsoncEdit>): Effect.Effect<string>;
+};
+
+/**
+ * Create a JSONC scanner.
+ *
+ * @param text - The JSONC string to scan
+ * @param ignoreTrivia - If true, skip whitespace, line breaks, and comments
+ * @returns A JsoncScanner for iterating over tokens
+ */
+export declare const createScanner: (text: string, ignoreTrivia?: boolean) => JsoncScanner;
+
+/**
+ * Find a node at a specific path in the AST.
+ *
+ * Traverses the AST following property names (strings) and
+ * array indices (numbers) in the path.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, pipe } from "effect";
+ * import { parseTree, findNode } from "@spencerbeggs/jsonc-effect";
+ *
+ * // Data-first
+ * const node = Effect.gen(function* () {
+ *   const root = 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"]));
+ * ```
+ */
+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 node covering a character offset.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, pipe } from "effect";
+ * import { parseTree, findNodeAtOffset } from "@spencerbeggs/jsonc-effect";
+ *
+ * // Data-last (pipeline)
+ * const node = pipe(root, findNodeAtOffset(5));
+ * ```
+ */
+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.
+ *
+ * Does NOT mutate the input — returns an array of edits to apply
+ * with applyEdits().
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { format, applyEdits } from "@spencerbeggs/jsonc-effect";
+ *
+ * const edits = Effect.runSync(format('{"a":1}'));
+ * const formatted = Effect.runSync(applyEdits('{"a":1}', edits));
+ * ```
+ */
+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).
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * import { Effect, pipe } from "effect";
+ * import { parseTree, getNodePath } from "@spencerbeggs/jsonc-effect";
+ *
+ * // Data-last (pipeline)
+ * const path = pipe(root, getNodePath(5));
+ * ```
+ */
+export declare const getNodePath: {
+    (targetOffset: number): (root: JsoncNode) => Effect.Effect<Option.Option<JsoncPath>>;
+    (root: JsoncNode, targetOffset: number): Effect.Effect<Option.Option<JsoncPath>>;
+};
+
+/**
+ * Evaluate a node subtree into a plain JavaScript value.
+ * Reconstructs objects and arrays from the AST.
+ */
+export declare const getNodeValue: (node: JsoncNode) => Effect.Effect<unknown, never, never>;
+
+/**
+ * A text edit to apply to a JSONC document.
+ */
+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 for exhaustive error handling.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse, type JsoncError } from "jsonc-effect";
+ *
+ * const program = someJsoncOperation.pipe(
+ *   Effect.catchTags({
+ *     JsoncParseError: (e) => Effect.succeed("parse failed"),
+ *     JsoncModificationError: (e) => Effect.succeed("modify failed"),
+ *     JsoncNodeNotFoundError: (e) => Effect.succeed("node not found"),
+ *   }),
+ * );
+ * ```
+ */
+export declare type JsoncError = JsoncParseError | JsoncNodeNotFoundError | JsoncModificationError;
+
+/**
+ * Options controlling JSONC formatting behavior.
+ */
+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;
+}, {}, {}>;
+
+/**
+ * Schema that transforms a JSONC string into an unknown JavaScript value.
+ *
+ * This is the first stage of a parsing pipeline:
+ *   JSONC string → unknown → (your typed schema)
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect"
+ * import { JsoncFromString } from "jsonc-effect"
+ *
+ * const MyConfigFromJsonc = Schema.compose(JsoncFromString, MyConfigSchema)
+ * const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(jsoncText)
+ * ```
+ */
+export declare const JsoncFromString: Schema.Schema<unknown, string>;
+
+/**
+ * Error raised when modify() produces invalid edits.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { modify } from "jsonc-effect";
+ *
+ * const program = modify("{}", ["deep", "path"], 42).pipe(
+ *   Effect.catchTag("JsoncModificationError", (e) => {
+ *     console.error(e.path, e.reason);
+ *     return Effect.succeed([]);
+ *   }),
+ * );
+ * ```
+ */
+export declare class JsoncModificationError extends JsoncModificationErrorBase<{
+    readonly path: ReadonlyArray<string | number>;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+/** @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.
+ */
+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.
+ */
+export declare class JsoncNodeNotFoundError extends JsoncNodeNotFoundErrorBase<{
+    readonly path: ReadonlyArray<string | number>;
+    readonly rootNodeType: string;
+}> {
+    get message(): string;
+}
+
+/** @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.
+ */
+export declare const JsoncNodeType: Schema.Literal<["object", "array", "property", "string", "number", "boolean", "null"]>;
+
+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.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse, JsoncParseError } from "jsonc-effect";
+ *
+ * const program = parse("{ invalid }").pipe(
+ *   Effect.catchTag("JsoncParseError", (e) => {
+ *     console.error(e.errors); // Array of JsoncParseErrorDetail
+ *     return Effect.succeed({});
+ *   }),
+ * );
+ * ```
+ */
+export declare class JsoncParseError extends JsoncParseErrorBase<{
+    readonly errors: ReadonlyArray<JsoncParseErrorDetail>;
+    readonly text: string;
+    readonly options?: Partial<JsoncParseOptions>;
+}> {
+    get message(): string;
+}
+
+/** @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.
+ */
+export declare const JsoncParseErrorCode: Schema.Literal<["InvalidSymbol", "InvalidNumberFormat", "PropertyNameExpected", "ValueExpected", "ColonExpected", "CommaExpected", "CloseBraceExpected", "CloseBracketExpected", "EndOfFileExpected", "InvalidCommentToken", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter"]>;
+
+export declare type JsoncParseErrorCode = Schema.Schema.Type<typeof JsoncParseErrorCode>;
+
+/**
+ * Detail for a single parse error with location information.
+ */
+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.
+ */
+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;
+}, {}, {}>;
+
+/**
+ * A path to a location in a JSONC document.
+ */
+export declare const JsoncPath: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
+
+export declare type JsoncPath = Schema.Schema.Type<typeof JsoncPath>;
+
+/**
+ * A range within a JSONC document.
+ */
+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;
+}, {}, {}>;
+
+/**
+ * Scan error codes produced by the scanner.
+ */
+export declare const JsoncScanError: Schema.Literal<["None", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter", "InvalidSymbol"]>;
+
+export declare type JsoncScanError = Schema.Schema.Type<typeof JsoncScanError>;
+
+/**
+ * JSONC Scanner interface — a stateful cursor over input text.
+ */
+export declare interface JsoncScanner {
+    /** Advance to the next token and return its kind */
+    scan(): JsoncSyntaxKind;
+    /** Get the current token kind */
+    getToken(): JsoncSyntaxKind;
+    /** Get the string value of the current token */
+    getTokenValue(): string;
+    /** Get the character offset of the current token */
+    getTokenOffset(): number;
+    /** Get the length of the current token */
+    getTokenLength(): number;
+    /** Get the line number of the current token start */
+    getTokenStartLine(): number;
+    /** Get the character position within the line */
+    getTokenStartCharacter(): number;
+    /** Get the scan error for the current token */
+    getTokenError(): JsoncScanError;
+    /** Get the current scanner position */
+    getPosition(): number;
+    /** Set the scanner position */
+    setPosition(pos: number): void;
+}
+
+/**
+ * A path segment: string for object keys, number for array indices.
+ */
+export declare const JsoncSegment: Schema.Union<[typeof Schema.String, typeof Schema.Number]>;
+
+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.
+ */
+export declare const JsoncSyntaxKind: Schema.Literal<["OpenBrace", "CloseBrace", "OpenBracket", "CloseBracket", "Comma", "Colon", "Null", "True", "False", "String", "Number", "LineComment", "BlockComment", "LineBreak", "Trivia", "Unknown", "EOF"]>;
+
+export declare type JsoncSyntaxKind = Schema.Schema.Type<typeof JsoncSyntaxKind>;
+
+/**
+ * A single token produced by the JSONC scanner.
+ */
+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.
+ */
+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 JSONC-to-unknown Schema with custom parse 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.
+ *
+ * @example
+ * ```typescript
+ * import { makeJsoncFromString } from "jsonc-effect"
+ *
+ * // Strict mode: no comments allowed
+ * const StrictJsoncFromString = makeJsoncFromString({
+ *   disallowComments: true,
+ *   allowTrailingComma: false,
+ * })
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```typescript
+ * 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)(jsoncText)
+ * ```
+ */
+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
+ * ```ts
+ * import { Effect, pipe } from "effect";
+ * import { modify, applyEdits } from "@spencerbeggs/jsonc-effect";
+ *
+ * // Data-first
+ * const edits = Effect.runSync(modify('{ "a": 1 }', ["a"], 2));
+ *
+ * // Data-last (pipeline)
+ * const result = pipe(
+ *   '{ "a": 1 }',
+ *   modify(["a"], 2),
+ *   Effect.flatMap((edits) => applyEdits('{ "a": 1 }', edits)),
+ *   Effect.runSync,
+ * );
+ * ```
+ */
+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 - The JSONC string to parse
+ * @param options - Optional parse options
+ * @returns An Effect that produces the parsed value or fails with JsoncParseError
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { parse } from "@spencerbeggs/jsonc-effect";
+ *
+ * // Basic usage
+ * const value = Effect.runSync(parse('{ "key": 42 }'));
+ *
+ * // With options
+ * const strict = Effect.runSync(parse('{ "key": 42 }', { disallowComments: true }));
+ * ```
+ */
+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 AST.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect";
+ * import { parseTree } from "@spencerbeggs/jsonc-effect";
+ *
+ * const result = Effect.runSync(parseTree('{ "a": 1 }'));
+ * if (Option.isSome(result)) {
+ *   console.log(result.value.type); // "object"
+ * }
+ * ```
+ */
+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 - 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
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect";
+ * import { stripComments } from "@spencerbeggs/jsonc-effect";
+ *
+ * const json = Effect.runSync(stripComments('{ "a": 1 // comment\n}'));
+ * // '{ "a": 1           \n}'
+ * ```
+ */
+export declare const stripComments: {
+    (text: string): Effect.Effect<string>;
+    (text: string, replaceCh: string): Effect.Effect<string>;
+};
+
+/**
+ * Create a Stream of visitor events from JSONC text.
+ *
+ * Uses a lazy generator internally — events are produced on demand
+ * as the stream is consumed, not pre-collected into memory.
+ *
+ * @example
+ * ```ts
+ * import { Chunk, Effect, Stream } from "effect";
+ * import { visit } from "@spencerbeggs/jsonc-effect";
+ *
+ * // Collect all events
+ * const all = Effect.runSync(
+ *   visit('{ "a": 1 }').pipe(Stream.runCollect, Effect.map(Chunk.toReadonlyArray)),
+ * );
+ *
+ * // 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)),
+ * );
+ * ```
+ */
+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.
+ */
+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 { }