kitcn 0.17.5 → 0.19.0

package/dist/{query-context-C90vNlc9.js → query-context-BzihIpnM.js}

@@ -23,6 +23,27 @@ function isFieldReference(value) {
 	return value && typeof value === "object" && value.__brand === "FieldReference";
 }
 /**
+* The pattern is the same for every row of a scan while the value is not, so
+* only the value genuinely has to be split per call. A small bounded cache
+* keeps the split pattern across rows without unbounded growth on
+* caller-supplied patterns; a query with a handful of LIKE filters still hits
+* on every row.
+*/
+const LIKE_PATTERN_CACHE_MAX = 16;
+const likePatternCache = /* @__PURE__ */ new Map();
+function likePatternCodePoints(pattern, caseInsensitive) {
+	const key = caseInsensitive ? `i:${pattern}` : `s:${pattern}`;
+	const cached = likePatternCache.get(key);
+	if (cached) return cached;
+	const source = Array.from(caseInsensitive ? pattern.toLowerCase() : pattern);
+	if (likePatternCache.size >= LIKE_PATTERN_CACHE_MAX) for (const oldest of likePatternCache.keys()) {
+		likePatternCache.delete(oldest);
+		break;
+	}
+	likePatternCache.set(key, source);
+	return source;
+}
+/**
 * SQL `LIKE` semantics: `%` matches any run of characters, `_` matches exactly
 * one, everything else is literal. Wildcards work anywhere in the pattern, not
 * only at the ends.
@@ -36,7 +57,7 @@ function isFieldReference(value) {
 */
 function matchLikePattern(value, pattern, caseInsensitive) {
 	const target = Array.from(caseInsensitive ? value.toLowerCase() : value);
-	const source = Array.from(caseInsensitive ? pattern.toLowerCase() : pattern);
+	const source = likePatternCodePoints(pattern, caseInsensitive);
 	let valueIndex = 0;
 	let patternIndex = 0;
 	let wildcardPatternIndex = -1;
@@ -507,11 +528,19 @@ function getIndexFields(table, index, schema) {
 	fields.push("_id");
 	return fields;
 }
-function getIndexKey(doc, indexFields) {
+/**
+* Read the index key out of a document.
+*
+* Takes field paths already split on `.` rather than the field names: the field
+* list is fixed for the life of a query, so splitting it once at `withIndex`
+* time saves an array allocation per field per document pulled through the
+* stream.
+*/
+function getIndexKey(doc, indexFieldPaths) {
 	const key = [];
-	for (const field of indexFields) {
+	for (const path of indexFieldPaths) {
 		let obj = doc;
-		for (const subfield of field.split(".")) obj = obj[subfield];
+		for (const subfield of path) obj = obj[subfield];
 		key.push(obj);
 	}
 	return key;
@@ -708,17 +737,26 @@ var QueryStream = class {
 	}
 	[Symbol.asyncIterator]() {
 		const iterator = this.iterWithKeys()[Symbol.asyncIterator]();
-		return { async next() {
-			const result = await iterator.next();
-			if (result.done) return {
-				done: true,
-				value: void 0
-			};
-			return {
-				done: false,
-				value: result.value[0]
-			};
-		} };
+		return {
+			async next() {
+				const result = await iterator.next();
+				if (result.done) return {
+					done: true,
+					value: void 0
+				};
+				return {
+					done: false,
+					value: result.value[0]
+				};
+			},
+			async return() {
+				await iterator.return?.();
+				return {
+					done: true,
+					value: void 0
+				};
+			}
+		};
 	}
 };
 var StreamDatabaseReader = class {
@@ -837,6 +875,7 @@ var OrderedStreamQuery = class extends StreamableQuery {
 			table: this.parent.parent.table,
 			index: this.parent.index,
 			indexFields: this.parent.q.indexFields,
+			indexFieldPaths: this.parent.q.indexFieldPaths,
 			order: this.order,
 			bounds: {
 				lowerBound: this.parent.q.lowerBoundIndexKey ?? [],
@@ -855,7 +894,7 @@ var OrderedStreamQuery = class extends StreamableQuery {
 		return db.query(table).withIndex(index, indexRange).order(order);
 	}
 	iterWithKeys() {
-		const { indexFields } = this.reflect();
+		const { indexFieldPaths } = this.reflect();
 		const iterable = this.inner();
 		return { [Symbol.asyncIterator]() {
 			const iterator = iterable[Symbol.asyncIterator]();
@@ -867,7 +906,7 @@ var OrderedStreamQuery = class extends StreamableQuery {
 				};
 				return {
 					done: false,
-					value: [result.value, getIndexKey(result.value, indexFields)]
+					value: [result.value, getIndexKey(result.value, indexFieldPaths)]
 				};
 			} };
 		} };
@@ -929,8 +968,11 @@ var ReflectIndexRange = class {
 	upperBoundInclusive = true;
 	equalityIndexFilter = [];
 	indexFields;
+	/** `indexFields`, each split on `.` once, for `getIndexKey`. */
+	indexFieldPaths;
 	constructor(indexFields) {
 		this.indexFields = indexFields;
+		this.indexFieldPaths = indexFields.map((field) => field.split("."));
 	}
 	eq(field, value) {
 		if (!this.#canLowerBound(field) || !this.#canUpperBound(field)) throw new Error(`Cannot use eq on field '${field}'`);
@@ -1022,16 +1064,24 @@ var ReflectIndexRange = class {
 function mergedStream(streams, orderByIndexFields) {
 	return new MergedStream(streams, orderByIndexFields);
 }
+/**
+* Marks sources that are already `OrderByStream`s, so `narrow` reuses them
+* instead of adding a redundant delegation layer per call.
+*
+* Module-private on purpose: wrapping is also where the ordering invariant is
+* checked, so no caller outside this file can skip it.
+*/
+const PRE_ORDERED_STREAMS = Symbol("preOrderedStreams");
 var MergedStream = class MergedStream extends QueryStream {
 	#order;
 	#streams;
 	#equalityIndexFilter;
 	#indexFields;
-	constructor(streams, orderByIndexFields) {
+	constructor(streams, orderByIndexFields, preOrdered) {
 		super();
 		if (streams.length === 0) throw new Error("Cannot union empty array of streams");
 		this.#order = allSame(streams.map((stream) => stream.getOrder()), "Cannot merge streams with different orders");
-		this.#streams = streams.map((stream) => new OrderByStream(stream, orderByIndexFields));
+		this.#streams = preOrdered === PRE_ORDERED_STREAMS ? streams : streams.map((stream) => new OrderByStream(stream, orderByIndexFields.slice()));
 		this.#indexFields = allSame(this.#streams.map((stream) => stream.getIndexFields()), "Cannot merge streams with different index fields. Consider using .orderBy()");
 		this.#equalityIndexFilter = commonPrefix(this.#streams.map((stream) => stream.getEqualityIndexFilter()));
 	}
@@ -1044,40 +1094,60 @@ var MergedStream = class MergedStream extends QueryStream {
 				done: false,
 				value: void 0
 			}));
-			return { async next() {
-				await Promise.all(iterators.map(async (iterator, i) => {
-					if (!results[i].done && !results[i].value) results[i] = await iterator.next();
-				}));
-				let minIndexKeyAndIndex;
-				for (let i = 0; i < results.length; i++) {
-					const result = results[i];
-					if (result.done || !result.value) continue;
-					const [_, resultIndexKey] = result.value;
-					if (minIndexKeyAndIndex === void 0) {
-						minIndexKeyAndIndex = [resultIndexKey, i];
-						continue;
+			let started = false;
+			let refillIndex;
+			return {
+				async next() {
+					if (started) {
+						if (refillIndex !== void 0) {
+							results[refillIndex] = await iterators[refillIndex].next();
+							refillIndex = void 0;
+						}
+					} else {
+						started = true;
+						await Promise.all(iterators.map(async (iterator, i) => {
+							results[i] = await iterator.next();
+						}));
 					}
-					const [prevMin, _prevMinIndex] = minIndexKeyAndIndex;
-					if (compareKeys({
-						value: resultIndexKey,
-						kind: "exact"
-					}, {
-						value: prevMin,
-						kind: "exact"
-					}) * comparisonInversion < 0) minIndexKeyAndIndex = [resultIndexKey, i];
+					let minIndexKeyAndIndex;
+					for (let i = 0; i < results.length; i++) {
+						const result = results[i];
+						if (result.done || !result.value) continue;
+						const [_, resultIndexKey] = result.value;
+						if (minIndexKeyAndIndex === void 0) {
+							minIndexKeyAndIndex = [resultIndexKey, i];
+							continue;
+						}
+						const [prevMin, _prevMinIndex] = minIndexKeyAndIndex;
+						if (compareKeys({
+							value: resultIndexKey,
+							kind: "exact"
+						}, {
+							value: prevMin,
+							kind: "exact"
+						}) * comparisonInversion < 0) minIndexKeyAndIndex = [resultIndexKey, i];
+					}
+					if (minIndexKeyAndIndex === void 0) return {
+						done: true,
+						value: void 0
+					};
+					const [_, minIndex] = minIndexKeyAndIndex;
+					const result = results[minIndex].value;
+					results[minIndex].value = void 0;
+					refillIndex = minIndex;
+					return {
+						done: false,
+						value: result
+					};
+				},
+				async return() {
+					await Promise.all(iterators.map((iterator) => iterator.return?.()));
+					return {
+						done: true,
+						value: void 0
+					};
 				}
-				if (minIndexKeyAndIndex === void 0) return {
-					done: true,
-					value: void 0
-				};
-				const [_, minIndex] = minIndexKeyAndIndex;
-				const result = results[minIndex].value;
-				results[minIndex].value = void 0;
-				return {
-					done: false,
-					value: result
-				};
-			} };
+			};
 		} };
 	}
 	getOrder() {
@@ -1090,7 +1160,7 @@ var MergedStream = class MergedStream extends QueryStream {
 		return this.#indexFields;
 	}
 	narrow(indexBounds) {
-		return new MergedStream(this.#streams.map((stream) => stream.narrow(indexBounds)), this.#indexFields);
+		return new MergedStream(this.#streams.map((stream) => stream.narrow(indexBounds)), this.#indexFields, PRE_ORDERED_STREAMS);
 	}
 };
 function allSame(values, errorMessage) {
@@ -1138,16 +1208,22 @@ var ConcatStreams = class ConcatStreams extends QueryStream {
 		this.#equalityIndexFilter = commonPrefix(streams.map((stream) => stream.getEqualityIndexFilter()));
 	}
 	iterWithKeys() {
-		const iterables = this.#streams.map((stream) => stream.iterWithKeys());
+		const streams = this.#streams;
 		const comparisonInversion = this.#order === "asc" ? 1 : -1;
-		let previousIndexKey;
 		return { [Symbol.asyncIterator]() {
-			const iterators = iterables.map((iterable) => iterable[Symbol.asyncIterator]());
-			return { async next() {
-				while (iterators.length > 0) {
-					const result = await iterators[0].next();
-					if (result.done) iterators.shift();
-					else {
+			let index = 0;
+			let iterator;
+			let previousIndexKey;
+			return {
+				async next() {
+					while (index < streams.length) {
+						iterator ??= streams[index].iterWithKeys()[Symbol.asyncIterator]();
+						const result = await iterator.next();
+						if (result.done) {
+							index++;
+							iterator = void 0;
+							continue;
+						}
 						const [_, indexKey] = result.value;
 						if (previousIndexKey !== void 0 && compareKeys({
 							value: previousIndexKey,
@@ -1159,12 +1235,21 @@ var ConcatStreams = class ConcatStreams extends QueryStream {
 						previousIndexKey = indexKey;
 						return result;
 					}
+					return {
+						done: true,
+						value: void 0
+					};
+				},
+				async return() {
+					await iterator?.return?.();
+					index = streams.length;
+					iterator = void 0;
+					return {
+						done: true,
+						value: void 0
+					};
 				}
-				return {
-					done: true,
-					value: void 0
-				};
-			} };
+			};
 		} };
 	}
 	getOrder() {
@@ -1237,6 +1322,18 @@ var FlatMapStreamIterator = class {
 			value: [u, [...this.#currentOuterItem.indexKey, ...indexKey]]
 		};
 	}
+	async return() {
+		try {
+			await this.#currentOuterItem?.innerIterator.return?.();
+		} finally {
+			this.#currentOuterItem = null;
+			await this.#outerIterator.return?.();
+		}
+		return {
+			done: true,
+			value: void 0
+		};
+	}
 };
 var FlatMapStream = class FlatMapStream extends QueryStream {
 	#stream;
@@ -1456,15 +1553,24 @@ var OrderByStream = class OrderByStream extends QueryStream {
 		const staticFilter = this.#staticFilter;
 		return { [Symbol.asyncIterator]() {
 			const iterator = iterable[Symbol.asyncIterator]();
-			return { async next() {
-				const result = await iterator.next();
-				if (result.done) return result;
-				const [doc, indexKey] = result.value;
-				return {
-					done: false,
-					value: [doc, indexKey.slice(staticFilter.length)]
-				};
-			} };
+			return {
+				async next() {
+					const result = await iterator.next();
+					if (result.done) return result;
+					const [doc, indexKey] = result.value;
+					return {
+						done: false,
+						value: [doc, indexKey.slice(staticFilter.length)]
+					};
+				},
+				async return() {
+					await iterator.return?.();
+					return {
+						done: true,
+						value: void 0
+					};
+				}
+			};
 		} };
 	}
 	narrow(indexBounds) {
@@ -1495,36 +1601,57 @@ var DistinctStream = class DistinctStream extends QueryStream {
 	iterWithKeys() {
 		const stream = this.#stream;
 		const distinctIndexFieldsLength = this.#distinctIndexFieldsLength;
+		const order = stream.getOrder();
+		const comparisonInversion = order === "asc" ? 1 : -1;
 		return { [Symbol.asyncIterator]() {
-			let currentStream = stream;
-			let currentIterator = currentStream.iterWithKeys()[Symbol.asyncIterator]();
-			return { async next() {
-				const result = await currentIterator.next();
-				if (result.done) return {
-					done: true,
-					value: void 0
-				};
-				const [doc, indexKey] = result.value;
-				if (doc === null) return {
-					done: false,
-					value: [null, indexKey]
-				};
-				const distinctIndexKey = indexKey.slice(0, distinctIndexFieldsLength);
-				if (stream.getOrder() === "asc") currentStream = currentStream.narrow({
-					lowerBound: distinctIndexKey,
-					lowerBoundInclusive: false,
-					upperBound: [],
-					upperBoundInclusive: true
-				});
-				else currentStream = currentStream.narrow({
-					lowerBound: [],
-					lowerBoundInclusive: true,
-					upperBound: distinctIndexKey,
-					upperBoundInclusive: false
-				});
-				currentIterator = currentStream.iterWithKeys()[Symbol.asyncIterator]();
-				return result;
-			} };
+			let currentIterator = stream.iterWithKeys()[Symbol.asyncIterator]();
+			let previousDistinctIndexKey;
+			return {
+				async next() {
+					const result = await currentIterator.next();
+					if (result.done) return {
+						done: true,
+						value: void 0
+					};
+					const [doc, indexKey] = result.value;
+					if (doc === null) return {
+						done: false,
+						value: [null, indexKey]
+					};
+					const distinctIndexKey = indexKey.slice(0, distinctIndexFieldsLength);
+					if (previousDistinctIndexKey !== void 0 && compareKeys({
+						value: previousDistinctIndexKey,
+						kind: "exact"
+					}, {
+						value: distinctIndexKey,
+						kind: "exact"
+					}) * comparisonInversion >= 0) throw new Error(`DistinctStream in wrong order: ${JSON.stringify(previousDistinctIndexKey)}, ${JSON.stringify(distinctIndexKey)}`);
+					previousDistinctIndexKey = distinctIndexKey;
+					let narrowed;
+					if (order === "asc") narrowed = stream.narrow({
+						lowerBound: distinctIndexKey,
+						lowerBoundInclusive: false,
+						upperBound: [],
+						upperBoundInclusive: true
+					});
+					else narrowed = stream.narrow({
+						lowerBound: [],
+						lowerBoundInclusive: true,
+						upperBound: distinctIndexKey,
+						upperBoundInclusive: false
+					});
+					await currentIterator.return?.();
+					currentIterator = narrowed.iterWithKeys()[Symbol.asyncIterator]();
+					return result;
+				},
+				async return() {
+					await currentIterator.return?.();
+					return {
+						done: true,
+						value: void 0
+					};
+				}
+			};
 		} };
 	}
 	narrow(indexBounds) {

package/dist/{where-clause-compiler-DVO0oBe9.d.ts → where-clause-compiler-CmBz9CWA.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;
   /**
@@ -2534,15 +2539,25 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * The where-clause compiler is built from declared indexes only, and `_id` is
    * never one of them, so an `id` filter can never be index-selected: it lands
    * in the post-filters and the stream walks the creation-time index until it
-   * happens on the row. `db.get()` reads exactly the rows asked for, so the ids
-   * are fetched directly and replayed as a creation-time-ordered stream — the
-   * order the scan would have produced, so stage order and cursors are the same.
+   * happens on the row. `db.get()` reads exactly the rows asked for.
+   *
+   * Rows come back in the order the ids were given, one read at a time. Missing
+   * or policy-filtered ids still cost a read, but a page does not reread the
+   * complete list. An `orderBy` on creation time is the exception: an id carries
+   * no creation time, so every id must be read before the first row is placed.
    *
    * Returns null when something else already owns the read: a pinned index, an
    * index the compiler did select, a `where(predicate)`, or an `orderBy` that
    * walks a different index.
    */
   private _buildIdLookupStream;
+  /**
+   * The declared index a stream read can walk to emit `field` in order.
+   *
+   * A stream orders by the index it scans, so only an index that leads with
+   * the field produces that order.
+   */
+  private _findStreamOrderIndex;
   private _buildBasePipelineStream;
   /**
    * Stream equivalent of the `db.query(...)` chain, used when a post-fetch
@@ -2616,6 +2631,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 +2685,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 +2695,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
@@ -4505,22 +4544,22 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "cursor";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "direction";
         };
       };
       updatedAt: ConvexNumberBuilderInitial<""> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.17.5",
+  "version": "0.19.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,8 +720,8 @@ const filtered = results.filter((a) => a.publishedAt >= startDate);
 
 ### Performance
 
-1. **Index first** — constrain leading index fields. Compound indexes follow prefix rules.
-2. **Bound scans** — use `maxScan` for predicate `where` (cursor mode only).
+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.
 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.