kitcn 0.31.1 → 0.32.0

package/dist/orm/migrations/index.d.ts

@@ -1,3 +1,3 @@
-import { C as MigrationStep, D as defineMigration, E as buildMigrationPlan, O as defineMigrationSet, S as MigrationStateMap, T as MigrationWriteMode, _ as MigrationManifestEntry, a as MAX_STATUS_RUN_LIMIT, b as MigrationRunStatus, c as MigrationRunChunkArgs, d as MigrationAppliedState, f as MigrationDefinition, g as MigrationDriftIssue, h as MigrationDocContext, k as detectMigrationDrift, l as MigrationStatusArgs, m as MigrationDoc, o as MigrationCancelArgs, p as MigrationDirection, s as MigrationRunArgs, u as createMigrationHandlers, v as MigrationMigrateOne, w as MigrationTableName, x as MigrationSet, y as MigrationPlan } from "../../capabilities-CG-oIMyR.js";
-import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-Bgkzm3Y-.js";
+import { C as MigrationStep, D as defineMigration, E as buildMigrationPlan, O as defineMigrationSet, S as MigrationStateMap, T as MigrationWriteMode, _ as MigrationManifestEntry, a as MAX_STATUS_RUN_LIMIT, b as MigrationRunStatus, c as MigrationRunChunkArgs, d as MigrationAppliedState, f as MigrationDefinition, g as MigrationDriftIssue, h as MigrationDocContext, k as detectMigrationDrift, l as MigrationStatusArgs, m as MigrationDoc, o as MigrationCancelArgs, p as MigrationDirection, s as MigrationRunArgs, u as createMigrationHandlers, v as MigrationMigrateOne, w as MigrationTableName, x as MigrationSet, y as MigrationPlan } from "../../capabilities-CD-Ij91k.js";
+import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-FDJTqLDC.js";
 export { MAX_STATUS_RUN_LIMIT, MIGRATION_RUN_TABLE, MIGRATION_STATE_TABLE, MIGRATION_STORAGE_TABLE_NAMES, type MigrationAppliedState, type MigrationCancelArgs, type MigrationDefinition, type MigrationDirection, type MigrationDoc, type MigrationDocContext, type MigrationDriftIssue, type MigrationManifestEntry, type MigrationMigrateOne, type MigrationPlan, type MigrationRunArgs, type MigrationRunChunkArgs, type MigrationRunStatus, type MigrationSet, type MigrationStateMap, type MigrationStatusArgs, type MigrationStep, type MigrationTableName, type MigrationWriteMode, buildMigrationPlan, createMigrationHandlers, defineMigration, defineMigrationSet, detectMigrationDrift, injectMigrationStorageTables, migrationCapability, migrationExtension, migrationStorageTables };

package/dist/{query-context-DdSg3fuk.js → query-context-D4z1CnDH.js}

@@ -545,6 +545,13 @@ var OrderedStreamQuery = class extends StreamableQuery {
 			minUpperBound = indexBounds.upperBound;
 			minUpperBoundInclusive = indexBounds.upperBoundInclusive;
 		}
+		if (compareKeys({
+			value: maxLowerBound,
+			kind: maxLowerBoundInclusive ? "predecessor" : "successor"
+		}, {
+			value: minUpperBound,
+			kind: minUpperBoundInclusive ? "successor" : "predecessor"
+		}) >= 0) return new EmptyStream(order, this.getIndexFields(), this.getEqualityIndexFilter());
 		return streamIndexRange(db, schema, table, index, {
 			lowerBound: maxLowerBound,
 			lowerBoundInclusive: maxLowerBoundInclusive,
@@ -1050,7 +1057,7 @@ var SingletonStream = class SingletonStream extends QueryStream {
 	}
 	narrow(indexBounds) {
 		if (indexKeyWithinBounds(this.#indexKey, indexBounds)) return new SingletonStream(this.#value, this.#order, this.#indexFields, this.#indexKey, this.#equalityIndexFilter);
-		return new EmptyStream(this.#order, this.#indexFields);
+		return new EmptyStream(this.#order, this.#indexFields, this.#equalityIndexFilter);
 	}
 };
 /**
@@ -1086,12 +1093,14 @@ function indexKeyWithinBounds(indexKey, indexBounds) {
 * towards maxScan.
 */
 var EmptyStream = class extends QueryStream {
+	#equalityIndexFilter;
 	#order;
 	#indexFields;
-	constructor(order, indexFields) {
+	constructor(order, indexFields, equalityIndexFilter = []) {
 		super();
 		this.#order = order;
 		this.#indexFields = indexFields;
+		this.#equalityIndexFilter = equalityIndexFilter;
 	}
 	iterWithKeys() {
 		return { [Symbol.asyncIterator]() {
@@ -1110,7 +1119,7 @@ var EmptyStream = class extends QueryStream {
 		return this.#indexFields;
 	}
 	getEqualityIndexFilter() {
-		return [];
+		return this.#equalityIndexFilter;
 	}
 	narrow(_indexBounds) {
 		return this;

package/dist/{schema-DbPcDW-N.js → schema-Bh7AmJwY.js}

@@ -1,7 +1,7 @@
 import { _ as json, f as text, h as arrayOf, m as integer, s as index, t as convexTable, v as objectOf } from "./table-d9o_n4R3.js";
 import { a as aggregateTreeTable, n as AGGREGATE_TREE_TABLE, r as aggregateNodeTable, t as AGGREGATE_NODE_TABLE } from "./schema-BFP_awgP.js";
 import { g as TablePolymorphic, h as TableName, i as OrmContext, m as TableDeleteConfig, n as Columns } from "./symbols-DDNAddkd.js";
-import { E as filterValuesEqual, L as matchLikePattern, T as filterValueInList, d as INTERNAL_CREATION_TIME_FIELD, f as PUBLIC_CREATED_AT_FIELD, j as isFieldReference, m as usesSystemCreatedAtAlias, n as findIndexForColumns, p as hasUserCreatedAtColumn, s as getIndexes, t as findExactIndexForColumns, u as CREATED_AT_MIGRATION_MESSAGE, w as fieldRef } from "./index-utils-C1DyktHe.js";
+import { E as filterValuesEqual, L as matchLikePattern, T as filterValueInList, d as INTERNAL_CREATION_TIME_FIELD, f as PUBLIC_CREATED_AT_FIELD, j as isFieldReference, m as usesSystemCreatedAtAlias, n as findIndexForColumns, p as hasUserCreatedAtColumn, s as getIndexes, t as findExactIndexForColumns, u as CREATED_AT_MIGRATION_MESSAGE, w as fieldRef } from "./index-utils-DvK7P6Q1.js";
 import { t as defineSchemaExtension } from "./extensions-Bp0XHanR.js";
 
 //#region src/internal/concurrency.ts

package/dist/{where-clause-compiler-Bgkzm3Y-.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-CG-oIMyR.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";
@@ -102,20 +102,25 @@ declare const migrationStorageTables: {
           fieldName: "status";
         };
       };
-      migrationId: ConvexTextBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
-          notNull: true;
+          tableName: "migration_state";
         };
       } & {
+        _: {
+          fieldName: "direction";
+        };
+      };
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "migrationId";
+          fieldName: "cursor";
         };
       };
-      checksum: ConvexTextBuilderInitial<""> & {
+      migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -125,10 +130,10 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "checksum";
+          fieldName: "migrationId";
         };
       };
-      applied: ConvexBooleanBuilderInitial<""> & {
+      checksum: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -138,34 +143,29 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "applied";
+          fieldName: "checksum";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      applied: ConvexBooleanBuilderInitial<""> & {
         _: {
-          tableName: "migration_state";
+          notNull: true;
         };
       } & {
-        _: {
-          fieldName: "direction";
-        };
-      };
-      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "applied";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "runId";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {
@@ -1024,19 +1024,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_bucket";
-        };
-      } & {
-        _: {
-          fieldName: "count";
-        };
-      };
       tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1093,6 +1080,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "keyParts";
         };
       };
+      count: ConvexNumberBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_bucket";
+        };
+      } & {
+        _: {
+          fieldName: "count";
+        };
+      };
       sumValues: ConvexCustomBuilderInitial<"", ConvexValidatorLike> & {
         _: {
           $type: Record<string, number>;
@@ -1356,7 +1356,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1366,10 +1366,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1379,10 +1379,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      keyHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1392,10 +1392,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          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<""> & {
@@ -1751,20 +1751,25 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
-      migrationId: ConvexTextBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
-          notNull: true;
+          tableName: "migration_state";
         };
       } & {
+        _: {
+          fieldName: "direction";
+        };
+      };
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "migrationId";
+          fieldName: "cursor";
         };
       };
-      checksum: ConvexTextBuilderInitial<""> & {
+      migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1774,10 +1779,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "checksum";
+          fieldName: "migrationId";
         };
       };
-      applied: ConvexBooleanBuilderInitial<""> & {
+      checksum: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1787,34 +1792,29 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "applied";
+          fieldName: "checksum";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      applied: ConvexBooleanBuilderInitial<""> & {
         _: {
-          tableName: "migration_state";
+          notNull: true;
         };
       } & {
-        _: {
-          fieldName: "direction";
-        };
-      };
-      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "applied";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "runId";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.31.1",
+  "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.