/**
 * Compose, merge, join, and paginate index queries as Effect streams.
 *
 * A query stream is an Effect `Stream` of decoded documents with stored keys, a
 * shared key layout, and a direction. Create one with
 * `reader.table(...).stream(index, range?, order?)` for a standard index. The
 * order defaults to `"asc"`; search indexes use `reader.table(...).search(...)`
 * instead. Unlike `reader.table(...).index(...).stream()`, this returns a
 * composable query stream rather than a plain `Stream` over one query.
 *
 * Creating or composing a stream does not read documents. Reads begin when you
 * run a consuming effect, such as `Stream.runCollect` or `paginate`, and each
 * run executes the queries again. Keep callbacks deterministic and read-only:
 * pagination, seeks, and reversal can reevaluate them.
 *
 * Key values are stored separately from emitted values. Pinning an index field
 * with `eq` removes it from the key; range bounds keep it. Keys retain creation
 * time and document-ID tiebreakers where applicable. `QueryStream` combinators
 * preserve the ordering information needed to merge and paginate; plain
 * `Stream` transforms return ordinary streams without that information. A key
 * layout describes the key positions, their visible labels, and implicit ID
 * positions. Reuse a stream's `keyLayout` with `empty` or `flatMap`.
 *
 * Return the whole `paginate` result from a paginated query handler. In React,
 * use `useStreamPaginatedQuery`, not `usePaginatedQuery`: stream pages aren't
 * tracked by Convex's query journal, so the stream hook pins and splits page
 * ranges to keep loaded pages gap-free. Foldkit's `PaginatedQuery` also
 * supports stream pagination.
 *
 * Stream querying is experimental. Its API may still change.
 */
import type { PaginationOptions as ConvexPaginationOptions, PaginationResult as ConvexPaginationResult } from "convex/server";
import { type Pipeable } from "effect/Pipeable";
import * as Array from "effect/Array";
import type * as Channel from "effect/Channel";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import type * as Types from "effect/Types";
import * as Document from "./Document";
import type * as Table from "./Table";
import * as QueryStreamKeyLabels from "./QueryStreamKeyLabels";
import * as QueryStreamKeyLayout from "./QueryStreamKeyLayout";
import * as QueryStreamOrderDirection from "./QueryStreamOrderDirection";
import * as QueryStreamKeyValues from "./QueryStreamKeyValues";
import * as QueryStreamKeyBounds from "./QueryStreamKeyBounds";
import * as QueryStreamIndexRange from "./QueryStreamIndexRange";
import * as QueryStreamReadBudget from "./QueryStreamReadBudget";
declare const ReadBudgetExceededError_base: Schema.Class<ReadBudgetExceededError, Schema.TaggedStruct<"ReadBudgetExceededError", {
    readonly rowsRead: Schema.Natural;
    readonly bytesRead: Schema.Natural;
}>, import("effect/Cause").YieldableError>;
/**
 * A page exhausted its read budget without a safe logical continuation.
 *
 * @experimental
 */
export declare class ReadBudgetExceededError extends ReadBudgetExceededError_base {
    get message(): string;
}
declare const IncompatibleStreamsError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
    readonly _tag: "IncompatibleStreamsError";
} & Readonly<A>;
/**
 * Thrown by `merge` when inputs have different directions, visible ordering
 * labels, or implicit-ID positions. The payload identifies the expected and
 * actual direction and layout; map and relabel compatible inputs before
 * merging.
 *
 * @experimental
 */
export declare class IncompatibleStreamsError extends IncompatibleStreamsError_base<{
    readonly expectedOrderDirection: QueryStreamOrderDirection.QueryStreamOrderDirection;
    readonly actualOrderDirection: QueryStreamOrderDirection.QueryStreamOrderDirection;
    readonly expectedKeyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout;
    readonly actualKeyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout;
}> {
    get message(): string;
}
declare const InnerStreamOrderMismatchError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
    readonly _tag: "InnerStreamOrderMismatchError";
} & Readonly<A>;
/**
 * A `flatMap` inner stream runs in a different direction from its outer stream.
 * The join dies with this error when it runs; `expectedOrderDirection` is the
 * outer direction and `actualOrderDirection` is the inner direction.
 *
 * @experimental
 */
export declare class InnerStreamOrderMismatchError extends InnerStreamOrderMismatchError_base<{
    readonly expectedOrderDirection: QueryStreamOrderDirection.QueryStreamOrderDirection;
    readonly actualOrderDirection: QueryStreamOrderDirection.QueryStreamOrderDirection;
}> {
    get message(): string;
}
declare const InnerStreamLayoutMismatchError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
    readonly _tag: "InnerStreamLayoutMismatchError";
} & Readonly<A>;
/**
 * A `flatMap` inner stream does not match the supplied `innerKeyLayout`,
 * including visible labels and implicit-ID positions. The join dies with this
 * error when it runs; the payload contains the expected and actual layouts.
 *
 * @experimental
 */
export declare class InnerStreamLayoutMismatchError extends InnerStreamLayoutMismatchError_base<{
    readonly expectedKeyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout;
    readonly actualKeyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout;
}> {
    get message(): string;
}
declare const MissingReversalRecipeError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
    readonly _tag: "MissingReversalRecipeError";
} & Readonly<A>;
/**
 * Thrown by `reverse` when a manually constructed stream has no `reverseWith`
 * recipe. Streams created through the table reader and `QueryStream`
 * combinators support reversal.
 *
 * @experimental
 */
export declare class MissingReversalRecipeError extends MissingReversalRecipeError_base {
    get message(): string;
}
/**
 * `paginate` dies with this error for `numItems: 0` and `cursor: null`, because
 * an empty initial page cannot establish a continuation boundary. Request a
 * positive number of items for the first page.
 *
 * @experimental
 */
export { EmptyInitialPageError, InvalidPageSizeError, } from "./QueryStreamPagination";
/**
 * Invalid numeric read limits.
 *
 * @experimental
 */
export { InvalidReadLimitError } from "./QueryStreamReadBudget";
/**
 * Runtime identifier used to distinguish query streams from plain streams.
 *
 * @experimental
 */
export declare const TypeId = "~@confect/server/QueryStream";
/**
 * Type of the query stream's runtime identifier.
 *
 * @experimental
 */
export type TypeId = typeof TypeId;
/**
 * A decoded value and its stored key. `doc: None` marks an element that was
 * read but filtered out: it emits no value, but still advances cursors. Mapping
 * a value does not recompute its key.
 *
 * @experimental
 */
export declare class Element<Doc> extends Data.Class<{
    readonly doc: Option.Option<Doc>;
    readonly keyValues: QueryStreamKeyValues.QueryStreamKeyValues;
}> {
}
/**
 * An Effect `Stream` whose stored keys determine its order and pagination
 * boundaries independently of its emitted values.
 *
 * TypeScript normally infers all five parameters from the table's `stream`
 * method and subsequent composition:
 *
 * - `Doc` is the emitted value: a decoded document or a mapped or joined result.
 * - `KeyLabels` is the branded readonly tuple of visible ordering names,
 *   initially the index fields not pinned by `eq`. `flatMap` appends labels and
 *   `renameKey` replaces them. Implicit ID tiebreakers are omitted from labels
 *   but retained in `keyLayout`.
 * - `OrderDirection` is `"asc"` or `"desc"`; the type defaults to their union.
 * - `E` contains typed failures while reading or transforming values. `never`
 *   means no typed failures, not no defects.
 * - `R` contains Effect services required to run the stream. The stream retains
 *   the database access supplied at creation, so it doesn't require providing
 *   `DatabaseReader` again; effectful callbacks can add requirements.
 *
 * Known label or direction mismatches prevent merging at compile time. Runtime
 * checks also compare implicit-ID positions. Reuse a compatible stream's
 * `keyLayout` for `empty` or `flatMap`'s `innerKeyLayout`.
 *
 * Consume with Effect's `Stream.runCollect` or `Stream.runHead`, or use
 * `unique` or `paginate`. A plain `Stream` transform such as `Stream.take`
 * returns an ordinary stream that can be consumed but no longer merged or
 * paginated with this module.
 *
 * @experimental
 */
export declare class QueryStream<out Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels = QueryStreamKeyLabels.QueryStreamKeyLabels, out OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection = QueryStreamOrderDirection.QueryStreamOrderDirection, out E = never, out R = never> implements Stream.Stream<Doc, E, R> {
    readonly orderDirection: OrderDirection;
    /**
     * Shared description of the key positions, including visible labels and
     * implicit IDs. Reuse with `empty` or `flatMap`'s `innerKeyLayout`. Reading
     * this property does not read documents. Direction is in `orderDirection`.
     */
    readonly keyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout<KeyLabels>;
    /**
     * Values paired with stored keys, including filtered markers that advance
     * cursors without emitting a value.
     */
    readonly annotated: Stream.Stream<Element<Doc>, E, R | QueryStreamReadBudget.QueryStreamReadBudget>;
    /**
     * Query recipe retained by direct index streams and rebuilt on each run.
     * Includes the effective index bounds. Composed streams instead delegate
     * range changes to their inputs through `narrowWith`.
     */
    readonly reflection?: Reflection | undefined;
    /**
     * Rebuilds the stream with validated key bounds, pushing them into index
     * ranges where that preserves the composition's results. Without this
     * recipe, `narrow` filters the annotated stream in memory. The constructor
     * guards recipe calls against bounds from incompatible layouts.
     */
    readonly narrowWith?: ((parsedBounds: QueryStreamKeyBounds.ParsedBounds) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>) | undefined;
    /**
     * Rebuilds the stream in the opposite direction using index scans and
     * seeks. Distinct streams keep their original representatives. Without this
     * recipe, `reverse` throws `MissingReversalRecipeError`.
     */
    readonly reverseWith?: (() => QueryStream<Doc, KeyLabels, QueryStreamOrderDirection.Flip<OrderDirection>, E, R>) | undefined;
    readonly [TypeId]: TypeId;
    readonly "~labels": Types.Invariant<KeyLabels>;
    readonly "~direction": Types.Covariant<OrderDirection>;
    readonly [Stream.TypeId]: Stream.VarianceStruct<Doc, E, R>;
    readonly pipe: Pipeable["pipe"];
    readonly channel: Channel.Channel<Array.NonEmptyReadonlyArray<Doc>, E, void, unknown, unknown, unknown, R>;
    constructor(orderDirection: OrderDirection, 
    /**
     * Shared description of the key positions, including visible labels and
     * implicit IDs. Reuse with `empty` or `flatMap`'s `innerKeyLayout`. Reading
     * this property does not read documents. Direction is in `orderDirection`.
     */
    keyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout<KeyLabels>, 
    /**
     * Values paired with stored keys, including filtered markers that advance
     * cursors without emitting a value.
     */
    annotated: Stream.Stream<Element<Doc>, E, R | QueryStreamReadBudget.QueryStreamReadBudget>, 
    /**
     * Query recipe retained by direct index streams and rebuilt on each run.
     * Includes the effective index bounds. Composed streams instead delegate
     * range changes to their inputs through `narrowWith`.
     */
    reflection?: Reflection | undefined, 
    /**
     * Rebuilds the stream with validated key bounds, pushing them into index
     * ranges where that preserves the composition's results. Without this
     * recipe, `narrow` filters the annotated stream in memory. The constructor
     * guards recipe calls against bounds from incompatible layouts.
     */
    narrowWith?: ((parsedBounds: QueryStreamKeyBounds.ParsedBounds) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>) | undefined, 
    /**
     * Rebuilds the stream in the opposite direction using index scans and
     * seeks. Distinct streams keep their original representatives. Without this
     * recipe, `reverse` throws `MissingReversalRecipeError`.
     */
    reverseWith?: (() => QueryStream<Doc, KeyLabels, QueryStreamOrderDirection.Flip<OrderDirection>, E, R>) | undefined);
    toStream(): Stream.Stream<Doc, E, R>;
}
/**
 * A query stream with any value, ordering, error, and requirement types.
 *
 * @experimental
 */
export type Any = QueryStream<any, any, any, any, any>;
/**
 * Check whether a value retains query-stream ordering and pagination support.
 * Plain `Stream` transforms return ordinary streams, for which this is false.
 *
 * @experimental
 */
export declare const isQueryStream: (u: unknown) => u is Any;
/**
 * Create a stream with no documents but a known key layout and direction. Use
 * it when a dynamic list of streams is empty, since `merge` requires at least
 * one input. The direction defaults to `"asc"`.
 *
 * Supply the document type in the first call, then reuse a compatible stream's
 * layout: `QueryStream.empty<NotesDoc>()(source.keyLayout, "desc")`. Creating
 * the source solely to obtain its layout does not read documents.
 *
 * @experimental
 */
export declare const empty: <Doc>() => {
    <const KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels>(keyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout<KeyLabels>): QueryStream<Doc, KeyLabels, "asc", never, never>;
    <const KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(keyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout<KeyLabels>, orderDirection: OrderDirection): QueryStream<Doc, KeyLabels, OrderDirection, never, never>;
};
/**
 * Database access needed to rebuild a direct index query on each run. Normally
 * supplied by `reader.table(...).stream(...)` rather than implemented
 * manually.
 *
 * @experimental
 */
export interface ReflectionReader {
    query(tableName: string): {
        withIndex(indexName: string, indexRange?: (q: any) => any): {
            order(orderDirection: QueryStreamOrderDirection.QueryStreamOrderDirection): AsyncIterable<unknown>;
        };
    };
}
/**
 * A reusable index-query description: database access, table schema, index,
 * range, and direction. Direct index streams retain this description instead of
 * a one-shot Convex query so each run can execute the query again. Narrowing
 * and pagination use it to rebuild queries with tighter index bounds.
 *
 * @experimental
 */
export interface Reflection<OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection = QueryStreamOrderDirection.QueryStreamOrderDirection> {
    readonly reader: ReflectionReader;
    readonly table: Table.AnyWithProps;
    readonly indexName: string;
    /**
     * Index fields in declared order, including `_creationTime` where applicable.
     * The `by_id` index uses only `["_id"]`.
     */
    readonly indexFieldPaths: ReadonlyArray<string>;
    /**
     * Index constraints. Equality constraints pin leading fields, removing them
     * from the stream's key; range bounds do not.
     */
    readonly indexRange: QueryStreamIndexRange.QueryStreamIndexRange;
    readonly orderDirection: OrderDirection;
    /**
     * Effective bounds in full index-key values, including pinned fields and ID
     * tiebreakers. If absent, bounds come from `indexRange`; supplied bounds
     * intersect those constraints rather than replacing them.
     */
    readonly indexBounds?: QueryStreamKeyBounds.IndexBounds;
}
/**
 * Create a reusable query stream from an index-query description. Prefer
 * `reader.table(...).stream(...)` for inferred document and ordering types.
 *
 * Construction does not read documents. Each consuming run rebuilds the index
 * queries within the supplied range and decodes their documents, failing with
 * `DocumentDecodeError` if decoding fails. Key values come from encoded index
 * values before decoding, with equality-pinned fields removed.
 *
 * @experimental
 */
export declare const fromReflection: <Doc, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection = QueryStreamOrderDirection.QueryStreamOrderDirection>(reflection: Reflection<OrderDirection>) => QueryStream<Doc, QueryStreamKeyLabels.QueryStreamKeyLabels, OrderDirection, Document.DocumentDecodeError, never>;
/**
 * Combine streams sharing a key layout into one stream in key order. Use this
 * to query several index ranges at once, such as notes by multiple roles.
 *
 * The merge emits the smallest next key when ascending and the largest when
 * descending. Unlike `Stream.merge`, it does not interleave by arrival time.
 * Overlapping inputs are not deduplicated: a document matched twice appears
 * twice. Supply at least one input; use `empty` for an empty dynamic list.
 *
 * Inputs need compatible document types and identical key layouts and
 * directions. TypeScript rejects known mismatches; runtime mismatches throw
 * `IncompatibleStreamsError` when combined. Map to a common value shape and use
 * `renameKey` when compatible indexes have different field names.
 *
 * @experimental
 */
export declare const merge: <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(streams: readonly [QueryStream<Doc, KeyLabels, OrderDirection, E, R>, ...ReadonlyArray<QueryStream<Doc, KeyLabels, NoInfer<OrderDirection>, E, R>>]) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>;
/**
 * Control concurrent callback evaluation in `filterEffect` and `mapEffect`.
 *
 * @experimental
 */
export interface EffectOptions {
    /**
     * Maximum number of document effects running at once, or `"unbounded"`.
     * Defaults to one at a time. Results retain stream order regardless of
     * completion order; callbacks must remain deterministic and read-only.
     */
    readonly concurrency?: number | "unbounded" | undefined;
}
/**
 * Keep values that satisfy a pure predicate without changing their stored keys.
 * Like `Stream.filter`, this removes emitted values, but it retains the
 * ordering information needed to merge and paginate the result.
 *
 * Rejected documents still count as reads and advance cursors. Filtering before
 * `distinct` selects each group's first matching document; filtering after it
 * tests only the chosen representative. Use `filterEffect` for predicates that
 * read another table, use a service, or fail with a typed error.
 *
 * @experimental
 */
export declare const filter: (<Doc>(predicate: (doc: Doc) => boolean) => <KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>) & (<Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>, predicate: (doc: Doc) => boolean) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>);
/**
 * Keep values that satisfy an effectful predicate, preserving stored keys and
 * cursor progress just like `filter`. The predicate can read other tables or
 * use services; its errors and requirements become part of the stream's types.
 *
 * Effects run one document at a time by default. Pass `{ concurrency }` to run
 * several at once while retaining stream order. Keep the predicate
 * deterministic and read-only, since seeks and pagination can run it again.
 * Separate lookups inside the predicate are not counted by pagination's read
 * budgets.
 *
 * @experimental
 */
export declare const filterEffect: (<Doc, E2, R2>(predicate: (doc: Doc) => Effect.Effect<boolean, E2, R2>, options?: EffectOptions) => <KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc, KeyLabels, OrderDirection, E | E2, R | R2>) & (<Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, E2, R2, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>, predicate: (doc: Doc) => Effect.Effect<boolean, E2, R2>, options?: EffectOptions) => QueryStream<Doc, KeyLabels, OrderDirection, E | E2, R | R2>);
/**
 * Transform emitted values with a pure function while keeping their stored key
 * values. The result retains merge and pagination support, unlike the plain
 * stream returned by `Stream.map`.
 *
 * The mapper may replace any fields, including indexed fields, or return a
 * different shape entirely. It does not recompute keys or sort by the new
 * values: mapping note text to its length still orders by the original text,
 * creation time, and ID, not by length. Preserve the input value rather than
 * mutating it. Use `mapEffect` when the mapper needs an effect.
 *
 * @experimental
 */
export declare const map: (<Doc, Doc2>(f: (doc: Doc) => Doc2) => <KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc2, KeyLabels, OrderDirection, E, R>) & (<Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, Doc2, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>, f: (doc: Doc) => Doc2) => QueryStream<Doc2, KeyLabels, OrderDirection, E, R>);
/**
 * Transform emitted values with an effect, preserving the original stored keys
 * just like `map`. The mapper may read another table or use services; its
 * errors and requirements become part of the stream's types.
 *
 * Effects run one document at a time by default. Pass `{ concurrency }` for
 * concurrent reads without changing output order. Keep the mapper deterministic
 * and read-only: seeks, reversal, and pagination can reevaluate it. Separate
 * lookups inside the mapper are not counted by pagination's read budgets.
 *
 * @experimental
 */
export declare const mapEffect: (<Doc, Doc2, E2, R2>(f: (doc: Doc) => Effect.Effect<Doc2, E2, R2>, options?: EffectOptions) => <KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc2, KeyLabels, OrderDirection, E | E2, R | R2>) & (<Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, Doc2, E2, R2, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>, f: (doc: Doc) => Effect.Effect<Doc2, E2, R2>, options?: EffectOptions) => QueryStream<Doc2, KeyLabels, OrderDirection, E | E2, R | R2>);
/**
 * Run an inner query stream for each outer document and concatenate the
 * results. Like sequential `Stream.flatMap`, each inner stream finishes before
 * the next begins. The joined key is the outer key followed by the inner key,
 * retaining both document IDs so equal timestamps remain distinguishable.
 *
 * Supply `options.innerKeyLayout` from a compatible stream's `keyLayout`. For
 * example, comments indexed by `noteId` and pinned to a note have the same
 * layout as comments ordered by creation time: one visible creation-time
 * position followed by an implicit ID. Creating the template reads no
 * documents. For nested joins or renamed streams, apply the same composition or
 * renaming to the template before reusing its layout.
 *
 * The layout is required when constructing the joined stream, before any outer
 * document is available to pass to `f`, including when the outer stream is
 * empty. It determines the joined key positions and the width of empty-inner
 * markers. It contains no query results or direction.
 *
 * Every inner stream must match that layout and the outer direction. TypeScript
 * rejects known mismatches; others die with `InnerStreamOrderMismatchError` or
 * `InnerStreamLayoutMismatchError` when the join runs.
 *
 * An empty inner stream emits no value by default, but leaves a filtered marker
 * that advances cursors past its outer document. Pass `options.onEmpty` to emit
 * `onEmpty(outer)` instead. The element type widens to include the placeholder,
 * so map inner values to a common shape when needed. Its key is the outer key
 * followed by null inner components, and pagination steps past it like any
 * element. Outer documents filtered out before the join remain absent.
 *
 * Keep `f` and `onEmpty` deterministic and read-only. Pagination, narrowing,
 * and reversal can reevaluate them; both outer and inner index reads count
 * toward pagination's budgets.
 *
 * @experimental
 */
export declare const flatMap: (<Doc, Doc2, InnerKeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E2, R2, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection, Doc3 = never>(f: (doc: Doc) => QueryStream<Doc2, InnerKeyLabels, OrderDirection, E2, R2>, options: {
    readonly innerKeyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout<NoInfer<InnerKeyLabels>>;
    readonly onEmpty?: ((doc: Doc) => Doc3) | undefined;
}) => <KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc2 | Doc3, QueryStreamKeyLabels.Concat<KeyLabels, InnerKeyLabels>, OrderDirection, E | E2, R | R2>) & (<Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, Doc2, InnerKeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E2, R2, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection, Doc3 = never>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>, f: (doc: Doc) => QueryStream<Doc2, InnerKeyLabels, NoInfer<OrderDirection>, E2, R2>, options: {
    readonly innerKeyLayout: QueryStreamKeyLayout.QueryStreamKeyLayout<NoInfer<InnerKeyLabels>>;
    readonly onEmpty?: ((doc: Doc) => Doc3) | undefined;
}) => QueryStream<Doc2 | Doc3, QueryStreamKeyLabels.Concat<KeyLabels, InnerKeyLabels>, OrderDirection, E | E2, R | R2>);
/**
 * Keep the first document for each distinct value of a key prefix. Similar to
 * `Stream.changes` on that prefix, this groups consecutive equal keys, but
 * seeks past the rest of each group instead of scanning it.
 *
 * Pass a prefix of the visible ordering labels, such as `["text"]` for notes
 * ordered by text and creation time. Prefix validity is checked by TypeScript
 * and at runtime. On a `flatMap` result, a prefix reaching into the inner key
 * also groups by the outer document, including its ID.
 *
 * Operation order controls representative selection. Filter before `distinct`
 * to choose the first matching document, or after it to test only the selected
 * representative. `reverse(distinct(q))` keeps those representatives and flips
 * their output order; `distinct(reverse(q))` selects from the other direction.
 *
 * Narrowing after `distinct` filters the original representatives without
 * selecting replacements. Narrowing before it constrains the input and can
 * change the representatives. Preserving representatives may require extra
 * reads outside output bounds and repeated callback evaluation.
 *
 * @experimental
 */
export declare const distinct: (<const PrefixNames extends ReadonlyArray<string>>(prefixNames: PrefixNames) => <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels<readonly [...PrefixNames, ...ReadonlyArray<string>]>, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>) & (<const PrefixNames extends ReadonlyArray<string>, Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels<readonly [...PrefixNames, ...ReadonlyArray<string>]>, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>, prefixNames: PrefixNames) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>);
/**
 * Relabel visible key positions without changing values or their order. This
 * does not sort or transform emitted documents.
 *
 * Use it to merge indexes or tables ordered by comparable values under
 * different field names. For example, relabel comments ordered by `["body",
 * "_creationTime"]` as `["text", "_creationTime"]` to merge with notes ordered
 * by text. Map both streams to a common value shape first.
 *
 * Supply exactly as many replacement labels as the original visible labels. The
 * values at corresponding positions must be comparable; relabeling does not
 * establish that semantic compatibility for you. Implicit ID tiebreakers keep
 * their positions. For joined streams, replacement labels cover the combined
 * key, outer labels first.
 *
 * @experimental
 */
export declare const renameKey: (<const ReplacementNames extends ReadonlyArray<string>>(replacementNames: ReplacementNames) => <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels & {
    readonly length: ReplacementNames["length"];
}, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc, QueryStreamKeyLabels.QueryStreamKeyLabels<ReplacementNames>, OrderDirection, E, R>) & (<const ReplacementNames extends ReadonlyArray<string>, Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels & {
    readonly length: ReplacementNames["length"];
}, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>, replacementNames: ReplacementNames) => QueryStream<Doc, QueryStreamKeyLabels.QueryStreamKeyLabels<ReplacementNames>, OrderDirection, E, R>);
/**
 * Run a composed query stream in the opposite direction without changing its
 * key layout. Use this for bidirectional pagination: a reversed feed can load
 * its earlier pages.
 *
 * Reversal uses index scans and seeks rather than collecting and reversing
 * values. Merges, filters, maps, flat-maps (including their inner streams),
 * distinct streams, renamed streams, and empty streams all support it.
 *
 * `reverse(distinct(q))` retains each group's original first representative and
 * reverses their output order. `distinct(reverse(q))` instead chooses the first
 * document from the other direction. Preserving representatives can require
 * extra reads to discover groups and seek their original first documents.
 *
 * A manually constructed stream without `reverseWith` throws
 * `MissingReversalRecipeError`.
 *
 * @experimental
 */
export declare const reverse: <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc, KeyLabels, QueryStreamOrderDirection.Flip<OrderDirection>, E, R>;
/**
 * Restrict a stream to keys between `start` and `end`. Provide at least one
 * endpoint, each with `keyValues` and a required `inclusive` flag; omit the
 * other endpoint to leave that side unbounded.
 *
 * Endpoints follow stream order: `start` is the lower key when ascending and
 * the upper key when descending. Repeated narrowing intersects existing bounds
 * and can only restrict the range further.
 *
 * A key may be a prefix of the full key. An inclusive prefix includes every key
 * extending it; an exclusive prefix excludes the whole group. For example,
 * creation-time bounds can use `[startTime]` and `[endTime]` without trailing
 * IDs. Equal endpoints produce an empty range unless both are inclusive, in
 * which case they select that key or prefix group.
 *
 * Bounds are pushed into index ranges where that preserves the composition's
 * results. On a distinct stream, full-key bounds filter original
 * representatives without choosing replacements; prefix bounds include or
 * exclude whole groups. This can require reads outside the output bounds. Apply
 * bounds before `distinct` instead to constrain which documents can represent a
 * group. Manually constructed streams without `narrowWith` are filtered in
 * memory.
 *
 * For pagination, pass the previous `continueCursor` unchanged to `paginate`;
 * do not decode a cursor into explicit bounds.
 *
 * @experimental
 */
export declare const narrow: ((narrowBounds: QueryStreamKeyBounds.NarrowBounds) => <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>) & (<Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R, OrderDirection extends QueryStreamOrderDirection.QueryStreamOrderDirection>(self: QueryStream<Doc, KeyLabels, OrderDirection, E, R>, narrowBounds: QueryStreamKeyBounds.NarrowBounds) => QueryStream<Doc, KeyLabels, OrderDirection, E, R>);
declare const NotUniqueError_base: Schema.Class<NotUniqueError, Schema.TaggedStruct<"NotUniqueError", {}>, import("effect/Cause").YieldableError>;
/**
 * `unique` found at least two emitted values. Narrow the query if at most one
 * value was expected, or use another consumer to handle multiple results.
 *
 * @experimental
 */
export declare class NotUniqueError extends NotUniqueError_base {
    get message(): string;
}
/**
 * Consume a stream expected to emit at most one value. The effect returns
 * `None` for no values and `Some(value)` for one, or fails with
 * `NotUniqueError` for two or more. Like `Stream.runHead` with a uniqueness
 * check, it inspects at most two emitted values; finding them may read
 * additional filtered documents.
 *
 * @experimental
 */
export declare const unique: <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R>(self: QueryStream<Doc, KeyLabels, QueryStreamOrderDirection.QueryStreamOrderDirection, E, R>) => Effect.Effect<Option.Option<Doc>, E | NotUniqueError, R>;
/**
 * Convex pagination options interpreted over a query stream's stored keys. Pass
 * a paginated query handler's `paginationOpts` directly to `paginate`.
 *
 * - `cursor`: required exclusive start boundary; `null` starts at the beginning.
 * - `numItems`: requested emitted values, excluding filtered documents. With an
 *   `endCursor`, it is not an item limit, but still informs split
 *   recommendations.
 * - `endCursor`: optional inclusive boundary returned by a previous page. Pins
 *   the page to a key range regardless of how many values it holds.
 * - `maximumRowsRead`: optional budget for physical document reads from
 *   underlying query-stream indexes, including filtered documents.
 * - `maximumBytesRead`: optional budget charging estimated document size on every
 *   read, not Convex's exact billed bytes. The final document can take the
 *   total over the limit because its size is known only after reading it.
 *
 * With `numItems: 0`, an existing cursor is returned unchanged with an empty
 * page and `isDone: false`; a null cursor dies with `EmptyInitialPageError`.
 *
 * @experimental
 */
export type PaginateOptions = ConvexPaginationOptions;
/**
 * One page in Convex's pagination result shape. Return the whole result to
 * reactive clients so they can pin and split pages; use `page` alone for a
 * one-shot read inside a handler.
 *
 * - `page`: emitted values, possibly empty despite progress past filtered keys.
 * - `continueCursor`: the next page's exclusive start. Pass it back unchanged as
 *   `cursor` while `isDone` is false.
 * - `splitCursor`: an optional interior boundary. Pin the left page with this as
 *   `endCursor`; start the right page here, retaining the original end.
 * - `pageStatus`: `"SplitRequired"` when a read budget stops at a safe boundary,
 *   or `"SplitRecommended"` when a pinned page grows too large or a page scans
 *   many keys. Both include a `splitCursor`; otherwise status may be absent.
 * - `isDone`: true confirms the stream's end. Reaching a pinned boundary does not
 *   prove completion. A split recommendation can report false even at the end,
 *   so handle splitting before requesting another page.
 *
 * @experimental
 */
export type PaginationResult<Doc> = ConvexPaginationResult<Doc>;
/**
 * Return an effect producing one page of a composed query stream. Start with
 * `cursor: null`, then pass each returned `continueCursor` back unchanged until
 * `isDone`. Cursors record key boundaries, not offsets or the last visible
 * document: filtered elements can advance the cursor without entering `page`.
 *
 * `cursor` is exclusive and `endCursor` is inclusive, in stream order. Without
 * an end boundary, `numItems` limits emitted values. With `endCursor`, the page
 * covers the pinned range regardless of its item count, keeping adjacent
 * reactive pages gap-free as data changes. See `PaginateOptions` for read
 * limits and the special case of a zero-sized request.
 *
 * Bounds are pushed into underlying index queries where possible, but composed
 * streams may read more documents than they return, including documents read on
 * earlier pages. Budgets count filtered documents, distinct-group discovery,
 * repeated seeks, merge prefetch, and both outer and inner query-stream reads
 * in joins. Arbitrary I/O inside callbacks, such as a separate lookup in
 * `mapEffect`, is not tracked.
 *
 * A budget-limited page returns `SplitRequired` at a safe logical boundary. If
 * the budget prevents safe progress or an interior split of a pinned page, the
 * effect fails with `ReadBudgetExceededError` rather than returning a
 * non-advancing cursor. Increase the budget or reduce the reads needed for
 * progress. See `PaginationResult` for split and completion handling.
 *
 * Malformed or incompatible cursors die with a `ConvexError` whose data is `{
 * paginationError: "InvalidCursor" }`; Confect's pagination clients restart
 * from the first page. Restart pagination whenever filters, ordering, or other
 * query semantics change, even if an old cursor is still accepted.
 *
 * Cursors expose boundary field names and key values, including document IDs.
 * They are neither opaque nor signed: clients can read or craft them. Do not
 * publicly paginate over sensitive indexed fields unless pinned with `eq`.
 * Never construct cursors from documents or decode them into `narrow` bounds.
 *
 * Return the whole result to reactive clients. React's
 * `useStreamPaginatedQuery` handles pinning, splitting, and invalid-cursor
 * resets; `usePaginatedQuery` does not support stream pages. Foldkit's
 * `PaginatedQuery` also supports them.
 *
 * @experimental
 */
export declare const paginate: {
    (options: PaginateOptions): <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R>(self: QueryStream<Doc, KeyLabels, QueryStreamOrderDirection.QueryStreamOrderDirection, E, R>) => Effect.Effect<PaginationResult<Doc>, E | ReadBudgetExceededError, R>;
    <Doc, KeyLabels extends QueryStreamKeyLabels.QueryStreamKeyLabels, E, R>(self: QueryStream<Doc, KeyLabels, QueryStreamOrderDirection.QueryStreamOrderDirection, E, R>, options: PaginateOptions): Effect.Effect<PaginationResult<Doc>, E | ReadBudgetExceededError, R>;
};
//# sourceMappingURL=QueryStream.d.ts.map