kitcn 0.31.1 → 0.32.1

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # kitcn
 
+## 0.32.1
+
+### Patch Changes
+
+- [#427](https://github.com/udecode/kitcn/pull/427) [`92381f5`](https://github.com/udecode/kitcn/commit/92381f56a660dfcd4679674f612e64c1518bcf75) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Improve the read cost of filtering parents by whether a related child exists.
+    `where: { posts: { type: 'wanted' } }` now stops at the first matching child
+    instead of loading the whole per-parent child window and testing it afterwards.
+    On one parent with 61 posts and a match sorting first, that is 2 document reads
+    instead of 62 — the same cost as the hand-written
+    `with: { posts: { where: { type: 'wanted' }, limit: 1 } }`. The same applies to
+    `where: { posts: true }`, to a relation existence test under `NOT`, and to
+    `through` relations, where it also stops at the first matching junction row.
+    Results are unchanged: the filter still decides from the same window it read
+    before, so a match past `defaultLimit` is excluded exactly as it was.
+  - A relation named more than once in one `where` — across `OR`, `AND` and `NOT`
+    branches — keeps the previous single unbounded load, because those branches
+    share it and each needs to read it in full.
+
+## 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

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
-import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-CG-oIMyR.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-Bgkzm3Y-.js";
+import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-Ctcw2VRq.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-BHGHbfb9.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/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-BKvk4lFx.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-BKvk4lFx.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";
@@ -111,29 +111,29 @@ declare const adapterWhereValidator: convex_values0.VObject<{
   mode?: "sensitive" | "insensitive" | undefined;
   connector?: "AND" | "OR" | undefined;
   operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-  value: string | number | boolean | string[] | number[] | null;
   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<"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" | "value" | "connector" | "field" | "operator">;
+}, "required", "mode" | "connector" | "field" | "operator" | "value">;
 declare const adapterArgsValidator: convex_values0.VObject<{
   where?: {
     mode?: "sensitive" | "insensitive" | undefined;
     connector?: "AND" | "OR" | undefined;
     operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
     field: string;
+    value: string | number | boolean | string[] | number[] | null;
   }[] | undefined;
   limit?: number | undefined;
   offset?: number | undefined;
   select?: string[] | undefined;
   sortBy?: {
-    direction: "asc" | "desc";
     field: string;
+    direction: "asc" | "desc";
   } | undefined;
   model: string;
 }, {
@@ -142,32 +142,32 @@ declare const adapterArgsValidator: convex_values0.VObject<{
   offset: convex_values0.VFloat64<number | undefined, "optional">;
   select: convex_values0.VArray<string[] | undefined, convex_values0.VString<string, "required">, "optional">;
   sortBy: convex_values0.VObject<{
-    direction: "asc" | "desc";
     field: string;
+    direction: "asc" | "desc";
   } | undefined, {
     direction: convex_values0.VUnion<"asc" | "desc", [convex_values0.VLiteral<"asc", "required">, convex_values0.VLiteral<"desc", "required">], "required", never>;
     field: convex_values0.VString<string, "required">;
-  }, "optional", "direction" | "field">;
+  }, "optional", "field" | "direction">;
   where: convex_values0.VArray<{
     mode?: "sensitive" | "insensitive" | undefined;
     connector?: "AND" | "OR" | undefined;
     operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
     field: string;
+    value: string | number | boolean | string[] | number[] | null;
   }[] | undefined, convex_values0.VObject<{
     mode?: "sensitive" | "insensitive" | undefined;
     connector?: "AND" | "OR" | undefined;
     operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    value: string | number | boolean | string[] | number[] | null;
     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<"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" | "value" | "connector" | "field" | "operator">, "optional">;
-}, "required", "model" | "where" | "limit" | "offset" | "select" | "sortBy" | "sortBy.direction" | "sortBy.field">;
+  }, "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-CG-oIMyR.d.ts → capabilities-Ctcw2VRq.d.ts}

@@ -2967,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;
   /**
@@ -3003,7 +3014,21 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _buildFieldFilterExpression;
   private _buildFilterExpression;
   private _mergeWithConfig;
+  /**
+   * Relation keys the filter tree mentions exactly once, across every OR/AND/NOT
+   * branch at this table level.
+   *
+   * `_mergeWithConfig` collapses the whole tree into one load per relation key,
+   * so a key two branches disagree about has to be loaded the way both branches
+   * can read. Only a key with a single occurrence has one predicate to satisfy,
+   * and only then can that predicate be pushed into the read plan.
+   *
+   * Relation values are not descended into: they belong to the target table and
+   * get their own count when that level is lowered.
+   */
+  private _collectSingleOccurrenceRelations;
   private _buildFilterWithConfig;
+  private _buildFilterWithConfigForLevel;
   private _stripFilterRelations;
   private _hasSearchDisallowedRelationFilter;
   private _searchFilterValuesEqual;
@@ -3057,6 +3082,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/{generated-contract-disabled-BKvk4lFx.d.ts → generated-contract-disabled-PdNGvNYP.d.ts}

@@ -201,8 +201,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       mode?: "sensitive" | "insensitive" | undefined;
       connector?: "AND" | "OR" | undefined;
       operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
     model: string;
   }, Promise<number | null>>;
@@ -211,8 +211,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
@@ -239,8 +239,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
@@ -268,8 +268,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
     } | {
@@ -283,14 +283,14 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       mode?: "sensitive" | "insensitive" | undefined;
       connector?: "AND" | "OR" | undefined;
       operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
     sortBy?: {
-      direction: "asc" | "desc";
       field: string;
+      direction: "asc" | "desc";
     } | undefined;
     model: string;
     paginationOpts: {
@@ -308,8 +308,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       mode?: "sensitive" | "insensitive" | undefined;
       connector?: "AND" | "OR" | undefined;
       operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-      value: string | number | boolean | string[] | number[] | null;
       field: string;
+      value: string | number | boolean | string[] | number[] | null;
     }[] | undefined;
     select?: string[] | undefined;
     model: string;
@@ -321,8 +321,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
         mode?: "sensitive" | "insensitive" | undefined;
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       set?: Record<string, any> | undefined;
       model: string;
@@ -335,8 +335,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
       update: {
@@ -370,8 +370,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       where?: {
         connector?: "AND" | "OR" | undefined;
         operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-        value: string | number | boolean | string[] | number[] | null;
         field: string;
+        value: string | number | boolean | string[] | number[] | null;
       }[] | undefined;
       model: string;
       update: {

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);

package/dist/orm/aggregate-index/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as RankIndexDefinition, G as CountBackfillChunkArgs, J as CountBackfillStatusArgs, K as CountBackfillKickoffArgs, Q as CountIndexDefinition, X as CountQueryPlan, Y as AggregateQueryPlan, Z as AggregateIndexDefinition, et as RankOrderField, q as CountBackfillMode, r as OrmCapability } from "../../capabilities-CG-oIMyR.js";
+import { $ as RankIndexDefinition, G as CountBackfillChunkArgs, J as CountBackfillStatusArgs, K as CountBackfillKickoffArgs, Q as CountIndexDefinition, X as CountQueryPlan, Y as AggregateQueryPlan, Z as AggregateIndexDefinition, et as RankOrderField, q as CountBackfillMode, r as OrmCapability } from "../../capabilities-Ctcw2VRq.js";
 
 //#region src/orm/aggregate-index/capability.d.ts
 /**

package/dist/orm/aggregate-index/index.js

@@ -1,7 +1,7 @@
 import { t as DirectAggregate } from "../../runtime-B-8HKSIE.js";
 import { n as Columns } from "../../symbols-DDNAddkd.js";
-import { d as INTERNAL_CREATION_TIME_FIELD, f as PUBLIC_CREATED_AT_FIELD, m as usesSystemCreatedAtAlias } from "../../index-utils-C1DyktHe.js";
-import { Q as normalizeTemporalComparableValue, a as AGGREGATE_STATE_TABLE, c as getAggregateIndexDefinitions, d as COUNT_ERROR, ht as mapWithConcurrency, i as AGGREGATE_RANK_TREE_TABLE, l as getRankIndexDefinitions, m as createError, n as AGGREGATE_EXTREMA_TABLE, r as AGGREGATE_MEMBER_TABLE, s as rankAggregateName, t as AGGREGATE_BUCKET_TABLE, u as AGGREGATE_ERROR } from "../../schema-DbPcDW-N.js";
+import { d as INTERNAL_CREATION_TIME_FIELD, f as PUBLIC_CREATED_AT_FIELD, m as usesSystemCreatedAtAlias } from "../../index-utils-DvK7P6Q1.js";
+import { Q as normalizeTemporalComparableValue, a as AGGREGATE_STATE_TABLE, c as getAggregateIndexDefinitions, d as COUNT_ERROR, ht as mapWithConcurrency, i as AGGREGATE_RANK_TREE_TABLE, l as getRankIndexDefinitions, m as createError, n as AGGREGATE_EXTREMA_TABLE, r as AGGREGATE_MEMBER_TABLE, s as rankAggregateName, t as AGGREGATE_BUCKET_TABLE, u as AGGREGATE_ERROR } from "../../schema-Bh7AmJwY.js";
 
 //#region src/orm/transaction-cache.ts
 /**

package/dist/orm/index.d.ts

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