kitcn 0.32.0 → 0.32.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # kitcn
 
+## 0.32.1
+
+### Patch Changes
+
+- [#427](https://github.com/udecode/kitcn/pull/427) [`92381f5`](https://github.com/udecode/kitcn/commit/92381f56a660dfcd4679674f612e64c1518bcf75) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Improve the read cost of filtering parents by whether a related child exists.
+    `where: { posts: { type: 'wanted' } }` now stops at the first matching child
+    instead of loading the whole per-parent child window and testing it afterwards.
+    On one parent with 61 posts and a match sorting first, that is 2 document reads
+    instead of 62 — the same cost as the hand-written
+    `with: { posts: { where: { type: 'wanted' }, limit: 1 } }`. The same applies to
+    `where: { posts: true }`, to a relation existence test under `NOT`, and to
+    `through` relations, where it also stops at the first matching junction row.
+    Results are unchanged: the filter still decides from the same window it read
+    before, so a match past `defaultLimit` is excluded exactly as it was.
+  - A relation named more than once in one `where` — across `OR`, `AND` and `NOT`
+    branches — keeps the previous single unbounded load, because those branches
+    share it and each needs to read it in full.
+
 ## 0.32.0
 
 ### Minor Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
-import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-CD-Ij91k.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-FDJTqLDC.js";
+import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-Ctcw2VRq.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-BHGHbfb9.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";

package/dist/{capabilities-CD-Ij91k.d.ts → capabilities-Ctcw2VRq.d.ts}

@@ -3014,7 +3014,21 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _buildFieldFilterExpression;
   private _buildFilterExpression;
   private _mergeWithConfig;
+  /**
+   * Relation keys the filter tree mentions exactly once, across every OR/AND/NOT
+   * branch at this table level.
+   *
+   * `_mergeWithConfig` collapses the whole tree into one load per relation key,
+   * so a key two branches disagree about has to be loaded the way both branches
+   * can read. Only a key with a single occurrence has one predicate to satisfy,
+   * and only then can that predicate be pushed into the read plan.
+   *
+   * Relation values are not descended into: they belong to the target table and
+   * get their own count when that level is lowered.
+   */
+  private _collectSingleOccurrenceRelations;
   private _buildFilterWithConfig;
+  private _buildFilterWithConfigForLevel;
   private _stripFilterRelations;
   private _hasSearchDisallowedRelationFilter;
   private _searchFilterValuesEqual;

package/dist/orm/aggregate-index/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as RankIndexDefinition, G as CountBackfillChunkArgs, J as CountBackfillStatusArgs, K as CountBackfillKickoffArgs, Q as CountIndexDefinition, X as CountQueryPlan, Y as AggregateQueryPlan, Z as AggregateIndexDefinition, et as RankOrderField, q as CountBackfillMode, r as OrmCapability } from "../../capabilities-CD-Ij91k.js";
+import { $ as RankIndexDefinition, G as CountBackfillChunkArgs, J as CountBackfillStatusArgs, K as CountBackfillKickoffArgs, Q as CountIndexDefinition, X as CountQueryPlan, Y as AggregateQueryPlan, Z as AggregateIndexDefinition, et as RankOrderField, q as CountBackfillMode, r as OrmCapability } from "../../capabilities-Ctcw2VRq.js";
 
 //#region src/orm/aggregate-index/capability.d.ts
 /**

package/dist/orm/index.d.ts

@@ -1,5 +1,5 @@
-import { $n as TableName, $t as OrmLifecycleChange, An as ConvexCheckBuilder, At as UpdateSet, Bn as ConvexTextBuilder, Br as IsPrimaryKey, Bt as RelationsBuilderColumnBase, C as MigrationStep, Cn as ConvexVectorIndexConfig, Cr as not, Ct as OrderByClause, D as defineMigration, Dn as searchIndex, Dr as startsWith, Dt as ReturningAll, E as buildMigrationPlan, En as rankIndex, Er as or, Et as PredicateWhereIndexConfig, Fn as ConvexUniqueConstraintBuilderOn, Fr as ColumnBuilderTypeConfig, Ft as ExtractTablesFromSchema, Gn as Columns, Gt as TablesRelationalConfig, H as RlsMode, Hn as text, Hr as NotNull, In as ConvexUniqueConstraintConfig, Ir as ColumnBuilderWithTableName, It as ExtractTablesWithRelations, Jn as OrmSchemaExtensionTables, Jt as ConvexDeletionBuilder, Kt as defineRelations, Ln as check, Lr as ColumnDataType, Lt as ManyConfig, M as DatabaseWithQuery, Mn as ConvexForeignKeyBuilder, Mr as ColumnBuilder, Mt as VectorSearchProvider, N as OrmReader$1, Nn as ConvexForeignKeyConfig, Nr as ColumnBuilderBaseConfig, Nt as unsetToken, O as defineMigrationSet, On as uniqueIndex, Ot as ReturningResult, P as OrmWriter$1, Pn as ConvexUniqueConstraintBuilder, Pr as ColumnBuilderRuntimeConfig, Qn as OrmSchemaTriggers, Qt as DiscriminatorBuilderConfig, Rn as foreignKey, Rr as DrizzleEntity, Rt as OneConfig, S as MigrationStateMap, Sn as ConvexVectorIndexBuilderOn, Sr as ne, St as MutationRunMode, T as MigrationWriteMode, Tn as index, Tr as notInArray, Tt as PaginatedResult, U as EdgeMetadata, V as RlsContext, Vn as ConvexTextBuilderInitial, Vr as IsUnique, Vt as RelationsBuilderColumnConfig, W as extractRelationsConfig, Wn as Brand, Wt as TableRelationalConfig, Xn as OrmSchemaExtensions, Xt as ConvexTable, Yt as ConvexDeletionConfig, Zn as OrmSchemaRelations, Zt as ConvexTableWithColumns, _ as MigrationManifestEntry, _n as ConvexRankIndexBuilderOn, _r as isNotNull, _t as MutationExecutionMode, an as RlsPolicy, ar as UnaryExpression, at as BuildRelationResult, b as MigrationRunStatus, bn as ConvexSearchIndexConfig, br as lt, bt as MutationResult, cn as rlsPolicy, cr as contains, ct as DBQueryConfig, d as MigrationAppliedState, dn as rlsRole, dr as fieldRef, dt as InferInsertModel, en as OrmLifecycleOperation, er as BinaryExpression, f as MigrationDefinition, fn as ConvexAggregateIndexBuilder, fr as gt, ft as InferModelFromColumns, g as MigrationDriftIssue, gn as ConvexRankIndexBuilder, gr as isFieldReference, gt as MutationExecuteResult, h as MigrationDocContext, hn as ConvexIndexBuilderOn, hr as inArray, ht as MutationExecuteConfig, i as OrmMigrationCapability, in as discriminator, ir as LogicalExpression, it as BuildQueryResult, j as DatabaseWithMutations, jn as ConvexCheckConfig, jr as AnyColumn, jt as VectorQueryConfig, k as detectMigrationDrift, kn as vectorIndex, kr as SystemFields, kt as ReturningSelection, ln as RlsRole, lr as endsWith, lt as FilterOperators, m as MigrationDoc, mn as ConvexIndexBuilder, mr as ilike, mt as InsertValue, n as OrmCapabilities, nn as convexTable, nr as FieldReference, nt as AggregateFieldValue, on as RlsPolicyConfig, or as and, ot as CountConfig, p as MigrationDirection, pn as ConvexAggregateIndexBuilderOn, pr as gte, pt as InferSelectModel, qt as defineRelationsPart, r as OrmCapability, rn as deletion, rr as FilterExpression, rt as AggregateResult, sn as RlsPolicyToOption, sr as between, st as CountResult, t as OrmAggregateCapability, tn as TableConfig, tr as ExpressionVisitor, tt as AggregateConfig, un as RlsRoleConfig, ur as eq, ut as GetColumnData, v as MigrationMigrateOne, vn as ConvexSearchIndexBuilder, vr as isNull, vt as MutationPaginateConfig, w as MigrationTableName, wn as aggregateIndex, wr as notBetween, wt as OrderDirection, x as MigrationSet, xn as ConvexVectorIndexBuilder, xr as lte, xt as MutationReturning, y as MigrationPlan, yn as ConvexSearchIndexBuilderOn, yr as like, yt as MutationPaginatedResult, zn as unique, zr as HasDefault, zt as RelationsBuilder } from "../capabilities-CD-Ij91k.js";
-import { $ as OrmClientWithApi$1, A as ConvexDateMode, B as ConvexBytesBuilderInitial, C as ConvexNumberBuilderInitial, D as id, E as ConvexIdBuilderInitial, F as custom, G as ConvexBigIntBuilder, H as ConvexBooleanBuilder, I as json, J as CreateOrmOptions, K as ConvexBigIntBuilderInitial, L as objectOf, M as ConvexCustomBuilder, N as ConvexCustomBuilderInitial, O as ConvexDateBuilder, P as arrayOf, Q as OrmClientBase$1, R as unionOf, S as ConvexNumberBuilder, St as defineTriggers, T as ConvexIdBuilder, U as ConvexBooleanBuilderInitial, V as bytes, W as boolean, X as GenericOrmCtx$1, Y as GenericOrm$1, Z as OrmApiResult, _ as ConvexTimestampMode, _t as OrmBeforeResult, a as requireSchemaRelations, at as ScheduledMutationBatchArgs, b as ConvexTextEnumBuilderInitial, bt as OrmTriggerContext, c as TableConfigResult, ct as scheduledDeleteFactory, d as OrmNotFoundError, et as OrmFunctions, f as ConvexVectorBuilder, g as ConvexTimestampBuilderInitial, gt as defineSchemaExtension, h as ConvexTimestampBuilder, ht as SchemaExtension, i as getSchemaTriggers, it as createOrm, j as date, k as ConvexDateBuilderInitial, l as getTableColumns, m as vector, n as defineSchema, nt as OrmWriterCtx, o as asc, ot as scheduledMutationBatchFactory, p as ConvexVectorBuilderInitial, q as bigint, r as getSchemaRelations, rt as ResolveOrmSchema, s as desc, st as ScheduledDeleteArgs, t as WhereClauseResult, tt as OrmReaderCtx, u as getTableConfig, v as timestamp, vt as OrmTableTriggers, w as integer, x as textEnum, xt as OrmTriggers, y as ConvexTextEnumBuilder, yt as OrmTriggerChange, z as ConvexBytesBuilder } from "../where-clause-compiler-FDJTqLDC.js";
+import { $n as TableName, $t as OrmLifecycleChange, An as ConvexCheckBuilder, At as UpdateSet, Bn as ConvexTextBuilder, Br as IsPrimaryKey, Bt as RelationsBuilderColumnBase, C as MigrationStep, Cn as ConvexVectorIndexConfig, Cr as not, Ct as OrderByClause, D as defineMigration, Dn as searchIndex, Dr as startsWith, Dt as ReturningAll, E as buildMigrationPlan, En as rankIndex, Er as or, Et as PredicateWhereIndexConfig, Fn as ConvexUniqueConstraintBuilderOn, Fr as ColumnBuilderTypeConfig, Ft as ExtractTablesFromSchema, Gn as Columns, Gt as TablesRelationalConfig, H as RlsMode, Hn as text, Hr as NotNull, In as ConvexUniqueConstraintConfig, Ir as ColumnBuilderWithTableName, It as ExtractTablesWithRelations, Jn as OrmSchemaExtensionTables, Jt as ConvexDeletionBuilder, Kt as defineRelations, Ln as check, Lr as ColumnDataType, Lt as ManyConfig, M as DatabaseWithQuery, Mn as ConvexForeignKeyBuilder, Mr as ColumnBuilder, Mt as VectorSearchProvider, N as OrmReader$1, Nn as ConvexForeignKeyConfig, Nr as ColumnBuilderBaseConfig, Nt as unsetToken, O as defineMigrationSet, On as uniqueIndex, Ot as ReturningResult, P as OrmWriter$1, Pn as ConvexUniqueConstraintBuilder, Pr as ColumnBuilderRuntimeConfig, Qn as OrmSchemaTriggers, Qt as DiscriminatorBuilderConfig, Rn as foreignKey, Rr as DrizzleEntity, Rt as OneConfig, S as MigrationStateMap, Sn as ConvexVectorIndexBuilderOn, Sr as ne, St as MutationRunMode, T as MigrationWriteMode, Tn as index, Tr as notInArray, Tt as PaginatedResult, U as EdgeMetadata, V as RlsContext, Vn as ConvexTextBuilderInitial, Vr as IsUnique, Vt as RelationsBuilderColumnConfig, W as extractRelationsConfig, Wn as Brand, Wt as TableRelationalConfig, Xn as OrmSchemaExtensions, Xt as ConvexTable, Yt as ConvexDeletionConfig, Zn as OrmSchemaRelations, Zt as ConvexTableWithColumns, _ as MigrationManifestEntry, _n as ConvexRankIndexBuilderOn, _r as isNotNull, _t as MutationExecutionMode, an as RlsPolicy, ar as UnaryExpression, at as BuildRelationResult, b as MigrationRunStatus, bn as ConvexSearchIndexConfig, br as lt, bt as MutationResult, cn as rlsPolicy, cr as contains, ct as DBQueryConfig, d as MigrationAppliedState, dn as rlsRole, dr as fieldRef, dt as InferInsertModel, en as OrmLifecycleOperation, er as BinaryExpression, f as MigrationDefinition, fn as ConvexAggregateIndexBuilder, fr as gt, ft as InferModelFromColumns, g as MigrationDriftIssue, gn as ConvexRankIndexBuilder, gr as isFieldReference, gt as MutationExecuteResult, h as MigrationDocContext, hn as ConvexIndexBuilderOn, hr as inArray, ht as MutationExecuteConfig, i as OrmMigrationCapability, in as discriminator, ir as LogicalExpression, it as BuildQueryResult, j as DatabaseWithMutations, jn as ConvexCheckConfig, jr as AnyColumn, jt as VectorQueryConfig, k as detectMigrationDrift, kn as vectorIndex, kr as SystemFields, kt as ReturningSelection, ln as RlsRole, lr as endsWith, lt as FilterOperators, m as MigrationDoc, mn as ConvexIndexBuilder, mr as ilike, mt as InsertValue, n as OrmCapabilities, nn as convexTable, nr as FieldReference, nt as AggregateFieldValue, on as RlsPolicyConfig, or as and, ot as CountConfig, p as MigrationDirection, pn as ConvexAggregateIndexBuilderOn, pr as gte, pt as InferSelectModel, qt as defineRelationsPart, r as OrmCapability, rn as deletion, rr as FilterExpression, rt as AggregateResult, sn as RlsPolicyToOption, sr as between, st as CountResult, t as OrmAggregateCapability, tn as TableConfig, tr as ExpressionVisitor, tt as AggregateConfig, un as RlsRoleConfig, ur as eq, ut as GetColumnData, v as MigrationMigrateOne, vn as ConvexSearchIndexBuilder, vr as isNull, vt as MutationPaginateConfig, w as MigrationTableName, wn as aggregateIndex, wr as notBetween, wt as OrderDirection, x as MigrationSet, xn as ConvexVectorIndexBuilder, xr as lte, xt as MutationReturning, y as MigrationPlan, yn as ConvexSearchIndexBuilderOn, yr as like, yt as MutationPaginatedResult, zn as unique, zr as HasDefault, zt as RelationsBuilder } from "../capabilities-Ctcw2VRq.js";
+import { $ as OrmClientWithApi$1, A as ConvexDateMode, B as ConvexBytesBuilderInitial, C as ConvexNumberBuilderInitial, D as id, E as ConvexIdBuilderInitial, F as custom, G as ConvexBigIntBuilder, H as ConvexBooleanBuilder, I as json, J as CreateOrmOptions, K as ConvexBigIntBuilderInitial, L as objectOf, M as ConvexCustomBuilder, N as ConvexCustomBuilderInitial, O as ConvexDateBuilder, P as arrayOf, Q as OrmClientBase$1, R as unionOf, S as ConvexNumberBuilder, St as defineTriggers, T as ConvexIdBuilder, U as ConvexBooleanBuilderInitial, V as bytes, W as boolean, X as GenericOrmCtx$1, Y as GenericOrm$1, Z as OrmApiResult, _ as ConvexTimestampMode, _t as OrmBeforeResult, a as requireSchemaRelations, at as ScheduledMutationBatchArgs, b as ConvexTextEnumBuilderInitial, bt as OrmTriggerContext, c as TableConfigResult, ct as scheduledDeleteFactory, d as OrmNotFoundError, et as OrmFunctions, f as ConvexVectorBuilder, g as ConvexTimestampBuilderInitial, gt as defineSchemaExtension, h as ConvexTimestampBuilder, ht as SchemaExtension, i as getSchemaTriggers, it as createOrm, j as date, k as ConvexDateBuilderInitial, l as getTableColumns, m as vector, n as defineSchema, nt as OrmWriterCtx, o as asc, ot as scheduledMutationBatchFactory, p as ConvexVectorBuilderInitial, q as bigint, r as getSchemaRelations, rt as ResolveOrmSchema, s as desc, st as ScheduledDeleteArgs, t as WhereClauseResult, tt as OrmReaderCtx, u as getTableConfig, v as timestamp, vt as OrmTableTriggers, w as integer, x as textEnum, xt as OrmTriggers, y as ConvexTextEnumBuilder, yt as OrmTriggerChange, z as ConvexBytesBuilder } from "../where-clause-compiler-BHGHbfb9.js";
 import { i as pretendRequired, n as deprecated, r as pretend } from "../validators-0I-Ik1EN.js";
 import { a as QueryCtxWithPreferredOrmQueryTable, i as QueryCtxWithOrmQueryTable, n as LookupByIdResultByCtx, o as getByIdWithOrmQueryFallback, r as QueryCtxWithOptionalOrmQueryTable, t as DocByCtx } from "../query-context-BkNjkDCk.js";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchemaDefinition } from "convex/server";

package/dist/orm/index.js

@@ -1322,6 +1322,20 @@ const DEFAULT_RELATION_FAN_OUT_MAX_KEYS = 1e3;
 * satisfies the limit.
 */
 const RELATION_FILTER_STREAM_CHUNK = 32;
+/**
+* Marks a relation config that only exists to answer "does a matching child
+* exist?" for a `where` clause. The lowered load may stop at the first
+* surviving child, but it must not widen the window it walks to find one --
+* that window is what decides the answer, so changing it would change results
+* rather than just their cost.
+*
+* A symbol, not a field: the emitted object is fed to the same relation loader
+* that serves a caller's `with`, and nothing a caller can write should be able
+* to claim this.
+*/
+const RELATION_EXISTENCE_PROBE = Symbol("kitcn.relationExistenceProbe");
+/** Lowering a subtree with this set emits no existence probes anywhere in it. */
+const NO_PROBE_RELATIONS = /* @__PURE__ */ new Set();
 const DEFAULT_AGGREGATE_CARTESIAN_MAX_KEYS = 4096;
 const DEFAULT_AGGREGATE_WORK_BUDGET = 16384;
 const PUBLIC_ID_FIELD = "id";
@@ -2391,7 +2405,47 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			}
 		}
 	}
+	/**
+	* Relation keys the filter tree mentions exactly once, across every OR/AND/NOT
+	* branch at this table level.
+	*
+	* `_mergeWithConfig` collapses the whole tree into one load per relation key,
+	* so a key two branches disagree about has to be loaded the way both branches
+	* can read. Only a key with a single occurrence has one predicate to satisfy,
+	* and only then can that predicate be pushed into the read plan.
+	*
+	* Relation values are not descended into: they belong to the target table and
+	* get their own count when that level is lowered.
+	*/
+	_collectSingleOccurrenceRelations(filter, tableConfig) {
+		const counts = /* @__PURE__ */ new Map();
+		const walk = (node) => {
+			if (!this._isRecord(node)) return;
+			for (const [key, value] of Object.entries(node)) {
+				if (value === void 0) continue;
+				if (key === "OR" || key === "AND") {
+					if (!Array.isArray(value)) continue;
+					for (const sub of value) walk(sub);
+					continue;
+				}
+				if (key === "NOT") {
+					walk(value);
+					continue;
+				}
+				if (!tableConfig.relations[key]) continue;
+				counts.set(key, (counts.get(key) ?? 0) + 1);
+			}
+		};
+		walk(filter);
+		const single = /* @__PURE__ */ new Set();
+		for (const [key, count] of counts) if (count === 1) single.add(key);
+		return single;
+	}
 	_buildFilterWithConfig(filter, tableConfig) {
+		if (!this._isRecord(filter)) return {};
+		return this._buildFilterWithConfigForLevel(filter, tableConfig, this._collectSingleOccurrenceRelations(filter, tableConfig));
+	}
+	_buildFilterWithConfigForLevel(filter, tableConfig, probeEligible) {
 		if (!this._isRecord(filter)) return {};
 		const result = {};
 		const entries = Object.entries(filter);
@@ -2401,27 +2455,36 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			if (key === "OR" || key === "AND") {
 				if (!Array.isArray(value) || value.length === 0) continue;
 				for (const sub of value) {
-					const nested = this._buildFilterWithConfig(sub, tableConfig);
+					const nested = this._buildFilterWithConfigForLevel(sub, tableConfig, probeEligible);
 					this._mergeWithConfig(result, nested);
 				}
 				continue;
 			}
 			if (key === "NOT") {
-				const nested = this._buildFilterWithConfig(value, tableConfig);
+				const nested = this._buildFilterWithConfigForLevel(value, tableConfig, probeEligible);
 				this._mergeWithConfig(result, nested);
 				continue;
 			}
 			this._assertNoLegacyPublicFieldName(key);
 			const relation = tableConfig.relations[key];
 			if (!relation) continue;
+			const probe = relation.relationType !== "one" && probeEligible.has(key) ? { [RELATION_EXISTENCE_PROBE]: true } : void 0;
 			if (typeof value === "boolean") {
-				result[key] = true;
+				result[key] = probe ?? true;
 				continue;
 			}
 			const targetTableConfig = this._getTableConfigByDbName(relation.targetTableName);
 			if (!targetTableConfig) continue;
-			const nested = this._buildFilterWithConfig(value, targetTableConfig);
-			result[key] = Object.keys(nested).length > 0 ? { with: nested } : true;
+			const nested = this._buildFilterWithConfigForLevel(value, targetTableConfig, probe ? this._collectSingleOccurrenceRelations(value, targetTableConfig) : NO_PROBE_RELATIONS);
+			const hasNested = Object.keys(nested).length > 0;
+			if (!probe) {
+				result[key] = hasNested ? { with: nested } : true;
+				continue;
+			}
+			const emitted = { ...probe };
+			if (Object.keys(value).length > 0) emitted.where = value;
+			if (hasNested) emitted.with = nested;
+			result[key] = emitted;
 		}
 		return result;
 	}
@@ -4955,9 +5018,10 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* parents in the round.
 	*/
 	async _readBoundedThroughLinks(params) {
-		const { applyTargetFilters, edge, enforceTargetKeyCap, entries, fetchLimit, fetchTargets, targetFields, throughIndexName, throughTableConfig } = params;
+		const { applyAmbientTargetFilters, applyConfigTargetFilter, edge, enforceTargetKeyCap, entries, fetchLimit, fetchTargets, scanLimit, targetFields, throughIndexName, throughTableConfig } = params;
 		const throughTargetFields = edge.through.targetFields;
 		const cursors = entries.map(([key, values]) => ({
+			ambientLinks: 0,
 			buffered: [],
 			exhausted: false,
 			iterator: this._queryByFields(this.db.query(edge.through.table), edge.through.sourceFields, values, throughIndexName)[Symbol.asyncIterator](),
@@ -4984,10 +5048,12 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		};
 		/** Target key -> the surviving document, absent when it did not survive. */
 		const survivorByKey = /* @__PURE__ */ new Map();
+		/** Target keys that cleared the ambient filters, survivors or not. */
+		const ambientKeys = /* @__PURE__ */ new Set();
 		const resolvedKeys = /* @__PURE__ */ new Set();
 		const survivors = [];
 		while (true) {
-			const active = cursors.filter((cursor) => cursor.links.length < fetchLimit && !(cursor.exhausted && cursor.buffered.length === 0));
+			const active = cursors.filter((cursor) => cursor.links.length < fetchLimit && (scanLimit === void 0 || cursor.ambientLinks < scanLimit) && !(cursor.exhausted && cursor.buffered.length === 0));
 			if (active.length === 0) break;
 			const candidatesPerCursor = await this._mapWithConcurrency(active, async (cursor) => {
 				const need = fetchLimit - cursor.links.length;
@@ -5006,7 +5072,12 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				enforceTargetKeyCap(resolvedKeys.size + newKeys.size);
 				const fetched = await fetchTargets(Array.from(newKeys.entries()));
 				for (const key of newKeys.keys()) resolvedKeys.add(key);
-				const surviving = await applyTargetFilters(fetched.map((entry) => entry.target).filter((target) => !!target));
+				const ambientTargets = await applyAmbientTargetFilters(fetched.map((entry) => entry.target).filter((target) => !!target));
+				for (const target of ambientTargets) {
+					const key = this._buildRelationKey(target, targetFields);
+					if (key) ambientKeys.add(key);
+				}
+				const surviving = await applyConfigTargetFilter(ambientTargets);
 				for (const target of surviving) {
 					const key = this._buildRelationKey(target, targetFields);
 					if (!key || survivorByKey.has(key)) continue;
@@ -5018,8 +5089,11 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				const cursor = active[i];
 				for (const link of candidatesPerCursor[i]) {
 					if (cursor.links.length >= fetchLimit) break;
+					if (scanLimit !== void 0 && cursor.ambientLinks >= scanLimit) break;
 					const key = this._buildRelationKey(link, throughTargetFields);
-					if (!key || !survivorByKey.has(key)) continue;
+					if (!key) continue;
+					if (ambientKeys.has(key)) cursor.ambientLinks += 1;
+					if (!survivorByKey.has(key)) continue;
 					cursor.links.push(link);
 				}
 			}
@@ -5072,6 +5146,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const relationDefinition = tableConfig.relations[relationName];
 		const strict = tableConfig.strict !== false;
 		const hasPostFetchTargetFilter = this.rls?.mode !== "skip" && isRlsEnabled(targetTableConfig.table) || Boolean(relationDefinition?.where) || Boolean(relationConfig && typeof relationConfig === "object" && "where" in relationConfig && relationConfig.where);
+		const isExistenceProbe = Boolean(relationConfig) && typeof relationConfig === "object" && relationConfig[RELATION_EXISTENCE_PROBE] === true;
 		let orderSpecs = [];
 		if (relationConfig && typeof relationConfig === "object" && "orderBy" in relationConfig) {
 			let orderByValue = relationConfig.orderBy;
@@ -5086,15 +5161,22 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (effectivePerParentLimit === void 0 && !this.allowFullScan) throw new Error(`Relation "${tableConfig.name}.${relationName}" requires limit, allowFullScan: true, or defineSchema(..., { defaults: { defaultLimit } }).`);
 		const perParentOffset = relationConfig && typeof relationConfig === "object" && "offset" in relationConfig ? relationConfig.offset : void 0;
 		if (perParentOffset !== void 0 && typeof perParentOffset !== "number") throw new Error("Only numeric offset is supported in kitcn ORM.");
+		const probeFetchLimit = isExistenceProbe ? 1 : void 0;
+		const probeScanLimit = isExistenceProbe ? effectivePerParentLimit : void 0;
+		const canBoundPerParentRead = effectivePerParentLimit !== void 0 || isExistenceProbe;
 		const applyOffsetAndLimit = (items) => {
 			let result = items;
 			if (perParentOffset !== void 0 && perParentOffset > 0) result = result.slice(perParentOffset);
 			if (effectivePerParentLimit !== void 0) result = result.slice(0, effectivePerParentLimit);
 			return result;
 		};
-		const applyPostFetchTargetFilters = async (candidateTargets) => {
-			let filteredTargets = await this._applyRlsSelectFilter(candidateTargets, targetTableConfig);
-			if (relationDefinition?.where) filteredTargets = filteredTargets.filter((target) => this._evaluateTableFilter(target, targetTableConfig, relationDefinition.where));
+		const applyAmbientTargetFilters = async (candidateTargets) => {
+			const visibleTargets = await this._applyRlsSelectFilter(candidateTargets, targetTableConfig);
+			if (!relationDefinition?.where) return visibleTargets;
+			return visibleTargets.filter((target) => this._evaluateTableFilter(target, targetTableConfig, relationDefinition.where));
+		};
+		const applyConfigTargetFilter = async (ambientTargets) => {
+			let filteredTargets = ambientTargets;
 			if (relationConfig && typeof relationConfig === "object" && "where" in relationConfig) {
 				const whereFilter = relationConfig.where;
 				if (typeof whereFilter === "function") {
@@ -5107,6 +5189,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			}
 			return filteredTargets;
 		};
+		const applyPostFetchTargetFilters = async (candidateTargets) => applyConfigTargetFilter(await applyAmbientTargetFilters(candidateTargets));
 		let targets = [];
 		let throughBySourceKey;
 		let targetFiltersApplied = false;
@@ -5141,14 +5224,16 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					};
 				});
 			};
-			if (orderSpecs.length === 0 && effectivePerParentLimit !== void 0) {
+			if (orderSpecs.length === 0 && canBoundPerParentRead) {
 				const bounded = await this._readBoundedThroughLinks({
-					applyTargetFilters: applyPostFetchTargetFilters,
+					applyAmbientTargetFilters,
+					applyConfigTargetFilter,
 					edge,
 					enforceTargetKeyCap,
 					entries,
-					fetchLimit: Math.max(perParentOffset ?? 0, 0) + effectivePerParentLimit,
+					fetchLimit: probeFetchLimit ?? Math.max(perParentOffset ?? 0, 0) + effectivePerParentLimit,
 					fetchTargets: fetchThroughTargets,
+					scanLimit: probeScanLimit,
 					targetFields,
 					throughIndexName,
 					throughTableConfig
@@ -5188,22 +5273,25 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			});
 			const orderServedByIndex = orderSpecs.length === 0 || orderPushdownDirection !== null;
 			const applyPushdownOrder = (query) => orderPushdownDirection ? query.order(orderPushdownDirection) : query;
-			const streamPostFetchTargetFilters = orderServedByIndex && hasPostFetchTargetFilter && effectivePerParentLimit !== void 0;
+			const streamPostFetchTargetFilters = orderServedByIndex && hasPostFetchTargetFilter && canBoundPerParentRead;
 			targetFiltersApplied = streamPostFetchTargetFilters;
 			targets = (await this._mapWithConcurrency(entries, async ([, values]) => {
 				const query = this._queryByFields(this.db.query(edge.targetTable), targetFields, values, indexName);
-				if (orderServedByIndex && !hasPostFetchTargetFilter && effectivePerParentLimit !== void 0) {
-					const fetchLimit = (perParentOffset ?? 0) + (effectivePerParentLimit ?? 0);
+				if (orderServedByIndex && !hasPostFetchTargetFilter && canBoundPerParentRead) {
+					const fetchLimit = probeFetchLimit ?? (perParentOffset ?? 0) + (effectivePerParentLimit ?? 0);
 					return await applyPushdownOrder(query).take(fetchLimit);
 				}
 				if (streamPostFetchTargetFilters) {
 					const visibleTargets = [];
-					const fetchLimit = Math.max(perParentOffset ?? 0, 0) + (effectivePerParentLimit ?? 0);
+					const fetchLimit = probeFetchLimit ?? Math.max(perParentOffset ?? 0, 0) + (effectivePerParentLimit ?? 0);
 					let batch = [];
+					let ambientSeen = 0;
 					const drain = async () => {
 						if (batch.length === 0) return;
-						const filtered = await applyPostFetchTargetFilters(batch);
+						const ambientTargets = await applyAmbientTargetFilters(batch);
 						batch = [];
+						ambientSeen += ambientTargets.length;
+						const filtered = await applyConfigTargetFilter(ambientTargets);
 						for (const row of filtered) {
 							if (visibleTargets.length >= fetchLimit) return;
 							visibleTargets.push(row);
@@ -5215,6 +5303,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 						if (batch.length < chunk) continue;
 						await drain();
 						if (visibleTargets.length >= fetchLimit) break;
+						if (probeScanLimit !== void 0 && ambientSeen >= probeScanLimit) break;
 					}
 					if (visibleTargets.length < fetchLimit) await drain();
 					return visibleTargets;

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-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";
+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-Ctcw2VRq.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-BHGHbfb9.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/{where-clause-compiler-FDJTqLDC.d.ts → where-clause-compiler-BHGHbfb9.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-CD-Ij91k.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-Ctcw2VRq.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";

package/package.json

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