kitcn 0.32.2 → 0.33.1

package/package.json

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

package/skills/kitcn/SKILL.md

@@ -34,7 +34,7 @@ Only remember these non-parity deltas:
 2. No `z.void()` outputs; omit `.output(...)` for no-value mutations.
 3. `.output(...)` parses the handler's value as-is and substitutes nothing: a handler must return the schema's *input* type, so `z.string().nullable()` needs an explicit `null` (`?? null`), not `undefined`. Model absent values as `.nullable()`, never a top-level `.optional()` — Convex wires `undefined` as `null` and cannot express top-level optionality, so `.output(z.string().optional())` publishes `v.string()` and the deployment rejects the `null` whenever the handler returns `undefined`. `.optional()` inside an object is fine. The low-level `returns:` option on `zCustomQuery`/`zCustomMutation`/`zCustomAction` differs — it substitutes `null` for `undefined` before parsing.
 4. Stacked `.input(...)` calls merge input shapes.
-5. `.paginated({ limit, item })` must be before `.query()` and auto-adds `input.cursor` + `input.limit`, output `{ page, continueCursor, isDone }`.
+5. `.paginated({ limit, item })` must be before `.query()` and adds `input.cursor`, `input.endCursor`, and `input.limit`; pass all three to ORM cursor queries so live splits stay bounded.
 6. Metadata is codegen’d onto `@convex/api` leaves (`api.namespace.fn.meta`) so never put secrets in `.meta(...)`; chaining `.meta(...)` is shallow merge and supports `defaultMeta`.
 7. Auth metadata drives client behavior: `auth: "optional"` waits for auth load then runs, `auth: "required"` waits then skips when logged out.
 8. `ctx.orm` enforces constraints + RLS; `ctx.db` bypasses them.
@@ -245,6 +245,7 @@ export const listProjects = authQuery
       where: { ownerId: ctx.userId },
       orderBy: { updatedAt: "desc" },
       cursor: input.cursor,
+      endCursor: input.endCursor,
       limit: input.limit,
     })
   );

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

@@ -58,6 +58,19 @@ const orders = convexTable(
 
 After deploying, CLI runs `aggregateBackfill` automatically. Wait for `aggregateBackfillStatus` (an internal query) to report `READY`.
 
+### Write costs
+
+Bulk ORM statements reuse aggregate bucket/member reads within uninterrupted
+statements: one bucket read per distinct tuple and one membership read per
+document. User hooks, policy callbacks and statement exit end reuse, preserving
+nested-mutation writes. Raw writer calls do not share cached rows.
+
+Shared bucket/extrema writes fold within statements. Aggregate reads (including
+returning relation counts) and user hook/policy entry flush pending writes;
+callbacks suspend batching until they settle so nested functions see stored
+writes. Reads/callbacks can increase flush count. Membership rows remain one
+write per changed document.
+
 ### `count()` — O(1) No-Scan Counts
 
 ```ts

package/skills/kitcn/references/features/auth-admin.md

@@ -265,6 +265,7 @@ export const getAllUsers = authQuery
   .query(async ({ ctx, input }) => {
     const result = await ctx.orm.query.user.findMany({
       cursor: input.cursor,
+      endCursor: input.endCursor,
       limit: input.limit,
     });
 

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

@@ -598,7 +598,9 @@ Per source:
 
 - `index: { name, range }` anchors that source on its own range. It overrides
   the chain-level `.withIndex(...)`; sources that omit it use the chain index.
-- `where` filters that source's rows after the read.
+- `where` is compiled against the table's indexes like a `findMany` where. It
+  bounds the read when it can be lowered onto the index that source walks;
+  whatever no index covers is filtered after the read.
 
 `interleaveBy` fields must be the trailing fields each source is already ordered
 by, so every field before them has to be pinned with `eq` in that source's
@@ -607,8 +609,18 @@ fields — e.g. `by_author_likes` (authorId, numLikes) with `eq("authorId", ...)
 merges with `numLikesAndType` (type, numLikes) with `eq("type", ...)` under
 `interleaveBy(["numLikes"])`.
 
-Anchor every source. A shared `.withIndex(...)` plus per-source `where` makes
-each source walk the same range and discard the misses after reading them.
+Whether a source `where` bounds the read depends on the index that source ends
+up walking. With no index pinned it picks one, so `{ where: { status: "active" } }`
+reads the `by_status` range. With a pinned index it may only narrow that same
+index: `.withIndex("by_status")` plus `{ where: { status: "active" } }` narrows,
+while `.withIndex("by_name")` plus the same `where` walks `by_name` and discards
+the misses.
+
+A pinned `range` is the source's scope, never a hint: a `where` alongside one
+always filters after the read rather than widening it. Lowering also has to
+preserve the merge, so a `where` is only lowered when the resulting order can
+still supply `interleaveBy`. Anchor a source with `index: { name, range }`
+whenever you need a specific range read.
 
 ### Pre-pagination transforms
 
@@ -630,6 +642,14 @@ const page = await ctx.orm.query.users
   .paginate({ cursor: null, limit: 20 });
 ```
 
+Children are read through an index that leads with the relation's foreign key.
+A stage `where` rides that index when one extends it — `where: { numLikes: { gt: 10 } }`
+on `posts` reads the `by_author_likes` (authorId, numLikes) range instead of
+every post by the author. Children then arrive in that index's order, so a
+lowered range field orders them ahead of creation time. Declare an index whose
+fields are `(...foreign key, ...filtered fields)` for the stage filters you
+page on.
+
 See [Select Composition Limitations](#select-composition-limitations) in API Reference.
 
 ## Pagination Modes
@@ -675,7 +695,7 @@ const page = await ctx.orm.query.users.withIndex("by_status").findMany({
 });
 ```
 
-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.
+Falls back to a bounded scan (needs `maxScan`) when the probed index cannot supply the requested `orderBy`, or when a union wider than 64 ranges is asked for an `orderBy` that sorts across values, such as `createdAt`. Up to 64 ranges are read as one merged stream; a wider union is read one range after another, which keeps it index-bounded at any list length but can only produce the index's own order.
 
 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.
 

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

@@ -374,20 +374,19 @@ export const list = publicQuery
   .input(z.object({ userId: z.string().optional() }))
   .paginated({ limit: 20, item: SessionSchema })
   .query(async ({ ctx, input }) => {
-    // input.cursor and input.limit auto-added
     return ctx.orm.query.session.findMany({
       where: input.userId ? { userId: input.userId } : undefined,
       orderBy: { createdAt: 'desc' },
       cursor: input.cursor,
+      endCursor: input.endCursor,
       limit: input.limit,
     });
-    // output auto-wrapped as { continueCursor, isDone, page }
   });
 ```
 
 `.paginated({ limit, item })`:
-- Adds `cursor` (string|null) and `limit` (number) to input
-- Auto-sets output schema: `{ continueCursor: string, isDone: boolean, page: T[] }`
+- Adds `cursor`, optional `endCursor`, and `limit` to input
+- Accepts the full Convex page result, including `pageStatus` and `splitCursor`
 - Must be called before `.query()`
 
 ### Return Value
@@ -414,7 +413,7 @@ const { data, isPlaceholderData } = useInfiniteQuery(
 
 ### Real-time & Error Recovery
 
-Each page maintains its own WebSocket subscription. Auto-recovers on `InvalidCursor` (resets to page 0) and `splitCursor` (auto-splits page). Pagination state persists in `queryClient` for scroll restoration.
+Each page maintains its own WebSocket subscription. Split pages use `endCursor` to keep adjacent subscriptions bounded. An `InvalidCursor` on a loaded page resets the list cleanly to page 0. Pagination state persists in `queryClient` for scroll restoration.
 
 ---