/**
 * yaml-effect — A pure Effect-based YAML 1.2 parser, stringifier, and toolkit
 * for TypeScript.
 *
 * @remarks
 * This library provides a complete YAML 1.2 processing pipeline built entirely
 * on the {@link https://effect.website | Effect} library. Every operation
 * returns an `Effect`, enabling typed error handling, composability, and
 * integration with Effect-based applications.
 *
 * **Core pipeline stages:**
 *
 * 1. **Lex** — tokenize raw YAML text via {@link lex} or {@link createScanner}
 * 2. **Parse** — build a Concrete Syntax Tree via {@link parseCST}
 * 3. **Compose** — produce a typed AST via {@link parseDocument}, {@link parseAllDocuments}, or {@link parse}
 * 4. **Stringify** — convert values or AST back to YAML via {@link stringify} or {@link stringifyDocument}
 *
 * **Additional capabilities:**
 *
 * - **Formatting** — re-indent, sort keys, strip comments via {@link format} and {@link formatAndApply}
 * - **Modification** — insert, replace, or remove values by path via {@link modify} and {@link modifyAndApply}
 * - **Equality** — semantic YAML comparison via {@link equals} and {@link equalsValue}
 * - **Visitor pattern** — SAX-style streaming traversal at AST ({@link visit}) and CST ({@link visitCST}) levels
 * - **Schema integration** — bidirectional Effect Schema composition via {@link YamlFromString} and {@link makeYamlSchema}
 *
 * @example Parsing and stringifying
 * ```ts
 * import { Effect } from "effect";
 * import { parse, stringify } from "yaml-effect";
 *
 * const program = Effect.gen(function* () {
 *   const value = yield* parse("name: Alice\nage: 30");
 *   console.log(value); // { name: "Alice", age: 30 }
 *
 *   const yaml = yield* stringify({ greeting: "hello", count: 42 });
 *   console.log(yaml); // "greeting: hello\ncount: 42\n"
 * });
 *
 * Effect.runSync(program);
 * ```
 *
 * @example Typed schema integration
 * ```ts
 * import { Effect, Schema } from "effect";
 * import { makeYamlSchema } from "yaml-effect";
 *
 * const UserSchema = makeYamlSchema(
 *   Schema.Struct({ name: Schema.String, age: Schema.Number }),
 * );
 *
 * const program = Effect.gen(function* () {
 *   const user = yield* Schema.decode(UserSchema)("name: Alice\nage: 30");
 *   console.log(user); // { name: "Alice", age: 30 }
 * });
 *
 * Effect.runSync(program);
 * ```
 *
 * @packageDocumentation
 */

import { Effect } from 'effect';
import { Option } from 'effect';
import { Schema } from 'effect';
import { Stream } from 'effect';
import { VoidIfEmpty } from 'effect/Types';
import { YieldableError } from 'effect/Cause';

/**
 * Emitted when the visitor encounters a YAML alias node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `name` — the anchor name this alias refers to (without the leading `*`).
 *
 * @public
 */
export declare class AliasEvent extends AliasEvent_base {
}

declare const AliasEvent_base: Schema.TaggedClass<AliasEvent, "AliasEvent", {
    readonly _tag: Schema.tag<"AliasEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    name: typeof Schema.String;
}>;

/**
 * Apply an array of text edits to YAML source text.
 *
 * @remarks
 * Edits are sorted in reverse offset order before application so that
 * earlier edits do not shift the offsets of later ones. Offsets beyond the
 * string boundary are clamped. The original `edits` array is not mutated.
 *
 * This function is a dual — it can be called either with both arguments
 * directly, or partially applied with just the edits array.
 *
 * @example Direct usage
 * ```typescript
 * import type { ReadonlyArray } from "effect"
 * import { Effect } from "effect"
 * import type { YamlEdit } from "yaml-effect"
 * import { applyEdits, format } from "yaml-effect"
 *
 * const yaml = "name:  John\n"
 *
 * const program = Effect.gen(function* () {
 *   const edits: ReadonlyArray<YamlEdit> = yield* format(yaml)
 *   const result: string = yield* applyEdits(yaml, edits)
 *   return result
 * })
 * ```
 *
 * @example Pipeline usage (partial application)
 * ```typescript
 * import { Effect, pipe } from "effect"
 * import { applyEdits, format } from "yaml-effect"
 *
 * const yaml = "name:  John\n"
 *
 * const program = pipe(
 *   format(yaml),
 *   Effect.flatMap(applyEdits(yaml)),
 * )
 * ```
 *
 * @public
 */
export declare const applyEdits: {
    (edits: ReadonlyArray<YamlEdit>): (text: string) => Effect.Effect<string>;
    (text: string, edits: ReadonlyArray<YamlEdit>): Effect.Effect<string>;
};

/**
 * YAML collection output styles.
 *
 * @public
 */
export declare const CollectionStyle: Schema.Literal<["block", "flow"]>;

/**
 * The union of all collection style string literals.
 *
 * @see {@link CollectionStyle}
 *
 * @public
 */
export declare type CollectionStyle = Schema.Schema.Type<typeof CollectionStyle>;

/**
 * Emitted when the visitor encounters a YAML comment.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `text` — the raw comment text (without the leading `#`).
 *
 * @public
 */
export declare class CommentEvent extends CommentEvent_base {
}

declare const CommentEvent_base: Schema.TaggedClass<CommentEvent, "CommentEvent", {
    readonly _tag: Schema.tag<"CommentEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    text: typeof Schema.String;
}>;

/**
 * Create a new YAML scanner for the given source text.
 *
 * @remarks
 * Returns a stateful, pull-based scanner. Call {@link YamlScanner.scan} to
 * advance to the next token, then use `getToken*` methods to inspect it.
 *
 * @example
 * ```typescript
 * import { createScanner } from "yaml-effect";
 *
 * const scanner = createScanner("key: value");
 * let kind = scanner.scan();
 * while (kind !== null) {
 *   console.log(kind, scanner.getTokenValue());
 *   kind = scanner.scan();
 * }
 * ```
 *
 * @public
 */
export declare function createScanner(text: string): YamlScanner;

/**
 * Emitted when the CST visitor encounters an alias reference node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text of the alias (including the leading `*`).
 *
 * @public
 */
export declare class CstAliasEvent extends CstAliasEvent_base {
}

declare const CstAliasEvent_base: Schema.TaggedClass<CstAliasEvent, "CstAliasEvent", {
    readonly _tag: Schema.tag<"CstAliasEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * Emitted when the CST visitor encounters a comment node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text of the comment (including the leading `#`).
 *
 * @public
 */
export declare class CstCommentEvent extends CstCommentEvent_base {
}

declare const CstCommentEvent_base: Schema.TaggedClass<CstCommentEvent, "CstCommentEvent", {
    readonly _tag: Schema.tag<"CstCommentEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * Emitted when the CST visitor encounters a directive node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text of the directive (e.g., `%YAML 1.2`).
 *
 * @public
 */
export declare class CstDirectiveEvent extends CstDirectiveEvent_base {
}

declare const CstDirectiveEvent_base: Schema.TaggedClass<CstDirectiveEvent, "CstDirectiveEvent", {
    readonly _tag: Schema.tag<"CstDirectiveEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * Emitted when the CST visitor exits a document node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 *
 * @public
 */
export declare class CstDocumentEndEvent extends CstDocumentEndEvent_base {
}

declare const CstDocumentEndEvent_base: Schema.TaggedClass<CstDocumentEndEvent, "CstDocumentEndEvent", {
    readonly _tag: Schema.tag<"CstDocumentEndEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Emitted when the CST visitor enters a document node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 *
 * @public
 */
export declare class CstDocumentStartEvent extends CstDocumentStartEvent_base {
}

declare const CstDocumentStartEvent_base: Schema.TaggedClass<CstDocumentStartEvent, "CstDocumentStartEvent", {
    readonly _tag: Schema.tag<"CstDocumentStartEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Emitted when the CST visitor encounters an error node in the CST.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text of the erroneous token.
 *
 * @public
 */
export declare class CstErrorEvent extends CstErrorEvent_base {
}

declare const CstErrorEvent_base: Schema.TaggedClass<CstErrorEvent, "CstErrorEvent", {
    readonly _tag: Schema.tag<"CstErrorEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * Emitted when the CST visitor encounters a scalar that is a map key.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text of the key scalar.
 *
 * @public
 */
export declare class CstKeyEvent extends CstKeyEvent_base {
}

declare const CstKeyEvent_base: Schema.TaggedClass<CstKeyEvent, "CstKeyEvent", {
    readonly _tag: Schema.tag<"CstKeyEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * Emitted when the CST visitor exits a block-map or flow-map node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 *
 * @public
 */
export declare class CstMapEndEvent extends CstMapEndEvent_base {
}

declare const CstMapEndEvent_base: Schema.TaggedClass<CstMapEndEvent, "CstMapEndEvent", {
    readonly _tag: Schema.tag<"CstMapEndEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Emitted when the CST visitor enters a block-map or flow-map node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text span of the mapping node.
 *
 * @public
 */
export declare class CstMapStartEvent extends CstMapStartEvent_base {
}

declare const CstMapStartEvent_base: Schema.TaggedClass<CstMapStartEvent, "CstMapStartEvent", {
    readonly _tag: Schema.tag<"CstMapStartEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * A single YAML Concrete Syntax Tree (CST) node, carrying its type, raw
 * source text span, position, and optional recursive children.
 *
 * @remarks
 * - `type` — a {@link CstNodeType} identifying the node kind.
 * - `source` — the raw text slice from the source document.
 * - `offset` — zero-based character offset where the node begins.
 * - `length` — character length of the node span.
 * - `children` — optional recursive child nodes.
 *
 * No interpretation occurs at the CST level — `true` is still the string
 * `"true"`.
 *
 * @public
 */
export declare class CstNode extends CstNode_base {
}

declare const CstNode_base: Schema.Class<CstNode, {
    type: Schema.Literal<["document", "directive", "comment", "block-map", "block-seq", "flow-map", "flow-seq", "block-scalar", "flow-scalar", "alias", "anchor", "tag", "whitespace", "newline", "error"]>;
    source: typeof Schema.String;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
    children: Schema.optional<Schema.Array$<Schema.suspend<CstNode, CstNode, never>>>;
}, Schema.Struct.Encoded<{
    type: Schema.Literal<["document", "directive", "comment", "block-map", "block-seq", "flow-map", "flow-seq", "block-scalar", "flow-scalar", "alias", "anchor", "tag", "whitespace", "newline", "error"]>;
    source: typeof Schema.String;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
    children: Schema.optional<Schema.Array$<Schema.suspend<CstNode, CstNode, never>>>;
}>, never, {
    readonly children?: readonly CstNode[] | undefined;
} & {
    readonly length: number;
} & {
    readonly offset: number;
} & {
    readonly source: string;
} & {
    readonly type: "alias" | "anchor" | "block-map" | "block-scalar" | "block-seq" | "comment" | "directive" | "document" | "error" | "flow-map" | "flow-scalar" | "flow-seq" | "newline" | "tag" | "whitespace";
}, {}, {}>;

/**
 * The 15 node types produced by the YAML CST parser.
 *
 * @public
 */
export declare const CstNodeType: Schema.Literal<["document", "directive", "comment", "block-map", "block-seq", "flow-map", "flow-seq", "block-scalar", "flow-scalar", "alias", "anchor", "tag", "whitespace", "newline", "error"]>;

/**
 * The union of all YAML CST node type string literals.
 *
 * @public
 */
export declare type CstNodeType = Schema.Schema.Type<typeof CstNodeType>;

/**
 * Emitted when the CST visitor encounters a standalone scalar (not a map key
 * or value — e.g., a sequence item or bare document scalar).
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text of the scalar (no type resolution).
 *
 * @public
 */
export declare class CstScalarEvent extends CstScalarEvent_base {
}

declare const CstScalarEvent_base: Schema.TaggedClass<CstScalarEvent, "CstScalarEvent", {
    readonly _tag: Schema.tag<"CstScalarEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * Emitted when the CST visitor exits a block-seq or flow-seq node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 *
 * @public
 */
export declare class CstSeqEndEvent extends CstSeqEndEvent_base {
}

declare const CstSeqEndEvent_base: Schema.TaggedClass<CstSeqEndEvent, "CstSeqEndEvent", {
    readonly _tag: Schema.tag<"CstSeqEndEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Emitted when the CST visitor enters a block-seq or flow-seq node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text span of the sequence node.
 *
 * @public
 */
export declare class CstSeqStartEvent extends CstSeqStartEvent_base {
}

declare const CstSeqStartEvent_base: Schema.TaggedClass<CstSeqStartEvent, "CstSeqStartEvent", {
    readonly _tag: Schema.tag<"CstSeqStartEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * Emitted when the CST visitor encounters a scalar that is a map value.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `source` — the raw source text of the value scalar.
 *
 * @public
 */
export declare class CstValueEvent extends CstValueEvent_base {
}

declare const CstValueEvent_base: Schema.TaggedClass<CstValueEvent, "CstValueEvent", {
    readonly _tag: Schema.tag<"CstValueEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    source: typeof Schema.String;
}>;

/**
 * Emitted when the visitor encounters a YAML directive.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `name` — the directive name (e.g., `"YAML"` or `"TAG"`).
 * - `parameters` — the directive's raw parameter string.
 *
 * @public
 */
export declare class DirectiveEvent extends DirectiveEvent_base {
}

declare const DirectiveEvent_base: Schema.TaggedClass<DirectiveEvent, "DirectiveEvent", {
    readonly _tag: Schema.tag<"DirectiveEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    name: typeof Schema.String;
    parameters: typeof Schema.String;
}>;

/**
 * Emitted when the visitor exits a YAML document node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 *
 * @public
 */
export declare class DocumentEndEvent extends DocumentEndEvent_base {
}

declare const DocumentEndEvent_base: Schema.TaggedClass<DocumentEndEvent, "DocumentEndEvent", {
    readonly _tag: Schema.tag<"DocumentEndEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Emitted when the visitor enters a YAML document node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `directives` — {@link YamlDirective} entries declared before the document
 *   content (e.g., `%YAML 1.2`).
 *
 * @public
 */
export declare class DocumentStartEvent extends DocumentStartEvent_base {
}

declare const DocumentStartEvent_base: Schema.TaggedClass<DocumentStartEvent, "DocumentStartEvent", {
    readonly _tag: Schema.tag<"DocumentStartEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    directives: Schema.Array$<typeof YamlDirective>;
}>;

/**
 * Compare two YAML strings for semantic equality.
 *
 * @remarks
 * Both strings are parsed via {@link parse} (which resolves anchors/aliases
 * to plain JS values) and then deep-compared. Comments, whitespace,
 * formatting, and object key ordering are ignored. Array order IS
 * significant. For multi-document input, only the first document is
 * compared.
 *
 * @example
 * ```typescript
 * import { equals } from "yaml-effect";
 * import { Effect, pipe } from "effect";
 *
 * const yamlA = "name: Alice\nage: 30";
 * const yamlB = "age: 30\nname: Alice"; // different key order
 *
 * const program = Effect.gen(function* () {
 *   // Direct style
 *   const result = yield* equals(yamlA, yamlB);
 *   console.log(result); // true (key order is ignored)
 *
 *   // Pipeline style
 *   const pipeResult = yield* pipe(yamlA, equals(yamlB));
 *   console.log(pipeResult); // true
 * });
 * ```
 *
 * @public
 */
export declare const equals: {
    (that: string): (self: string) => Effect.Effect<boolean, YamlComposerError>;
    (self: string, that: string): Effect.Effect<boolean, YamlComposerError>;
};

/**
 * Compare a YAML string against a JavaScript value for semantic equality.
 *
 * @remarks
 * Only the YAML string is parsed; the JS value is used as-is. Same
 * comparison semantics as {@link equals}.
 *
 * @example
 * ```typescript
 * import { equalsValue } from "yaml-effect";
 * import { Effect } from "effect";
 *
 * const yaml = "items:\n  - one\n  - two";
 * const expected = { items: ["one", "two"] };
 *
 * const program = Effect.gen(function* () {
 *   const result = yield* equalsValue(yaml, expected);
 *   console.log(result); // true
 * });
 * ```
 *
 * @public
 */
export declare const equalsValue: {
    (value: unknown): (self: string) => Effect.Effect<boolean, YamlComposerError>;
    (self: string, value: unknown): Effect.Effect<boolean, YamlComposerError>;
};

/**
 * Navigate to a node within the AST tree by following a path of string keys
 * (for mappings) and numeric indices (for sequences).
 *
 * @example
 * ```typescript
 * import { findNode, parseDocument } from "yaml-effect";
 * import { Effect, Option, pipe } from "effect";
 *
 * const program = Effect.gen(function* () {
 *   const doc = yield* parseDocument("server:\n  host: localhost\n  ports:\n    - 8080\n    - 8443");
 *   const root = doc.contents!;
 *
 *   // Direct style
 *   const host = yield* findNode(root, ["server", "host"]);
 *   // host: Option.Some<YamlScalar>
 *
 *   // Pipeline style
 *   const port = yield* pipe(root, findNode(["server", "ports", 0]));
 *   // port: Option.Some<YamlScalar> with value 8080
 *
 *   // Missing path returns Option.None
 *   const missing = yield* findNode(root, ["server", "missing"]);
 *   console.log(Option.isNone(missing)); // true
 * });
 * ```
 *
 * @public
 */
export declare const findNode: {
    (path: YamlPath): (root: YamlNode) => Effect.Effect<Option.Option<YamlNode>>;
    (root: YamlNode, path: YamlPath): Effect.Effect<Option.Option<YamlNode>>;
};

/**
 * Find the deepest AST node that contains the given character offset.
 *
 * @example
 * ```typescript
 * import { findNodeAtOffset, isScalar, parseDocument } from "yaml-effect";
 * import { Effect, Option } from "effect";
 *
 * const yaml = "name: Alice";
 * const program = Effect.gen(function* () {
 *   const doc = yield* parseDocument(yaml);
 *   const root = doc.contents!;
 *
 *   // Offset 6 points into the value "Alice"
 *   const node = yield* findNodeAtOffset(root, 6);
 *   if (Option.isSome(node) && isScalar(node.value)) {
 *     console.log(node.value.value); // "Alice"
 *   }
 * });
 * ```
 *
 * @public
 */
export declare const findNodeAtOffset: {
    (offset: number): (root: YamlNode) => Effect.Effect<Option.Option<YamlNode>>;
    (root: YamlNode, offset: number): Effect.Effect<Option.Option<YamlNode>>;
};

/**
 * Compute formatting edits for a YAML document.
 *
 * @remarks
 * Parses the input into an AST Document, applies formatting options, and
 * stringifies back. Returns the diff as an array of {@link YamlEdit} objects.
 * When `options.range` is set, only edits within that range are returned.
 *
 * @example Formatting with indent change and sorted keys
 * ```typescript
 * import { Effect } from "effect"
 * import type { RawFormatOptions } from "yaml-effect"
 * import { format } from "yaml-effect"
 *
 * const yaml = "b: 2\na: 1\n"
 * const options: RawFormatOptions = { indent: 4, sortKeys: true }
 *
 * const program = Effect.gen(function* () {
 *   const edits = yield* format(yaml, options)
 *   // edits is an array of YamlEdit objects describing
 *   // the changes needed to reformat the document
 *   return edits
 * })
 * ```
 *
 * @public
 */
export declare function format(text: string, options?: RawFormatOptions): Effect.Effect<ReadonlyArray<YamlEdit>, YamlFormatError>;

/**
 * Format a YAML document in one step.
 *
 * @remarks
 * Convenience combining parse, apply options, and stringify. Returns the
 * formatted string directly without computing a diff.
 *
 * @example One-step formatting
 * ```typescript
 * import { Effect } from "effect"
 * import { formatAndApply } from "yaml-effect"
 *
 * const yaml = "b: 2\na: 1\n"
 *
 * const program = Effect.gen(function* () {
 *   const formatted: string = yield* formatAndApply(yaml, {
 *     indent: 4,
 *     sortKeys: true,
 *   })
 *   // formatted is the fully reformatted YAML string
 *   return formatted
 * })
 * ```
 *
 * @public
 */
export declare function formatAndApply(text: string, options?: RawFormatOptions): Effect.Effect<string, YamlFormatError>;

/**
 * Return the path segments leading to the node at the given offset.
 *
 * @example
 * ```typescript
 * import { getNodePath, parseDocument } from "yaml-effect";
 * import { Effect, Option } from "effect";
 *
 * const yaml = "server:\n  host: localhost\n  ports:\n    - 8080";
 * const program = Effect.gen(function* () {
 *   const doc = yield* parseDocument(yaml);
 *   const root = doc.contents!;
 *
 *   // Offset pointing into "localhost" value
 *   const path = yield* getNodePath(root, 16);
 *   if (Option.isSome(path)) {
 *     console.log(path.value); // ["server", "host"]
 *   }
 * });
 * ```
 *
 * @public
 */
export declare const getNodePath: {
    (offset: number): (root: YamlNode) => Effect.Effect<Option.Option<YamlPath>>;
    (root: YamlNode, offset: number): Effect.Effect<Option.Option<YamlPath>>;
};

/**
 * Extract the plain JavaScript value from a YAML AST node.
 *
 * - {@link YamlScalar} returns its `value` field.
 * - {@link YamlMap} returns a plain JS object built from its pairs.
 * - {@link YamlSeq} returns a plain JS array built from its items.
 * - {@link YamlAlias} returns the anchor name string (not resolved).
 *
 * @example
 * ```typescript
 * import { getNodeValue, findNode, parseDocument } from "yaml-effect";
 * import { Effect, Option } from "effect";
 *
 * const yaml = "server:\n  host: localhost\n  port: 8080";
 * const program = Effect.gen(function* () {
 *   const doc = yield* parseDocument(yaml);
 *   const root = doc.contents!;
 *
 *   // Extract the entire document as a plain JS object
 *   const value = yield* getNodeValue(root);
 *   console.log(value); // { server: { host: "localhost", port: 8080 } }
 *
 *   // Extract a nested node's value
 *   const hostNode = yield* findNode(root, ["server", "host"]);
 *   if (Option.isSome(hostNode)) {
 *     const hostValue = yield* getNodeValue(hostNode.value);
 *     console.log(hostValue); // "localhost"
 *   }
 * });
 * ```
 *
 * @public
 */
export declare function getNodeValue(node: YamlNode): Effect.Effect<unknown>;

/**
 * Returns `true` if the value is a {@link YamlAlias} instance.
 *
 * @public
 */
export declare function isAlias(node: unknown): node is YamlAlias;

/**
 * Returns `true` when `event` is a {@link AliasEvent}.
 *
 * @public
 */
export declare const isAliasEvent: (event: YamlVisitorEvent) => event is AliasEvent;

/**
 * Returns `true` when `event` is a {@link CommentEvent}.
 *
 * @public
 */
export declare const isCommentEvent: (event: YamlVisitorEvent) => event is CommentEvent;

/**
 * Returns `true` when `event` is a {@link CstAliasEvent}.
 *
 * @public
 */
export declare const isCstAliasEvent: (event: YamlCstVisitorEvent) => event is CstAliasEvent;

/**
 * Returns `true` when `event` is a {@link CstCommentEvent}.
 *
 * @public
 */
export declare const isCstCommentEvent: (event: YamlCstVisitorEvent) => event is CstCommentEvent;

/**
 * Returns `true` when `event` is a {@link CstDirectiveEvent}.
 *
 * @public
 */
export declare const isCstDirectiveEvent: (event: YamlCstVisitorEvent) => event is CstDirectiveEvent;

/**
 * Returns `true` when `event` is a {@link CstDocumentEndEvent}.
 *
 * @public
 */
export declare const isCstDocumentEndEvent: (event: YamlCstVisitorEvent) => event is CstDocumentEndEvent;

/**
 * Returns `true` when `event` is a {@link CstDocumentStartEvent}.
 *
 * @public
 */
export declare const isCstDocumentStartEvent: (event: YamlCstVisitorEvent) => event is CstDocumentStartEvent;

/**
 * Returns `true` when `event` is a {@link CstErrorEvent}.
 *
 * @public
 */
export declare const isCstErrorEvent: (event: YamlCstVisitorEvent) => event is CstErrorEvent;

/**
 * Returns `true` when `event` is a {@link CstKeyEvent}.
 *
 * @public
 */
export declare const isCstKeyEvent: (event: YamlCstVisitorEvent) => event is CstKeyEvent;

/**
 * Returns `true` when `event` is a {@link CstMapEndEvent}.
 *
 * @public
 */
export declare const isCstMapEndEvent: (event: YamlCstVisitorEvent) => event is CstMapEndEvent;

/**
 * Returns `true` when `event` is a {@link CstMapStartEvent}.
 *
 * @public
 */
export declare const isCstMapStartEvent: (event: YamlCstVisitorEvent) => event is CstMapStartEvent;

/**
 * Returns `true` when `event` is a {@link CstScalarEvent}.
 *
 * @public
 */
export declare const isCstScalarEvent: (event: YamlCstVisitorEvent) => event is CstScalarEvent;

/**
 * Returns `true` when `event` is a {@link CstSeqEndEvent}.
 *
 * @public
 */
export declare const isCstSeqEndEvent: (event: YamlCstVisitorEvent) => event is CstSeqEndEvent;

/**
 * Returns `true` when `event` is a {@link CstSeqStartEvent}.
 *
 * @public
 */
export declare const isCstSeqStartEvent: (event: YamlCstVisitorEvent) => event is CstSeqStartEvent;

/**
 * Returns `true` when `event` is a {@link CstValueEvent}.
 *
 * @public
 */
export declare const isCstValueEvent: (event: YamlCstVisitorEvent) => event is CstValueEvent;

/**
 * Returns `true` when `event` is a {@link DirectiveEvent}.
 *
 * @public
 */
export declare const isDirectiveEvent: (event: YamlVisitorEvent) => event is DirectiveEvent;

/**
 * Returns `true` if the value is a {@link YamlDocument} instance.
 *
 * @public
 */
export declare function isDocument(node: unknown): node is YamlDocument;

/**
 * Returns `true` when `event` is a {@link DocumentEndEvent}.
 *
 * @public
 */
export declare const isDocumentEndEvent: (event: YamlVisitorEvent) => event is DocumentEndEvent;

/**
 * Returns `true` when `event` is a {@link DocumentStartEvent}.
 *
 * @public
 */
export declare const isDocumentStartEvent: (event: YamlVisitorEvent) => event is DocumentStartEvent;

/**
 * Returns `true` if the value is a {@link YamlMap} instance.
 *
 * @public
 */
export declare function isMap(node: unknown): node is YamlMap;

/**
 * Returns `true` when `event` is a {@link MapEndEvent}.
 *
 * @public
 */
export declare const isMapEndEvent: (event: YamlVisitorEvent) => event is MapEndEvent;

/**
 * Returns `true` when `event` is a {@link MapStartEvent}.
 *
 * @public
 */
export declare const isMapStartEvent: (event: YamlVisitorEvent) => event is MapStartEvent;

/**
 * Returns `true` if the value is any YAML AST node type.
 *
 * @public
 */
export declare function isNode(node: unknown): node is YamlNode;

/**
 * Returns `true` if the value is a {@link YamlPair} instance.
 *
 * @public
 */
export declare function isPair(node: unknown): node is YamlPair;

/**
 * Returns `true` when `event` is a {@link PairEvent}.
 *
 * @public
 */
export declare const isPairEvent: (event: YamlVisitorEvent) => event is PairEvent;

/**
 * Returns `true` if the value is a {@link YamlScalar} instance.
 *
 * @example
 * ```typescript
 * import type { YamlNode } from "yaml-effect";
 * import { isScalar, isMap, isSeq, isPair, isAlias, isNode, isDocument, parseDocument } from "yaml-effect";
 * import { Effect } from "effect";
 *
 * const program = Effect.gen(function* () {
 *   const doc = yield* parseDocument("name: Alice\nitems:\n  - one\n  - two");
 *   const root = doc.contents!;
 *
 *   // Type guard narrows to specific node types
 *   if (isMap(root)) {
 *     const pair = root.items[0];
 *     if (isPair(pair) && isScalar(pair.key)) {
 *       console.log(pair.key.value); // "name"
 *     }
 *   }
 *
 *   // isNode matches any AST node type
 *   console.log(isNode(root));     // true
 *   console.log(isDocument(doc));  // true
 *   console.log(isAlias(root));    // false
 *   console.log(isSeq(root));     // false
 * });
 * ```
 *
 * @public
 */
export declare function isScalar(node: unknown): node is YamlScalar;

/**
 * Returns `true` when `event` is a {@link ScalarEvent}.
 *
 * @public
 */
export declare const isScalarEvent: (event: YamlVisitorEvent) => event is ScalarEvent;

/**
 * Returns `true` if the value is a {@link YamlSeq} instance.
 *
 * @public
 */
export declare function isSeq(node: unknown): node is YamlSeq;

/**
 * Returns `true` when `event` is a {@link SeqEndEvent}.
 *
 * @public
 */
export declare const isSeqEndEvent: (event: YamlVisitorEvent) => event is SeqEndEvent;

/**
 * Returns `true` when `event` is a {@link SeqStartEvent}.
 *
 * @public
 */
export declare const isSeqStartEvent: (event: YamlVisitorEvent) => event is SeqStartEvent;

/**
 * Tokenize a YAML source string into an Effect {@link Stream} of {@link YamlToken}.
 *
 * @remarks
 * Lexer errors are embedded as `"error"` tokens in the success channel; the
 * downstream parser/composer will collect them and raise `YamlLexError`
 * if needed.
 *
 * @example
 * ```typescript
 * import { Effect, Stream } from "effect";
 * import { lex } from "yaml-effect";
 *
 * const program = lex("key: value").pipe(
 *   Stream.filter((t) => t.kind === "scalar"),
 *   Stream.runCollect,
 *   Effect.map((chunk) => [...chunk].map((t) => t.value)),
 * );
 *
 * const scalars = Effect.runSync(program);
 * console.log(scalars); // ["key", "value"]
 * ```
 *
 * @public
 */
export declare function lex(text: string): Stream.Stream<YamlToken, never>;

/**
 * Creates a Schema that decodes a multi-document YAML string into an array of
 * plain JavaScript values, and encodes an array of values back into a
 * multi-document YAML string.
 *
 * @param parseOptions - Options to pass to the YAML parser.
 * @returns A Schema that decodes/encodes between YAML strings and arrays of unknown values.
 *
 * @example
 * ```typescript
 * import { Effect, Schema } from "effect";
 * import { YamlAllFromString } from "yaml-effect";
 *
 * const program = Effect.gen(function* () {
 *   const docs = yield* Schema.decode(YamlAllFromString)(
 *     "name: Alice\n---\nname: Bob",
 *   );
 *   console.log(docs); // [{ name: "Alice" }, { name: "Bob" }]
 * });
 *
 * Effect.runSync(program);
 * ```
 *
 * @public
 */
export declare function makeYamlAllFromString(parseOptions?: Partial<YamlParseOptions>): Schema.Schema<ReadonlyArray<unknown>, string>;

/**
 * Creates a Schema that decodes a YAML string into a {@link YamlDocument},
 * preserving the full AST structure, directives, and metadata.
 *
 * @param parseOptions - Options to pass to the YAML parser.
 * @returns A Schema that decodes/encodes between YAML strings and YamlDocument instances.
 *
 * @example
 * ```typescript
 * import { Effect, Schema } from "effect";
 * import type { YamlDocument } from "yaml-effect";
 * import { makeYamlDocumentSchema } from "yaml-effect";
 *
 * const DocSchema = makeYamlDocumentSchema();
 *
 * const program = Effect.gen(function* () {
 *   const doc: YamlDocument = yield* Schema.decode(DocSchema)(
 *     "# comment\nkey: value",
 *   );
 *   console.log(doc.contents); // YamlMap node
 *   console.log(doc.comment); // "comment"
 * });
 *
 * Effect.runSync(program);
 * ```
 *
 * @public
 */
export declare function makeYamlDocumentSchema(parseOptions?: Partial<YamlParseOptions>): Schema.Schema<YamlDocument, string>;

/**
 * Creates a {@link YamlFromString} schema with custom parse and stringify
 * options.
 *
 * @param parseOptions - Options to pass to the YAML parser.
 * @param stringifyOptions - Options to pass to the YAML stringifier.
 * @returns A Schema that decodes/encodes between YAML strings and unknown values.
 *
 * @example
 * ```typescript
 * import { makeYamlFromString } from "yaml-effect";
 *
 * const lenientYaml = makeYamlFromString(
 *   { strict: false },
 *   { indent: 4 },
 * );
 * ```
 *
 * @public
 */
export declare function makeYamlFromString(parseOptions?: Partial<YamlParseOptions>, stringifyOptions?: Partial<YamlStringifyOptions>): Schema.Schema<unknown, string>;

/**
 * Creates a fully typed Schema that decodes YAML strings into a domain type
 * `A` and encodes `A` values back into YAML strings.
 *
 * @param targetSchema - The Effect Schema describing the target domain type.
 * @param options - Optional parse and stringify options.
 * @returns A composed Schema from YAML string to `A`.
 *
 * @example
 * ```typescript
 * import { Effect, Schema } from "effect";
 * import { makeYamlSchema } from "yaml-effect";
 *
 * const ConfigSchema = makeYamlSchema(
 *   Schema.Struct({
 *     host: Schema.String,
 *     port: Schema.Number,
 *     debug: Schema.Boolean,
 *   }),
 * );
 *
 * const program = Effect.gen(function* () {
 *   const config = yield* Schema.decode(ConfigSchema)(
 *     "host: localhost\nport: 3000\ndebug: true",
 *   );
 *   console.log(config.port); // 3000
 *
 *   const yaml = yield* Schema.encode(ConfigSchema)(config);
 *   console.log(yaml); // "host: localhost\nport: 3000\ndebug: true\n"
 * });
 *
 * Effect.runSync(program);
 * ```
 *
 * @public
 */
export declare function makeYamlSchema<A, I, R>(targetSchema: Schema.Schema<A, I, R>, options?: {
    parseOptions?: Partial<YamlParseOptions>;
    stringifyOptions?: Partial<YamlStringifyOptions>;
}): Schema.Schema<A, string, R>;

/**
 * Emitted when the visitor exits a YAML mapping node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 *
 * @public
 */
export declare class MapEndEvent extends MapEndEvent_base {
}

declare const MapEndEvent_base: Schema.TaggedClass<MapEndEvent, "MapEndEvent", {
    readonly _tag: Schema.tag<"MapEndEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Emitted when the visitor enters a YAML mapping node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `style` — the presentation style of the mapping (`"block"` or `"flow"`).
 * - `tag` — optional explicit YAML tag (e.g., `!!map`).
 * - `anchor` — optional anchor name for aliasing.
 *
 * @public
 */
export declare class MapStartEvent extends MapStartEvent_base {
}

declare const MapStartEvent_base: Schema.TaggedClass<MapStartEvent, "MapStartEvent", {
    readonly _tag: Schema.tag<"MapStartEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    style: Schema.Literal<["block", "flow"]>;
    tag: Schema.optional<typeof Schema.String>;
    anchor: Schema.optional<typeof Schema.String>;
}>;

/**
 * Compute edits to insert, replace, or remove a value at a YAML path.
 *
 * @remarks
 * Parses the input, navigates to the target path in the Document AST,
 * applies the change, stringifies back, and diffs to produce edits.
 * Pass `undefined` as `value` to remove the property or element.
 *
 * This function is a dual — it can be called with all three arguments
 * directly, or partially applied with path and value first.
 *
 * @example Replacing a value
 * ```typescript
 * import { Effect } from "effect"
 * import { applyEdits, modify } from "yaml-effect"
 *
 * const yaml = "name: John\nage: 30\n"
 *
 * const program = Effect.gen(function* () {
 *   const edits = yield* modify(yaml, ["name"], "Jane")
 *   const result = yield* applyEdits(yaml, edits)
 *   return result
 * })
 * ```
 *
 * @example Inserting a new key
 * ```typescript
 * import { Effect } from "effect"
 * import { applyEdits, modify } from "yaml-effect"
 *
 * const yaml = "name: John\n"
 *
 * const program = Effect.gen(function* () {
 *   const edits = yield* modify(yaml, ["email"], "john@example.com")
 *   const result = yield* applyEdits(yaml, edits)
 *   return result
 * })
 * ```
 *
 * @example Removing a key
 * ```typescript
 * import { Effect } from "effect"
 * import { applyEdits, modify } from "yaml-effect"
 *
 * const yaml = "name: John\nage: 30\n"
 *
 * const program = Effect.gen(function* () {
 *   const edits = yield* modify(yaml, ["age"], undefined)
 *   const result = yield* applyEdits(yaml, edits)
 *   return result
 * })
 * ```
 *
 * @public
 */
export declare const modify: {
    (path: YamlPath, value: unknown): (text: string) => Effect.Effect<ReadonlyArray<YamlEdit>, YamlModificationError>;
    (text: string, path: YamlPath, value: unknown): Effect.Effect<ReadonlyArray<YamlEdit>, YamlModificationError>;
};

/**
 * Modify a YAML document in one step.
 *
 * @remarks
 * Same as {@link modify} but returns the modified string directly instead
 * of computing a diff. This function is a dual — it can be called with all
 * three arguments directly, or partially applied with path and value first.
 *
 * @example One-step modification
 * ```typescript
 * import { Effect } from "effect"
 * import { modifyAndApply } from "yaml-effect"
 *
 * const yaml = "name: John\nage: 30\n"
 *
 * const program = Effect.gen(function* () {
 *   const result: string = yield* modifyAndApply(yaml, ["name"], "Jane")
 *   return result
 * })
 * ```
 *
 * @public
 */
export declare const modifyAndApply: {
    (path: YamlPath, value: unknown): (text: string) => Effect.Effect<string, YamlModificationError>;
    (text: string, path: YamlPath, value: unknown): Effect.Effect<string, YamlModificationError>;
};

/**
 * Emitted when the visitor encounters a key-value pair within a mapping.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `key` — the resolved key value of the pair.
 * - `value` — the resolved value of the pair.
 *
 * @public
 */
export declare class PairEvent extends PairEvent_base {
}

declare const PairEvent_base: Schema.TaggedClass<PairEvent, "PairEvent", {
    readonly _tag: Schema.tag<"PairEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    key: typeof Schema.Unknown;
    value: typeof Schema.Unknown;
}>;

/**
 * Parse YAML text and return the plain JavaScript value.
 *
 * @remarks
 * This is the highest-level parse function. It parses a single document,
 * resolves anchors/aliases, enforces unique keys (by default), and returns
 * the resulting JavaScript value (object, array, or scalar).
 *
 * @example
 * ```typescript
 * import { Effect } from "effect";
 * import { parse } from "yaml-effect";
 *
 * const program = parse("name: Alice\nage: 30").pipe(
 *   Effect.tap((value) => Effect.log(value)),
 *   Effect.catchTag("YamlComposerError", (err) =>
 *     Effect.logError(`Parse failed: ${err.message}`),
 *   ),
 * );
 *
 * Effect.runPromise(program);
 * // => { name: "Alice", age: 30 }
 * ```
 *
 * @param text - The YAML source text to parse.
 * @param options - Optional parse options (e.g. `{ uniqueKeys: false }`).
 * @returns An `Effect` that resolves to the parsed JavaScript value, or
 *   fails with a {@link YamlComposerError}.
 *
 * @public
 */
export declare function parse(text: string, options?: Partial<YamlParseOptions>): Effect.Effect<unknown, YamlComposerError>;

/**
 * Parse YAML text containing multiple documents into an array of
 * {@link YamlDocument}.
 *
 * @remarks
 * Splits the input on `---` document-start markers. Each document is
 * independently composed, and any fatal error in any document causes
 * the entire Effect to fail.
 *
 * @example
 * ```typescript
 * import { Effect } from "effect";
 * import { parseAllDocuments } from "yaml-effect";
 *
 * const yaml = `
 * name: first
 * ---
 * name: second
 * `;
 *
 * const program = parseAllDocuments(yaml).pipe(
 *   Effect.tap((docs) => Effect.log(`Parsed ${docs.length} documents`)),
 * );
 *
 * Effect.runPromise(program);
 * ```
 *
 * @param text - The YAML source text containing one or more documents.
 * @param options - Optional parse options.
 * @returns An `Effect` that resolves to a read-only array of {@link YamlDocument}.
 *
 * @public
 */
export declare function parseAllDocuments(text: string, options?: Partial<YamlParseOptions>): Effect.Effect<ReadonlyArray<YamlDocument>, YamlComposerError>;

/**
 * Parse YAML source text into a stream of CST nodes (one per document).
 *
 * @remarks
 * Each CST node preserves every character of the original input, including
 * whitespace, comments, and structural indicators. No value interpretation
 * occurs at this stage — `true` is still the string `"true"`.
 *
 * @example
 * ```typescript
 * import { Effect, Stream } from "effect";
 * import { parseCST } from "yaml-effect";
 *
 * const program = parseCST("key: value").pipe(
 *   Stream.runCollect,
 *   Effect.map((chunk) => {
 *     const docs = [...chunk];
 *     console.log(docs[0].type); // "document"
 *   }),
 * );
 *
 * Effect.runSync(program);
 * ```
 *
 * @public
 */
export declare function parseCST(text: string): Stream.Stream<CstNode, never>;

/**
 * Parse YAML text into a single {@link YamlDocument}.
 *
 * @remarks
 * Returns the first document found in the input. If the input is empty,
 * a document with `null` contents is returned. Fatal composer errors
 * (undefined aliases, alias count exceeded, unexpected tokens) cause
 * the Effect to fail with a {@link YamlComposerError}.
 *
 * @example
 * ```typescript
 * import { Effect } from "effect";
 * import { parseDocument } from "yaml-effect";
 *
 * const program = parseDocument("name: Alice\nage: 30").pipe(
 *   Effect.tap((doc) => Effect.log(`Document has ${doc.errors.length} errors`)),
 * );
 *
 * Effect.runPromise(program);
 * ```
 *
 * @param text - The YAML source text to parse.
 * @param options - Optional parse options.
 * @returns An `Effect` that resolves to a {@link YamlDocument}.
 *
 * @public
 */
export declare function parseDocument(text: string, options?: Partial<YamlParseOptions>): Effect.Effect<YamlDocument, YamlComposerError>;

/**
 * Plain-object formatting options accepted by {@link format},
 * {@link formatAndApply}, and {@link stripComments}.
 *
 * @remarks
 * This interface mirrors {@link YamlFormattingOptions} but uses plain optional
 * fields instead of Schema.Class validation, making it convenient for callers
 * who do not need full schema-level validation. The `range` field restricts
 * returned edits to a byte range within the source text.
 *
 * @public
 */
export declare interface RawFormatOptions {
    /** Number of spaces per indentation level (default: 2). */
    indent?: number;
    /** Maximum line width before the stringifier wraps long scalars. */
    lineWidth?: number;
    /** Default quoting style for scalar values. */
    defaultScalarStyle?: ScalarStyle;
    /** Default style (`block` or `flow`) for collections. */
    defaultCollectionStyle?: CollectionStyle;
    /** When `true`, map keys are sorted alphabetically. */
    sortKeys?: boolean;
    /** When `true`, a trailing newline is appended to the output. */
    finalNewline?: boolean;
    /** When `true`, comments are preserved in the output. */
    preserveComments?: boolean;
    /** Restrict returned edits to this byte range within the source text. */
    range?: {
        offset: number;
        length: number;
    };
}

/**
 * Emitted when the visitor encounters a YAML scalar node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `value` — the resolved JavaScript value (null, boolean, number, or string).
 * - `style` — the scalar presentation style in the source document.
 * - `tag` — optional explicit YAML tag (e.g., `!!str`, `!!int`).
 * - `anchor` — optional anchor name for aliasing.
 *
 * @public
 */
export declare class ScalarEvent extends ScalarEvent_base {
}

declare const ScalarEvent_base: Schema.TaggedClass<ScalarEvent, "ScalarEvent", {
    readonly _tag: Schema.tag<"ScalarEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    value: typeof Schema.Unknown;
    style: Schema.Literal<["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>;
    tag: Schema.optional<typeof Schema.String>;
    anchor: Schema.optional<typeof Schema.String>;
}>;

/**
 * YAML scalar output styles.
 *
 * @public
 */
export declare const ScalarStyle: Schema.Literal<["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>;

/**
 * The union of all scalar style string literals.
 *
 * @see {@link ScalarStyle}
 *
 * @public
 */
export declare type ScalarStyle = Schema.Schema.Type<typeof ScalarStyle>;

/**
 * Emitted when the visitor exits a YAML sequence node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 *
 * @public
 */
export declare class SeqEndEvent extends SeqEndEvent_base {
}

declare const SeqEndEvent_base: Schema.TaggedClass<SeqEndEvent, "SeqEndEvent", {
    readonly _tag: Schema.tag<"SeqEndEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Emitted when the visitor enters a YAML sequence node.
 *
 * @remarks
 * - `path` — path segments from the root to this node.
 * - `depth` — zero-based nesting depth.
 * - `style` — the presentation style of the sequence (`"block"` or `"flow"`).
 * - `tag` — optional explicit YAML tag (e.g., `!!seq`).
 * - `anchor` — optional anchor name for aliasing.
 *
 * @public
 */
export declare class SeqStartEvent extends SeqStartEvent_base {
}

declare const SeqStartEvent_base: Schema.TaggedClass<SeqStartEvent, "SeqStartEvent", {
    readonly _tag: Schema.tag<"SeqStartEvent">;
} & {
    path: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
    depth: Schema.filter<typeof Schema.Int>;
    style: Schema.Literal<["block", "flow"]>;
    tag: Schema.optional<typeof Schema.String>;
    anchor: Schema.optional<typeof Schema.String>;
}>;

/**
 * Converts a JavaScript value into a YAML text string.
 *
 * @remarks
 * Handles all primitive types, arrays, and plain objects. Special numbers
 * (`Infinity`, `-Infinity`, `NaN`) are rendered as `.inf`, `-.inf`, and
 * `.nan` respectively. Circular references cause a {@link YamlStringifyError}.
 *
 * @example
 * ```typescript
 * import { Effect } from "effect";
 * import { stringify } from "yaml-effect";
 *
 * const data = { name: "Alice", tags: ["admin", "user"], active: true };
 *
 * const program = stringify(data).pipe(
 *   Effect.tap((yaml) => Effect.log(yaml)),
 * );
 *
 * Effect.runPromise(program);
 * // name: Alice
 * // tags:
 * //   - admin
 * //   - user
 * // active: true
 * ```
 *
 * @example Customizing output format
 * ```typescript
 * import { Effect } from "effect";
 * import { stringify } from "yaml-effect";
 *
 * const program = stringify({ key: "value" }, {
 *   indent: 4,
 *   defaultCollectionStyle: "flow",
 *   finalNewline: false,
 * }).pipe(Effect.tap((yaml) => Effect.log(yaml)));
 *
 * Effect.runPromise(program);
 * // {key: value}
 * ```
 *
 * @param value - The value to stringify.
 * @param options - Optional formatting options. Defaults are used for any
 *   omitted fields.
 * @returns An `Effect` that resolves to the YAML text string.
 *
 * @public
 */
export declare function stringify(value: unknown, options?: YamlStringifyOptions | Partial<ConstructorParameters<typeof YamlStringifyOptions>[0]>): Effect.Effect<string, YamlStringifyError>;

/**
 * Converts a {@link YamlDocument} AST into a YAML text string, preserving
 * the style metadata encoded in each AST node.
 *
 * @remarks
 * Scalar nodes use their `style` field (`"plain"`, `"single-quoted"`,
 * `"double-quoted"`, `"block-literal"`, `"block-folded"`) to control
 * rendering. Collection nodes use their `style` field (`"block"` or
 * `"flow"`). Nodes without an explicit style fall back to the defaults in
 * `options`.
 *
 * @example
 * ```typescript
 * import { Effect } from "effect";
 * import { parseDocument } from "yaml-effect";
 * import { stringifyDocument } from "yaml-effect";
 *
 * const program = parseDocument("name: Alice\nage: 30").pipe(
 *   Effect.flatMap((doc) => stringifyDocument(doc)),
 *   Effect.tap((yaml) => Effect.log(yaml)),
 * );
 *
 * Effect.runPromise(program);
 * // name: Alice
 * // age: 30
 * ```
 *
 * @param doc - The parsed YAML document whose AST to serialize.
 * @param options - Optional formatting options.
 * @returns An `Effect` that resolves to the YAML text string.
 *
 * @public
 */
export declare function stringifyDocument(doc: YamlDocument, options?: YamlStringifyOptions | Partial<ConstructorParameters<typeof YamlStringifyOptions>[0]>): Effect.Effect<string, YamlStringifyError>;

/**
 * Remove all comments from a YAML document.
 *
 * @remarks
 * Without `replaceCh`: parses the document, removes all comment fields from
 * the AST, and stringifies back. Full-line comments are removed entirely.
 *
 * With `replaceCh` (a single character): replaces each character of comment
 * text (including the `#` marker) with the given character to preserve
 * character offsets. Newlines are always preserved.
 *
 * @example Removing comments from YAML
 * ```typescript
 * import { Effect } from "effect"
 * import { stripComments } from "yaml-effect"
 *
 * const yaml = "name: John # the user name\nage: 30 # years\n"
 *
 * const program = Effect.gen(function* () {
 *   const stripped: string = yield* stripComments(yaml)
 *   // stripped has all comments removed from the document
 *   return stripped
 * })
 * ```
 *
 * @public
 */
export declare function stripComments(text: string, replaceCh?: string): Effect.Effect<string, YamlFormatError>;

/**
 * Walk a YAML text string and emit a `Stream` of {@link YamlVisitorEvent}
 * values in document order.
 *
 * @remarks
 * The stream emits events for every node encountered during the traversal,
 * including `DocumentStartEvent`/`DocumentEndEvent` pairs, collection open/
 * close events, and leaf-node events for scalars and aliases.
 *
 * Multi-document YAML streams (separated by `---`) produce separate document
 * event pairs for each document.
 *
 * The returned stream is lazy — only events up to the point of consumption
 * are generated. This makes it safe to use with `Stream.take` or similar
 * operators for early termination.
 *
 * @example Streaming events and taking the first 5
 * ```typescript
 * import { Effect, Stream } from "effect"
 * import type { YamlVisitorEvent } from "yaml-effect"
 * import { visit } from "yaml-effect"
 *
 * const yaml = "name: John\nage: 30\ntags:\n  - admin\n  - user\n"
 *
 * const program = Effect.gen(function* () {
 *   const events: ReadonlyArray<YamlVisitorEvent> = yield* Stream.runCollect(
 *     visit(yaml).pipe(Stream.take(5)),
 *   ).pipe(Effect.map((chunk) => [...chunk]))
 *   return events
 * })
 * ```
 *
 * @param text - The YAML source text to visit.
 * @param options - Optional parse options forwarded to the composer.
 * @returns A `Stream` of `YamlVisitorEvent` values, failing with
 *   `YamlComposerError` on fatal parse errors.
 *
 * @public
 */
export declare function visit(text: string, options?: Partial<YamlParseOptions>): Stream.Stream<YamlVisitorEvent, YamlComposerError>;

/**
 * Walk a YAML text string and collect the results of applying `predicate` to
 * each {@link YamlVisitorEvent}.
 *
 * @remarks
 * Only events for which `predicate` returns `Option.some(value)` are included
 * in the result array.  Events that return `Option.none()` are silently
 * discarded.
 *
 * @example Collecting all scalar values from a document
 * ```typescript
 * import { Effect, Option } from "effect"
 * import { isScalarEvent, visitCollect } from "yaml-effect"
 *
 * const yaml = "name: John\nage: 30\n"
 *
 * const program = Effect.gen(function* () {
 *   const values: ReadonlyArray<unknown> = yield* visitCollect(
 *     yaml,
 *     (event) =>
 *       isScalarEvent(event) ? Option.some(event.value) : Option.none(),
 *   )
 *   // values contains: ["name", "John", "age", 30]
 *   return values
 * })
 * ```
 *
 * @typeParam A - The type of values extracted by the predicate.
 * @param text - The YAML source text to visit.
 * @param predicate - A function mapping each event to `Option.some(value)` to
 *   collect it or `Option.none()` to skip it.
 * @param options - Optional parse options forwarded to the composer.
 * @returns An `Effect` resolving to a `ReadonlyArray<A>` of collected values,
 *   failing with `YamlComposerError` on fatal parse errors.
 *
 * @public
 */
export declare function visitCollect<A>(text: string, predicate: (event: YamlVisitorEvent) => Option.Option<A>, options?: Partial<YamlParseOptions>): Effect.Effect<ReadonlyArray<A>, YamlComposerError>;

/**
 * Walk YAML source text at the CST level and emit a `Stream` of
 * {@link YamlCstVisitorEvent} values in document order.
 *
 * @remarks
 * The stream emits events for every CST node encountered during traversal,
 * including `CstDocumentStartEvent`/`CstDocumentEndEvent` pairs, collection
 * open/close events, and leaf-node events for scalars, aliases, comments, and
 * directives.
 *
 * All content is delivered as raw source strings — `true` is still the string
 * `"true"`.  CST-level errors are surfaced as {@link CstErrorEvent} nodes; the
 * error channel is always `never`.
 *
 * @example Streaming CST events
 * ```typescript
 * import { Effect, Stream } from "effect"
 * import type { YamlCstVisitorEvent } from "yaml-effect"
 * import { visitCST } from "yaml-effect"
 *
 * const yaml = "name: John\nage: 30\n"
 *
 * const program = Effect.gen(function* () {
 *   const events: ReadonlyArray<YamlCstVisitorEvent> = yield* Stream.runCollect(
 *     visitCST(yaml),
 *   ).pipe(Effect.map((chunk) => [...chunk]))
 *   return events
 * })
 * ```
 *
 * @param text - The YAML source text to visit.
 * @returns A `Stream` of `YamlCstVisitorEvent` values, never failing.
 *
 * @public
 */
export declare function visitCST(text: string): Stream.Stream<YamlCstVisitorEvent, never>;

/**
 * Walk YAML source text at the CST level and collect the results of applying
 * `predicate` to each {@link YamlCstVisitorEvent}.
 *
 * @remarks
 * Only events for which `predicate` returns `Option.some(value)` are included
 * in the result array.  Events that return `Option.none()` are silently
 * discarded.
 *
 * @example Collecting all CST keys from a document
 * ```typescript
 * import { Effect, Option } from "effect"
 * import { isCstKeyEvent, visitCSTCollect } from "yaml-effect"
 *
 * const yaml = "name: John\nage: 30\n"
 *
 * const program = Effect.gen(function* () {
 *   const keys: ReadonlyArray<string> = yield* visitCSTCollect(
 *     yaml,
 *     (event) =>
 *       isCstKeyEvent(event) ? Option.some(event.source) : Option.none(),
 *   )
 *   // keys contains the raw source strings: ["name", "age"]
 *   return keys
 * })
 * ```
 *
 * @typeParam A - The type of values extracted by the predicate.
 * @param text - The YAML source text to visit.
 * @param predicate - A function mapping each event to `Option.some(value)` to
 *   collect it or `Option.none()` to skip it.
 * @returns An `Effect` resolving to a `ReadonlyArray<A>` of collected values,
 *   never failing.
 *
 * @public
 */
export declare function visitCSTCollect<A>(text: string, predicate: (event: YamlCstVisitorEvent) => Option.Option<A>): Effect.Effect<ReadonlyArray<A>, never>;

/**
 * A YAML alias AST node, referencing a previously defined anchor by name.
 *
 * @remarks
 * - `name` — the anchor name this alias refers to (without the leading `*`).
 * - `offset` — zero-based character offset where the alias begins.
 * - `length` — character length of the alias span.
 *
 * @example
 * ```typescript
 * import { YamlAlias } from "yaml-effect";
 *
 * const alias = new YamlAlias({
 *   name: "defaults",
 *   offset: 20,
 *   length: 9,
 * });
 * console.log(alias.name); // "defaults"
 * ```
 *
 * @public
 */
export declare class YamlAlias extends YamlAlias_base {
}

declare const YamlAlias_base: Schema.TaggedClass<YamlAlias, "YamlAlias", {
    readonly _tag: Schema.tag<"YamlAlias">;
} & {
    name: typeof Schema.String;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
}>;

/**
 * A Schema that decodes a multi-document YAML string into an array of unknown
 * values and encodes an array of values back into a multi-document YAML string.
 *
 * @public
 */
export declare const YamlAllFromString: Schema.Schema<ReadonlyArray<unknown>, string>;

/**
 * Error raised when YAML composition encounters one or more semantic errors.
 *
 * @remarks
 * Contains the full source `text` and an `errors` array of
 * {@link YamlErrorDetail} instances with precise position information for
 * each problem found.
 *
 * @see {@link parse} — may fail with this error
 * @see {@link parseDocument} — may fail with this error
 * @see {@link parseAllDocuments} — may fail with this error
 *
 * @example Catching with `Effect.catchTag`
 * ```ts
 * import { Effect } from "effect";
 * import { parse } from "yaml-effect";
 *
 * const program = parse("a: *undefined_alias").pipe(
 *   Effect.catchTag("YamlComposerError", (e) => {
 *     for (const detail of e.errors) {
 *       console.error(
 *         `[${detail.code}] ${detail.message} at ${detail.line}:${detail.column}`,
 *       );
 *     }
 *     return Effect.succeed(null);
 *   }),
 * );
 * ```
 *
 * @public
 */
export declare class YamlComposerError extends YamlComposerErrorBase<{
    readonly errors: ReadonlyArray<YamlErrorDetail>;
    readonly text: string;
}> {
    get message(): string;
}

/**
 * Base class for {@link YamlComposerError}.
 *
 * @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 `YamlComposerError` class
 * extends it with concrete fields, giving api-extractor a simple class
 * declaration to work with.
 *
 * @internal
 */
export declare const YamlComposerErrorBase: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
    readonly _tag: "YamlComposerError";
} & Readonly<A>;

/**
 * A discriminated union of all thirteen SAX-style YAML CST visitor events.
 *
 * @remarks
 * Use the individual type-guard helpers (`isCstScalarEvent`, `isCstKeyEvent`,
 * etc.) to narrow an event to a specific variant.
 *
 * @public
 */
export declare const YamlCstVisitorEvent: Schema.Union<[typeof CstDocumentStartEvent, typeof CstDocumentEndEvent, typeof CstMapStartEvent, typeof CstMapEndEvent, typeof CstSeqStartEvent, typeof CstSeqEndEvent, typeof CstKeyEvent, typeof CstValueEvent, typeof CstScalarEvent, typeof CstAliasEvent, typeof CstCommentEvent, typeof CstDirectiveEvent, typeof CstErrorEvent]>;

/**
 * The union of all YAML CST visitor event types.
 *
 * @see {@link YamlCstVisitorEvent}
 *
 * @public
 */
export declare type YamlCstVisitorEvent = Schema.Schema.Type<typeof YamlCstVisitorEvent>;

/**
 * A YAML directive appearing at the top of a document (e.g., `%YAML 1.2`
 * or `%TAG ! tag:yaml.org,2002:`).
 *
 * @remarks
 * - `name` — the directive name. `"YAML"` and `"TAG"` are the YAML 1.2
 *   spec-defined directives with semantic meaning. Any other name is a
 *   *reserved* directive (per YAML 1.2 §6.8.1) which YAML processors must
 *   ignore semantically but should preserve for round-trip fidelity.
 * - `parameters` — the directive's parameter tokens as raw strings.
 *
 * @public
 */
export declare class YamlDirective extends YamlDirective_base {
}

declare const YamlDirective_base: Schema.Class<YamlDirective, {
    name: typeof Schema.String;
    parameters: Schema.Array$<typeof Schema.String>;
}, Schema.Struct.Encoded<{
    name: typeof Schema.String;
    parameters: Schema.Array$<typeof Schema.String>;
}>, never, {
    readonly name: string;
} & {
    readonly parameters: readonly string[];
}, {}, {}>;

/**
 * A parsed YAML document, containing the root AST node, any parse errors or
 * warnings, YAML directives, and an optional document-level comment.
 *
 * @remarks
 * - `contents` — the root {@link YamlNode} of the document, or `null` for an
 *   empty document.
 * - `errors` — {@link YamlErrorDetail} entries produced during parsing.
 * - `warnings` — non-fatal {@link YamlErrorDetail} entries produced during
 *   parsing.
 * - `directives` — {@link YamlDirective} entries declared before the document
 *   content.
 * - `comment` — optional document-level comment text.
 *
 * @example
 * ```typescript
 * import type { YamlNode } from "yaml-effect";
 * import { isMap, isScalar, parseDocument } from "yaml-effect";
 * import { Effect } from "effect";
 *
 * const program = Effect.gen(function* () {
 *   const doc = yield* parseDocument("name: Alice\nage: 30");
 *
 *   // Access the root AST node
 *   const root: YamlNode | null = doc.contents;
 *   if (root && isMap(root)) {
 *     console.log(root.items.length); // 2
 *   }
 *
 *   // Check for parse errors and warnings
 *   console.log(doc.errors.length);   // 0
 *   console.log(doc.warnings.length); // 0
 * });
 * ```
 *
 * @public
 */
export declare class YamlDocument extends YamlDocument_base {
}

declare const YamlDocument_base: Schema.Class<YamlDocument, {
    contents: Schema.NullOr<Schema.suspend<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAlias | YamlMap | YamlScalar | YamlSeq, never>>;
    errors: Schema.Array$<typeof YamlErrorDetail>;
    warnings: Schema.Array$<typeof YamlErrorDetail>;
    directives: Schema.Array$<typeof YamlDirective>;
    comment: Schema.optional<typeof Schema.String>;
    hasDocumentStart: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
    hasDocumentEnd: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
    /**
     * `true` when the document-start marker `---` was followed by a tab
     * character in the source (e.g. `---\tscalar`). Used by the canonical
     * stringifier to emit `...` terminator (libyaml's emitter does this for
     * tab-after-`---` to avoid downstream re-tokenisation ambiguity). Optional;
     * absent on synthetic docs.
     */
    hasDocumentStartTab: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
}, Schema.Struct.Encoded<{
    contents: Schema.NullOr<Schema.suspend<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAlias | YamlMap | YamlScalar | YamlSeq, never>>;
    errors: Schema.Array$<typeof YamlErrorDetail>;
    warnings: Schema.Array$<typeof YamlErrorDetail>;
    directives: Schema.Array$<typeof YamlDirective>;
    comment: Schema.optional<typeof Schema.String>;
    hasDocumentStart: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
    hasDocumentEnd: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
    /**
     * `true` when the document-start marker `---` was followed by a tab
     * character in the source (e.g. `---\tscalar`). Used by the canonical
     * stringifier to emit `...` terminator (libyaml's emitter does this for
     * tab-after-`---` to avoid downstream re-tokenisation ambiguity). Optional;
     * absent on synthetic docs.
     */
    hasDocumentStartTab: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
}>, never, {
    readonly comment?: string | undefined;
} & {
    readonly hasDocumentEnd?: boolean;
} & {
    readonly hasDocumentStart?: boolean;
} & {
    readonly hasDocumentStartTab?: boolean;
} & {
    readonly contents: YamlAlias | YamlMap | YamlScalar | YamlSeq | null;
} & {
    readonly directives: readonly YamlDirective[];
} & {
    readonly errors: readonly YamlErrorDetail[];
} & {
    readonly warnings: readonly YamlErrorDetail[];
}, {}, {}>;

/**
 * A non-mutating text edit describing a replacement within a YAML 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 `""`.
 *
 * @example
 * ```typescript
 * import { YamlEdit } from "yaml-effect";
 *
 * // Replace 5 characters starting at offset 6 with "Bob"
 * const replaceEdit = new YamlEdit({ offset: 6, length: 5, content: "Bob" });
 *
 * // Insert text at offset 0 without removing anything
 * const insertEdit = new YamlEdit({ offset: 0, length: 0, content: "# header\n" });
 *
 * // Delete 3 characters starting at offset 10
 * const deleteEdit = new YamlEdit({ offset: 10, length: 3, content: "" });
 * ```
 *
 * @public
 */
export declare class YamlEdit extends YamlEdit_base {
}

declare const YamlEdit_base: Schema.Class<YamlEdit, {
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
    content: typeof Schema.String;
}, Schema.Struct.Encoded<{
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
    content: typeof Schema.String;
}>, never, {
    readonly content: string;
} & {
    readonly length: number;
} & {
    readonly offset: number;
}, {}, {}>;

/**
 * Union of all YAML error types.
 *
 * @public
 */
export declare type YamlError = YamlLexError | YamlParseError | YamlComposerError | YamlStringifyError | YamlFormatError | YamlModificationError | YamlNodeNotFoundError | YamlSchemaError;

/**
 * Detail for a single YAML error, including the error code, a human-readable
 * message, and the exact position within the source document.
 *
 * @remarks
 * - `code` — a {@link YamlErrorCode} 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.
 * - `line` — zero-based line number of the error.
 * - `column` — zero-based column within the line.
 *
 * @public
 */
export declare class YamlErrorDetail extends YamlErrorDetail_base {
}

declare const YamlErrorDetail_base: Schema.Class<YamlErrorDetail, {
    code: Schema.Union<[Schema.Literal<["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literal<["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection"]>, Schema.Literal<["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>]>;
    message: typeof Schema.String;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
    line: Schema.filter<typeof Schema.Int>;
    column: Schema.filter<typeof Schema.Int>;
}, Schema.Struct.Encoded<{
    code: Schema.Union<[Schema.Literal<["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literal<["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection"]>, Schema.Literal<["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>]>;
    message: typeof Schema.String;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
    line: Schema.filter<typeof Schema.Int>;
    column: Schema.filter<typeof Schema.Int>;
}>, never, {
    readonly code: "AliasCountExceeded" | "CircularAlias" | "DuplicateAnchor" | "DuplicateKey" | "InvalidAnchorName" | "InvalidBlockStructure" | "InvalidDirective" | "InvalidEscapeSequence" | "InvalidIndentation" | "InvalidTagHandle" | "InvalidTagValue" | "InvalidUnicode" | "MalformedFlowCollection" | "MissingKey" | "MissingValue" | "TabIndentation" | "UndefinedAlias" | "UnexpectedByteOrderMark" | "UnexpectedCharacter" | "UnexpectedToken" | "UnresolvedTag" | "UnterminatedBlockScalar" | "UnterminatedFlowCollection" | "UnterminatedString";
} & {
    readonly column: number;
} & {
    readonly length: number;
} & {
    readonly line: number;
} & {
    readonly message: string;
} & {
    readonly offset: number;
}, {}, {}>;

/**
 * Error raised when YAML formatting fails.
 *
 * @remarks
 * Contains the `text` that could not be formatted and a `reason` string
 * explaining the failure.
 *
 * @example Catching with `Effect.catchTag`
 * ```ts
 * import { Effect } from "effect";
 * import { format } from "yaml-effect";
 *
 * const program = format("malformed: [yaml").pipe(
 *   Effect.catchTag("YamlFormatError", (e) => {
 *     console.error(`Format failed: ${e.reason}`);
 *     return Effect.succeed(e.text);
 *   }),
 * );
 * ```
 *
 * @public
 */
export declare class YamlFormatError extends YamlFormatErrorBase<{
    readonly text: string;
    readonly reason: string;
}> {
    get message(): string;
}

/**
 * Base class for {@link YamlFormatError}.
 *
 * @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 `YamlFormatError` class
 * extends it with concrete fields, giving api-extractor a simple class
 * declaration to work with.
 *
 * @internal
 */
export declare const YamlFormatErrorBase: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
    readonly _tag: "YamlFormatError";
} & Readonly<A>;

/**
 * Options controlling YAML formatting behavior.
 *
 * @remarks
 * Extends all {@link YamlStringifyOptions} fields with formatting-specific
 * options. Fields are repeated rather than using class inheritance so that
 * `Schema.Class` composition remains straightforward and avoids
 * `Schema.extend` complexities.
 *
 * - `indent` — number of spaces per indentation level. Defaults to `2`.
 * - `lineWidth` — preferred maximum line width. Defaults to `80`.
 * - `defaultScalarStyle` — scalar output style. Defaults to `"plain"`.
 * - `defaultCollectionStyle` — collection output style. Defaults to `"block"`.
 * - `sortKeys` — sort mapping keys alphabetically. Defaults to `false`.
 * - `finalNewline` — end output with a trailing newline. Defaults to `true`.
 * - `preserveComments` — when `true`, comments in the source document are
 *   preserved in the formatted output. Defaults to `true`.
 * - `range` — when provided, restrict formatting to this region of the
 *   document. Optional; defaults to formatting the entire document.
 *
 * @public
 */
export declare class YamlFormattingOptions extends YamlFormattingOptions_base {
}

declare const YamlFormattingOptions_base: Schema.Class<YamlFormattingOptions, {
    indent: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    lineWidth: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    defaultScalarStyle: Schema.optionalWith<Schema.Literal<["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>, {
        default: () => "plain";
    }>;
    defaultCollectionStyle: Schema.optionalWith<Schema.Literal<["block", "flow"]>, {
        default: () => "block";
    }>;
    sortKeys: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
    finalNewline: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
    preserveComments: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
    range: Schema.optional<typeof YamlRange>;
}, Schema.Struct.Encoded<{
    indent: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    lineWidth: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    defaultScalarStyle: Schema.optionalWith<Schema.Literal<["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>, {
        default: () => "plain";
    }>;
    defaultCollectionStyle: Schema.optionalWith<Schema.Literal<["block", "flow"]>, {
        default: () => "block";
    }>;
    sortKeys: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
    finalNewline: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
    preserveComments: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
    range: Schema.optional<typeof YamlRange>;
}>, never, {
    readonly range?: YamlRange | undefined;
} & {
    readonly defaultCollectionStyle?: "block" | "flow";
} & {
    readonly defaultScalarStyle?: "block-folded" | "block-literal" | "double-quoted" | "plain" | "single-quoted";
} & {
    readonly finalNewline?: boolean;
} & {
    readonly indent?: number;
} & {
    readonly lineWidth?: number;
} & {
    readonly preserveComments?: boolean;
} & {
    readonly sortKeys?: boolean;
}, {}, {}>;

/**
 * A Schema that decodes a YAML string into an unknown value and encodes
 * an unknown value back into a YAML string.
 *
 * @example
 * ```typescript
 * import { Effect, Schema } from "effect";
 * import { YamlFromString } from "yaml-effect";
 *
 * const decode = Schema.decode(YamlFromString);
 * const encode = Schema.encode(YamlFromString);
 *
 * const program = decode("name: Alice\nage: 30").pipe(
 *   Effect.tap((value) => Effect.log(value)),
 *   // => { name: "Alice", age: 30 }
 *   Effect.flatMap((value) => encode(value)),
 *   Effect.tap((yaml) => Effect.log(yaml)),
 *   // => "name: Alice\nage: 30\n"
 * );
 *
 * Effect.runPromise(program);
 * ```
 *
 * @public
 */
export declare const YamlFromString: Schema.Schema<unknown, string>;

/**
 * Error raised when YAML lexing encounters one or more tokenization errors.
 *
 * @remarks
 * Contains the full source `text` and an `errors` array of
 * {@link YamlErrorDetail} instances with precise position information for
 * each problem found.
 *
 * @see {@link lex} — may produce tokens that cause this error downstream
 *
 * @example Catching with `Effect.catchTag`
 * ```ts
 * import { Effect } from "effect";
 * import { parse } from "yaml-effect";
 *
 * const program = parse("key: [unclosed").pipe(
 *   Effect.catchTag("YamlLexError", (e) => {
 *     for (const detail of e.errors) {
 *       console.error(
 *         `[${detail.code}] ${detail.message} at ${detail.line}:${detail.column}`,
 *       );
 *     }
 *     return Effect.succeed(null);
 *   }),
 * );
 * ```
 *
 * @public
 */
export declare class YamlLexError extends YamlLexErrorBase<{
    readonly errors: ReadonlyArray<YamlErrorDetail>;
    readonly text: string;
}> {
    get message(): string;
}

/**
 * Base class for {@link YamlLexError}.
 *
 * @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 `YamlLexError` class
 * extends it with concrete fields, giving api-extractor a simple class
 * declaration to work with.
 *
 * @internal
 */
export declare const YamlLexErrorBase: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
    readonly _tag: "YamlLexError";
} & Readonly<A>;

/**
 * A YAML mapping AST node, representing a collection of key-value pairs.
 *
 * @remarks
 * - `items` — the array of {@link YamlPair} entries in this mapping.
 * - `style` — the presentation style: `"block"` or `"flow"`.
 * - `tag` — optional explicit YAML tag (e.g., `!!map`).
 * - `anchor` — optional anchor name for aliasing.
 * - `comment` — optional leading or trailing comment text.
 * - `offset` — zero-based character offset where the mapping begins.
 * - `length` — character length of the mapping span.
 *
 * @example
 * ```typescript
 * import { YamlMap, YamlPair, YamlScalar } from "yaml-effect";
 *
 * const map = new YamlMap({
 *   items: [
 *     new YamlPair({
 *       key: new YamlScalar({ value: "host", style: "plain", offset: 0, length: 4 }),
 *       value: new YamlScalar({ value: "localhost", style: "plain", offset: 6, length: 9 }),
 *     }),
 *   ],
 *   style: "block",
 *   offset: 0,
 *   length: 15,
 * });
 * ```
 *
 * @public
 */
export declare class YamlMap extends YamlMap_base {
}

declare const YamlMap_base: Schema.TaggedClass<YamlMap, "YamlMap", {
    readonly _tag: Schema.tag<"YamlMap">;
} & {
    items: Schema.Array$<Schema.suspend<YamlPair, YamlPair, never>>;
    tag: Schema.optional<typeof Schema.String>;
    anchor: Schema.optional<typeof Schema.String>;
    style: Schema.Literal<["block", "flow"]>;
    comment: Schema.optional<typeof Schema.String>;
    /**
     * `true` when the source span of this mapping covers two or more lines.
     * Used by the canonical stringifier — flow-style maps that span multiple
     * lines in source signal "this was a complex flow construct" and trigger
     * different canonical output rules (e.g. emit `---` for VJP3/01). Optional;
     * absent on synthetic nodes.
     */
    sourceMultiline: Schema.optional<typeof Schema.Boolean>;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Error raised when YAML modification 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.
 *
 * @example Catching with `Effect.catchTag`
 * ```ts
 * import { Effect } from "effect";
 * import { modify } from "yaml-effect";
 *
 * const program = modify("{}", ["deep", "path"], 42).pipe(
 *   Effect.catchTag("YamlModificationError", (e) => {
 *     console.error(`Failed at [${e.path.join(", ")}]: ${e.reason}`);
 *     return Effect.succeed([]);
 *   }),
 * );
 * ```
 *
 * @public
 */
export declare class YamlModificationError extends YamlModificationErrorBase<{
    readonly path: ReadonlyArray<string | number>;
    readonly reason: string;
}> {
    get message(): string;
}

/**
 * Base class for {@link YamlModificationError}.
 *
 * @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 `YamlModificationError`
 * class extends it with concrete fields, giving api-extractor a simple class
 * declaration to work with.
 *
 * @internal
 */
export declare const YamlModificationErrorBase: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
    readonly _tag: "YamlModificationError";
} & Readonly<A>;

/**
 * A discriminated union schema covering all four YAML AST node types:
 * {@link YamlScalar}, {@link YamlMap}, {@link YamlSeq}, and {@link YamlAlias}.
 *
 * @remarks
 * The union is defined lazily via `Schema.suspend` to break the circular
 * reference chain: `YamlNode → YamlMap → YamlPair → YamlNode`.
 *
 * @public
 */
export declare const YamlNode: Schema.Schema<YamlScalar | YamlMap | YamlSeq | YamlAlias>;

/**
 * The union of all YAML AST node types.
 *
 * @public
 */
export declare type YamlNode = Schema.Schema.Type<typeof YamlNode>;

/**
 * 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 Catching with `Effect.catchTag`
 * ```ts
 * import { Effect } from "effect";
 * import { parseDocument, findNode } from "yaml-effect";
 *
 * const program = parseDocument("a: 1").pipe(
 *   Effect.flatMap((doc) => findNode(doc.contents!, ["missing"])),
 *   Effect.catchTag("YamlNodeNotFoundError", (e) => {
 *     console.error(`Not found: [${e.path.join(", ")}] in ${e.rootNodeType}`);
 *     return Effect.succeed(undefined);
 *   }),
 * );
 * ```
 *
 * @public
 */
export declare class YamlNodeNotFoundError extends YamlNodeNotFoundErrorBase<{
    readonly path: ReadonlyArray<string | number>;
    readonly rootNodeType: string;
}> {
    get message(): string;
}

/**
 * Base class for {@link YamlNodeNotFoundError}.
 *
 * @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 `YamlNodeNotFoundError`
 * class extends it with concrete fields, giving api-extractor a simple class
 * declaration to work with.
 *
 * @internal
 */
export declare const YamlNodeNotFoundErrorBase: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
    readonly _tag: "YamlNodeNotFoundError";
} & Readonly<A>;

/**
 * A YAML key-value pair AST node, representing one entry within a mapping.
 *
 * @remarks
 * - `key` — the {@link YamlNode} serving as the mapping key.
 * - `value` — the {@link YamlNode} serving as the mapping value, or `null`
 *   when the value is absent (e.g., `key:` with no value).
 * - `comment` — optional trailing or inline comment text.
 *
 * @example
 * ```typescript
 * import { YamlPair, YamlScalar } from "yaml-effect";
 *
 * const pair = new YamlPair({
 *   key: new YamlScalar({ value: "name", style: "plain", offset: 0, length: 4 }),
 *   value: new YamlScalar({ value: "Alice", style: "plain", offset: 6, length: 5 }),
 * });
 * ```
 *
 * @public
 */
export declare class YamlPair extends YamlPair_base {
}

declare const YamlPair_base: Schema.TaggedClass<YamlPair, "YamlPair", {
    readonly _tag: Schema.tag<"YamlPair">;
} & {
    key: Schema.suspend<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAlias | YamlMap | YamlScalar | YamlSeq, never>;
    value: Schema.NullOr<Schema.suspend<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAlias | YamlMap | YamlScalar | YamlSeq, never>>;
    comment: Schema.optional<typeof Schema.String>;
}>;

/**
 * Error raised when YAML parsing encounters one or more structural errors.
 *
 * @remarks
 * Contains the full source `text` and an `errors` array of
 * {@link YamlErrorDetail} instances with precise position information for
 * each problem found.
 *
 * @see {@link parseCST} — may fail with this error
 *
 * @example Catching with `Effect.catchTag`
 * ```ts
 * import { Effect } from "effect";
 * import { parse } from "yaml-effect";
 *
 * const program = parse("key:\n\tvalue: 1").pipe(
 *   Effect.catchTag("YamlParseError", (e) => {
 *     for (const detail of e.errors) {
 *       console.error(
 *         `[${detail.code}] ${detail.message} at ${detail.line}:${detail.column}`,
 *       );
 *     }
 *     return Effect.succeed(null);
 *   }),
 * );
 * ```
 *
 * @public
 */
export declare class YamlParseError extends YamlParseErrorBase<{
    readonly errors: ReadonlyArray<YamlErrorDetail>;
    readonly text: string;
}> {
    get message(): string;
}

/**
 * Base class for {@link YamlParseError}.
 *
 * @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 `YamlParseError` class
 * extends it with concrete fields, giving api-extractor a simple class
 * declaration to work with.
 *
 * @internal
 */
export declare const YamlParseErrorBase: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
    readonly _tag: "YamlParseError";
} & Readonly<A>;

/**
 * Options controlling YAML parse behavior.
 *
 * @remarks
 * - `strict` — when `true`, parse errors are treated as failures rather than
 *   being recovered. Defaults to `true`.
 * - `maxAliasCount` — maximum number of alias nodes allowed in a single
 *   document to prevent alias-based denial-of-service attacks. Must be a
 *   non-negative integer. Defaults to `100`.
 * - `uniqueKeys` — when `true`, duplicate keys within a mapping are treated
 *   as errors. Defaults to `true`.
 *
 * @public
 */
export declare class YamlParseOptions extends YamlParseOptions_base {
}

declare const YamlParseOptions_base: Schema.Class<YamlParseOptions, {
    strict: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
    maxAliasCount: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    uniqueKeys: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
}, Schema.Struct.Encoded<{
    strict: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
    maxAliasCount: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    uniqueKeys: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
}>, never, {
    readonly maxAliasCount?: number;
} & {
    readonly strict?: boolean;
} & {
    readonly uniqueKeys?: boolean;
}, {}, {}>;

/**
 * An ordered sequence of path segments describing a location within a YAML
 * document tree. Each segment is either a `string` (object key) or a
 * `number` (array index).
 *
 * @public
 */
export declare type YamlPath = ReadonlyArray<string | number>;

/**
 * A range within a YAML 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 `YamlRange` to formatting options to restrict
 * operations to a specific region of the document.
 *
 * @example
 * ```typescript
 * import { YamlRange } from "yaml-effect";
 *
 * // Represents characters 10 through 24 of a YAML document
 * const range = new YamlRange({ offset: 10, length: 15 });
 * console.log(range.offset); // 10
 * console.log(range.length); // 15
 * ```
 *
 * @public
 */
export declare class YamlRange extends YamlRange_base {
}

declare const YamlRange_base: Schema.Class<YamlRange, {
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
}, Schema.Struct.Encoded<{
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
}>, never, {
    readonly length: number;
} & {
    readonly offset: number;
}, {}, {}>;

/**
 * A YAML scalar AST node, representing a leaf value such as a string,
 * number, boolean, or null.
 *
 * @remarks
 * - `value` — the resolved JavaScript value (null, boolean, number, or string).
 * - `style` — the scalar presentation style in the source document.
 * - `tag` — optional explicit YAML tag (e.g., `!!str`, `!!int`).
 * - `anchor` — optional anchor name for aliasing.
 * - `comment` — optional trailing or leading comment text.
 * - `offset` — zero-based character offset where the scalar begins.
 * - `length` — character length of the scalar span.
 *
 * @example
 * ```typescript
 * import { YamlScalar } from "yaml-effect";
 *
 * const scalar = new YamlScalar({
 *   value: "hello",
 *   style: "plain",
 *   offset: 0,
 *   length: 5,
 * });
 * console.log(scalar.value); // "hello"
 * ```
 *
 * @public
 */
export declare class YamlScalar extends YamlScalar_base {
}

declare const YamlScalar_base: Schema.TaggedClass<YamlScalar, "YamlScalar", {
    readonly _tag: Schema.tag<"YamlScalar">;
} & {
    value: typeof Schema.Unknown;
    tag: Schema.optional<typeof Schema.String>;
    style: Schema.Literal<["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>;
    anchor: Schema.optional<typeof Schema.String>;
    comment: Schema.optional<typeof Schema.String>;
    chomp: Schema.optional<Schema.Literal<["strip", "clip", "keep"]>>;
    raw: Schema.optional<typeof Schema.String>;
    /**
     * `true` when the source span of this scalar covers two or more lines.
     * Used by the canonical stringifier to make decisions that depend on
     * source-shape (e.g. multi-line plain or DQ scalar root needing a `...`
     * terminator). Optional; absent on synthetic nodes produced by user code.
     */
    sourceMultiline: Schema.optional<typeof Schema.Boolean>;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
}>;

/**
 * A stateful YAML scanner that produces tokens one at a time.
 *
 * Provides a pull-based accessor API: call {@link YamlScanner.scan} to advance
 * to the next token, then use the `getToken*` methods to inspect the current
 * token without advancing again.
 *
 * @public
 */
export declare interface YamlScanner {
    /** Advance to the next token and return its kind, or `null` at end-of-input. */
    scan(): YamlTokenKind | null;
    /** Return the kind of the current token without advancing, or `null` before any scan. */
    getToken(): YamlTokenKind | null;
    /** Return the value string of the current token. */
    getTokenValue(): string;
    /** Return the zero-based character offset of the current token start. */
    getTokenOffset(): number;
    /** Return the character length of the current token span. */
    getTokenLength(): number;
    /** Return the zero-based line number of the current token start. */
    getTokenLine(): number;
    /** Return the zero-based column of the current token start. */
    getTokenColumn(): number;
    /** Return the current scanner position (next character to be scanned). */
    getPosition(): number;
    /**
     * Reset the scanner to the given character offset and rescan from there.
     *
     * @remarks
     * All block-structure state (indentation, flow depth, pending tokens) is
     * reset. For reliable results, pass an offset previously returned by
     * {@link getTokenOffset} rather than an arbitrary mid-token position.
     */
    setPosition(pos: number): void;
}

/**
 * Error raised when YAML schema validation fails.
 *
 * @remarks
 * Contains the `text` that failed validation and the underlying `cause`
 * of the validation failure.
 *
 * @see {@link makeYamlSchema} — produces schemas that may fail with this error
 *
 * @example Catching with `Effect.catchTag`
 * ```ts
 * import { Effect, Schema } from "effect";
 * import { makeYamlSchema } from "yaml-effect";
 *
 * const schema = makeYamlSchema(Schema.Struct({ name: Schema.String }));
 * const program = Schema.decode(schema)("not_a_mapping: true").pipe(
 *   Effect.catchTag("YamlSchemaError", (e) => {
 *     console.error("Schema validation failed for:", e.text);
 *     return Effect.succeed({ name: "default" });
 *   }),
 * );
 * ```
 *
 * @public
 */
export declare class YamlSchemaError extends YamlSchemaErrorBase<{
    readonly text: string;
    readonly cause: unknown;
}> {
    get message(): string;
}

/**
 * Base class for {@link YamlSchemaError}.
 *
 * @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 `YamlSchemaError` class
 * extends it with concrete fields, giving api-extractor a simple class
 * declaration to work with.
 *
 * @internal
 */
export declare const YamlSchemaErrorBase: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
    readonly _tag: "YamlSchemaError";
} & Readonly<A>;

/**
 * A YAML sequence AST node, representing an ordered list of values.
 *
 * @remarks
 * - `items` — the array of {@link YamlNode} values in this sequence.
 * - `style` — the presentation style: `"block"` or `"flow"`.
 * - `tag` — optional explicit YAML tag (e.g., `!!seq`).
 * - `anchor` — optional anchor name for aliasing.
 * - `comment` — optional leading or trailing comment text.
 * - `offset` — zero-based character offset where the sequence begins.
 * - `length` — character length of the sequence span.
 *
 * @example
 * ```typescript
 * import { YamlSeq, YamlScalar } from "yaml-effect";
 *
 * const seq = new YamlSeq({
 *   items: [
 *     new YamlScalar({ value: "one", style: "plain", offset: 4, length: 3 }),
 *     new YamlScalar({ value: "two", style: "plain", offset: 10, length: 3 }),
 *   ],
 *   style: "block",
 *   offset: 0,
 *   length: 13,
 * });
 * ```
 *
 * @public
 */
export declare class YamlSeq extends YamlSeq_base {
}

declare const YamlSeq_base: Schema.TaggedClass<YamlSeq, "YamlSeq", {
    readonly _tag: Schema.tag<"YamlSeq">;
} & {
    items: Schema.Array$<Schema.suspend<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAlias | YamlMap | YamlScalar | YamlSeq, never>>;
    tag: Schema.optional<typeof Schema.String>;
    anchor: Schema.optional<typeof Schema.String>;
    style: Schema.Literal<["block", "flow"]>;
    comment: Schema.optional<typeof Schema.String>;
    /**
     * `true` when the source span of this sequence covers two or more lines.
     * Mirrors the same field on {@link YamlMap}; used by canonical-stringifier
     * decisions that need to differentiate single-line flow source from
     * multi-line flow source. Optional; absent on synthetic nodes.
     */
    sourceMultiline: Schema.optional<typeof Schema.Boolean>;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
}>;

/**
 * Error raised when YAML stringification fails.
 *
 * @remarks
 * Contains the `value` that could not be stringified and a `reason` string
 * explaining the failure.
 *
 * @see {@link stringify} — may fail with this error
 * @see {@link stringifyDocument} — may fail with this error
 *
 * @example Catching with `Effect.catchTag`
 * ```ts
 * import { Effect } from "effect";
 * import { stringify } from "yaml-effect";
 *
 * const program = stringify(circularValue).pipe(
 *   Effect.catchTag("YamlStringifyError", (e) => {
 *     console.error(`Stringify failed: ${e.reason}`);
 *     return Effect.succeed("");
 *   }),
 * );
 * ```
 *
 * @public
 */
export declare class YamlStringifyError extends YamlStringifyErrorBase<{
    readonly value: unknown;
    readonly reason: string;
}> {
    get message(): string;
}

/**
 * Base class for {@link YamlStringifyError}.
 *
 * @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 `YamlStringifyError` class
 * extends it with concrete fields, giving api-extractor a simple class
 * declaration to work with.
 *
 * @internal
 */
export declare const YamlStringifyErrorBase: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
    readonly _tag: "YamlStringifyError";
} & Readonly<A>;

/**
 * Options controlling YAML stringify behavior.
 *
 * @remarks
 * - `indent` — number of spaces per indentation level. Must be a non-negative
 *   integer. Defaults to `2`.
 * - `lineWidth` — preferred maximum line width for wrapping scalars and
 *   collections. Defaults to `80`.
 * - `defaultScalarStyle` — the scalar output style to use when no explicit
 *   style is requested. Defaults to `"plain"`.
 * - `defaultCollectionStyle` — the collection output style to use when no
 *   explicit style is requested. Defaults to `"block"`.
 * - `sortKeys` — when `true`, mapping keys are sorted alphabetically.
 *   Defaults to `false`.
 * - `finalNewline` — when `true`, the output ends with a trailing newline.
 *   Defaults to `true`.
 *
 * @public
 */
export declare class YamlStringifyOptions extends YamlStringifyOptions_base {
}

declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, {
    indent: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    lineWidth: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    defaultScalarStyle: Schema.optionalWith<Schema.Literal<["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>, {
        default: () => "plain";
    }>;
    defaultCollectionStyle: Schema.optionalWith<Schema.Literal<["block", "flow"]>, {
        default: () => "block";
    }>;
    sortKeys: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
    finalNewline: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
    forceDefaultStyles: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
}, Schema.Struct.Encoded<{
    indent: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    lineWidth: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
        default: () => number;
    }>;
    defaultScalarStyle: Schema.optionalWith<Schema.Literal<["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>, {
        default: () => "plain";
    }>;
    defaultCollectionStyle: Schema.optionalWith<Schema.Literal<["block", "flow"]>, {
        default: () => "block";
    }>;
    sortKeys: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
    finalNewline: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => true;
    }>;
    forceDefaultStyles: Schema.optionalWith<typeof Schema.Boolean, {
        default: () => false;
    }>;
}>, never, {
    readonly defaultCollectionStyle?: "block" | "flow";
} & {
    readonly defaultScalarStyle?: "block-folded" | "block-literal" | "double-quoted" | "plain" | "single-quoted";
} & {
    readonly finalNewline?: boolean;
} & {
    readonly forceDefaultStyles?: boolean;
} & {
    readonly indent?: number;
} & {
    readonly lineWidth?: number;
} & {
    readonly sortKeys?: boolean;
}, {}, {}>;

/**
 * A single YAML token produced by the lexer, carrying its kind, raw text
 * value, and exact source position.
 *
 * @remarks
 * - `kind` — a {@link YamlTokenKind} identifying the token type.
 * - `value` — the raw text slice from the source document.
 * - `offset` — zero-based character offset where the token begins.
 * - `length` — character length of the token span.
 * - `line` — zero-based line number of the token start.
 * - `column` — zero-based column within the line of the token start.
 *
 * @public
 */
export declare class YamlToken extends YamlToken_base {
}

declare const YamlToken_base: Schema.Class<YamlToken, {
    kind: Schema.Literal<["document-start", "document-end", "directive", "tag", "anchor", "alias", "scalar", "block-map-start", "block-map-key", "block-map-value", "block-seq-start", "block-seq-entry", "flow-map-start", "flow-map-end", "flow-seq-start", "flow-seq-end", "flow-separator", "newline", "whitespace", "comment", "byte-order-mark", "error"]>;
    value: typeof Schema.String;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
    line: Schema.filter<typeof Schema.Int>;
    column: Schema.filter<typeof Schema.Int>;
}, Schema.Struct.Encoded<{
    kind: Schema.Literal<["document-start", "document-end", "directive", "tag", "anchor", "alias", "scalar", "block-map-start", "block-map-key", "block-map-value", "block-seq-start", "block-seq-entry", "flow-map-start", "flow-map-end", "flow-seq-start", "flow-seq-end", "flow-separator", "newline", "whitespace", "comment", "byte-order-mark", "error"]>;
    value: typeof Schema.String;
    offset: Schema.filter<typeof Schema.Int>;
    length: Schema.filter<typeof Schema.Int>;
    line: Schema.filter<typeof Schema.Int>;
    column: Schema.filter<typeof Schema.Int>;
}>, never, {
    readonly column: number;
} & {
    readonly kind: "alias" | "anchor" | "block-map-key" | "block-map-start" | "block-map-value" | "block-seq-entry" | "block-seq-start" | "byte-order-mark" | "comment" | "directive" | "document-end" | "document-start" | "error" | "flow-map-end" | "flow-map-start" | "flow-separator" | "flow-seq-end" | "flow-seq-start" | "newline" | "scalar" | "tag" | "whitespace";
} & {
    readonly length: number;
} & {
    readonly line: number;
} & {
    readonly offset: number;
} & {
    readonly value: string;
}, {}, {}>;

/**
 * The 22 token kinds produced by the YAML lexer.
 *
 * @public
 */
export declare const YamlTokenKind: Schema.Literal<["document-start", "document-end", "directive", "tag", "anchor", "alias", "scalar", "block-map-start", "block-map-key", "block-map-value", "block-seq-start", "block-seq-entry", "flow-map-start", "flow-map-end", "flow-seq-start", "flow-seq-end", "flow-separator", "newline", "whitespace", "comment", "byte-order-mark", "error"]>;

/**
 * The union of all YAML token kind string literals.
 *
 * @public
 */
export declare type YamlTokenKind = Schema.Schema.Type<typeof YamlTokenKind>;

/**
 * A discriminated union of all eleven SAX-style YAML visitor events.
 *
 * @remarks
 * Use the individual type-guard helpers (`isScalarEvent`, `isMapStartEvent`,
 * etc.) to narrow an event to a specific variant.
 *
 * @public
 */
export declare const YamlVisitorEvent: Schema.Union<[typeof DocumentStartEvent, typeof DocumentEndEvent, typeof MapStartEvent, typeof MapEndEvent, typeof SeqStartEvent, typeof SeqEndEvent, typeof PairEvent, typeof ScalarEvent, typeof AliasEvent, typeof CommentEvent, typeof DirectiveEvent]>;

/**
 * The union of all YAML visitor event types.
 *
 * @see {@link YamlVisitorEvent}
 *
 * @public
 */
export declare type YamlVisitorEvent = Schema.Schema.Type<typeof YamlVisitorEvent>;

export { }