kitcn 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # kitcn
 
+## 0.32.0
+
+### Minor Changes
+
+- [#425](https://github.com/udecode/kitcn/pull/425) [`495eb0b`](https://github.com/udecode/kitcn/commit/495eb0b2bd285484250ca69d75de135287531bbb) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Breaking changes
+
+  - Cursor pages for an index-union filter with no `orderBy` are now in the order of the index the read walks, grouped by the probed value, instead of creation order. Add `orderBy` to keep newest-first paging.
+
+  ```ts
+  // Before
+  const page = await db.query.users.withIndex("by_status").findMany({
+    where: { status: { in: ["active", "pending"] } },
+    cursor: null,
+    limit: 20,
+    maxScan: 500,
+  });
+
+  // After
+  const page = await db.query.users.withIndex("by_status").findMany({
+    where: { status: { in: ["active", "pending"] } },
+    orderBy: { createdAt: "desc" },
+    cursor: null,
+    limit: 20,
+  });
+  ```
+
+  ## Features
+
+  - Page `in`, `notIn`, `ne`, and same-field equality `OR` filters from one index range per value instead of scanning the table. Cursor pagination over these filters no longer needs `maxScan`, and `orderBy` sorts across the whole result rather than per value.
+
+  ## Patches
+
+  - Fix `select()` composition and `endCursor` pagination reading a whole index instead of the compiled index ranges when the filter is an index union.
+  - Keep no-`orderBy` cursor direction consistent when `endCursor` routes an index union through the advanced stream path.
+  - Prevent `endCursor` narrowing from reopening disjoint equality ranges and duplicating merged-stream rows.
+  - Fix cursor pagination with a residual post-filter reading a whole index instead of the compiled index ranges when the filter is an index union.
+  - Fall back to a bounded scan when the probed index cannot supply the requested `orderBy` or the union is wider than 64 ranges.
+
+### Patch Changes
+
+- [#426](https://github.com/udecode/kitcn/pull/426) [`466623c`](https://github.com/udecode/kitcn/commit/466623c8b581c38a066fa078309d25cfab166ea7) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Fix a multi-field `orderBy` reading the whole table even when a declared
+    compound index already produces that exact order. `orderBy: [asc(type),
+asc(numLikes)]` with `limit: 5` against an index on `(type, numLikes)` now
+    reads 5 documents instead of every row, at any table size — previously the
+    read cost was the same whether you asked for 5 rows or 50. The same bound
+    applies to relations: `with: { posts: { orderBy: { numLikes: 'asc' },
+limit: 2 } }` now reads 2 children per parent instead of all of them.
+  - Prefer an index that supplies more of the requested sort when several serve
+    the filter equally well, so `(orgId, createdAt, title)` is chosen over
+    `(orgId, createdAt)` for a sort on both `createdAt` and `title`. An index with
+    another unrequested key after `title` is not treated as an exact sort because
+    that key would change which tied rows survive `limit`.
+  - Stop warning that secondary `orderBy` fields are unstable across pages when
+    the index carries the whole sort. A Convex cursor is the index key, so those
+    pages are stable. The warning still fires — with corrected wording — when no
+    index serves the full sort and the extra fields really are dropped.
+  - Sorts that mix directions, skip an index key, or run over a column that can
+    be missing or null keep using the post-fetch sort, so row order and null
+    placement are unchanged.
+  - Use Convex value ordering for non-null post-fetch values, including UTF-8
+    strings, signed zero, and NaN, so an index-backed top-k and its post-fetch
+    fallback select the same rows.
+  - Preserve the existing implicit creation-time tie order when an
+    equality-pinned leading sort field points opposite to the moving fields.
+    Add `createdAt` in the moving direction to make that sort index-bounded.
+
+## 0.31.1
+
+### Patch Changes
+
+- [#424](https://github.com/udecode/kitcn/pull/424) [`0e3a221`](https://github.com/udecode/kitcn/commit/0e3a2214e8e1037b323e603f19c2df89b0d95602) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Stop `aggregateBackfill` rewriting the stored state it is about to delete.
+    Clearing a `rankIndex` walked the btree once per member — a root-to-leaf
+    descent plus a patch on every node along the way — and then dropped the whole
+    tree regardless, so all of that work was thrown away. Clearing an
+    `aggregateIndex` did the same thing with buckets, decrementing each one down to
+    zero before deleting it. Both now delete their member rows outright and let the
+    existing tree and bucket sweeps reclaim the rest. Clearing 120 rank members
+    across three partitions went from 201 btree node writes to 15, one per node.
+  - Fix a `rankIndex` clear crashing with `Unexpected field 'deletionStack'` once a
+    partition holds more than a few hundred rows. The rank storage tables now
+    reuse the same definitions the btree writes to, so a large tree can persist its
+    traversal state and resume across mutations. Run
+    `npx convex dev` (or your usual codegen) to pick the schema up.
+  - Report real work from a clear chunk instead of a fixed guess, so
+    `aggregateBackfill --batch-size` now bounds a clear by the documents it
+    actually touches. Multi-partition rank indexes no longer schedule far more
+    chunks than the remaining work needs.
+  - Allow an app to declare `aggregateStorageTables` from `kitcn/aggregate`
+    alongside a table that also declares a `rankIndex`. `defineSchema` used to
+    reject that combination as a duplicate table name.
+
 ## 0.31.0
 
 ### Minor Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
-import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-DPB-JKlm.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-Dddhscyy.js";
+import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-CD-Ij91k.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-FDJTqLDC.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";
@@ -136,6 +136,10 @@ declare const aggregateStorageTables: {
 //#endregion
 //#region src/aggregate-core/btree.d.ts
 type Key$2 = Value;
+type DeleteTreesResult = {
+  /** True once this aggregate owns no tree row at all. */done: boolean; /** Documents this call wrote, so callers can charge a real work budget. */
+  documents: number;
+};
 //#endregion
 //#region src/aggregate-core/positions.d.ts
 type Bound$1<K extends Key$2, ID extends string> = {
@@ -240,11 +244,12 @@ declare class Aggregate<K extends Key, ID extends string, TNamespace extends Val
     rootLazy?: boolean;
   }, TNamespace>): Promise<void>;
   /**
-   * Deletes up to `limit` namespace trees without recreating them. Returns true
-   * once this aggregate owns no trees, so callers can drain every namespace
-   * across several mutations instead of walking them all in one.
+   * Deletes up to `limit` nodes from one namespace tree without recreating it,
+   * reporting `done` once this aggregate owns no trees and how many documents
+   * the call wrote. Callers drain every namespace across several mutations
+   * instead of walking them all in one, and charge their budget by `documents`.
    */
-  deleteTrees(ctx: RunMutationCtx, limit: number): Promise<boolean>;
+  deleteTrees(ctx: RunMutationCtx, limit: number): Promise<DeleteTreesResult>;
   makeRootLazy(ctx: RunMutationCtx, namespace: TNamespace): Promise<void>;
   paginateNamespaces(ctx: RunQueryCtx, cursor?: string, pageSize?: number): Promise<{
     cursor: string;

package/dist/aggregate/index.js

@@ -1,4 +1,5 @@
-import { n as TableAggregate$1, r as aggregateStorageTables, t as DirectAggregate$1 } from "../runtime-BcvcfaP8.js";
+import { n as TableAggregate$1, t as DirectAggregate$1 } from "../runtime-B-8HKSIE.js";
+import { i as aggregateStorageTables } from "../schema-BFP_awgP.js";
 
 //#region src/aggregate/index.ts
 const wrapTriggerFactory = (methodName, factory) => ((...args) => {

package/dist/auth/generated/index.d.ts

@@ -1,2 +1,2 @@
-import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, b as GenericAuthBeforeResult, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../../generated-contract-disabled-CTUQ9nxL.js";
+import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, b as GenericAuthBeforeResult, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../../generated-contract-disabled-PdNGvNYP.js";
 export { type AuthRuntime, BetterAuthOptionsWithoutDatabase, type GeneratedAuthDisabledReasonKind, GenericAuthBeforeResult, GenericAuthDefinition, GenericAuthTriggerChange, GenericAuthTriggerHandlers, GenericAuthTriggers, createDisabledAuthRuntime, defineAuth, getGeneratedAuthDisabledReason };

package/dist/auth/index.d.ts

@@ -1,7 +1,7 @@
 import { a as QueryCtxWithPreferredOrmQueryTable, n as LookupByIdResultByCtx, t as DocByCtx } from "../query-context-BkNjkDCk.js";
 import { t as GetAuth } from "../types-ex0-J-SC.js";
 import { t as GenericCtx } from "../context-utils-Cbv4r0AA.js";
-import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, _ as updateManyHandler, a as AuthFunctions, b as GenericAuthBeforeResult, c as consumeOneHandler, d as createHandler, f as deleteManyHandler, g as incrementOneHandler, h as findOneHandler, i as getGeneratedAuthDisabledReason, l as countHandler, m as findManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as deleteOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as createApi, v as updateOneHandler, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../generated-contract-disabled-CTUQ9nxL.js";
+import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, _ as updateManyHandler, a as AuthFunctions, b as GenericAuthBeforeResult, c as consumeOneHandler, d as createHandler, f as deleteManyHandler, g as incrementOneHandler, h as findOneHandler, i as getGeneratedAuthDisabledReason, l as countHandler, m as findManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as deleteOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as createApi, v as updateOneHandler, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../generated-contract-disabled-PdNGvNYP.js";
 import * as convex_values0 from "convex/values";
 import { Infer } from "convex/values";
 import { AuthConfig, DocumentByName, GenericDataModel, GenericMutationCtx, GenericQueryCtx, GenericSchema, PaginationOptions, PaginationResult, SchemaDefinition, TableNamesInDataModel } from "convex/server";
@@ -109,28 +109,28 @@ type AdapterPaginationOptions = PaginationOptions & {
 };
 declare const adapterWhereValidator: convex_values0.VObject<{
   mode?: "sensitive" | "insensitive" | undefined;
-  operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
   connector?: "AND" | "OR" | undefined;
-  value: string | number | boolean | string[] | number[] | null;
+  operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
   field: string;
+  value: string | number | boolean | string[] | number[] | null;
 }, {
   connector: convex_values0.VUnion<"AND" | "OR" | undefined, [convex_values0.VLiteral<"AND", "required">, convex_values0.VLiteral<"OR", "required">], "optional", never>;
   field: convex_values0.VString<string, "required">;
   mode: convex_values0.VUnion<"sensitive" | "insensitive" | undefined, [convex_values0.VLiteral<"sensitive", "required">, convex_values0.VLiteral<"insensitive", "required">], "optional", never>;
-  operator: convex_values0.VUnion<"eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
+  operator: convex_values0.VUnion<"lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
   value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
-}, "required", "mode" | "operator" | "value" | "field" | "connector">;
+}, "required", "mode" | "connector" | "field" | "operator" | "value">;
 declare const adapterArgsValidator: convex_values0.VObject<{
-  limit?: number | undefined;
   where?: {
     mode?: "sensitive" | "insensitive" | undefined;
-    operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
     connector?: "AND" | "OR" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
+    operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
     field: string;
+    value: string | number | boolean | string[] | number[] | null;
   }[] | undefined;
-  select?: string[] | undefined;
+  limit?: number | undefined;
   offset?: number | undefined;
+  select?: string[] | undefined;
   sortBy?: {
     field: string;
     direction: "asc" | "desc";
@@ -150,24 +150,24 @@ declare const adapterArgsValidator: convex_values0.VObject<{
   }, "optional", "field" | "direction">;
   where: convex_values0.VArray<{
     mode?: "sensitive" | "insensitive" | undefined;
-    operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
     connector?: "AND" | "OR" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
+    operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
     field: string;
+    value: string | number | boolean | string[] | number[] | null;
   }[] | undefined, convex_values0.VObject<{
     mode?: "sensitive" | "insensitive" | undefined;
-    operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
     connector?: "AND" | "OR" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
+    operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
     field: string;
+    value: string | number | boolean | string[] | number[] | null;
   }, {
     connector: convex_values0.VUnion<"AND" | "OR" | undefined, [convex_values0.VLiteral<"AND", "required">, convex_values0.VLiteral<"OR", "required">], "optional", never>;
     field: convex_values0.VString<string, "required">;
     mode: convex_values0.VUnion<"sensitive" | "insensitive" | undefined, [convex_values0.VLiteral<"sensitive", "required">, convex_values0.VLiteral<"insensitive", "required">], "optional", never>;
-    operator: convex_values0.VUnion<"eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
+    operator: convex_values0.VUnion<"lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
     value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
-  }, "required", "mode" | "operator" | "value" | "field" | "connector">, "optional">;
-}, "required", "limit" | "where" | "model" | "select" | "offset" | "sortBy" | "sortBy.field" | "sortBy.direction">;
+  }, "required", "mode" | "connector" | "field" | "operator" | "value">, "optional">;
+}, "required", "model" | "where" | "limit" | "offset" | "select" | "sortBy" | "sortBy.field" | "sortBy.direction">;
 declare const hasUniqueFields: (betterAuthSchema: BetterAuthDBSchema, model: string, input: Record<string, any>) => boolean;
 declare const checkUniqueFields: <Schema extends SchemaDefinition<any, any>>(ctx: GenericQueryCtx<GenericDataModel>, schema: Schema, betterAuthSchema: BetterAuthDBSchema, table: string, input: Record<string, any>, doc?: Record<string, any>) => Promise<void>;
 declare const selectFields: <T extends TableNamesInDataModel<GenericDataModel>, D extends DocumentByName<GenericDataModel, T>>(doc: D | null, select?: string[]) => D | null;

package/dist/auth/index.js

@@ -3,8 +3,8 @@ import { r as partial } from "../validators-CIoUYCqO.js";
 import { i as defineAuth, n as createDisabledAuthRuntime, r as getGeneratedAuthDisabledReason, t as DEFAULT_AUTH_DEFINITION_PATH } from "../generated-contract-disabled-RyPYlwq0.js";
 import { n as createGeneratedFunctionReference, o as isQueryCtx, s as isRunMutationCtx } from "../api-entry-Buvjl9hn.js";
 import { i as customQuery, n as customCtx, r as customMutation } from "../customFunctions-X_B4kET8.js";
-import { C as eq, o as getAggregateIndexes } from "../index-utils-C1DyktHe.js";
-import { o as mergedStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken } from "../query-context-DdSg3fuk.js";
+import { C as eq, o as getAggregateIndexes } from "../index-utils-DvK7P6Q1.js";
+import { o as mergedStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken } from "../query-context-D4z1CnDH.js";
 import { n as convex } from "../convex-plugin-AbNQl1Sg.js";
 import { v } from "convex/values";
 import { internalActionGeneric, internalMutationGeneric, internalQueryGeneric, paginationOptsValidator } from "convex/server";

package/dist/{capabilities-DPB-JKlm.d.ts → capabilities-CD-Ij91k.d.ts}

@@ -2341,12 +2341,16 @@ type ClearIndexChunkResult = {
  * reports whether anything is left. Callers drive it to completion across
  * transactions, so clearing a large index never has to fit in one mutation.
  *
- * Members are removed through the normal delta machinery rather than raw
- * deletes, so buckets and extrema stay consistent with the members that remain
- * at every intermediate step. That keeps concurrent writers correct while the
- * clear drains. Residual bucket/extrema rows (drift with no member behind them)
- * are swept only once no members are left, and the loop re-checks members
- * afterwards.
+ * Member rows are deleted outright rather than run back through the delta
+ * machinery. The bucket and extrema branches below drop every row this index
+ * owns whatever it holds, so folding a removal delta into a bucket first would
+ * only rewrite a document this same clear is about to delete.
+ *
+ * Branch order is load-bearing: buckets and extrema are swept only once no
+ * members are left, and the loop re-checks members afterwards. The intermediate
+ * "members gone, buckets still populated" state is safe because `setCountState`
+ * refuses to leave CLEARING while a bucket or extrema row survives, and the
+ * CLEARING write barrier keeps concurrent writers out of the index.
  */
 declare const clearCountIndexChunk: (db: GenericDatabaseWriter<any>, tableName: string, indexName: string, batchSize: number) => Promise<ClearIndexChunkResult>;
 declare const listCountStates: (db: GenericDatabaseReader<any> | GenericDatabaseWriter<any>) => Promise<CountState[]>;
@@ -2392,10 +2396,20 @@ declare const ensureRankAllowedForRls: (tableConfig: TableRelationalConfig, rlsM
 declare const compileRankPlan: (tableConfig: TableRelationalConfig, indexName: string, where: unknown) => RankQueryPlan;
 declare const ensureRankIndexReady: (db: GenericDatabaseReader<any> | GenericDatabaseWriter<any>, tableName: string, indexName: string) => Promise<void>;
 /**
- * Removes at most `batchSize` rank members and reports whether anything is
- * left. Each member is removed from the btree before its row is dropped, so the
- * tree stays consistent with the members that remain and a partially drained
- * clear can safely resume in a later mutation.
+ * Removes at most `batchSize` documents of a rank index's stored state and
+ * reports whether anything is left. Callers drive it to completion across
+ * transactions, so clearing a large index never has to fit in one mutation.
+ *
+ * Member rows are dropped without touching the btree. The tree branch below
+ * deletes every node whatever it contains, so removing a member key first would
+ * only buy a root-to-leaf descent plus an aggregate patch per level on nodes
+ * this same clear is about to delete.
+ *
+ * Branch order is load-bearing: a member delete recreates the tree it lands on,
+ * so the members must be gone before the first node is dropped. The
+ * intermediate "members gone, tree still full" state is safe because
+ * `setCountState` refuses to leave CLEARING while a tree row survives, and the
+ * CLEARING write barrier keeps concurrent writers out of the index.
  */
 declare const clearRankIndexChunk: (db: GenericDatabaseWriter<any>, tableName: string, indexName: string, batchSize: number) => Promise<{
   done: boolean;
@@ -2953,6 +2967,17 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _normalizeOrderByValue;
   private _normalizeOrderBy;
   private _orderBySpecs;
+  /**
+   * Whether rows can be missing this sort column or hold null in it.
+   *
+   * Only the declared validator can answer: a column that is not `.notNull()`
+   * compiles to `v.optional(v.union(v.null(), T))`, so both absent and null are
+   * legal stored values — and `timestamp().notNull().defaultNow()` on
+   * `createdAt` is deliberately emitted as optional for migration safety, so
+   * reading `config.notNull` alone would answer wrong for it. Anything the
+   * lookup cannot resolve counts as nullable, which only costs a pushdown.
+   */
+  private _isNullableOrderField;
   private _resolveNonPaginatedLimit;
   private _compareByOrderSpecs;
   /**
@@ -3043,6 +3068,33 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * the field produces that order.
    */
   private _findStreamOrderIndex;
+  /**
+   * The compiled index union, as one ordered stream.
+   *
+   * Each probe is its own index range, so the union is only usable where the
+   * merged order is the order the read has to produce. `mergedStream` orders by
+   * a *suffix* of the index key, and a suffix may only drop key components the
+   * probes all pin to a single value — so the requested field has to sit inside
+   * the pinned run or immediately after it. Returns null when it does not, and
+   * the caller falls back to the plan's plain index range or a bounded scan.
+   */
+  private _buildProbeUnionStream;
+  /**
+   * The read the compiled plan describes, as a stream, with nothing filtered
+   * yet.
+   *
+   * Precedence: the compiled index union, then the compiled index range, then
+   * the caller's pinned `.withIndex(...)`, then an index that supplies the
+   * requested order, then a full scan. The first two rungs can only ever refine
+   * what the caller pinned — `_toConvexQuery` discards a compiled plan that
+   * would displace a caller's index or its bounds before it gets here.
+   *
+   * `probeUnion` tells the caller the read is bounded by index ranges rather
+   * than by scan length, which is what makes a scan budget unnecessary. A
+   * rejected union stays unanchored; its original predicate remains in
+   * `queryConfig.postFilters` for the caller to apply while pulling the scan.
+   */
+  private _buildPlanStream;
   private _buildBasePipelineStream;
   /**
    * Stream equivalent of the `db.query(...)` chain, used when a post-fetch

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as Columns, D as TableName, E as RlsPolicies, O as createSystemFields, S as getRankIndexes, T as OrmSchemaExtensions, _ as loadEsbuild, a as generateMeta, b as getAggregateIndexes, c as resolveSchemaDefaultExport, f as createProjectJiti, g as loadDotenv, h as loadClackPrompts, i as resolveConfiguredBackend, l as schemaDeclaresAggregateIndexes, m as loadBabelParser, n as withLocalCodegenEnv, o as getConvexConfig, p as CRPC_BUILDER_STUB_SOURCE, r as loadCliConfig, s as collectSchemaTables, t as getLocalBackendEnvVars, u as logger, v as highlighter, w as EnableRLS, x as getIndexes, y as isColorEnabled } from "./local-env-DGSkmXQk.mjs";
+import { C as Columns, D as TableName, E as RlsPolicies, O as createSystemFields, S as getRankIndexes, T as OrmSchemaExtensions, _ as loadEsbuild, a as generateMeta, b as getAggregateIndexes, c as resolveSchemaDefaultExport, f as createProjectJiti, g as loadDotenv, h as loadClackPrompts, i as resolveConfiguredBackend, l as schemaDeclaresAggregateIndexes, m as loadBabelParser, n as withLocalCodegenEnv, o as getConvexConfig, p as CRPC_BUILDER_STUB_SOURCE, r as loadCliConfig, s as collectSchemaTables, t as getLocalBackendEnvVars, u as logger, v as highlighter, w as EnableRLS, x as getIndexes, y as isColorEnabled } from "./local-env-CYYSNf_o.mjs";
 import { createRequire } from "node:module";
 import fs, { existsSync, readFileSync } from "node:fs";
 import path, { basename, delimiter, dirname, extname, isAbsolute, join, posix, relative, resolve } from "node:path";

package/dist/{generated-contract-disabled-CTUQ9nxL.d.ts → generated-contract-disabled-PdNGvNYP.d.ts}

@@ -199,20 +199,20 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
   count: convex_server0.RegisteredQuery<"internal", {
     where?: {
       mode?: "sensitive" | "insensitive" | undefined;
-      operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
       connector?: "AND" | "OR" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
+      operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
     model: string;
   }, Promise<number | null>>;
   consumeOne: convex_server0.RegisteredMutation<"internal", {
     input: {
       where?: {
-        operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
         connector?: "AND" | "OR" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
+        operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
@@ -235,26 +235,26 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
     };
   }, Promise<any>>;
   deleteMany: convex_server0.RegisteredMutation<"internal", {
-    paginationOpts: {
-      id?: number;
-      endCursor?: string | null;
-      maximumRowsRead?: number;
-      maximumBytesRead?: number;
-      numItems: number;
-      cursor: string | null;
-    };
     input: {
       where?: {
-        operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
         connector?: "AND" | "OR" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
+        operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
       where?: any[] | undefined;
       model: string;
     };
+    paginationOpts: {
+      id?: number;
+      endCursor?: string | null;
+      maximumRowsRead?: number;
+      maximumBytesRead?: number;
+      numItems: number;
+      cursor: string | null;
+    };
   }, Promise<{
     count: number;
     ids: any[];
@@ -266,10 +266,10 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
   deleteOne: convex_server0.RegisteredMutation<"internal", {
     input: {
       where?: {
-        operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
         connector?: "AND" | "OR" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
+        operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
@@ -278,20 +278,21 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
     };
   }, Promise<Record<string, unknown> | undefined>>;
   findMany: convex_server0.RegisteredQuery<"internal", {
-    limit?: number | undefined;
     join?: any;
     where?: {
       mode?: "sensitive" | "insensitive" | undefined;
-      operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
       connector?: "AND" | "OR" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
+      operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
+    limit?: number | undefined;
     offset?: number | undefined;
     sortBy?: {
       field: string;
       direction: "asc" | "desc";
     } | undefined;
+    model: string;
     paginationOpts: {
       id?: number;
       endCursor?: string | null;
@@ -300,16 +301,15 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       numItems: number;
       cursor: string | null;
     };
-    model: string;
   }, Promise<PaginationResult<convex_server0.GenericDocument>>>;
   findOne: convex_server0.RegisteredQuery<"internal", {
     join?: any;
     where?: {
       mode?: "sensitive" | "insensitive" | undefined;
-      operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
       connector?: "AND" | "OR" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
+      operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
     select?: string[] | undefined;
     model: string;
@@ -319,10 +319,10 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
     input: {
       where?: {
         mode?: "sensitive" | "insensitive" | undefined;
-        operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
         connector?: "AND" | "OR" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
+        operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       set?: Record<string, any> | undefined;
       model: string;
@@ -331,31 +331,31 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
   }, Promise<any>>;
   rotateKeys: convex_server0.RegisteredAction<"internal", {}, Promise<unknown>>;
   updateMany: convex_server0.RegisteredMutation<"internal", {
-    paginationOpts: {
-      id?: number;
-      endCursor?: string | null;
-      maximumRowsRead?: number;
-      maximumBytesRead?: number;
-      numItems: number;
-      cursor: string | null;
-    };
     input: {
       where?: {
-        operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
         connector?: "AND" | "OR" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
+        operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
+      model: string;
       update: {
         [x: string]: unknown;
         [x: number]: unknown;
         [x: symbol]: unknown;
       };
-      model: string;
     } | {
       where?: any[] | undefined;
-      update: any;
       model: string;
+      update: any;
+    };
+    paginationOpts: {
+      id?: number;
+      endCursor?: string | null;
+      maximumRowsRead?: number;
+      maximumBytesRead?: number;
+      numItems: number;
+      cursor: string | null;
     };
   }, Promise<{
     count: number;
@@ -368,21 +368,21 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
   updateOne: convex_server0.RegisteredMutation<"internal", {
     input: {
       where?: {
-        operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
         connector?: "AND" | "OR" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
+        operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
+      model: string;
       update: {
         [x: string]: unknown;
         [x: number]: unknown;
         [x: symbol]: unknown;
       };
-      model: string;
     } | {
       where?: any[] | undefined;
-      update: any;
       model: string;
+      update: any;
     };
   }, Promise<any>>;
 };

package/dist/{index-utils-C1DyktHe.js → index-utils-DvK7P6Q1.js}

@@ -458,10 +458,11 @@ const hasColumnPrefix = (index, columns) => {
 *
 * Convex walks an index in full key order, so once a leading run of fields is
 * pinned to a single value by `eq`, the remainder of the scan is already sorted
-* by the next index field — and by `_creationTime` once every declared field is
-* pinned, because Convex appends it as the implicit trailing key. When that
-* field is the one the caller asked to sort by, `.order(dir).take(n)` returns
-* the exact page and nothing has to be collected and sorted afterwards.
+* by the next index field, then the one after that — and by `_creationTime`
+* once every declared field is consumed, because Convex appends it as the
+* implicit trailing key. When that sequence is the one the caller asked to sort
+* by, `.order(dir).take(n)` returns the exact page and nothing has to be
+* collected and sorted afterwards.
 *
 * This is the single owner of that decision. The top-level query planner and
 * the relation loader both call it, so a bound one of them can push into the
@@ -472,12 +473,34 @@ const hasColumnPrefix = (index, columns) => {
 */
 function resolveIndexOrderPushdown(params) {
 	const { indexFields, pinnedEqCount, orderSpecs } = params;
-	if (!indexFields || orderSpecs.length !== 1) return null;
-	const primary = orderSpecs[0];
+	if (!indexFields || orderSpecs.length === 0) return null;
 	const eqCount = Math.min(Math.max(pinnedEqCount, 0), indexFields.length);
-	for (let i = 0; i < eqCount; i += 1) if (indexFields[i] === primary.field) return primary.direction;
-	const nativeField = eqCount >= indexFields.length ? INTERNAL_CREATION_TIME_FIELD : indexFields[eqCount];
-	return primary.field === nativeField ? primary.direction : null;
+	const pinnedFields = new Set(indexFields.slice(0, eqCount));
+	/** Next unpinned index key the scan will sort by. */
+	let cursor = eqCount;
+	/** Direction every unpinned spec has to agree on. */
+	let direction = null;
+	let consumedCreationTime = false;
+	let hasNullableSpec = false;
+	for (const spec of orderSpecs) {
+		if (pinnedFields.has(spec.field)) continue;
+		if (direction === null) direction = spec.direction;
+		else if (direction !== spec.direction) return null;
+		if (spec.nullable !== false) hasNullableSpec = true;
+		if (consumedCreationTime) return null;
+		if (cursor >= indexFields.length) {
+			if (spec.field !== INTERNAL_CREATION_TIME_FIELD) return null;
+			consumedCreationTime = true;
+			continue;
+		}
+		if (spec.field !== indexFields[cursor]) return null;
+		cursor += 1;
+	}
+	if (orderSpecs.length > 1 && direction !== null && cursor < indexFields.length) return null;
+	const primary = orderSpecs[0];
+	if (direction !== null && pinnedFields.has(primary.field) && primary.direction !== direction && !consumedCreationTime) return null;
+	if (orderSpecs.length > 1 && hasNullableSpec) return null;
+	return direction ?? orderSpecs[0].direction;
 }
 function findRelationIndex(table, columns, relationName, targetTableName, strict = true, allowFullScan = false, orderSpecs = []) {
 	const indexes = getIndexes(table);