@gaganref/confect-server 0.0.0-stage → 10.3.1-fork.10

package/dist/QueryStream.js

@@ -0,0 +1,943 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { decode } from "./Document.js";
+import { make } from "./QueryStreamKeyLabels.js";
+import { Equivalence, concat, format, fromIndex, rename, resolvePrefix, runtimeWidth } from "./QueryStreamKeyLayout.js";
+import { complete, toPrefix, values } from "./QueryStreamKey.js";
+import { Order as Order$1, extract } from "./QueryStreamKeyValues.js";
+import { fromKeyLayout } from "./QueryStreamCursor.js";
+import { flip } from "./QueryStreamOrderDirection.js";
+import { fromStreamKey, keyValues } from "./QueryStreamIndexPrefix.js";
+import { admittedByLower, admittedByUpper, forLayout, fromParsed, intersect, intersectIndexBounds, parse, parseBound, tightestLower, tightestParsedLower, tightestParsedUpper, tightestUpper, toBounds, unbounded } from "./QueryStreamKeyBounds.js";
+import { apply, equalityPrefixLength, fromBounds, toBounds as toBounds$1 } from "./QueryStreamIndexRange.js";
+import { EmptyInitialPageError, InvalidPageSizeError, Range, Start, finish, initial, parseRequest, record } from "./QueryStreamPagination.js";
+import { InvalidReadLimitError, Limits, QueryStreamReadBudget, make as make$1 } from "./QueryStreamReadBudget.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { dual, identity, pipe } from "effect/Function";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import { ConvexError } from "convex/values";
+import * as Array from "effect/Array";
+import * as Order from "effect/Order";
+import * as Predicate from "effect/Predicate";
+import * as Result from "effect/Result";
+import * as Data from "effect/Data";
+import * as Stream from "effect/Stream";
+import { pipeArguments } from "effect/Pipeable";
+import * as Chunk from "effect/Chunk";
+import * as Filter from "effect/Filter";
+import * as Pull from "effect/Pull";
+import * as Sink from "effect/Sink";
+import * as String from "effect/String";
+import * as Tuple from "effect/Tuple";
+//#region src/QueryStream.ts
+var QueryStream_exports = /* @__PURE__ */ __exportAll({
+	Element: () => Element,
+	EmptyInitialPageError: () => EmptyInitialPageError,
+	IncompatibleStreamsError: () => IncompatibleStreamsError,
+	InnerStreamLayoutMismatchError: () => InnerStreamLayoutMismatchError,
+	InnerStreamOrderMismatchError: () => InnerStreamOrderMismatchError,
+	InvalidPageSizeError: () => InvalidPageSizeError,
+	InvalidReadLimitError: () => InvalidReadLimitError,
+	MissingReversalRecipeError: () => MissingReversalRecipeError,
+	NotUniqueError: () => NotUniqueError,
+	QueryStream: () => QueryStream,
+	ReadBudgetExceededError: () => ReadBudgetExceededError,
+	TypeId: () => TypeId,
+	distinct: () => distinct,
+	empty: () => empty,
+	filter: () => filter,
+	filterEffect: () => filterEffect,
+	flatMap: () => flatMap,
+	fromReflection: () => fromReflection,
+	isQueryStream: () => isQueryStream,
+	map: () => map,
+	mapEffect: () => mapEffect,
+	merge: () => merge,
+	narrow: () => narrow,
+	paginate: () => paginate,
+	renameKey: () => renameKey,
+	reverse: () => reverse,
+	unique: () => unique
+});
+/**
+* A page exhausted its read budget without a safe logical continuation.
+*
+* @experimental
+*/
+var ReadBudgetExceededError = class extends Schema.TaggedError()("ReadBudgetExceededError", {
+	rowsRead: Schema.Natural,
+	bytesRead: Schema.Natural
+}) {
+	get message() {
+		return "The read budget was exhausted before a safe page boundary; increase the budget or simplify the query";
+	}
+};
+/**
+* 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
+*/
+var IncompatibleStreamsError = class extends Data.TaggedError("IncompatibleStreamsError") {
+	get message() {
+		return `QueryStream.merge: all streams must share an order and key layout (got ${this.expectedOrderDirection} ${format(this.expectedKeyLayout)} and ${this.actualOrderDirection} ${format(this.actualKeyLayout)})`;
+	}
+};
+/**
+* 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
+*/
+var InnerStreamOrderMismatchError = class extends Data.TaggedError("InnerStreamOrderMismatchError") {
+	get message() {
+		return `QueryStream.flatMap: inner stream order (${this.actualOrderDirection}) differs from the outer stream's (${this.expectedOrderDirection})`;
+	}
+};
+/**
+* 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
+*/
+var InnerStreamLayoutMismatchError = class extends Data.TaggedError("InnerStreamLayoutMismatchError") {
+	get message() {
+		return `QueryStream.flatMap: inner stream key layout (${format(this.actualKeyLayout)}) differs from innerKeyLayout (${format(this.expectedKeyLayout)})`;
+	}
+};
+/**
+* Thrown by `reverse` when a manually constructed stream has no `reverseWith`
+* recipe. Streams created through the table reader and `QueryStream`
+* combinators support reversal.
+*
+* @experimental
+*/
+var MissingReversalRecipeError = class extends Data.TaggedError("MissingReversalRecipeError") {
+	get message() {
+		return "QueryStream.reverse: this stream cannot be reversed without a reversal recipe";
+	}
+};
+/**
+* Runtime identifier used to distinguish query streams from plain streams.
+*
+* @experimental
+*/
+const TypeId = "~@confect/server/QueryStream";
+/**
+* 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
+*/
+var Element = class extends Data.Class {};
+/**
+* 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
+*/
+var QueryStream = class {
+	orderDirection;
+	keyLayout;
+	annotated;
+	reflection;
+	narrowWith;
+	reverseWith;
+	constructor(orderDirection, keyLayout, annotated, reflection, narrowWith, reverseWith) {
+		this.orderDirection = orderDirection;
+		this.keyLayout = keyLayout;
+		this.annotated = annotated;
+		this.reflection = reflection;
+		this.narrowWith = narrowWith;
+		this.reverseWith = reverseWith;
+		if (narrowWith !== void 0) this.narrowWith = (parsedBounds) => narrowWith(Result.getOrThrowWith(forLayout(keyLayout, parsedBounds), identity));
+	}
+	toStream() {
+		return Stream.unwrap(Effect.gen({ self: this }, function* () {
+			const readBudget = yield* Effect.serviceOption(QueryStreamReadBudget).pipe(Effect.flatMap(Option.match({
+				onNone: () => make$1({
+					maximumRowsRead: Option.none(),
+					maximumBytesRead: Option.none()
+				}),
+				onSome: Effect.succeed
+			})));
+			return Stream.filterMap(this.annotated, Filter.fromPredicateOption(({ doc }) => doc)).pipe(Stream.provideService(QueryStreamReadBudget, readBudget));
+		}));
+	}
+};
+const streamVariance = {
+	_R: identity,
+	_E: identity,
+	_A: identity
+};
+const queryStreamPrototype = QueryStream.prototype;
+Object.defineProperties(queryStreamPrototype, {
+	[TypeId]: { value: TypeId },
+	[Stream.TypeId]: { value: streamVariance },
+	pipe: { value: function() {
+		return pipeArguments(this, arguments);
+	} },
+	channel: { get() {
+		return Stream.toChannel(this.toStream());
+	} }
+});
+/**
+* Check whether a value retains query-stream ordering and pagination support.
+* Plain `Stream` transforms return ordinary streams, for which this is false.
+*
+* @experimental
+*/
+const isQueryStream = (u) => Predicate.hasProperty(u, TypeId);
+/**
+* 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
+*/
+const empty = () => (keyLayout, orderDirection = "asc") => {
+	const make = (currentOrderDirection) => new QueryStream(currentOrderDirection, keyLayout, Stream.empty, void 0, () => make(currentOrderDirection), () => make(flip(currentOrderDirection)));
+	return make(orderDirection);
+};
+/**
+* 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
+*/
+const fromReflection = (reflection) => makeLeaf(reflection, reflection.indexBounds === void 0 ? toBounds$1(reflection.indexRange) : intersectIndexBounds(toBounds$1(reflection.indexRange), reflection.indexBounds));
+/**
+* Complete the source index paths with Convex's implicit ID tiebreaker. These
+* paths address the encoded document and are never ordering aliases.
+*/
+const completeFieldPaths = (fieldPaths) => Option.exists(Array.last(fieldPaths), (fieldPath) => fieldPath === "_id") ? fieldPaths : Array.append(fieldPaths, "_id");
+const makeLeaf = (reflection, indexBounds) => {
+	const fullFieldPaths = completeFieldPaths(reflection.indexFieldPaths);
+	const equalityPrefixLength$1 = equalityPrefixLength(reflection.indexRange);
+	const keyLayout = Result.getOrThrowWith(fromIndex(reflection.indexFieldPaths, equalityPrefixLength$1), identity);
+	const keyPaths = Array.map(Array.drop(fullFieldPaths, equalityPrefixLength$1), (fieldPath) => String.split(fieldPath, "."));
+	const equalityKeyValues = Array.take(indexBounds.lower.keyValues, equalityPrefixLength$1);
+	const indexRanges = Result.getOrThrowWith(fromBounds(fullFieldPaths, reflection.orderDirection, indexBounds), identity);
+	const encodedDocuments = Stream.fromIterable(indexRanges).pipe(Stream.flatMap((indexRange) => Stream.suspend(() => Stream.fromAsyncIterable(reflection.reader.query(reflection.table.tableName).withIndex(reflection.indexName, (q) => apply(indexRange, q)).order(reflection.orderDirection), identity).pipe(Stream.orDie))));
+	const annotated = Stream.unwrap(Effect.map(QueryStreamReadBudget, (readBudget) => readBudget.accountFor(encodedDocuments))).pipe(Stream.mapEffect((encoded) => Effect.map(decode(reflection.table)(encoded), (doc) => new Element({
+		doc: Option.some(doc),
+		keyValues: extract(encoded, keyPaths)
+	}))));
+	const toFullKeySpace = (bound) => ({
+		keyValues: keyValues(Result.getOrThrowWith(fromStreamKey(fullFieldPaths, equalityKeyValues, bound.key), identity)),
+		inclusive: bound.inclusive
+	});
+	return new QueryStream(reflection.orderDirection, keyLayout, annotated, {
+		...reflection,
+		indexBounds
+	}, (parsedBounds) => makeLeaf(reflection, {
+		lower: Option.match(parsedBounds.lower, {
+			onNone: () => indexBounds.lower,
+			onSome: (bound) => tightestLower(indexBounds.lower, toFullKeySpace(bound))
+		}),
+		upper: Option.match(parsedBounds.upper, {
+			onNone: () => indexBounds.upper,
+			onSome: (bound) => tightestUpper(indexBounds.upper, toFullKeySpace(bound))
+		})
+	}), () => makeLeaf({
+		...reflection,
+		orderDirection: flip(reflection.orderDirection)
+	}, indexBounds));
+};
+const MergeSource = Data.taggedEnum();
+var MergeCandidate = class extends Data.Class {};
+const fillMergeSource = (source) => MergeSource.$match(source, {
+	NeedsPull: ({ pull }) => pull.pipe(Effect.map((elements) => MergeSource.Buffered({
+		pull,
+		head: Array.headNonEmpty(elements),
+		tail: Chunk.fromIterable(Array.tailNonEmpty(elements))
+	})), Pull.catchDone(() => Effect.gen(function* () {
+		return (yield* (yield* QueryStreamReadBudget).isStopped) ? MergeSource.BudgetLimited() : MergeSource.Exhausted();
+	}))),
+	Buffered: () => Effect.succeed(source),
+	Exhausted: () => Effect.succeed(source),
+	BudgetLimited: () => Effect.succeed(source)
+});
+/**
+* One step of the k-way merge as a pure unfold: fill every source, emit the
+* earliest head (ties go to the earliest source, keeping the merge stable), and
+* return the sources with that head consumed. `undefined` when every source is
+* exhausted or an input stopped before its next key was known.
+*/
+const mergeStep = (keyOrder) => (sources) => Effect.gen(function* () {
+	const readBudget = yield* QueryStreamReadBudget;
+	const filled = yield* Effect.forEach(sources, fillMergeSource, { concurrency: (yield* readBudget.isUnlimited) ? "unbounded" : 1 });
+	if (filled.some((source) => MergeSource.$is("BudgetLimited")(source))) return void 0;
+	const isEarlier = Order.isLessThan(keyOrder);
+	const earliest = Array.reduce(filled, Option.none(), (best, source, index) => Option.match(source._tag === "Buffered" ? Option.some(source.head) : Option.none(), {
+		onNone: () => best,
+		onSome: (head) => Option.match(best, {
+			onNone: () => Option.some(new MergeCandidate({
+				index,
+				element: head
+			})),
+			onSome: ({ element: bestElement }) => isEarlier(head.keyValues, bestElement.keyValues) ? Option.some(new MergeCandidate({
+				index,
+				element: head
+			})) : best
+		})
+	}));
+	return Option.getOrUndefined(Option.map(earliest, ({ index, element }) => Tuple.make(element, Array.map(filled, (source, sourceIndex) => sourceIndex === index && source._tag === "Buffered" ? Option.match(Chunk.head(source.tail), {
+		onNone: () => MergeSource.NeedsPull({ pull: source.pull }),
+		onSome: (head) => MergeSource.Buffered({
+			pull: source.pull,
+			head,
+			tail: Chunk.drop(source.tail, 1)
+		})
+	}) : source))));
+});
+/**
+* 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
+*/
+const merge = (streams) => {
+	const head = Array.headNonEmpty(streams);
+	const incompatible = Array.findFirst(Array.tailNonEmpty(streams), (stream) => stream.orderDirection !== head.orderDirection || !Equivalence(stream.keyLayout, head.keyLayout));
+	if (Option.isSome(incompatible)) throw new IncompatibleStreamsError({
+		expectedOrderDirection: head.orderDirection,
+		actualOrderDirection: incompatible.value.orderDirection,
+		expectedKeyLayout: head.keyLayout,
+		actualKeyLayout: incompatible.value.keyLayout
+	});
+	return mergeUnchecked(streams);
+};
+/**
+* `merge` without the compatibility check—for re-merging branches that were
+* validated when the merge was built (narrowing never changes a branch's order
+* or key layout).
+*/
+const mergeUnchecked = (streams) => {
+	const head = Array.headNonEmpty(streams);
+	const annotated = Stream.unwrap(Effect.map(Effect.forEach(streams, (stream) => Stream.toPull(stream.annotated)), (pulls) => Stream.unfold(Array.map(pulls, (pull) => MergeSource.NeedsPull({ pull })), mergeStep(Order$1(head.orderDirection)))));
+	return new QueryStream(head.orderDirection, head.keyLayout, annotated, void 0, (parsedBounds) => mergeUnchecked([narrowByParsedBounds(head, parsedBounds), ...Array.map(Array.tailNonEmpty(streams), (stream) => narrowByParsedBounds(stream, parsedBounds))]), () => mergeUnchecked([reverse(head), ...Array.map(Array.tailNonEmpty(streams), (stream) => reverse(stream))]));
+};
+/**
+* Derive a stream by transforming each present document into `Some` (keep,
+* possibly changed) or `None` (drop). Key values are preserved and dropped
+* elements stay in cursor accounting as read-but-filtered, so the result
+* remains mergeable and paginable; narrowing narrows the input and re-applies
+* the transform, so cursor bounds keep pushing down to leaves.
+*/
+const transform = (self, f) => new QueryStream(self.orderDirection, self.keyLayout, Stream.map(self.annotated, ({ doc, keyValues }) => new Element({
+	doc: Option.flatMap(doc, f),
+	keyValues
+})), void 0, (parsedBounds) => transform(narrowByParsedBounds(self, parsedBounds), f), () => transform(reverse(self), f));
+/**
+* The effectful {@link transform}.
+*/
+const transformEffect = (self, f, options) => new QueryStream(self.orderDirection, self.keyLayout, Stream.mapEffect(self.annotated, ({ doc, keyValues }) => Option.match(doc, {
+	onNone: () => Effect.succeed(new Element({
+		doc: Option.none(),
+		keyValues
+	})),
+	onSome: (value) => Effect.map(f(value), (mapped) => new Element({
+		doc: mapped,
+		keyValues
+	}))
+}), { concurrency: options?.concurrency }), void 0, (parsedBounds) => transformEffect(narrowByParsedBounds(self, parsedBounds), f, options), () => transformEffect(reverse(self), f, options));
+/**
+* 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
+*/
+const filter = dual(2, (self, predicate) => transform(self, (doc) => predicate(doc) ? Option.some(doc) : Option.none()));
+/**
+* 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
+*/
+const filterEffect = dual((args) => isQueryStream(args[0]), (self, predicate, options) => transformEffect(self, (doc) => Effect.map(predicate(doc), (keep) => keep ? Option.some(doc) : Option.none()), options));
+/**
+* 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
+*/
+const map = dual(2, (self, f) => transform(self, (doc) => Option.some(f(doc))));
+/**
+* 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
+*/
+const mapEffect = dual((args) => isQueryStream(args[0]), (self, f, options) => transformEffect(self, (doc) => Effect.asSome(f(doc)), options));
+/**
+* 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
+*/
+const flatMap = dual(3, (self, f, options) => {
+	return makeFlatMap(self, f, options.innerKeyLayout, Option.fromUndefinedOr(options.onEmpty), {
+		lower: Option.none(),
+		upper: Option.none()
+	});
+});
+const FlatMapBound = Data.taggedEnum();
+const combineLowerRefinements = (existing, incoming) => Option.orElse(Option.zipWith(existing, incoming, (left, right) => {
+	const ordering = Order$1("asc")(left.outerKeyValues, right.outerKeyValues);
+	return ordering > 0 ? left : ordering < 0 ? right : {
+		outerKeyValues: left.outerKeyValues,
+		innerParsedBound: Result.getOrThrowWith(tightestParsedLower(left.innerParsedBound, right.innerParsedBound), identity)
+	};
+}), () => Option.orElse(existing, () => incoming));
+const combineUpperRefinements = (existing, incoming) => Option.orElse(Option.zipWith(existing, incoming, (left, right) => {
+	const ordering = Order$1("asc")(left.outerKeyValues, right.outerKeyValues);
+	return ordering < 0 ? left : ordering > 0 ? right : {
+		outerKeyValues: left.outerKeyValues,
+		innerParsedBound: Result.getOrThrowWith(tightestParsedUpper(left.innerParsedBound, right.innerParsedBound), identity)
+	};
+}), () => Option.orElse(existing, () => incoming));
+const makeFlatMap = (self, f, innerKeyLayout, onEmpty, refinements) => {
+	const outerLength = runtimeWidth(self.keyLayout);
+	const keyLayout = concat(self.keyLayout, innerKeyLayout);
+	const emptyInnerKeyValues = Array.makeBy(runtimeWidth(innerKeyLayout), () => null);
+	const validated = (inner) => {
+		if (inner.orderDirection !== self.orderDirection) throw new InnerStreamOrderMismatchError({
+			expectedOrderDirection: self.orderDirection,
+			actualOrderDirection: inner.orderDirection
+		});
+		if (!Equivalence(inner.keyLayout, innerKeyLayout)) throw new InnerStreamLayoutMismatchError({
+			expectedKeyLayout: innerKeyLayout,
+			actualKeyLayout: inner.keyLayout
+		});
+		return inner;
+	};
+	const innerParsedBoundsFor = (outerKeyValues) => Result.getOrThrowWith(fromParsed(innerKeyLayout, {
+		lower: Option.map(Option.filter(refinements.lower, (refinement) => Order$1("asc")(outerKeyValues, refinement.outerKeyValues) === 0), (refinement) => refinement.innerParsedBound),
+		upper: Option.map(Option.filter(refinements.upper, (refinement) => Order$1("asc")(outerKeyValues, refinement.outerKeyValues) === 0), (refinement) => refinement.innerParsedBound)
+	}), identity);
+	const markerStream = (outerKeyValues, innerParsedBounds, doc) => {
+		const { aboveLower, belowUpper } = keyPredicates(innerParsedBounds);
+		return aboveLower(emptyInnerKeyValues) && belowUpper(emptyInnerKeyValues) ? Stream.succeed(new Element({
+			doc,
+			keyValues: Array.appendAll(outerKeyValues, emptyInnerKeyValues)
+		})) : Stream.empty;
+	};
+	const annotated = self.annotated.pipe(Stream.flatMap(({ doc: outerDoc, keyValues: outerKeyValues }) => {
+		const innerParsedBounds = innerParsedBoundsFor(outerKeyValues);
+		return Option.match(outerDoc, {
+			onNone: () => markerStream(outerKeyValues, innerParsedBounds, Option.none()),
+			onSome: (doc) => {
+				const inner = validated(f(doc));
+				return narrowByParsedBounds(inner, innerParsedBounds).annotated.pipe(Stream.map(({ doc: innerDoc, keyValues: innerKeyValues }) => new Element({
+					doc: innerDoc,
+					keyValues: Array.appendAll(outerKeyValues, innerKeyValues)
+				})), Stream.orElseIfEmpty(() => Stream.unwrap(Effect.gen(function* () {
+					const readBudget = yield* QueryStreamReadBudget;
+					if (yield* readBudget.isStopped) return Stream.empty;
+					const original = yield* Option.match(Option.gen(function* () {
+						yield* onEmpty;
+						return yield* Option.orElse(innerParsedBounds.lower, () => innerParsedBounds.upper);
+					}), {
+						onNone: () => Effect.succeed(Option.none()),
+						onSome: () => Stream.runHead(inner.annotated)
+					});
+					const isStopped = yield* readBudget.isStopped;
+					return Option.match(original, {
+						onSome: () => Stream.empty,
+						onNone: () => isStopped ? Stream.empty : markerStream(outerKeyValues, innerParsedBounds, Option.map(onEmpty, (makeEmpty) => makeEmpty(doc)))
+					});
+				}))));
+			}
+		});
+	}));
+	const split = (bound) => {
+		const keyValues = values(bound.key);
+		const { inclusive } = bound;
+		return keyValues.length <= outerLength ? FlatMapBound.Outer({
+			keyValues,
+			inclusive
+		}) : FlatMapBound.Inner({
+			outerKeyValues: Array.take(keyValues, outerLength),
+			innerParsedBound: Result.getOrThrowWith(parseBound(innerKeyLayout, {
+				keyValues: Array.drop(keyValues, outerLength),
+				inclusive
+			}), identity)
+		});
+	};
+	const outerBound = (bound) => FlatMapBound.$match(bound, {
+		Outer: ({ keyValues, inclusive }) => ({
+			keyValues,
+			inclusive
+		}),
+		Inner: ({ outerKeyValues }) => ({
+			keyValues: outerKeyValues,
+			inclusive: true
+		})
+	});
+	return new QueryStream(self.orderDirection, keyLayout, annotated, void 0, (parsedBounds) => {
+		const lower = Option.map(parsedBounds.lower, split);
+		const upper = Option.map(parsedBounds.upper, split);
+		return makeFlatMap(narrowByKeyBounds(self, {
+			lower: Option.map(lower, outerBound),
+			upper: Option.map(upper, outerBound)
+		}), f, innerKeyLayout, onEmpty, {
+			lower: combineLowerRefinements(refinements.lower, Option.filter(lower, FlatMapBound.$is("Inner"))),
+			upper: combineUpperRefinements(refinements.upper, Option.filter(upper, FlatMapBound.$is("Inner")))
+		});
+	}, () => makeFlatMap(reverse(self), (doc) => reverse(f(doc)), innerKeyLayout, onEmpty, refinements));
+};
+/**
+* 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
+*/
+const distinct = dual(2, (self, prefixNames) => {
+	return makeDistinct(self, Result.getOrThrowWith(resolvePrefix(self.keyLayout, make(prefixNames)), identity), self.orderDirection, unbounded(self.keyLayout));
+});
+/**
+* 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
+*/
+const renameKey = dual(2, (self, replacementNames) => renameKeyImpl(self, make(replacementNames)));
+const renameKeyImpl = (self, replacementKeyLabels) => {
+	const keyLayout = Result.getOrThrowWith(rename(self.keyLayout, replacementKeyLabels), identity);
+	return new QueryStream(self.orderDirection, keyLayout, self.annotated, void 0, (parsedBounds) => renameKeyImpl(narrowByKeyBounds(self, toBounds(parsedBounds)), replacementKeyLabels), () => renameKeyImpl(reverse(self), replacementKeyLabels));
+};
+const makeDistinct = (self, distinctLength, orderDirection, parsedBounds) => {
+	const afterKeyValues = (keyValues) => {
+		const pastGroup = {
+			keyValues,
+			inclusive: false
+		};
+		return orderDirection === "asc" ? {
+			lower: Option.some(pastGroup),
+			upper: Option.none()
+		} : {
+			lower: Option.none(),
+			upper: Option.some(pastGroup)
+		};
+	};
+	const groupBound = (bound) => Option.map(bound, ({ inclusive, key }) => ({
+		keyValues: Array.take(values(key), distinctLength),
+		inclusive: values(key).length > distinctLength || inclusive
+	}));
+	const { aboveLower, belowUpper } = keyPredicates(parsedBounds);
+	const isAdmitted = (keyValues) => aboveLower(keyValues) && belowUpper(keyValues);
+	const annotated = Stream.unwrap(Effect.map(QueryStreamReadBudget, (readBudget) => Stream.paginate(narrowByKeyBounds(orderDirection === self.orderDirection ? self : reverse(self), {
+		lower: groupBound(parsedBounds.lower),
+		upper: groupBound(parsedBounds.upper)
+	}), (current) => Effect.gen(function* () {
+		if (yield* readBudget.isStopped) return Tuple.make([], Option.none());
+		const discovered = yield* Stream.runHead(current.annotated);
+		if (Option.isNone(discovered)) return Tuple.make([], Option.none());
+		const element = discovered.value;
+		const { doc, keyValues } = element;
+		const prefixKeyValues = Array.take(keyValues, distinctLength);
+		if (orderDirection === self.orderDirection) {
+			const nextKeyValues = Option.match(doc, {
+				onNone: () => keyValues,
+				onSome: () => prefixKeyValues
+			});
+			return Tuple.make(isAdmitted(keyValues) ? [element] : [], Option.some(narrowByKeyBounds(current, afterKeyValues(nextKeyValues))));
+		}
+		const next = Option.some(narrowByKeyBounds(current, afterKeyValues(prefixKeyValues)));
+		const { firstKeyValues, selected } = yield* narrowByKeyBounds(self, {
+			lower: Option.some({
+				keyValues: prefixKeyValues,
+				inclusive: true
+			}),
+			upper: Option.some({
+				keyValues: prefixKeyValues,
+				inclusive: true
+			})
+		}).annotated.pipe(Stream.run(Sink.fold(() => ({
+			firstKeyValues: Option.none(),
+			selected: Option.none()
+		}), (probe) => Option.isNone(probe.selected), (probe, candidate) => Effect.succeed({
+			firstKeyValues: Option.orElse(probe.firstKeyValues, () => Option.some(candidate.keyValues)),
+			selected: Option.as(candidate.doc, candidate)
+		}))));
+		if (Option.isSome(selected)) {
+			const representative = selected.value;
+			return Tuple.make(isAdmitted(representative.keyValues) ? [representative] : [], next);
+		}
+		if (yield* readBudget.isStopped) return Tuple.make([], Option.none());
+		const checkpointKeyValues = Option.getOrElse(firstKeyValues, () => keyValues);
+		return Tuple.make(isAdmitted(checkpointKeyValues) ? [new Element({
+			doc: Option.none(),
+			keyValues: checkpointKeyValues
+		})] : [], next);
+	}))));
+	return new QueryStream(orderDirection, self.keyLayout, annotated, void 0, (incomingParsedBounds) => makeDistinct(self, distinctLength, orderDirection, Result.getOrThrowWith(intersect(parsedBounds, incomingParsedBounds), identity)), () => makeDistinct(self, distinctLength, flip(orderDirection), parsedBounds));
+};
+/**
+* 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
+*/
+const reverse = (self) => {
+	if (self.reverseWith === void 0) throw new MissingReversalRecipeError();
+	return self.reverseWith();
+};
+/**
+* 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
+*/
+const narrow = dual(2, (self, narrowBounds) => {
+	const start = Option.fromUndefinedOr(narrowBounds.start);
+	const end = Option.fromUndefinedOr(narrowBounds.end);
+	const keyBounds = self.orderDirection === "asc" ? {
+		lower: start,
+		upper: end
+	} : {
+		lower: end,
+		upper: start
+	};
+	return narrowByKeyBounds(self, keyBounds);
+});
+const narrowByKeyBounds = (self, keyBounds) => {
+	const parsedBounds = Result.getOrThrowWith(parse(self.keyLayout, keyBounds), identity);
+	return narrowByParsedBounds(self, parsedBounds);
+};
+const narrowByParsedBounds = (self, parsedBounds) => {
+	const unbounded = Option.isNone(parsedBounds.lower) && Option.isNone(parsedBounds.upper);
+	if (!unbounded && self.narrowWith !== void 0) return self.narrowWith(parsedBounds);
+	Result.getOrThrowWith(forLayout(self.keyLayout, parsedBounds), identity);
+	return unbounded ? self : narrowInMemory(self, parsedBounds);
+};
+/**
+* The fallback for streams that don't know how to rebuild themselves.
+*/
+const keyPredicates = (parsedBounds) => {
+	const complete$1 = (keyValues) => Result.getOrThrowWith(complete(parsedBounds.keyLayout, keyValues), identity);
+	return {
+		aboveLower: (keyValues) => Result.getOrThrowWith(admittedByLower(parsedBounds)(complete$1(keyValues)), identity),
+		belowUpper: (keyValues) => Result.getOrThrowWith(admittedByUpper(parsedBounds)(complete$1(keyValues)), identity)
+	};
+};
+const narrowInMemory = (self, parsedBounds) => {
+	const { aboveLower, belowUpper } = keyPredicates(parsedBounds);
+	const dropOutOfRange = self.orderDirection === "asc" ? Stream.dropWhile(({ keyValues }) => !aboveLower(keyValues)) : Stream.dropWhile(({ keyValues }) => !belowUpper(keyValues));
+	const takeInRange = self.orderDirection === "asc" ? Stream.takeWhile(({ keyValues }) => belowUpper(keyValues)) : Stream.takeWhile(({ keyValues }) => aboveLower(keyValues));
+	return new QueryStream(self.orderDirection, self.keyLayout, pipe(self.annotated, dropOutOfRange, takeInRange), void 0, void 0, self.reverseWith === void 0 ? void 0 : () => narrowInMemory(reverse(self), parsedBounds));
+};
+/**
+* `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
+*/
+var NotUniqueError = class extends Schema.TaggedError()("NotUniqueError", {}) {
+	get message() {
+		return "Expected the query stream to contain at most one document";
+	}
+};
+/**
+* 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
+*/
+const unique = Effect.fn("QueryStream.unique")((self) => self.pipe(Stream.take(2), Stream.runCollect, Effect.flatMap((docs) => docs.length >= 2 ? Effect.fail(new NotUniqueError()) : Effect.succeed(Array.head(docs)))));
+/**
+* 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
+*/
+const paginate = dual(2, Effect.fn("QueryStream.paginate")(function* (self, options) {
+	const cursorSchema = fromKeyLayout(self.keyLayout);
+	const encodeCursor = Schema.encodeEffect(cursorSchema);
+	const decodeCursor = Schema.decodeEffect(cursorSchema);
+	const complete$2 = (keyValues) => Result.getOrThrowWith(complete(self.keyLayout, keyValues), identity);
+	const decoded = yield* Effect.all({
+		start: Option.match(Option.fromNullOr(options.cursor), {
+			onNone: () => Effect.succeed(Start.Beginning()),
+			onSome: (cursor) => Effect.map(decodeCursor(cursor), (key) => Start.After({
+				cursor,
+				key
+			}))
+		}),
+		range: Option.match(Option.fromNullishOr(options.endCursor), {
+			onNone: () => Effect.succeed(Range.Unpinned()),
+			onSome: (cursor) => cursor === "[]" ? Effect.succeed(Range.ThroughEnd()) : Effect.map(decodeCursor(cursor), (key) => Range.ThroughKey({ key }))
+		})
+	}).pipe(Effect.catchTag("SchemaError", () => Effect.die(new ConvexError({ paginationError: "InvalidCursor" }))));
+	const request = yield* parseRequest(options.numItems, decoded.start, decoded.range).pipe(Effect.fromResult, Effect.catchTags({
+		InvalidPageSizeError: Effect.die,
+		EmptyInitialPageError: Effect.die
+	}));
+	if (request._tag === "Unchanged") return {
+		page: [],
+		isDone: false,
+		continueCursor: request.cursor
+	};
+	const start = Option.map(request.after, (key) => ({
+		key: toPrefix(key),
+		inclusive: false
+	}));
+	const end = Range.$match(request.range, {
+		Unpinned: () => Option.none(),
+		ThroughEnd: () => Option.none(),
+		ThroughKey: ({ key }) => Option.some({
+			key: toPrefix(key),
+			inclusive: true
+		})
+	});
+	const narrowed = narrowByParsedBounds(self, Result.getOrThrowWith(fromParsed(self.keyLayout, self.orderDirection === "asc" ? {
+		lower: start,
+		upper: end
+	} : {
+		lower: end,
+		upper: start
+	}), identity));
+	const readBudget = yield* QueryStreamReadBudget;
+	const collected = yield* Stream.run(narrowed.annotated, Sink.fold(() => initial(), (state) => state._tag === "Reading", (state, { doc, keyValues }) => Effect.map(readBudget.isExhausted, (hitLimit) => record(request, state, doc, complete$2(keyValues), hitLimit))));
+	const stopped = yield* readBudget.isStopped;
+	const outcome = finish(request, collected, stopped);
+	if (Result.isFailure(outcome)) return yield* new ReadBudgetExceededError(yield* readBudget.getReadCounts);
+	const encode = (key) => encodeCursor(key).pipe(Effect.catchTag("SchemaError", Effect.die));
+	const encodeSplit = (result) => Effect.gen(function* () {
+		const continueCursor = yield* Match.value(result.continuation).pipe(Match.tagsExhaustive({
+			End: () => Effect.succeed("[]"),
+			Key: ({ key }) => encode(key)
+		}));
+		return {
+			page: Array.fromIterable(result.page),
+			isDone: false,
+			continueCursor,
+			pageStatus: result._tag,
+			splitCursor: yield* encode(result.splitKey)
+		};
+	});
+	return yield* Match.value(outcome.success).pipe(Match.tagsExhaustive({
+		Done: ({ page }) => Effect.succeed({
+			page: Array.fromIterable(page),
+			isDone: true,
+			continueCursor: "[]"
+		}),
+		Continue: ({ page, key }) => Effect.map(encode(key), (continueCursor) => ({
+			page: Array.fromIterable(page),
+			isDone: false,
+			continueCursor
+		})),
+		SplitRequired: encodeSplit,
+		SplitRecommended: encodeSplit
+	}));
+}, (effect, _self, options) => Effect.provideServiceEffect(effect, QueryStreamReadBudget, Schema.decodeEffect(Limits)(options).pipe(Effect.catchTag("SchemaError", (cause) => Effect.die(new InvalidReadLimitError({ cause }))), Effect.flatMap(make$1)))));
+//#endregion
+export { Element, EmptyInitialPageError, IncompatibleStreamsError, InnerStreamLayoutMismatchError, InnerStreamOrderMismatchError, InvalidPageSizeError, InvalidReadLimitError, MissingReversalRecipeError, NotUniqueError, QueryStream, QueryStream_exports, ReadBudgetExceededError, TypeId, distinct, empty, filter, filterEffect, flatMap, fromReflection, isQueryStream, map, mapEffect, merge, narrow, paginate, renameKey, reverse, unique };
+
+//# sourceMappingURL=QueryStream.js.map