kitcn 0.32.0 → 0.32.2

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";
@@ -1619,6 +1633,20 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* intervening write would make it stale.
 	*/
 	_documentByNormalizedId = /* @__PURE__ */ new Map();
+	/**
+	* Single target documents resolved by an eq-pinned key during one execution,
+	* keyed on the read itself: table, index, join columns and their values.
+	*
+	* `_documentByNormalizedId` only covers a join on the primary id. A relation
+	* joined on any other column resolves its target with `.first()` instead, and
+	* the same one-row-at-a-time membership predicate re-issues that read once per
+	* drain. The index is fixed for the whole relation and the key is pinned by
+	* `eq`, so the first row is a pure function of this key within an execution.
+	*
+	* Same scope and staleness argument as `_documentByNormalizedId`: not handed
+	* to the next run by `_forExecution`, so an intervening write is still seen.
+	*/
+	_firstDocumentByFieldKey = /* @__PURE__ */ new Map();
 	constructor(schema, tableConfig, edgeMetadata, db, config, mode, _allEdges, rls, relationLoading, vectorSearchProvider, configuredIndex, countIndexReadiness) {
 		super();
 		this.schema = schema;
@@ -2391,7 +2419,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 +2469,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;
 	}
@@ -4637,18 +4714,75 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (!this._allEdges) return [];
 		return this._allEdges.filter((edge) => edge.sourceTable === tableName);
 	}
+	/**
+	* A memo entry is a snapshot, so every caller has to get its own document.
+	*
+	* Relation loaders write nested `with` results and `extras` straight onto the
+	* target they were handed, and `hydrateDateFieldsForRead` copies every own key
+	* it finds. Two loads that share one entry would therefore publish each
+	* other's fields — a relation asked for as `true` coming back carrying a
+	* nested relation only the `where` requested. Those writes are all top-level,
+	* so a shallow copy is exactly as much isolation as they need.
+	*/
+	_ownedCopy(doc) {
+		return doc === null || doc === void 0 ? null : { ...doc };
+	}
 	async _getById(tableName, id) {
 		if (id === null || id === void 0) return null;
 		const normalizedId = this.db.normalizeId(tableName, id);
 		if (normalizedId === null) return null;
 		const existing = this._documentByNormalizedId.get(normalizedId);
-		if (existing) return await existing;
+		if (existing) return this._ownedCopy(await existing);
 		const pending = Promise.resolve(this.db.get(normalizedId)).catch((error) => {
 			this._documentByNormalizedId.delete(normalizedId);
 			throw error;
 		});
 		this._documentByNormalizedId.set(normalizedId, pending);
-		return await pending;
+		return this._ownedCopy(await pending);
+	}
+	/**
+	* Identity of one `_firstByFields` read, or null when the join values cannot
+	* be encoded losslessly.
+	*
+	* `JSON.stringify` alone is not safe here. It renders every `ArrayBuffer` as
+	* `{}` and `NaN`/`Infinity`/`-Infinity` as `null`, so two distinct join values
+	* would share one entry, and it throws outright on `int64`. The relation
+	* loader's own per-batch key map cannot catch that, because the residual
+	* relation `where` hands it one row at a time — a map of one never compares
+	* two values. This key is the only thing that tells them apart.
+	*
+	* `convexToJson` is the same wire encoding the client uses for query keys, so
+	* every Convex value round-trips distinctly. Anything it rejects is not a
+	* Convex value and simply goes unmemoized.
+	*/
+	_firstByFieldsMemoKey(tableName, fields, values, indexName) {
+		try {
+			return JSON.stringify([
+				tableName,
+				indexName,
+				fields,
+				values.map((value) => convexToJson(value))
+			]);
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* `_getById` for a relation joined on something other than the primary id:
+	* resolve one target document by an eq-pinned key, memoized per execution.
+	*/
+	async _firstByFields(tableName, fields, values, indexName) {
+		const read = () => this._queryByFields(this.db.query(tableName), fields, values, indexName).first();
+		const key = this._firstByFieldsMemoKey(tableName, fields, values, indexName);
+		if (key === null) return await read();
+		const existing = this._firstDocumentByFieldKey.get(key);
+		if (existing) return this._ownedCopy(await existing);
+		const pending = Promise.resolve(read()).catch((error) => {
+			this._firstDocumentByFieldKey.delete(key);
+			throw error;
+		});
+		this._firstDocumentByFieldKey.set(key, pending);
+		return this._ownedCopy(await pending);
 	}
 	_getRelationConcurrency() {
 		const value = this.relationLoading?.concurrency;
@@ -4800,7 +4934,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			const resolveTargetMatch = async (values) => {
 				let target = null;
 				if (useGetById) target = await this._getById(edge.targetTable, values[0]);
-				else target = await this._queryByFields(this.db.query(edge.targetTable), targetFields, values, targetIndexName).first();
+				else target = await this._firstByFields(edge.targetTable, targetFields, values, targetIndexName);
 				if (!target) return false;
 				return this._evaluateTableFilter(target, targetTableConfig, whereRecord);
 			};
@@ -4902,7 +5036,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const fetched = await this._mapWithConcurrency(entries, async ([key, values]) => {
 			let target = null;
 			if (useGetById) target = await this._getById(edge.targetTable, values[0]);
-			else target = await this._queryByFields(this.db.query(edge.targetTable), targetFields, values, indexName).first();
+			else target = await this._firstByFields(edge.targetTable, targetFields, values, indexName);
 			return {
 				key,
 				target
@@ -4955,9 +5089,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 +5119,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 +5143,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 +5160,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 +5217,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 +5232,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 +5260,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			}
 			return filteredTargets;
 		};
+		const applyPostFetchTargetFilters = async (candidateTargets) => applyConfigTargetFilter(await applyAmbientTargetFilters(candidateTargets));
 		let targets = [];
 		let throughBySourceKey;
 		let targetFiltersApplied = false;
@@ -5134,21 +5288,23 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				return await this._mapWithConcurrency(keyEntries, async ([key, values]) => {
 					let target = null;
 					if (useGetById) target = await this._getById(edge.targetTable, values[0]);
-					else target = await this._queryByFields(this.db.query(edge.targetTable), targetFields, values, indexName).first();
+					else target = await this._firstByFields(edge.targetTable, targetFields, values, indexName);
 					return {
 						key,
 						target
 					};
 				});
 			};
-			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 +5344,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 +5374,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-BJm_VSDT.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-Dgf4lrO-.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 };