kitcn 0.31.0 → 0.32.0

package/dist/{where-clause-compiler-Dddhscyy.d.ts → where-clause-compiler-FDJTqLDC.d.ts}

@@ -1,4 +1,4 @@
-import { $t as OrmLifecycleChange, A as CreateDatabaseOptions, Ar as $Type, B as getUniqueIndexes, Ct as OrderByClause, F as CascadeMode, Ft as ExtractTablesFromSchema, Gn as Columns, Gt as TablesRelationalConfig, Ht as RelationsBuilderConfigValue, I as DeleteMode, Kn as OrmRuntimeDefaults, L as SerializedFilterExpression, Mr as ColumnBuilder, Mt as VectorSearchProvider, N as OrmReader, Nr as ColumnBuilderBaseConfig, Or as SystemFieldAliases, P as OrmWriter, Pt as AnyRelationsBuilderConfig, Qn as OrmSchemaTriggers, R as getChecks, U as EdgeMetadata, Un as ConvexColumnBuilder, Ur as entityKind, Ut as RelationsConfigWithSchema, Vn as ConvexTextBuilderInitial, Wt as TableRelationalConfig, Xt as ConvexTable, Yn as OrmSchemaExtensionTriggers, Zn as OrmSchemaRelations, Zt as ConvexTableWithColumns, an as RlsPolicy, dt as InferInsertModel, kr as SystemFields, pt as InferSelectModel, qn as OrmSchemaExtensionRelations, r as OrmCapability, rr as FilterExpression$1, x as MigrationSet, z as getForeignKeys, zr as HasDefault, zt as RelationsBuilder } from "./capabilities-DPB-JKlm.js";
+import { $t as OrmLifecycleChange, A as CreateDatabaseOptions, Ar as $Type, B as getUniqueIndexes, Ct as OrderByClause, F as CascadeMode, Ft as ExtractTablesFromSchema, Gn as Columns, Gt as TablesRelationalConfig, Ht as RelationsBuilderConfigValue, I as DeleteMode, Kn as OrmRuntimeDefaults, L as SerializedFilterExpression, Mr as ColumnBuilder, Mt as VectorSearchProvider, N as OrmReader, Nr as ColumnBuilderBaseConfig, Or as SystemFieldAliases, P as OrmWriter, Pt as AnyRelationsBuilderConfig, Qn as OrmSchemaTriggers, R as getChecks, U as EdgeMetadata, Un as ConvexColumnBuilder, Ur as entityKind, Ut as RelationsConfigWithSchema, Vn as ConvexTextBuilderInitial, Wt as TableRelationalConfig, Xt as ConvexTable, Yn as OrmSchemaExtensionTriggers, Zn as OrmSchemaRelations, Zt as ConvexTableWithColumns, an as RlsPolicy, dt as InferInsertModel, kr as SystemFields, pt as InferSelectModel, qn as OrmSchemaExtensionRelations, r as OrmCapability, rr as FilterExpression$1, x as MigrationSet, z as getForeignKeys, zr as HasDefault, zt as RelationsBuilder } from "./capabilities-CD-Ij91k.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Validator, Value } from "convex/values";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchedulableFunctionReference, Scheduler, SchemaDefinition, internalActionGeneric, internalMutationGeneric, internalQueryGeneric } from "convex/server";
@@ -111,6 +111,15 @@ declare const migrationStorageTables: {
           fieldName: "direction";
         };
       };
+      cursor: ConvexTextBuilderInitial<""> & {
+        _: {
+          tableName: "migration_state";
+        };
+      } & {
+        _: {
+          fieldName: "cursor";
+        };
+      };
       migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -159,15 +168,6 @@ declare const migrationStorageTables: {
           fieldName: "runId";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
-        _: {
-          tableName: "migration_state";
-        };
-      } & {
-        _: {
-          fieldName: "cursor";
-        };
-      };
       processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1011,7 +1011,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      count: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1021,10 +1021,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1034,7 +1034,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "tableKey";
         };
       };
       indexName: ConvexTextBuilderInitial<""> & {
@@ -1050,7 +1050,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "indexName";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      keyHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1060,10 +1060,14 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "keyHash";
         };
       };
-      keyHash: ConvexTextBuilderInitial<""> & {
+      keyParts: ConvexCustomBuilderInitial<"", convex_values0.VArray<any[], convex_values0.Validator<any, "required", any>, "required">> & {
+        _: {
+          $type: convex_values0.Value[];
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -1073,14 +1077,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyHash";
+          fieldName: "keyParts";
         };
       };
-      keyParts: ConvexCustomBuilderInitial<"", convex_values0.VArray<any[], convex_values0.Validator<any, "required", any>, "required">> & {
-        _: {
-          $type: convex_values0.Value[];
-        };
-      } & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1090,7 +1090,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyParts";
+          fieldName: "count";
         };
       };
       sumValues: ConvexCustomBuilderInitial<"", ConvexValidatorLike> & {
@@ -1136,7 +1136,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_member: ConvexTableWithColumns<{
     name: "aggregate_member";
     columns: {
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      kind: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1146,10 +1146,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "kind";
         };
       };
-      kind: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1159,10 +1159,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "kind";
+          fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1172,10 +1172,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1185,7 +1185,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1326,7 +1326,11 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_extrema: ConvexTableWithColumns<{
     name: "aggregate_extrema";
     columns: {
-      count: ConvexNumberBuilderInitial<""> & {
+      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
+        _: {
+          $type: convex_values0.Value;
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -1336,14 +1340,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "value";
         };
       };
-      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
-        _: {
-          $type: convex_values0.Value;
-        };
-      } & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1353,10 +1353,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "value";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1366,7 +1366,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "tableKey";
         };
       };
       indexName: ConvexTextBuilderInitial<""> & {
@@ -1382,7 +1382,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "indexName";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      keyHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1392,10 +1392,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "keyHash";
         };
       };
-      keyHash: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1405,7 +1405,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyHash";
+          fieldName: "count";
         };
       };
       fieldName: ConvexTextBuilderInitial<""> & {
@@ -1470,6 +1470,15 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "aggregateName";
         };
       };
+      deletionStack: ConvexCustomBuilderInitial<"", convex_values0.VArray<convex_values0.GenericId<"aggregate_rank_node">[], convex_values0.VId<convex_values0.GenericId<"aggregate_rank_node">, "required">, "required">> & {
+        _: {
+          tableName: "aggregate_rank_tree";
+        };
+      } & {
+        _: {
+          fieldName: "deletionStack";
+        };
+      };
       maxNodeSize: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1484,10 +1493,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       };
       namespace: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
-        _: {
-          $type: convex_values0.Value;
-        };
-      } & {
         _: {
           tableName: "aggregate_rank_tree";
         };
@@ -1518,14 +1523,13 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_rank_node: ConvexTableWithColumns<{
     name: "aggregate_rank_node";
     columns: {
-      aggregate: ConvexCustomBuilderInitial<"", ConvexValidatorLike> & {
-        _: {
-          $type: {
-            count: number;
-            sum: number;
-          };
-        };
-      } & {
+      aggregate: ConvexCustomBuilderInitial<"", convex_values0.VObject<{
+        count: number;
+        sum: number;
+      }, {
+        count: convex_values0.VFloat64<number, "required">;
+        sum: convex_values0.VFloat64<number, "required">;
+      }, "required", "count" | "sum">> & {
         _: {
           tableName: "aggregate_rank_node";
         };
@@ -1534,15 +1538,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "aggregate";
         };
       };
-      items: ConvexCustomBuilderInitial<"", convex_values0.VArray<any[], convex_values0.Validator<any, "required", any>, "required">> & {
-        _: {
-          $type: {
-            k: convex_values0.Value;
-            v: convex_values0.Value;
-            s: number;
-          }[];
-        };
-      } & {
+      items: ConvexCustomBuilderInitial<"", convex_values0.VArray<{
+        k: any;
+        v: any;
+        s: number;
+      }[], convex_values0.VObject<{
+        k: any;
+        v: any;
+        s: number;
+      }, {
+        k: convex_values0.VAny<any, "required", string>;
+        v: convex_values0.VAny<any, "required", string>;
+        s: convex_values0.VFloat64<number, "required">;
+      }, "required", "k" | "v" | "s" | `k.${string}` | `v.${string}`>, "required">> & {
         _: {
           notNull: true;
         };
@@ -1555,11 +1563,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "items";
         };
       };
-      subtrees: ConvexCustomBuilderInitial<"", convex_values0.VArray<any[], convex_values0.Validator<any, "required", any>, "required">> & {
-        _: {
-          $type: string[];
-        };
-      } & {
+      subtrees: ConvexCustomBuilderInitial<"", convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">> & {
         _: {
           notNull: true;
         };
@@ -1592,6 +1596,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
+      kind: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "kind";
+        };
+      };
       cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
@@ -1658,7 +1675,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "lastError";
         };
       };
-      kind: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1668,7 +1685,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "kind";
+          fieldName: "tableKey";
         };
       };
       indexName: ConvexTextBuilderInitial<""> & {
@@ -1710,19 +1727,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "metricDefinitionHash";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_state";
-        };
-      } & {
-        _: {
-          fieldName: "tableKey";
-        };
-      };
     };
   }, {
     by_creation_time: ["_creationTime"];
@@ -1756,6 +1760,15 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "direction";
         };
       };
+      cursor: ConvexTextBuilderInitial<""> & {
+        _: {
+          tableName: "migration_state";
+        };
+      } & {
+        _: {
+          fieldName: "cursor";
+        };
+      };
       migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1804,15 +1817,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "runId";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
-        _: {
-          tableName: "migration_state";
-        };
-      } & {
-        _: {
-          fieldName: "cursor";
-        };
-      };
       processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;

package/package.json

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

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

@@ -262,9 +262,22 @@ Rules:
 Relation `limit`/`orderBy` are pushed into the relation index when the index
 already walks in that order. After the FK, `index('by_user').on(t.userId)`
 orders by creation time, so `with: { posts: { limit: 5, orderBy: { createdAt:
-'desc' } } }` reads 5 posts per parent. Sorting by any other column reads the
-parent's whole child partition and sorts in memory — put the sort column in the
-relation index (`index('by_user_rank').on(t.userId, t.rank)`) to stay bounded.
+'desc' } } }` reads 5 posts per parent. Multi-field sorts are pushed down too
+when the index carries all of them: `index('by_user_rank').on(t.userId, t.rank)`
+serves `orderBy: { rank: 'asc', createdAt: 'asc' }`, since the FK pins `userId`,
+`rank` is the next key and `createdAt` is Convex's implicit trailing one.
+Non-null values use Convex value ordering on both index-backed and post-fetch
+paths, including UTF-8 strings, signed zero, and NaN.
+When the first requested field is equality-pinned but points opposite to the
+moving fields, include `createdAt` in the moving direction as the final sort
+field. Without that explicit tie-break, the ORM post-fetch sorts to preserve
+which tied rows survive `limit`.
+Every unpinned declared index key must be requested. An extra key after the
+requested fields would break ties before Convex's implicit creation-time key,
+so the ORM keeps the post-fetch sort to preserve which rows survive `limit`.
+Sorting by any other column — or by one that can be missing or `null` — reads
+the parent's whole child partition and sorts in memory; put the sort columns in
+the relation index, in sort order, to stay bounded.
 
 ### Nested `with` depth
 
@@ -649,6 +662,23 @@ const page2 = await ctx.orm.query.posts.findMany({
 
 Return: `{ page, continueCursor, isDone, pageStatus?, splitCursor? }`
 
+### Index-union filters
+
+`in`, `notIn`, `ne`, and same-field equality `OR` compile to one index range per value when the field is one an index leads with. Cursor pages come from those ranges as a merged stream, so `orderBy` sorts across the whole result and no scan budget is needed.
+
+```ts
+const page = await ctx.orm.query.users.withIndex("by_status").findMany({
+  where: { status: { in: ["active", "pending"] } },
+  orderBy: { createdAt: "desc" },
+  cursor: null,
+  limit: 20,
+});
+```
+
+Falls back to a bounded scan (needs `maxScan`) when the probed index cannot supply the requested `orderBy`, or when the union is wider than 64 ranges.
+
+Without an `orderBy`, an index-union page is in the order of the index it walks — grouped by the probed value — not in creation order.
+
 ### Boundary pinning with `endCursor`
 
 ```ts
@@ -736,7 +766,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). A `.select()` ID-list query with `orderBy` needs a single field that an index leads with.
+2. **Bound scans** — use `maxScan` for predicate `where` (cursor mode only). `in`/`notIn`/`ne` on an indexed leading field page from index ranges and need no budget. 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.

package/dist/id-BVdWER1U.js

@@ -1,37 +0,0 @@
-import { b as ConvexColumnBuilder, x as entityKind } from "./table-d9o_n4R3.js";
-import { v } from "convex/values";
-
-//#region src/orm/builders/id.ts
-/**
-* ID column builder class
-* Compiles to v.id(tableName) or v.optional(v.id(tableName))
-*/
-var ConvexIdBuilder = class extends ConvexColumnBuilder {
-	static [entityKind] = "ConvexIdBuilder";
-	constructor(name, tableName) {
-		super(name, "string", "ConvexId");
-		this.tableName = tableName;
-		this.config.referenceTable = tableName;
-	}
-	/**
-	* Expose Convex validator for schema integration
-	*/
-	get convexValidator() {
-		if (this.config.notNull) return v.id(this.tableName);
-		return v.optional(v.union(v.null(), v.id(this.tableName)));
-	}
-	/**
-	* Compile to Convex validator
-	* .notNull() → v.id(tableName)
-	* nullable → v.optional(v.id(tableName))
-	*/
-	build() {
-		return this.convexValidator;
-	}
-};
-function id(tableName) {
-	return new ConvexIdBuilder("", tableName);
-}
-
-//#endregion
-export { id as t };