kitcn 0.17.4 → 0.18.0

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

@@ -2470,6 +2470,11 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _orderBySpecs;
   private _resolveNonPaginatedLimit;
   private _compareByOrderSpecs;
+  /**
+   * Physical table name to relational config. Called once per row on the
+   * relation-count path, so the linear schema scan is indexed once per schema
+   * object rather than repeated. The schema is fixed for the process lifetime.
+   */
   private _getTableConfigByDbName;
   private _matchLike;
   /**
@@ -2616,6 +2621,16 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    */
   private _toConvexQuery;
   private _buildRelationKey;
+  /**
+   * How many leading fields of the scanned index are pinned to a single value.
+   *
+   * `splitFilters` emits index filters in index-key order — a run of `eq`, then
+   * at most one range on the first unpinned field — so the leading `eq` run is
+   * the prefix Convex holds constant. A multi-probe plan carries no index
+   * filters; each probe supplies its own bound instead, and the union is only
+   * as pinned as its least pinned probe.
+   */
+  private _indexEqPrefixCount;
   private _buildIndexPredicate;
   private _buildFilterPredicate;
   private _queryByFields;
@@ -2660,9 +2675,7 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _createRelationCountError;
   private _remapRelationCountError;
   private _coerceRelationCountWhere;
-  private _normalizeRelationCountCacheValue;
   private _getRelationCountParentKey;
-  private _buildRelationCountExecutionKey;
   private _readIndexedRelationCount;
   private _countRelationForRow;
   private _loadRelationCounts;
@@ -2672,6 +2685,22 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * M6.5 Phase 2: Added support for nested relations
    */
   private _loadOneRelation;
+  /**
+   * Junction links per parent, stopped once each parent holds `fetchLimit`
+   * links whose target actually reaches the page.
+   *
+   * A link only contributes if its target exists and survives target RLS and
+   * the relation `where` — all of which run after the junction read. Sizing the
+   * read on links alone therefore under-fills: three dangling or filtered links
+   * first and `{ limit: 3 }` returns nothing. So the read is refilled in rounds,
+   * each round resolving only the targets it newly needs and asking again for
+   * whatever the survivors did not cover.
+   *
+   * Rounds are the unit rather than single links because both the target fetch
+   * and the relation `where` de-duplicate and batch their own reads across the
+   * parents in the round.
+   */
+  private _readBoundedThroughLinks;
   /**
    * Load many() relation (one-to-many)
    * Example: users.posts where posts.authorId → users.id
@@ -4338,19 +4367,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_state: ConvexTableWithColumns<{
     name: "aggregate_state";
     columns: {
-      status: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_state";
-        };
-      } & {
-        _: {
-          fieldName: "status";
-        };
-      };
       kind: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -4438,6 +4454,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "metricDefinitionHash";
         };
       };
+      status: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "status";
+        };
+      };
       processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -4492,38 +4521,38 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly migration_state: ConvexTableWithColumns<{
     name: "migration_state";
     columns: {
-      status: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "cursor";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "direction";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4533,7 +4562,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "status";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {
@@ -4646,7 +4675,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly migration_run: ConvexTableWithColumns<{
     name: "migration_run";
     columns: {
-      status: ConvexTextBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4656,10 +4685,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "direction";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4669,10 +4698,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4682,7 +4711,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "status";
         };
       };
       startedAt: ConvexNumberBuilderInitial<""> & {

package/package.json

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

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

@@ -254,6 +254,13 @@ Rules:
 - `one()` with `to: ...id` → uses `db.get()` (no extra index)
 - Missing index throws unless `allowFullScan` on parent query
 
+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.
+
 ## Schema Definition
 
 ```ts
@@ -713,7 +720,7 @@ const filtered = results.filter((a) => a.publishedAt >= startDate);
 
 ### Performance
 
-1. **Index first** — constrain leading index fields. Compound indexes follow prefix rules.
+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).
 3. **Limit results** — always use `limit` or cursor pagination.
 4. **Cursor stability** — keep same `where`/`orderBy` between page requests.