kitcn 0.18.0 → 0.19.0

package/dist/aggregate/index.d.ts

@@ -1,4 +1,4 @@
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial, dn as ConvexTableWithColumns, tr as ConvexTextBuilderInitial } from "../where-clause-compiler-B1weGkP4.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial, dn as ConvexTableWithColumns, tr as ConvexTextBuilderInitial } from "../where-clause-compiler-CmBz9CWA.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";

package/dist/auth/index.js

@@ -3,7 +3,7 @@ import { r as partial } from "../validators-C7LelqTN.js";
 import { i as defineAuth, n as createDisabledAuthRuntime, r as getGeneratedAuthDisabledReason, t as DEFAULT_AUTH_DEFINITION_PATH } from "../generated-contract-disabled-BXaz7JCE.js";
 import { n as createGeneratedFunctionReference, o as isQueryCtx, s as isRunMutationCtx } from "../api-entry-N3nBOlI2.js";
 import { n as customCtx, r as customMutation } from "../customFunctions-DxEEO4Dq.js";
-import { o as mergedStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken, y as eq } from "../query-context-CJE_hYA3.js";
+import { o as mergedStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken, y as eq } from "../query-context-BzihIpnM.js";
 import { n as convex } from "../convex-plugin-BHVCqWTH.js";
 import { v } from "convex/values";
 import { internalActionGeneric, internalMutationGeneric, internalQueryGeneric, paginationOptsValidator } from "convex/server";

package/dist/orm/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as GenericOrmCtx$1, $n as unique, $r as endsWith, $t as ManyConfig, A as ConvexDateMode, An as ConvexRankIndexBuilder, Ar as ReturningResult, At as MigrationManifestEntry, B as ConvexBytesBuilderInitial, Bn as rankIndex, Br as OrmSchemaRelations, Bt as defineMigration, C as ConvexNumberBuilderInitial, Ci as ColumnBuilderWithTableName, Cn as RlsRole, Cr as MutationReturning, Ct as MigrationStatusArgs, D as id, Di as IsPrimaryKey, Dn as ConvexAggregateIndexBuilderOn, Dr as PaginatedResult, Dt as MigrationDoc, E as ConvexIdBuilderInitial, Ei as HasDefault, En as ConvexAggregateIndexBuilder, Er as OrderDirection, Et as MigrationDirection, F as custom, Fn as ConvexVectorIndexBuilder, Fr as unsetToken, Ft as MigrationStateMap, G as ConvexBigIntBuilder, Gn as ConvexCheckConfig, Gr as ExpressionVisitor, Gt as OrmReader$1, H as ConvexBooleanBuilder, Hn as uniqueIndex, Hr as TableName, Ht as detectMigrationDrift, I as json, In as ConvexVectorIndexBuilderOn, Ir as Brand, It as MigrationStep, J as CountBackfillChunkArgs, Jn as ConvexUniqueConstraintBuilder, Jr as LogicalExpression, Jt as RlsMode, K as ConvexBigIntBuilderInitial, Kn as ConvexForeignKeyBuilder, Kr as FieldReference, Kt as OrmWriter$1, L as objectOf, Ln as ConvexVectorIndexConfig, Lr as Columns, Lt as MigrationTableName, M as ConvexCustomBuilder, Mn as ConvexSearchIndexBuilder, Mr as UpdateSet, Mt as MigrationPlan, N as ConvexCustomBuilderInitial, Nn as ConvexSearchIndexBuilderOn, Nr as VectorQueryConfig, Nt as MigrationRunStatus, O as ConvexDateBuilder, Oi as IsUnique, On as ConvexIndexBuilder, Or as PredicateWhereIndexConfig, Ot as MigrationDocContext, P as arrayOf, Pn as ConvexSearchIndexConfig, Pr as VectorSearchProvider, Pt as MigrationSet, Q as GenericOrm$1, Qn as foreignKey, Qr as contains, Qt as ExtractTablesWithRelations, R as unionOf, Rn as aggregateIndex, Rr as OrmSchemaExtensionTables, Rt as MigrationWriteMode, S as ConvexNumberBuilder, Si as ColumnBuilderTypeConfig, Sn as rlsPolicy, Sr as MutationResult, St as MigrationRunChunkArgs, T as ConvexIdBuilder, Ti as DrizzleEntity, Tn as rlsRole, Tr as OrderByClause, Tt as MigrationDefinition, U as ConvexBooleanBuilderInitial, Un as vectorIndex, Ur as SystemFields, Ut as DatabaseWithMutations, V as bytes, Vn as searchIndex, Vr as OrmSchemaTriggers, Vt as defineMigrationSet, W as boolean, Wn as ConvexCheckBuilder, Wr as BinaryExpression, Wt as DatabaseWithQuery, X as CountBackfillStatusArgs, Xn as ConvexUniqueConstraintConfig, Xr as and, Xt as extractRelationsConfig, Y as CountBackfillKickoffArgs, Yn as ConvexUniqueConstraintBuilderOn, Yr as UnaryExpression, Yt as EdgeMetadata, Z as CreateOrmOptions, Zn as check, Zr as between, Zt as ExtractTablesFromSchema, _ as ConvexTimestampMode, _i as startsWith, _n as deletion, _r as MutationExecuteConfig, _t as OrmTriggerContext, a as requireSchemaRelations, ai as inArray, an as TablesRelationalConfig, ar as AggregateResult, at as OrmWriterCtx, b as ConvexTextEnumBuilderInitial, bi as ColumnBuilderBaseConfig, bn as RlsPolicyConfig, br as MutationPaginateConfig, bt as MigrationCancelArgs, c as TableConfigResult, ci as isNull, cn as ConvexDeletionBuilder, cr as CountConfig, ct as ScheduledMutationBatchArgs, d as OrmNotFoundError, di as lte, dn as ConvexTableWithColumns, dr as FilterOperators, dt as scheduledDeleteFactory, ei as eq, en as OneConfig, er as ConvexTextBuilder, et as OrmApiResult, f as ConvexVectorBuilder, fi as ne, fn as DiscriminatorBuilderConfig, fr as GetColumnData, ft as SchemaExtension, g as ConvexTimestampBuilderInitial, gi as or, gn as convexTable, gr as InsertValue, gt as OrmTriggerChange, h as ConvexTimestampBuilder, hi as notInArray, hn as TableConfig, hr as InferSelectModel, ht as OrmTableTriggers, i as getSchemaTriggers, ii as ilike, in as TableRelationalConfig, ir as AggregateFieldValue, it as OrmReaderCtx, j as date, jn as ConvexRankIndexBuilderOn, jr as ReturningSelection, jt as MigrationMigrateOne, k as ConvexDateBuilderInitial, ki as NotNull, kn as ConvexIndexBuilderOn, kr as ReturningAll, kt as MigrationDriftIssue, l as getTableColumns, li as like, ln as ConvexDeletionConfig, lr as CountResult, lt as scheduledMutationBatchFactory, m as vector, mi as notBetween, mn as OrmLifecycleOperation, mr as InferModelFromColumns, mt as OrmBeforeResult, n as defineSchema, ni as gt, nn as RelationsBuilderColumnBase, nr as text, nt as OrmClientWithApi$1, o as asc, oi as isFieldReference, on as defineRelations, or as BuildQueryResult, ot as ResolveOrmSchema, p as ConvexVectorBuilderInitial, pi as not, pn as OrmLifecycleChange, pr as InferInsertModel, pt as defineSchemaExtension, q as bigint, qn as ConvexForeignKeyConfig, qr as FilterExpression, qt as RlsContext, r as getSchemaRelations, ri as gte, rn as RelationsBuilderColumnConfig, rr as AggregateConfig, rt as OrmFunctions, s as desc, si as isNotNull, sn as defineRelationsPart, sr as BuildRelationResult, st as createOrm, t as WhereClauseResult, ti as fieldRef, tn as RelationsBuilder, tr as ConvexTextBuilderInitial, tt as OrmClientBase$1, u as getTableConfig, ui as lt, un as ConvexTable, ur as DBQueryConfig, ut as ScheduledDeleteArgs, v as timestamp, vi as AnyColumn, vn as discriminator, vr as MutationExecuteResult, vt as OrmTriggers, w as integer, wi as ColumnDataType, wn as RlsRoleConfig, wr as MutationRunMode, wt as MigrationAppliedState, x as textEnum, xi as ColumnBuilderRuntimeConfig, xn as RlsPolicyToOption, xr as MutationPaginatedResult, xt as MigrationRunArgs, y as ConvexTextEnumBuilder, yi as ColumnBuilder, yn as RlsPolicy, yr as MutationExecutionMode, yt as defineTriggers, z as ConvexBytesBuilder, zn as index, zr as OrmSchemaExtensions, zt as buildMigrationPlan } from "../where-clause-compiler-B1weGkP4.js";
+import { $ as GenericOrmCtx$1, $n as unique, $r as endsWith, $t as ManyConfig, A as ConvexDateMode, An as ConvexRankIndexBuilder, Ar as ReturningResult, At as MigrationManifestEntry, B as ConvexBytesBuilderInitial, Bn as rankIndex, Br as OrmSchemaRelations, Bt as defineMigration, C as ConvexNumberBuilderInitial, Ci as ColumnBuilderWithTableName, Cn as RlsRole, Cr as MutationReturning, Ct as MigrationStatusArgs, D as id, Di as IsPrimaryKey, Dn as ConvexAggregateIndexBuilderOn, Dr as PaginatedResult, Dt as MigrationDoc, E as ConvexIdBuilderInitial, Ei as HasDefault, En as ConvexAggregateIndexBuilder, Er as OrderDirection, Et as MigrationDirection, F as custom, Fn as ConvexVectorIndexBuilder, Fr as unsetToken, Ft as MigrationStateMap, G as ConvexBigIntBuilder, Gn as ConvexCheckConfig, Gr as ExpressionVisitor, Gt as OrmReader$1, H as ConvexBooleanBuilder, Hn as uniqueIndex, Hr as TableName, Ht as detectMigrationDrift, I as json, In as ConvexVectorIndexBuilderOn, Ir as Brand, It as MigrationStep, J as CountBackfillChunkArgs, Jn as ConvexUniqueConstraintBuilder, Jr as LogicalExpression, Jt as RlsMode, K as ConvexBigIntBuilderInitial, Kn as ConvexForeignKeyBuilder, Kr as FieldReference, Kt as OrmWriter$1, L as objectOf, Ln as ConvexVectorIndexConfig, Lr as Columns, Lt as MigrationTableName, M as ConvexCustomBuilder, Mn as ConvexSearchIndexBuilder, Mr as UpdateSet, Mt as MigrationPlan, N as ConvexCustomBuilderInitial, Nn as ConvexSearchIndexBuilderOn, Nr as VectorQueryConfig, Nt as MigrationRunStatus, O as ConvexDateBuilder, Oi as IsUnique, On as ConvexIndexBuilder, Or as PredicateWhereIndexConfig, Ot as MigrationDocContext, P as arrayOf, Pn as ConvexSearchIndexConfig, Pr as VectorSearchProvider, Pt as MigrationSet, Q as GenericOrm$1, Qn as foreignKey, Qr as contains, Qt as ExtractTablesWithRelations, R as unionOf, Rn as aggregateIndex, Rr as OrmSchemaExtensionTables, Rt as MigrationWriteMode, S as ConvexNumberBuilder, Si as ColumnBuilderTypeConfig, Sn as rlsPolicy, Sr as MutationResult, St as MigrationRunChunkArgs, T as ConvexIdBuilder, Ti as DrizzleEntity, Tn as rlsRole, Tr as OrderByClause, Tt as MigrationDefinition, U as ConvexBooleanBuilderInitial, Un as vectorIndex, Ur as SystemFields, Ut as DatabaseWithMutations, V as bytes, Vn as searchIndex, Vr as OrmSchemaTriggers, Vt as defineMigrationSet, W as boolean, Wn as ConvexCheckBuilder, Wr as BinaryExpression, Wt as DatabaseWithQuery, X as CountBackfillStatusArgs, Xn as ConvexUniqueConstraintConfig, Xr as and, Xt as extractRelationsConfig, Y as CountBackfillKickoffArgs, Yn as ConvexUniqueConstraintBuilderOn, Yr as UnaryExpression, Yt as EdgeMetadata, Z as CreateOrmOptions, Zn as check, Zr as between, Zt as ExtractTablesFromSchema, _ as ConvexTimestampMode, _i as startsWith, _n as deletion, _r as MutationExecuteConfig, _t as OrmTriggerContext, a as requireSchemaRelations, ai as inArray, an as TablesRelationalConfig, ar as AggregateResult, at as OrmWriterCtx, b as ConvexTextEnumBuilderInitial, bi as ColumnBuilderBaseConfig, bn as RlsPolicyConfig, br as MutationPaginateConfig, bt as MigrationCancelArgs, c as TableConfigResult, ci as isNull, cn as ConvexDeletionBuilder, cr as CountConfig, ct as ScheduledMutationBatchArgs, d as OrmNotFoundError, di as lte, dn as ConvexTableWithColumns, dr as FilterOperators, dt as scheduledDeleteFactory, ei as eq, en as OneConfig, er as ConvexTextBuilder, et as OrmApiResult, f as ConvexVectorBuilder, fi as ne, fn as DiscriminatorBuilderConfig, fr as GetColumnData, ft as SchemaExtension, g as ConvexTimestampBuilderInitial, gi as or, gn as convexTable, gr as InsertValue, gt as OrmTriggerChange, h as ConvexTimestampBuilder, hi as notInArray, hn as TableConfig, hr as InferSelectModel, ht as OrmTableTriggers, i as getSchemaTriggers, ii as ilike, in as TableRelationalConfig, ir as AggregateFieldValue, it as OrmReaderCtx, j as date, jn as ConvexRankIndexBuilderOn, jr as ReturningSelection, jt as MigrationMigrateOne, k as ConvexDateBuilderInitial, ki as NotNull, kn as ConvexIndexBuilderOn, kr as ReturningAll, kt as MigrationDriftIssue, l as getTableColumns, li as like, ln as ConvexDeletionConfig, lr as CountResult, lt as scheduledMutationBatchFactory, m as vector, mi as notBetween, mn as OrmLifecycleOperation, mr as InferModelFromColumns, mt as OrmBeforeResult, n as defineSchema, ni as gt, nn as RelationsBuilderColumnBase, nr as text, nt as OrmClientWithApi$1, o as asc, oi as isFieldReference, on as defineRelations, or as BuildQueryResult, ot as ResolveOrmSchema, p as ConvexVectorBuilderInitial, pi as not, pn as OrmLifecycleChange, pr as InferInsertModel, pt as defineSchemaExtension, q as bigint, qn as ConvexForeignKeyConfig, qr as FilterExpression, qt as RlsContext, r as getSchemaRelations, ri as gte, rn as RelationsBuilderColumnConfig, rr as AggregateConfig, rt as OrmFunctions, s as desc, si as isNotNull, sn as defineRelationsPart, sr as BuildRelationResult, st as createOrm, t as WhereClauseResult, ti as fieldRef, tn as RelationsBuilder, tr as ConvexTextBuilderInitial, tt as OrmClientBase$1, u as getTableConfig, ui as lt, un as ConvexTable, ur as DBQueryConfig, ut as ScheduledDeleteArgs, v as timestamp, vi as AnyColumn, vn as discriminator, vr as MutationExecuteResult, vt as OrmTriggers, w as integer, wi as ColumnDataType, wn as RlsRoleConfig, wr as MutationRunMode, wt as MigrationAppliedState, x as textEnum, xi as ColumnBuilderRuntimeConfig, xn as RlsPolicyToOption, xr as MutationPaginatedResult, xt as MigrationRunArgs, y as ConvexTextEnumBuilder, yi as ColumnBuilder, yn as RlsPolicy, yr as MutationExecutionMode, yt as defineTriggers, z as ConvexBytesBuilder, zn as index, zr as OrmSchemaExtensions, zt as buildMigrationPlan } from "../where-clause-compiler-CmBz9CWA.js";
 import { i as pretendRequired, n as deprecated, r as pretend } from "../validators-BhsByJeg.js";
 import { a as QueryCtxWithPreferredOrmQueryTable, i as QueryCtxWithOrmQueryTable, n as LookupByIdResultByCtx, o as getByIdWithOrmQueryFallback, r as QueryCtxWithOptionalOrmQueryTable, t as DocByCtx } from "../query-context-CNo9ffvI.js";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchemaDefinition } from "convex/server";

package/dist/orm/index.js

@@ -1,6 +1,6 @@
 import { A as vectorIndex, B as ConvexColumnBuilder, C as RlsPolicy, D as rankIndex, E as index, F as arrayOf, I as custom, L as json, M as createSystemFields, N as integer, O as searchIndex, P as id, R as objectOf, S as TablePolymorphic, T as aggregateIndex, V as entityKind, _ as OrmSchemaRelations, a as deletion, b as TableDeleteConfig, c as Columns, d as OrmSchemaDefinition, f as OrmSchemaExtensionRelations, g as OrmSchemaOptions, h as OrmSchemaExtensions, i as convexTable, j as text, k as uniqueIndex, l as EnableRLS, m as OrmSchemaExtensionTriggers, o as discriminator, p as OrmSchemaExtensionTables, s as Brand, t as DirectAggregate, u as OrmContext, v as OrmSchemaTriggers, w as rlsPolicy, x as TableName, y as RlsPolicies, z as unionOf } from "../runtime-DmVSOe24.js";
 import { a as pretendRequired, i as pretend, n as deprecated } from "../validators-C7LelqTN.js";
-import { A as like, B as or, C as gt, D as isFieldReference, E as inArray, F as not, I as notBetween, L as notIlike, M as lte, N as matchLikePattern, O as isNotNull, P as ne, R as notInArray, S as filterValuesEqual, T as ilike, V as startsWith, _ as contains, a as indexKeyWithinBounds, b as fieldRef, c as streamIndexRange, d as and, f as arrayContained, g as column, h as between, i as getIndexFields, j as lt, k as isNull, l as isUnsetToken, m as arrayOverlaps, n as EmptyStream, o as mergedStream, p as arrayContains, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken, v as endsWith, w as gte, x as filterValueInList, y as eq, z as notLike } from "../query-context-CJE_hYA3.js";
+import { A as like, B as or, C as gt, D as isFieldReference, E as inArray, F as not, I as notBetween, L as notIlike, M as lte, N as matchLikePattern, O as isNotNull, P as ne, R as notInArray, S as filterValuesEqual, T as ilike, V as startsWith, _ as contains, a as indexKeyWithinBounds, b as fieldRef, c as streamIndexRange, d as and, f as arrayContained, g as column, h as between, i as getIndexFields, j as lt, k as isNull, l as isUnsetToken, m as arrayOverlaps, n as EmptyStream, o as mergedStream, p as arrayContains, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken, v as endsWith, w as gte, x as filterValueInList, y as eq, z as notLike } from "../query-context-BzihIpnM.js";
 import { compareValues, v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric } from "convex/server";
 
@@ -4585,6 +4585,42 @@ var BufferedQueryStream = class BufferedQueryStream extends QueryStream {
 		return this.equalityIndexFilter;
 	}
 };
+const ID_LIST_POSITION_FIELD = "__kitcn_id_list_position";
+/**
+* Reads an `id` / `id in [...]` where one document at a time, in the order the
+* ids were given.
+*
+* The index key is the position in the de-duplicated id list, so a cursor names
+* a position and `narrow` drops entries without reading them. A page reads only
+* the listed positions it visits, not every id in the list on every page.
+*/
+var LazyIdListQueryStream = class LazyIdListQueryStream extends QueryStream {
+	constructor(readId, entries, order) {
+		super();
+		this.readId = readId;
+		this.entries = entries;
+		this.order = order;
+	}
+	iterWithKeys() {
+		const entries = this.entries;
+		const readId = this.readId;
+		return { async *[Symbol.asyncIterator]() {
+			for (const [position, id] of entries) yield [await readId(id), [position]];
+		} };
+	}
+	narrow(indexBounds) {
+		return new LazyIdListQueryStream(this.readId, this.entries.filter(([position]) => indexKeyWithinBounds([position], indexBounds)), this.order);
+	}
+	getOrder() {
+		return this.order;
+	}
+	getIndexFields() {
+		return [ID_LIST_POSITION_FIELD];
+	}
+	getEqualityIndexFilter() {
+		return [];
+	}
+};
 const PIPELINE_LIMIT_ORDINAL_FIELD = "__kitcn_limit_ordinal";
 /** Cap a stream at its first `limit` matching documents without eager reads. */
 var LimitedMatchesQueryStream = class LimitedMatchesQueryStream extends QueryStream {
@@ -5787,9 +5823,12 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* The where-clause compiler is built from declared indexes only, and `_id` is
 	* never one of them, so an `id` filter can never be index-selected: it lands
 	* in the post-filters and the stream walks the creation-time index until it
-	* happens on the row. `db.get()` reads exactly the rows asked for, so the ids
-	* are fetched directly and replayed as a creation-time-ordered stream — the
-	* order the scan would have produced, so stage order and cursors are the same.
+	* happens on the row. `db.get()` reads exactly the rows asked for.
+	*
+	* Rows come back in the order the ids were given, one read at a time. Missing
+	* or policy-filtered ids still cost a read, but a page does not reread the
+	* complete list. An `orderBy` on creation time is the exception: an id carries
+	* no creation time, so every id must be read before the first row is placed.
 	*
 	* Returns null when something else already owns the read: a pinned index, an
 	* index the compiler did select, a `where(predicate)`, or an `orderBy` that
@@ -5801,13 +5840,26 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const primaryOrder = queryConfig.order?.[0];
 		if (primaryOrder && primaryOrder.field !== INTERNAL_CREATION_TIME_FIELD) return null;
 		const ids = idLookup.kind === "in" ? Array.from(new Map(idLookup.ids.map((id) => [String(id), id])).values()) : [idLookup.id];
-		const rows = (await this._mapWithConcurrency(ids, async (id) => {
-			return this._getById(this.tableConfig.name, id);
-		})).filter((row) => !!row);
+		const readId = (id) => this._getById(this.tableConfig.name, id);
+		if (!primaryOrder) {
+			const entries = ids.map((id, position) => [position, id]);
+			if (order === "desc") entries.reverse();
+			return new LazyIdListQueryStream(readId, entries, order);
+		}
+		const rows = (await this._mapWithConcurrency(ids, readId)).filter((row) => !!row);
 		rows.sort((a, b) => compareValues(a[INTERNAL_CREATION_TIME_FIELD], b[INTERNAL_CREATION_TIME_FIELD]) || compareValues(a[INTERNAL_ID_FIELD], b[INTERNAL_ID_FIELD]));
 		if (order === "desc") rows.reverse();
 		return new BufferedQueryStream(rows.map((row) => [row, [row[INTERNAL_CREATION_TIME_FIELD], row[INTERNAL_ID_FIELD]]]), order, [INTERNAL_CREATION_TIME_FIELD, INTERNAL_ID_FIELD], []);
 	}
+	/**
+	* The declared index a stream read can walk to emit `field` in order.
+	*
+	* A stream orders by the index it scans, so only an index that leads with
+	* the field produces that order.
+	*/
+	_findStreamOrderIndex(field) {
+		return getIndexes(this.tableConfig.table).find((index) => index.fields[0] === field);
+	}
 	_buildBasePipelineStream(queryConfig, wherePredicate, configuredIndex) {
 		const schemaDefinition = this._getSchemaDefinitionOrThrow();
 		let streamQuery = stream(this.db, schemaDefinition).query(this.tableConfig.name);
@@ -5819,8 +5871,8 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			return indexQuery;
 		});
 		else if (configuredIndex?.name) streamQuery = streamQuery.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
-		else if (primaryOrder && primaryOrder.field !== "_creationTime") {
-			const orderIndex = getIndexes(this.tableConfig.table).find((idx) => idx.fields[0] === primaryOrder.field);
+		else if (primaryOrder && primaryOrder.field !== INTERNAL_CREATION_TIME_FIELD) {
+			const orderIndex = this._findStreamOrderIndex(primaryOrder.field);
 			if (orderIndex) streamQuery = streamQuery.withIndex(orderIndex.name, (q) => q);
 		}
 		streamQuery = streamQuery.order(primaryOrderDirection);
@@ -6978,7 +7030,11 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					streamQuery = mergedStream(streams, pipeline.interleaveBy.map((field) => this._normalizePublicFieldName(field)));
 				}
 			} else {
-				if (isCursorPaginated && maxScan !== void 0 && idLookup?.kind === "in") throw new Error("An id IN pipeline cannot use maxScan because creation-order replay requires reading the complete ID list.");
+				const orderedIdList = isCursorPaginated && maxScan !== void 0 && idLookup?.kind === "in" ? queryConfig.order?.[0] : void 0;
+				if (orderedIdList) {
+					if (orderedIdList.field === INTERNAL_CREATION_TIME_FIELD) throw new Error("An id IN pipeline cannot combine orderBy on createdAt with maxScan, because ordering an id list by creation time requires reading every id in the list. Drop maxScan, or drop orderBy to page in id-list order at one read per row.");
+					if (queryConfig.order?.length !== 1 || configuredIndex?.name || queryConfig.index || !this._findStreamOrderIndex(orderedIdList.field)) throw new Error(`An id IN pipeline cannot combine orderBy on ${this._toPublicFilterFieldName(orderedIdList.field)} with maxScan, because the scan cannot produce that order. It needs a single orderBy field that an index leads with, and no index pinned by withIndex().`);
+				}
 				streamQuery = await this._buildIdLookupStream({
 					configuredIndex,
 					idLookup,

package/dist/{query-context-CJE_hYA3.js → query-context-BzihIpnM.js}

@@ -528,11 +528,19 @@ function getIndexFields(table, index, schema) {
 	fields.push("_id");
 	return fields;
 }
-function getIndexKey(doc, indexFields) {
+/**
+* Read the index key out of a document.
+*
+* Takes field paths already split on `.` rather than the field names: the field
+* list is fixed for the life of a query, so splitting it once at `withIndex`
+* time saves an array allocation per field per document pulled through the
+* stream.
+*/
+function getIndexKey(doc, indexFieldPaths) {
 	const key = [];
-	for (const field of indexFields) {
+	for (const path of indexFieldPaths) {
 		let obj = doc;
-		for (const subfield of field.split(".")) obj = obj[subfield];
+		for (const subfield of path) obj = obj[subfield];
 		key.push(obj);
 	}
 	return key;
@@ -729,17 +737,26 @@ var QueryStream = class {
 	}
 	[Symbol.asyncIterator]() {
 		const iterator = this.iterWithKeys()[Symbol.asyncIterator]();
-		return { async next() {
-			const result = await iterator.next();
-			if (result.done) return {
-				done: true,
-				value: void 0
-			};
-			return {
-				done: false,
-				value: result.value[0]
-			};
-		} };
+		return {
+			async next() {
+				const result = await iterator.next();
+				if (result.done) return {
+					done: true,
+					value: void 0
+				};
+				return {
+					done: false,
+					value: result.value[0]
+				};
+			},
+			async return() {
+				await iterator.return?.();
+				return {
+					done: true,
+					value: void 0
+				};
+			}
+		};
 	}
 };
 var StreamDatabaseReader = class {
@@ -858,6 +875,7 @@ var OrderedStreamQuery = class extends StreamableQuery {
 			table: this.parent.parent.table,
 			index: this.parent.index,
 			indexFields: this.parent.q.indexFields,
+			indexFieldPaths: this.parent.q.indexFieldPaths,
 			order: this.order,
 			bounds: {
 				lowerBound: this.parent.q.lowerBoundIndexKey ?? [],
@@ -876,7 +894,7 @@ var OrderedStreamQuery = class extends StreamableQuery {
 		return db.query(table).withIndex(index, indexRange).order(order);
 	}
 	iterWithKeys() {
-		const { indexFields } = this.reflect();
+		const { indexFieldPaths } = this.reflect();
 		const iterable = this.inner();
 		return { [Symbol.asyncIterator]() {
 			const iterator = iterable[Symbol.asyncIterator]();
@@ -888,7 +906,7 @@ var OrderedStreamQuery = class extends StreamableQuery {
 				};
 				return {
 					done: false,
-					value: [result.value, getIndexKey(result.value, indexFields)]
+					value: [result.value, getIndexKey(result.value, indexFieldPaths)]
 				};
 			} };
 		} };
@@ -950,8 +968,11 @@ var ReflectIndexRange = class {
 	upperBoundInclusive = true;
 	equalityIndexFilter = [];
 	indexFields;
+	/** `indexFields`, each split on `.` once, for `getIndexKey`. */
+	indexFieldPaths;
 	constructor(indexFields) {
 		this.indexFields = indexFields;
+		this.indexFieldPaths = indexFields.map((field) => field.split("."));
 	}
 	eq(field, value) {
 		if (!this.#canLowerBound(field) || !this.#canUpperBound(field)) throw new Error(`Cannot use eq on field '${field}'`);
@@ -1043,16 +1064,24 @@ var ReflectIndexRange = class {
 function mergedStream(streams, orderByIndexFields) {
 	return new MergedStream(streams, orderByIndexFields);
 }
+/**
+* Marks sources that are already `OrderByStream`s, so `narrow` reuses them
+* instead of adding a redundant delegation layer per call.
+*
+* Module-private on purpose: wrapping is also where the ordering invariant is
+* checked, so no caller outside this file can skip it.
+*/
+const PRE_ORDERED_STREAMS = Symbol("preOrderedStreams");
 var MergedStream = class MergedStream extends QueryStream {
 	#order;
 	#streams;
 	#equalityIndexFilter;
 	#indexFields;
-	constructor(streams, orderByIndexFields) {
+	constructor(streams, orderByIndexFields, preOrdered) {
 		super();
 		if (streams.length === 0) throw new Error("Cannot union empty array of streams");
 		this.#order = allSame(streams.map((stream) => stream.getOrder()), "Cannot merge streams with different orders");
-		this.#streams = streams.map((stream) => new OrderByStream(stream, orderByIndexFields));
+		this.#streams = preOrdered === PRE_ORDERED_STREAMS ? streams : streams.map((stream) => new OrderByStream(stream, orderByIndexFields.slice()));
 		this.#indexFields = allSame(this.#streams.map((stream) => stream.getIndexFields()), "Cannot merge streams with different index fields. Consider using .orderBy()");
 		this.#equalityIndexFilter = commonPrefix(this.#streams.map((stream) => stream.getEqualityIndexFilter()));
 	}
@@ -1065,40 +1094,60 @@ var MergedStream = class MergedStream extends QueryStream {
 				done: false,
 				value: void 0
 			}));
-			return { async next() {
-				await Promise.all(iterators.map(async (iterator, i) => {
-					if (!results[i].done && !results[i].value) results[i] = await iterator.next();
-				}));
-				let minIndexKeyAndIndex;
-				for (let i = 0; i < results.length; i++) {
-					const result = results[i];
-					if (result.done || !result.value) continue;
-					const [_, resultIndexKey] = result.value;
-					if (minIndexKeyAndIndex === void 0) {
-						minIndexKeyAndIndex = [resultIndexKey, i];
-						continue;
+			let started = false;
+			let refillIndex;
+			return {
+				async next() {
+					if (started) {
+						if (refillIndex !== void 0) {
+							results[refillIndex] = await iterators[refillIndex].next();
+							refillIndex = void 0;
+						}
+					} else {
+						started = true;
+						await Promise.all(iterators.map(async (iterator, i) => {
+							results[i] = await iterator.next();
+						}));
 					}
-					const [prevMin, _prevMinIndex] = minIndexKeyAndIndex;
-					if (compareKeys({
-						value: resultIndexKey,
-						kind: "exact"
-					}, {
-						value: prevMin,
-						kind: "exact"
-					}) * comparisonInversion < 0) minIndexKeyAndIndex = [resultIndexKey, i];
+					let minIndexKeyAndIndex;
+					for (let i = 0; i < results.length; i++) {
+						const result = results[i];
+						if (result.done || !result.value) continue;
+						const [_, resultIndexKey] = result.value;
+						if (minIndexKeyAndIndex === void 0) {
+							minIndexKeyAndIndex = [resultIndexKey, i];
+							continue;
+						}
+						const [prevMin, _prevMinIndex] = minIndexKeyAndIndex;
+						if (compareKeys({
+							value: resultIndexKey,
+							kind: "exact"
+						}, {
+							value: prevMin,
+							kind: "exact"
+						}) * comparisonInversion < 0) minIndexKeyAndIndex = [resultIndexKey, i];
+					}
+					if (minIndexKeyAndIndex === void 0) return {
+						done: true,
+						value: void 0
+					};
+					const [_, minIndex] = minIndexKeyAndIndex;
+					const result = results[minIndex].value;
+					results[minIndex].value = void 0;
+					refillIndex = minIndex;
+					return {
+						done: false,
+						value: result
+					};
+				},
+				async return() {
+					await Promise.all(iterators.map((iterator) => iterator.return?.()));
+					return {
+						done: true,
+						value: void 0
+					};
 				}
-				if (minIndexKeyAndIndex === void 0) return {
-					done: true,
-					value: void 0
-				};
-				const [_, minIndex] = minIndexKeyAndIndex;
-				const result = results[minIndex].value;
-				results[minIndex].value = void 0;
-				return {
-					done: false,
-					value: result
-				};
-			} };
+			};
 		} };
 	}
 	getOrder() {
@@ -1111,7 +1160,7 @@ var MergedStream = class MergedStream extends QueryStream {
 		return this.#indexFields;
 	}
 	narrow(indexBounds) {
-		return new MergedStream(this.#streams.map((stream) => stream.narrow(indexBounds)), this.#indexFields);
+		return new MergedStream(this.#streams.map((stream) => stream.narrow(indexBounds)), this.#indexFields, PRE_ORDERED_STREAMS);
 	}
 };
 function allSame(values, errorMessage) {
@@ -1159,16 +1208,22 @@ var ConcatStreams = class ConcatStreams extends QueryStream {
 		this.#equalityIndexFilter = commonPrefix(streams.map((stream) => stream.getEqualityIndexFilter()));
 	}
 	iterWithKeys() {
-		const iterables = this.#streams.map((stream) => stream.iterWithKeys());
+		const streams = this.#streams;
 		const comparisonInversion = this.#order === "asc" ? 1 : -1;
-		let previousIndexKey;
 		return { [Symbol.asyncIterator]() {
-			const iterators = iterables.map((iterable) => iterable[Symbol.asyncIterator]());
-			return { async next() {
-				while (iterators.length > 0) {
-					const result = await iterators[0].next();
-					if (result.done) iterators.shift();
-					else {
+			let index = 0;
+			let iterator;
+			let previousIndexKey;
+			return {
+				async next() {
+					while (index < streams.length) {
+						iterator ??= streams[index].iterWithKeys()[Symbol.asyncIterator]();
+						const result = await iterator.next();
+						if (result.done) {
+							index++;
+							iterator = void 0;
+							continue;
+						}
 						const [_, indexKey] = result.value;
 						if (previousIndexKey !== void 0 && compareKeys({
 							value: previousIndexKey,
@@ -1180,12 +1235,21 @@ var ConcatStreams = class ConcatStreams extends QueryStream {
 						previousIndexKey = indexKey;
 						return result;
 					}
+					return {
+						done: true,
+						value: void 0
+					};
+				},
+				async return() {
+					await iterator?.return?.();
+					index = streams.length;
+					iterator = void 0;
+					return {
+						done: true,
+						value: void 0
+					};
 				}
-				return {
-					done: true,
-					value: void 0
-				};
-			} };
+			};
 		} };
 	}
 	getOrder() {
@@ -1258,6 +1322,18 @@ var FlatMapStreamIterator = class {
 			value: [u, [...this.#currentOuterItem.indexKey, ...indexKey]]
 		};
 	}
+	async return() {
+		try {
+			await this.#currentOuterItem?.innerIterator.return?.();
+		} finally {
+			this.#currentOuterItem = null;
+			await this.#outerIterator.return?.();
+		}
+		return {
+			done: true,
+			value: void 0
+		};
+	}
 };
 var FlatMapStream = class FlatMapStream extends QueryStream {
 	#stream;
@@ -1477,15 +1553,24 @@ var OrderByStream = class OrderByStream extends QueryStream {
 		const staticFilter = this.#staticFilter;
 		return { [Symbol.asyncIterator]() {
 			const iterator = iterable[Symbol.asyncIterator]();
-			return { async next() {
-				const result = await iterator.next();
-				if (result.done) return result;
-				const [doc, indexKey] = result.value;
-				return {
-					done: false,
-					value: [doc, indexKey.slice(staticFilter.length)]
-				};
-			} };
+			return {
+				async next() {
+					const result = await iterator.next();
+					if (result.done) return result;
+					const [doc, indexKey] = result.value;
+					return {
+						done: false,
+						value: [doc, indexKey.slice(staticFilter.length)]
+					};
+				},
+				async return() {
+					await iterator.return?.();
+					return {
+						done: true,
+						value: void 0
+					};
+				}
+			};
 		} };
 	}
 	narrow(indexBounds) {
@@ -1516,36 +1601,57 @@ var DistinctStream = class DistinctStream extends QueryStream {
 	iterWithKeys() {
 		const stream = this.#stream;
 		const distinctIndexFieldsLength = this.#distinctIndexFieldsLength;
+		const order = stream.getOrder();
+		const comparisonInversion = order === "asc" ? 1 : -1;
 		return { [Symbol.asyncIterator]() {
-			let currentStream = stream;
-			let currentIterator = currentStream.iterWithKeys()[Symbol.asyncIterator]();
-			return { async next() {
-				const result = await currentIterator.next();
-				if (result.done) return {
-					done: true,
-					value: void 0
-				};
-				const [doc, indexKey] = result.value;
-				if (doc === null) return {
-					done: false,
-					value: [null, indexKey]
-				};
-				const distinctIndexKey = indexKey.slice(0, distinctIndexFieldsLength);
-				if (stream.getOrder() === "asc") currentStream = currentStream.narrow({
-					lowerBound: distinctIndexKey,
-					lowerBoundInclusive: false,
-					upperBound: [],
-					upperBoundInclusive: true
-				});
-				else currentStream = currentStream.narrow({
-					lowerBound: [],
-					lowerBoundInclusive: true,
-					upperBound: distinctIndexKey,
-					upperBoundInclusive: false
-				});
-				currentIterator = currentStream.iterWithKeys()[Symbol.asyncIterator]();
-				return result;
-			} };
+			let currentIterator = stream.iterWithKeys()[Symbol.asyncIterator]();
+			let previousDistinctIndexKey;
+			return {
+				async next() {
+					const result = await currentIterator.next();
+					if (result.done) return {
+						done: true,
+						value: void 0
+					};
+					const [doc, indexKey] = result.value;
+					if (doc === null) return {
+						done: false,
+						value: [null, indexKey]
+					};
+					const distinctIndexKey = indexKey.slice(0, distinctIndexFieldsLength);
+					if (previousDistinctIndexKey !== void 0 && compareKeys({
+						value: previousDistinctIndexKey,
+						kind: "exact"
+					}, {
+						value: distinctIndexKey,
+						kind: "exact"
+					}) * comparisonInversion >= 0) throw new Error(`DistinctStream in wrong order: ${JSON.stringify(previousDistinctIndexKey)}, ${JSON.stringify(distinctIndexKey)}`);
+					previousDistinctIndexKey = distinctIndexKey;
+					let narrowed;
+					if (order === "asc") narrowed = stream.narrow({
+						lowerBound: distinctIndexKey,
+						lowerBoundInclusive: false,
+						upperBound: [],
+						upperBoundInclusive: true
+					});
+					else narrowed = stream.narrow({
+						lowerBound: [],
+						lowerBoundInclusive: true,
+						upperBound: distinctIndexKey,
+						upperBoundInclusive: false
+					});
+					await currentIterator.return?.();
+					currentIterator = narrowed.iterWithKeys()[Symbol.asyncIterator]();
+					return result;
+				},
+				async return() {
+					await currentIterator.return?.();
+					return {
+						done: true,
+						value: void 0
+					};
+				}
+			};
 		} };
 	}
 	narrow(indexBounds) {

package/dist/{where-clause-compiler-B1weGkP4.d.ts → where-clause-compiler-CmBz9CWA.d.ts}

@@ -2539,15 +2539,25 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * The where-clause compiler is built from declared indexes only, and `_id` is
    * never one of them, so an `id` filter can never be index-selected: it lands
    * in the post-filters and the stream walks the creation-time index until it
-   * happens on the row. `db.get()` reads exactly the rows asked for, so the ids
-   * are fetched directly and replayed as a creation-time-ordered stream — the
-   * order the scan would have produced, so stage order and cursors are the same.
+   * happens on the row. `db.get()` reads exactly the rows asked for.
+   *
+   * Rows come back in the order the ids were given, one read at a time. Missing
+   * or policy-filtered ids still cost a read, but a page does not reread the
+   * complete list. An `orderBy` on creation time is the exception: an id carries
+   * no creation time, so every id must be read before the first row is placed.
    *
    * Returns null when something else already owns the read: a pinned index, an
    * index the compiler did select, a `where(predicate)`, or an `orderBy` that
    * walks a different index.
    */
   private _buildIdLookupStream;
+  /**
+   * The declared index a stream read can walk to emit `field` in order.
+   *
+   * A stream orders by the index it scans, so only an index that leads with
+   * the field produces that order.
+   */
+  private _findStreamOrderIndex;
   private _buildBasePipelineStream;
   /**
    * Stream equivalent of the `db.query(...)` chain, used when a post-fetch
@@ -4367,6 +4377,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_state: ConvexTableWithColumns<{
     name: "aggregate_state";
     columns: {
+      status: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "status";
+        };
+      };
       kind: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -4454,19 +4477,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "metricDefinitionHash";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_state";
-        };
-      } & {
-        _: {
-          fieldName: "status";
-        };
-      };
       processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -4521,38 +4531,38 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly migration_state: ConvexTableWithColumns<{
     name: "migration_state";
     columns: {
-      cursor: ConvexTextBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "status";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "cursor";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "direction";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4562,7 +4572,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "updatedAt";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {
@@ -4675,7 +4685,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly migration_run: ConvexTableWithColumns<{
     name: "migration_run";
     columns: {
-      direction: ConvexTextBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4685,10 +4695,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "status";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4698,10 +4708,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "direction";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4711,7 +4721,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "updatedAt";
         };
       };
       startedAt: ConvexNumberBuilderInitial<""> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",

package/skills/kitcn/references/features/orm.md

@@ -721,7 +721,7 @@ const filtered = results.filter((a) => a.publishedAt >= startDate);
 ### Performance
 
 1. **Index first** — constrain leading index fields. Compound indexes follow prefix rules. Put the `orderBy` column right after the constrained prefix so the scan is already sorted and `limit` bounds the read.
-2. **Bound scans** — use `maxScan` for predicate `where` (cursor mode only).
+2. **Bound scans** — use `maxScan` for predicate `where` (cursor mode only). A `.select()` ID-list query with `orderBy` needs a single field that an index leads with.
 3. **Limit results** — always use `limit` or cursor pagination.
 4. **Cursor stability** — keep same `where`/`orderBy` between page requests.
 5. **`allowFullScan`** — non-cursor only. Cursor mode uses `maxScan` instead.