kitcn 0.26.3 → 0.27.1

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # kitcn
 
+## 0.27.1
+
+### Patch Changes
+
+- [#396](https://github.com/udecode/kitcn/pull/396) [`8fca5cc`](https://github.com/udecode/kitcn/commit/8fca5cc53c37bd6f651cfbfbf50b87d5461d0ce5) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Match every args variant from `crpc.<path>.queryFilter()` when `args` is
+    omitted, `null`, or `{}`, in both the React and Solid bindings. The filter
+    built a key with an empty args slot, which TanStack's partial matching never
+    matched, so `invalidateQueries` silently refreshed nothing and stale data
+    stayed on screen. Pass args to narrow the filter; omit them to reach every
+    variant. `crpc.http.*.queryFilter()` follows the same rule.
+
+  ```ts
+  // Before
+  crpc.analytics.getReport.queryFilter(); // ['convexQuery', 'analytics:getReport', undefined] — matched nothing
+  queryClient.invalidateQueries(crpc.analytics.getReport.queryFilter()); // no-op
+
+  // After
+  crpc.analytics.getReport.queryFilter(); // ['convexQuery', 'analytics:getReport']
+  queryClient.invalidateQueries(crpc.analytics.getReport.queryFilter()); // every args variant
+  ```
+
+## 0.27.0
+
+### Minor Changes
+
+- [#395](https://github.com/udecode/kitcn/pull/395) [`2c9ffd2`](https://github.com/udecode/kitcn/commit/2c9ffd20987e4a94cb5790cbb72e6249f1fdfcf4) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Breaking changes
+
+  - Nested `with:` now loads every level it is given, up to 10, instead of quietly dropping everything past the third. A config that nests deeper throws `RELATION_DEPTH_EXCEEDED` rather than returning a shorter tree. Deep `with:` configs that used to come back truncated now come back complete — and read the rows that completeness costs.
+
+  ```ts
+  // Before: the fourth level was dropped, with no error
+  const rows = await ctx.orm.query.comments.findMany({
+    limit: 20,
+    with: {
+      replies: {
+        limit: 10,
+        with: { replies: { limit: 10, with: { author: true } } },
+      },
+    },
+  });
+  rows[0].replies[0].replies[0].author; // undefined
+
+  // After: loaded, because it was asked for
+  rows[0].replies[0].replies[0].author; // { id, name }
+  ```
+
+  ## Patches
+
+  - Resolve `with: { _count }` at every level of a nested `with:`, including the deepest one returned. A tree can now report how many children it withheld without a second pass that re-reads every node the caller already holds.
+
 ## 0.26.3
 
 ### Patch Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
-import { Bn as ConvexTextBuilderInitial, Xt as ConvexTableWithColumns } from "../capabilities-QNGgWHQd.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-DfFcNKtn.js";
+import { Bn as ConvexTextBuilderInitial, Xt as ConvexTableWithColumns } from "../capabilities-CLCYgRdY.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-CErbOMvj.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-QNGgWHQd.d.ts → capabilities-CLCYgRdY.d.ts}

@@ -3131,7 +3131,7 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    * @param rows - Array of parent records to load relations for
    * @param withConfig - Relation configuration object
    * @param depth - Current recursion depth (default 0)
-   * @param maxDepth - Maximum recursion depth (default 3)
+   * @param maxDepth - Runaway ceiling for self-referential configs (default `MAX_RELATION_DEPTH`)
    * @param targetTableEdges - Edge metadata for nested relations (optional, defaults to this.edgeMetadata)
    */
   private _loadRelations;
@@ -3142,6 +3142,7 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    */
   private _loadSingleRelation;
   private _createRelationCountError;
+  private _createRelationDepthError;
   private _remapRelationCountError;
   private _coerceRelationCountWhere;
   private _getRelationCountParentKey;

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

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

package/dist/orm/index.d.ts

@@ -1,5 +1,5 @@
-import { $n as BinaryExpression, $t as OrmLifecycleOperation, A as DatabaseWithMutations, An as ConvexCheckConfig, Ar as AnyColumn, At as VectorQueryConfig, B as RlsContext, Bn as ConvexTextBuilderInitial, Br as IsUnique, Bt as RelationsBuilderColumnConfig, C as MigrationTableName, Cn as aggregateIndex, Cr as notBetween, Ct as OrderDirection, D as defineMigrationSet, Dn as uniqueIndex, Dt as ReturningResult, E as defineMigration, En as searchIndex, Er as startsWith, Et as ReturningAll, Fn as ConvexUniqueConstraintConfig, Fr as ColumnBuilderWithTableName, Ft as ExtractTablesWithRelations, Gt as defineRelations, H as EdgeMetadata, In as check, Ir as ColumnDataType, It as ManyConfig, Jt as ConvexDeletionConfig, Kt as defineRelationsPart, Ln as foreignKey, Lr as DrizzleEntity, Lt as OneConfig, M as OrmReader$1, Mn as ConvexForeignKeyConfig, Mr as ColumnBuilderBaseConfig, Mt as unsetToken, N as OrmWriter$1, Nn as ConvexUniqueConstraintBuilder, Nr as ColumnBuilderRuntimeConfig, O as detectMigrationDrift, On as vectorIndex, Or as SystemFields, Ot as ReturningSelection, Pn as ConvexUniqueConstraintBuilderOn, Pr as ColumnBuilderTypeConfig, Pt as ExtractTablesFromSchema, Qn as TableName, Qt as OrmLifecycleChange, Rn as unique, Rr as HasDefault, Rt as RelationsBuilder, S as MigrationStep, Sn as ConvexVectorIndexConfig, Sr as not, St as OrderByClause, T as buildMigrationPlan, Tn as rankIndex, Tr as or, Tt as PredicateWhereIndexConfig, U as extractRelationsConfig, Un as Brand, Ut as TableRelationalConfig, V as RlsMode, Vn as text, Vr as NotNull, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yn as OrmSchemaExtensions, Yt as ConvexTable, Zn as OrmSchemaTriggers, Zt as DiscriminatorBuilderConfig, _ as MigrationMigrateOne, _n as ConvexSearchIndexBuilder, _r as isNull, _t as MutationPaginateConfig, an as RlsPolicyConfig, ar as and, at as CountConfig, b as MigrationSet, bn as ConvexVectorIndexBuilder, br as lte, bt as MutationReturning, cn as RlsRole, cr as endsWith, ct as FilterOperators, d as MigrationDefinition, dn as ConvexAggregateIndexBuilder, dr as gt, dt as InferModelFromColumns, en as TableConfig, er as ExpressionVisitor, et as AggregateConfig, f as MigrationDirection, fn as ConvexAggregateIndexBuilderOn, fr as gte, ft as InferSelectModel, g as MigrationManifestEntry, gn as ConvexRankIndexBuilderOn, gr as isNotNull, gt as MutationExecutionMode, h as MigrationDriftIssue, hn as ConvexRankIndexBuilder, hr as isFieldReference, ht as MutationExecuteResult, i as OrmMigrationCapability, in as RlsPolicy, ir as UnaryExpression, it as BuildRelationResult, j as DatabaseWithQuery, jn as ConvexForeignKeyBuilder, jr as ColumnBuilder, jt as VectorSearchProvider, kn as ConvexCheckBuilder, kt as UpdateSet, ln as RlsRoleConfig, lr as eq, lt as GetColumnData, m as MigrationDocContext, mn as ConvexIndexBuilderOn, mr as inArray, mt as MutationExecuteConfig, n as OrmCapabilities, nn as deletion, nr as FilterExpression, nt as AggregateResult, on as RlsPolicyToOption, or as between, ot as CountResult, p as MigrationDoc, pn as ConvexIndexBuilder, pr as ilike, pt as InsertValue, qn as OrmSchemaExtensionTables, qt as ConvexDeletionBuilder, r as OrmCapability, rn as discriminator, rr as LogicalExpression, rt as BuildQueryResult, sn as rlsPolicy, sr as contains, st as DBQueryConfig, t as OrmAggregateCapability, tn as convexTable, tr as FieldReference, tt as AggregateFieldValue, u as MigrationAppliedState, un as rlsRole, ur as fieldRef, ut as InferInsertModel, v as MigrationPlan, vn as ConvexSearchIndexBuilderOn, vr as like, vt as MutationPaginatedResult, w as MigrationWriteMode, wn as index, wr as notInArray, wt as PaginatedResult, x as MigrationStateMap, xn as ConvexVectorIndexBuilderOn, xr as ne, xt as MutationRunMode, y as MigrationRunStatus, yn as ConvexSearchIndexConfig, yr as lt, yt as MutationResult, zn as ConvexTextBuilder, zr as IsPrimaryKey, zt as RelationsBuilderColumnBase } from "../capabilities-QNGgWHQd.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-DfFcNKtn.js";
+import { $n as BinaryExpression, $t as OrmLifecycleOperation, A as DatabaseWithMutations, An as ConvexCheckConfig, Ar as AnyColumn, At as VectorQueryConfig, B as RlsContext, Bn as ConvexTextBuilderInitial, Br as IsUnique, Bt as RelationsBuilderColumnConfig, C as MigrationTableName, Cn as aggregateIndex, Cr as notBetween, Ct as OrderDirection, D as defineMigrationSet, Dn as uniqueIndex, Dt as ReturningResult, E as defineMigration, En as searchIndex, Er as startsWith, Et as ReturningAll, Fn as ConvexUniqueConstraintConfig, Fr as ColumnBuilderWithTableName, Ft as ExtractTablesWithRelations, Gt as defineRelations, H as EdgeMetadata, In as check, Ir as ColumnDataType, It as ManyConfig, Jt as ConvexDeletionConfig, Kt as defineRelationsPart, Ln as foreignKey, Lr as DrizzleEntity, Lt as OneConfig, M as OrmReader$1, Mn as ConvexForeignKeyConfig, Mr as ColumnBuilderBaseConfig, Mt as unsetToken, N as OrmWriter$1, Nn as ConvexUniqueConstraintBuilder, Nr as ColumnBuilderRuntimeConfig, O as detectMigrationDrift, On as vectorIndex, Or as SystemFields, Ot as ReturningSelection, Pn as ConvexUniqueConstraintBuilderOn, Pr as ColumnBuilderTypeConfig, Pt as ExtractTablesFromSchema, Qn as TableName, Qt as OrmLifecycleChange, Rn as unique, Rr as HasDefault, Rt as RelationsBuilder, S as MigrationStep, Sn as ConvexVectorIndexConfig, Sr as not, St as OrderByClause, T as buildMigrationPlan, Tn as rankIndex, Tr as or, Tt as PredicateWhereIndexConfig, U as extractRelationsConfig, Un as Brand, Ut as TableRelationalConfig, V as RlsMode, Vn as text, Vr as NotNull, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yn as OrmSchemaExtensions, Yt as ConvexTable, Zn as OrmSchemaTriggers, Zt as DiscriminatorBuilderConfig, _ as MigrationMigrateOne, _n as ConvexSearchIndexBuilder, _r as isNull, _t as MutationPaginateConfig, an as RlsPolicyConfig, ar as and, at as CountConfig, b as MigrationSet, bn as ConvexVectorIndexBuilder, br as lte, bt as MutationReturning, cn as RlsRole, cr as endsWith, ct as FilterOperators, d as MigrationDefinition, dn as ConvexAggregateIndexBuilder, dr as gt, dt as InferModelFromColumns, en as TableConfig, er as ExpressionVisitor, et as AggregateConfig, f as MigrationDirection, fn as ConvexAggregateIndexBuilderOn, fr as gte, ft as InferSelectModel, g as MigrationManifestEntry, gn as ConvexRankIndexBuilderOn, gr as isNotNull, gt as MutationExecutionMode, h as MigrationDriftIssue, hn as ConvexRankIndexBuilder, hr as isFieldReference, ht as MutationExecuteResult, i as OrmMigrationCapability, in as RlsPolicy, ir as UnaryExpression, it as BuildRelationResult, j as DatabaseWithQuery, jn as ConvexForeignKeyBuilder, jr as ColumnBuilder, jt as VectorSearchProvider, kn as ConvexCheckBuilder, kt as UpdateSet, ln as RlsRoleConfig, lr as eq, lt as GetColumnData, m as MigrationDocContext, mn as ConvexIndexBuilderOn, mr as inArray, mt as MutationExecuteConfig, n as OrmCapabilities, nn as deletion, nr as FilterExpression, nt as AggregateResult, on as RlsPolicyToOption, or as between, ot as CountResult, p as MigrationDoc, pn as ConvexIndexBuilder, pr as ilike, pt as InsertValue, qn as OrmSchemaExtensionTables, qt as ConvexDeletionBuilder, r as OrmCapability, rn as discriminator, rr as LogicalExpression, rt as BuildQueryResult, sn as rlsPolicy, sr as contains, st as DBQueryConfig, t as OrmAggregateCapability, tn as convexTable, tr as FieldReference, tt as AggregateFieldValue, u as MigrationAppliedState, un as rlsRole, ur as fieldRef, ut as InferInsertModel, v as MigrationPlan, vn as ConvexSearchIndexBuilderOn, vr as like, vt as MutationPaginatedResult, w as MigrationWriteMode, wn as index, wr as notInArray, wt as PaginatedResult, x as MigrationStateMap, xn as ConvexVectorIndexBuilderOn, xr as ne, xt as MutationRunMode, y as MigrationRunStatus, yn as ConvexSearchIndexConfig, yr as lt, yt as MutationResult, zn as ConvexTextBuilder, zr as IsPrimaryKey, zt as RelationsBuilderColumnBase } from "../capabilities-CLCYgRdY.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-CErbOMvj.js";
 import { i as pretendRequired, n as deprecated, r as pretend } from "../validators-wOIjhkfN.js";
 import { a as QueryCtxWithPreferredOrmQueryTable, i as QueryCtxWithOrmQueryTable, n as LookupByIdResultByCtx, o as getByIdWithOrmQueryFallback, r as QueryCtxWithOptionalOrmQueryTable, t as DocByCtx } from "../query-context-DJONf8X5.js";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchemaDefinition } from "convex/server";

package/dist/orm/index.js

@@ -1287,6 +1287,16 @@ const RELATION_COUNT_ERROR = {
 	NOT_INDEXED: "RELATION_COUNT_NOT_INDEXED",
 	FILTER_UNSUPPORTED: "RELATION_COUNT_FILTER_UNSUPPORTED"
 };
+const RELATION_DEPTH_ERROR = "RELATION_DEPTH_EXCEEDED";
+/**
+* How many levels of `with` the relation loader will follow. A `with` config is
+* a finite object the caller wrote, so its own nesting is the real bound; this
+* ceiling only stops a self-referential config from recursing forever. Reaching
+* it throws rather than returning a shallower tree than was asked for, because
+* a page that quietly drops its deepest level is indistinguishable from a page
+* whose deepest level is genuinely empty.
+*/
+const MAX_RELATION_DEPTH = 10;
 /**
 * Physical-table-name lookup, keyed on schema identity. The schema is a
 * module-level immutable, so the index outlives any single request.
@@ -2425,7 +2435,9 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			operation: "select",
 			rls: this.rls
 		});
-		if (!withConfig || depth >= maxDepth) return;
+		if (!withConfig) return;
+		const relationNames = Object.keys(withConfig).filter((relationName) => relationName !== "_count");
+		if (relationNames.length > 0 && depth >= maxDepth) throw this._createRelationDepthError(tableConfig, relationNames[0], maxDepth);
 		for (const [relationName, relationConfig] of Object.entries(withConfig)) {
 			if (relationName === "_count") {
 				this._assertRelationCountRlsPlan(relationConfig, edges);
@@ -2481,9 +2493,9 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const extrasConfig = this.config.extras;
 		const resolvedExtras = typeof extrasConfig === "function" ? extrasConfig(tableColumns) : extrasConfig;
 		if (polymorphicState) this._assertPolymorphicAliasCollisions(polymorphicState.configs, requestedWith, resolvedExtras);
-		this._assertRlsSelectPlan(effectiveWith, this.tableConfig, this.edgeMetadata, 0, 3);
+		this._assertRlsSelectPlan(effectiveWith, this.tableConfig, this.edgeMetadata, 0, MAX_RELATION_DEPTH);
 		let rowsWithRelations = rows;
-		if (effectiveWith) rowsWithRelations = await this._loadRelations(rowsWithRelations, effectiveWith, 0, 3, this.edgeMetadata, this.tableConfig);
+		if (effectiveWith) rowsWithRelations = await this._loadRelations(rowsWithRelations, effectiveWith, 0, MAX_RELATION_DEPTH, this.edgeMetadata, this.tableConfig);
 		if (polymorphicState) this._synthesizePolymorphicRows(rowsWithRelations, polymorphicState.configs);
 		if (resolvedExtras) rowsWithRelations = this._applyExtras(rowsWithRelations, resolvedExtras, tableColumns, effectiveWith, this.tableConfig.name, this.tableConfig);
 		return this._selectColumns(rowsWithRelations, this.config.columns, tableColumns, this.tableConfig);
@@ -3774,8 +3786,8 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			if (pipeline) throw new Error("pageByKey cannot be combined with pipeline.");
 		}
 		const preflightWith = this._resolveWithVariantsState(config.with, this._resolvePolymorphicFinalizeState()).effectiveWith;
-		this._assertRlsSelectPlan(preflightWith, this.tableConfig, this.edgeMetadata, 0, 3);
-		if (whereFilter) this._assertRlsSelectPlan(this._buildFilterWithConfig(whereFilter, this.tableConfig), this.tableConfig, this.edgeMetadata, 0, 3);
+		this._assertRlsSelectPlan(preflightWith, this.tableConfig, this.edgeMetadata, 0, MAX_RELATION_DEPTH);
+		if (whereFilter) this._assertRlsSelectPlan(this._buildFilterWithConfig(whereFilter, this.tableConfig), this.tableConfig, this.edgeMetadata, 0, MAX_RELATION_DEPTH);
 		const idLookup = this._extractIdOnlyWhere(whereFilter);
 		if (idLookup && !vectorSearchConfig && !searchConfig && !wherePredicate && !isCursorPaginated && !pipeline && !pageByKey && endCursor === void 0 && configuredIndex === void 0) {
 			const orderSpecs = this._orderBySpecs(config.orderBy);
@@ -3809,7 +3821,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				order: pageByKey.order
 			});
 			let rows = await this._applyRlsSelectFilter(page.page, this.tableConfig);
-			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 			return {
 				page: await this._finalizeRows(rows),
 				indexKeys: page.indexKeys,
@@ -3935,7 +3947,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				});
 				let pageRows = paginationResult.page;
 				pageRows = await this._applyRlsSelectFilter(pageRows, this.tableConfig);
-				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 				return {
 					page: await this._finalizeRows(pageRows),
 					continueCursor: paginationResult.continueCursor,
@@ -3948,7 +3960,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			let rows = limit === void 0 ? await searchQuery.collect() : await searchQuery.take(offset > 0 ? offset + limit : limit);
 			if (offset > 0) rows = rows.slice(offset);
 			rows = await this._applyRlsSelectFilter(rows, this.tableConfig);
-			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 			const selectedRows = await this._finalizeRows(rows);
 			return this._returnSelectedRows(selectedRows);
 		}
@@ -4028,7 +4040,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				});
 				let pageRows = paginationResult.page;
 				pageRows = await this._applyRlsSelectFilter(pageRows, this.tableConfig);
-				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 				return {
 					page: await this._finalizeRows(pageRows),
 					continueCursor: paginationResult.continueCursor,
@@ -4044,7 +4056,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			let rows = limit === void 0 || paginateAfterPostFetchSort ? await streamQuery.collect() : await streamQuery.take(offset > 0 ? offset + limit : limit);
 			if (!paginateAfterPostFetchSort && offset > 0) rows = rows.slice(offset);
 			rows = await this._applyRlsSelectFilter(rows, this.tableConfig);
-			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 			if (usePostFetchSort && postFetchOrders.length > 0) rows = rows.sort((a, b) => this._compareByOrderSpecs(a, b, postFetchOrders));
 			if (paginateAfterPostFetchSort) {
 				if (offset > 0) rows = rows.slice(offset);
@@ -4079,7 +4091,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			let rows = Array.from(new Map(probeRows.flat().map((row) => [String(row._id), row])).values());
 			if (queryConfig.postFilters.length > 0) rows = rows.filter((row) => queryConfig.postFilters.every((filter) => this._evaluatePostFetchFilter(row, filter)));
 			rows = await this._applyRlsSelectFilter(rows, this.tableConfig);
-			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 			if (postFetchOrders.length > 0) rows = rows.sort((a, b) => this._compareByOrderSpecs(a, b, postFetchOrders));
 			if (probeOffset > 0) rows = rows.slice(probeOffset);
 			if (probeLimit !== void 0) rows = rows.slice(0, probeLimit);
@@ -4090,7 +4102,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			const visibleRows = await this._applyRlsSelectFilter([row], this.tableConfig);
 			if (visibleRows.length === 0) return false;
 			if (!whereFilter) return true;
-			return (await this._applyRelationsFilterToRows(visibleRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with)).length > 0;
+			return (await this._applyRelationsFilterToRows(visibleRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with)).length > 0;
 		};
 		if (isCursorPaginated) {
 			if (queryConfig.strategy === "multiProbe") if (maxScan === void 0) {
@@ -4116,7 +4128,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				});
 				let pageRows = paginationResult.page;
 				pageRows = await this._applyRlsSelectFilter(pageRows, this.tableConfig);
-				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 				return {
 					page: await this._finalizeRows(pageRows),
 					continueCursor: paginationResult.continueCursor,
@@ -4148,7 +4160,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 				});
 				let pageRows = paginationResult.page;
 				pageRows = await this._applyRlsSelectFilter(pageRows, this.tableConfig);
-				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+				if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 				return {
 					page: await this._finalizeRows(pageRows),
 					continueCursor: paginationResult.continueCursor,
@@ -4203,7 +4215,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 			});
 			let pageRows = paginationResult.page;
 			pageRows = await this._applyRlsSelectFilter(pageRows, this.tableConfig);
-			if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+			if (whereFilter) pageRows = await this._applyRelationsFilterToRows(pageRows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 			return {
 				page: await this._finalizeRows(pageRows),
 				continueCursor: paginationResult.continueCursor,
@@ -4235,7 +4247,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (queryConfig.postFilters.length > 0) rows = rows.filter((row) => queryConfig.postFilters.every((filter) => this._evaluatePostFetchFilter(row, filter)));
 		if (!residualLimitStream) {
 			rows = await this._applyRlsSelectFilter(rows, this.tableConfig);
-			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, 3, this.config.with);
+			if (whereFilter) rows = await this._applyRelationsFilterToRows(rows, this.tableConfig, whereFilter, this.edgeMetadata, 0, MAX_RELATION_DEPTH, this.config.with);
 		}
 		if (sizeAfterPostFilter) {
 			if (offset > 0) rows = rows.slice(offset);
@@ -4420,14 +4432,14 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* @param rows - Array of parent records to load relations for
 	* @param withConfig - Relation configuration object
 	* @param depth - Current recursion depth (default 0)
-	* @param maxDepth - Maximum recursion depth (default 3)
+	* @param maxDepth - Runaway ceiling for self-referential configs (default `MAX_RELATION_DEPTH`)
 	* @param targetTableEdges - Edge metadata for nested relations (optional, defaults to this.edgeMetadata)
 	*/
-	async _loadRelations(rows, withConfig, depth = 0, maxDepth = 3, targetTableEdges = this.edgeMetadata, tableConfig = this.tableConfig) {
+	async _loadRelations(rows, withConfig, depth = 0, maxDepth = MAX_RELATION_DEPTH, targetTableEdges = this.edgeMetadata, tableConfig = this.tableConfig) {
 		if (!withConfig || rows.length === 0) return rows;
-		if (depth >= maxDepth) return rows;
 		const relationCountConfig = withConfig._count;
 		const relationEntries = Object.entries(withConfig).filter(([relationName]) => relationName !== "_count");
+		if (relationEntries.length > 0 && depth >= maxDepth) throw this._createRelationDepthError(tableConfig, relationEntries[0][0], maxDepth);
 		await Promise.all(relationEntries.map(([relationName, relationConfig]) => this._loadSingleRelation(rows, relationName, relationConfig, depth, maxDepth, targetTableEdges, tableConfig)));
 		if (relationCountConfig !== void 0) await this._loadRelationCounts(rows, relationCountConfig, targetTableEdges, tableConfig);
 		return rows;
@@ -4446,6 +4458,9 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	_createRelationCountError(code, message) {
 		return /* @__PURE__ */ new Error(`${code}: ${message}`);
 	}
+	_createRelationDepthError(tableConfig, relationName, maxDepth) {
+		return /* @__PURE__ */ new Error(`${RELATION_DEPTH_ERROR}: '${tableConfig.name}.${relationName}' nests \`with\` more than ${maxDepth} levels deep. Trim the nesting, or check whether the config object references itself.`);
+	}
 	_remapRelationCountError(error, relationPath) {
 		const message = error instanceof Error ? error.message : String(error);
 		if (message.startsWith(`${COUNT_ERROR.NOT_INDEXED}:`)) return this._createRelationCountError(RELATION_COUNT_ERROR.NOT_INDEXED, `${relationPath} ${message.slice(`${COUNT_ERROR.NOT_INDEXED}: `.length)}`);

package/dist/orm/migrations/index.d.ts

@@ -1,3 +1,3 @@
-import { C as MigrationTableName, D as defineMigrationSet, E as defineMigration, O as detectMigrationDrift, S as MigrationStep, T as buildMigrationPlan, _ as MigrationMigrateOne, a as MigrationCancelArgs, b as MigrationSet, c as MigrationStatusArgs, d as MigrationDefinition, f as MigrationDirection, g as MigrationManifestEntry, h as MigrationDriftIssue, l as createMigrationHandlers, m as MigrationDocContext, o as MigrationRunArgs, p as MigrationDoc, s as MigrationRunChunkArgs, u as MigrationAppliedState, v as MigrationPlan, w as MigrationWriteMode, x as MigrationStateMap, y as MigrationRunStatus } from "../../capabilities-QNGgWHQd.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-DfFcNKtn.js";
+import { C as MigrationTableName, D as defineMigrationSet, E as defineMigration, O as detectMigrationDrift, S as MigrationStep, T as buildMigrationPlan, _ as MigrationMigrateOne, a as MigrationCancelArgs, b as MigrationSet, c as MigrationStatusArgs, d as MigrationDefinition, f as MigrationDirection, g as MigrationManifestEntry, h as MigrationDriftIssue, l as createMigrationHandlers, m as MigrationDocContext, o as MigrationRunArgs, p as MigrationDoc, s as MigrationRunChunkArgs, u as MigrationAppliedState, v as MigrationPlan, w as MigrationWriteMode, x as MigrationStateMap, y as MigrationRunStatus } from "../../capabilities-CLCYgRdY.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-CErbOMvj.js";
 export { 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/react/index.js

@@ -499,6 +499,38 @@ const getTransformer = (transformer) => {
 */
 const encodeWire = (value, transformer) => getTransformer(transformer).input.serialize(value);
 
+//#endregion
+//#region src/internal/query-filter.ts
+/**
+* Whether a `queryFilter` call actually narrowed by args.
+*
+* Nullish args and `{}` all mean "match every args variant". They have to
+* collapse to a shorter prefix key rather than sit in the args slot, because
+* TanStack matches filters with `partialMatchKey`, which walks
+* `Object.keys(filterKey)` — an args slot holding `undefined` or `null` is
+* compared against the real args and fails on every entry that carries any,
+* so the filter silently matches nothing.
+*/
+function hasQueryFilterArgs(args) {
+	if (args == null) return false;
+	if (typeof args === "object") return Object.keys(args).length > 0;
+	return true;
+}
+/**
+* Build the key for a Convex `queryFilter`.
+*
+* With args, this is the exact 3-element key and TanStack partial-matches the
+* args object. Without args, it stops before the args slot so the filter
+* matches every variant of the function.
+*/
+function buildConvexFilterKey(prefix, funcName, args) {
+	return hasQueryFilterArgs(args) ? [
+		prefix,
+		funcName,
+		args
+	] : [prefix, funcName];
+}
+
 //#endregion
 //#region src/react/http-proxy.ts
 /**
@@ -579,10 +611,9 @@ function createRecursiveHttpProxy(opts, path = []) {
 		}
 		if (prop === "queryKey") return (args) => buildHttpQueryKey(routeKey, args);
 		if (prop === "queryFilter") return (args, filters) => {
-			const hasArgs = args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0);
 			return {
 				...filters,
-				queryKey: hasArgs ? buildHttpQueryKey(routeKey, args) : buildHttpQueryPrefixKey(routeKey)
+				queryKey: hasQueryFilterArgs(args) ? buildHttpQueryKey(routeKey, args) : buildHttpQueryPrefixKey(routeKey)
 			};
 		};
 		if (prop === "mutationOptions") {
@@ -813,16 +844,21 @@ function resolveEnabled(allowed, enabled) {
 /**
 * Check if query key is for a Convex query function.
 * Format: ['convexQuery', 'namespace:functionName', { args }]
+*
+* Requires the args slot: a 2-element key is a `queryFilter` prefix, never a
+* cache key, and hashing one would serialize `undefined` args and throw.
 */
 function isConvexQuery(queryKey) {
-	return queryKey.length >= 2 && queryKey[0] === "convexQuery";
+	return queryKey.length >= 3 && queryKey[0] === "convexQuery";
 }
 /**
 * Check if query key is for a Convex action function.
 * Format: ['convexAction', 'namespace:functionName', { args }]
+*
+* Requires the args slot, for the same reason as {@link isConvexQuery}.
 */
-function isConvexAction$1(queryKey) {
-	return queryKey.length >= 2 && queryKey[0] === "convexAction";
+function isConvexAction(queryKey) {
+	return queryKey.length >= 3 && queryKey[0] === "convexAction";
 }
 /**
 * Serialize args the same way they go over the wire, so non-native Convex
@@ -856,7 +892,7 @@ function hashConvexAction(queryKey) {
 function createHashFn(fallback = hashKey) {
 	return (queryKey) => {
 		if (isConvexQuery(queryKey)) return hashConvexQuery(queryKey);
-		if (isConvexAction$1(queryKey)) return hashConvexAction(queryKey);
+		if (isConvexAction(queryKey)) return hashConvexAction(queryKey);
 		return fallback(queryKey);
 	};
 }
@@ -1254,11 +1290,7 @@ function createRecursiveProxy(api, path, meta, transformer) {
 			const prefix = getQueryKeyPrefix(path, meta);
 			return {
 				...filters,
-				queryKey: [
-					prefix,
-					funcName,
-					args
-				]
+				queryKey: buildConvexFilterKey(prefix, funcName, args)
 			};
 		};
 		if (prop === "infiniteQueryOptions") return (args = {}, opts = {}) => {
@@ -1906,13 +1938,6 @@ function isConvexSkipped(queryKey) {
 	return queryKey.length >= 2 && ["convexQuery", "convexAction"].includes(queryKey[0]) && queryKey[2] === "skip";
 }
 /**
-* Check if query key is for a Convex action function.
-* Format: ['convexAction', 'namespace:functionName', { args }]
-*/
-function isConvexAction(queryKey) {
-	return queryKey.length >= 2 && queryKey[0] === "convexAction";
-}
-/**
 * Write a subscription value into an already-resolved Query.
 *
 * Going through the Query skips the query-key re-hash that the key-based

package/dist/rsc/index.js

@@ -116,16 +116,21 @@ function createServerCRPCProxy(options) {
 /**
 * Check if query key is for a Convex query function.
 * Format: ['convexQuery', 'namespace:functionName', { args }]
+*
+* Requires the args slot: a 2-element key is a `queryFilter` prefix, never a
+* cache key, and hashing one would serialize `undefined` args and throw.
 */
 function isConvexQuery(queryKey) {
-	return queryKey.length >= 2 && queryKey[0] === "convexQuery";
+	return queryKey.length >= 3 && queryKey[0] === "convexQuery";
 }
 /**
 * Check if query key is for a Convex action function.
 * Format: ['convexAction', 'namespace:functionName', { args }]
+*
+* Requires the args slot, for the same reason as {@link isConvexQuery}.
 */
 function isConvexAction(queryKey) {
-	return queryKey.length >= 2 && queryKey[0] === "convexAction";
+	return queryKey.length >= 3 && queryKey[0] === "convexAction";
 }
 /**
 * Serialize args the same way they go over the wire, so non-native Convex

package/dist/solid/index.js

@@ -800,6 +800,38 @@ const getTransformer = (transformer) => {
 */
 const encodeWire = (value, transformer) => getTransformer(transformer).input.serialize(value);
 
+//#endregion
+//#region src/internal/query-filter.ts
+/**
+* Whether a `queryFilter` call actually narrowed by args.
+*
+* Nullish args and `{}` all mean "match every args variant". They have to
+* collapse to a shorter prefix key rather than sit in the args slot, because
+* TanStack matches filters with `partialMatchKey`, which walks
+* `Object.keys(filterKey)` — an args slot holding `undefined` or `null` is
+* compared against the real args and fails on every entry that carries any,
+* so the filter silently matches nothing.
+*/
+function hasQueryFilterArgs(args) {
+	if (args == null) return false;
+	if (typeof args === "object") return Object.keys(args).length > 0;
+	return true;
+}
+/**
+* Build the key for a Convex `queryFilter`.
+*
+* With args, this is the exact 3-element key and TanStack partial-matches the
+* args object. Without args, it stops before the args slot so the filter
+* matches every variant of the function.
+*/
+function buildConvexFilterKey(prefix, funcName, args) {
+	return hasQueryFilterArgs(args) ? [
+		prefix,
+		funcName,
+		args
+	] : [prefix, funcName];
+}
+
 //#endregion
 //#region src/solid/http-proxy.ts
 /**
@@ -880,10 +912,9 @@ function createRecursiveHttpProxy(opts, path = []) {
 		}
 		if (prop === "queryKey") return (args) => buildHttpQueryKey(routeKey, args);
 		if (prop === "queryFilter") return (args, filters) => {
-			const hasArgs = args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0);
 			return {
 				...filters,
-				queryKey: hasArgs ? buildHttpQueryKey(routeKey, args) : buildHttpQueryPrefixKey(routeKey)
+				queryKey: hasQueryFilterArgs(args) ? buildHttpQueryKey(routeKey, args) : buildHttpQueryPrefixKey(routeKey)
 			};
 		};
 		if (prop === "mutationOptions") {
@@ -1493,11 +1524,7 @@ function createRecursiveProxy(api, path, meta, transformer) {
 			const prefix = getQueryKeyPrefix(path, meta);
 			return {
 				...filters,
-				queryKey: [
-					prefix,
-					funcName,
-					args
-				]
+				queryKey: buildConvexFilterKey(prefix, funcName, args)
 			};
 		};
 		if (prop === "infiniteQueryOptions") return (args = {}, opts = {}) => {
@@ -1996,16 +2023,21 @@ async function clearAuthBoundQueries(cache, isAuthBound) {
 /**
 * Check if query key is for a Convex query function.
 * Format: ['convexQuery', 'namespace:functionName', { args }]
+*
+* Requires the args slot: a 2-element key is a `queryFilter` prefix, never a
+* cache key, and hashing one would serialize `undefined` args and throw.
 */
 function isConvexQuery(queryKey) {
-	return queryKey.length >= 2 && queryKey[0] === "convexQuery";
+	return queryKey.length >= 3 && queryKey[0] === "convexQuery";
 }
 /**
 * Check if query key is for a Convex action function.
 * Format: ['convexAction', 'namespace:functionName', { args }]
+*
+* Requires the args slot, for the same reason as {@link isConvexQuery}.
 */
-function isConvexAction$1(queryKey) {
-	return queryKey.length >= 2 && queryKey[0] === "convexAction";
+function isConvexAction(queryKey) {
+	return queryKey.length >= 3 && queryKey[0] === "convexAction";
 }
 /**
 * Serialize args the same way they go over the wire, so non-native Convex
@@ -2039,7 +2071,7 @@ function hashConvexAction(queryKey) {
 function createHashFn(fallback = hashKey) {
 	return (queryKey) => {
 		if (isConvexQuery(queryKey)) return hashConvexQuery(queryKey);
-		if (isConvexAction$1(queryKey)) return hashConvexAction(queryKey);
+		if (isConvexAction(queryKey)) return hashConvexAction(queryKey);
 		return fallback(queryKey);
 	};
 }
@@ -2123,13 +2155,6 @@ function isConvexSkipped(queryKey) {
 	return queryKey.length >= 2 && ["convexQuery", "convexAction"].includes(queryKey[0]) && queryKey[2] === "skip";
 }
 /**
-* Check if query key is for a Convex action function.
-* Format: ['convexAction', 'namespace:functionName', { args }]
-*/
-function isConvexAction(queryKey) {
-	return queryKey.length >= 2 && queryKey[0] === "convexAction";
-}
-/**
 * Bridges TanStack Query with Convex real-time subscriptions (SolidJS).
 *
 * Uses `ConvexClient.onUpdate()` instead of `ConvexReactClient.watchQuery()`.

package/dist/{where-clause-compiler-DfFcNKtn.d.ts → where-clause-compiler-CErbOMvj.d.ts}

@@ -1,4 +1,4 @@
-import { Bn as ConvexTextBuilderInitial, Dr as SystemFieldAliases, F as DeleteMode, Gn as OrmRuntimeDefaults, H as EdgeMetadata, Hn as ConvexColumnBuilder, Hr as entityKind, Ht as RelationsConfigWithSchema, I as SerializedFilterExpression, Jn as OrmSchemaExtensionTriggers, Kn as OrmSchemaExtensionRelations, L as getChecks, M as OrmReader, Mr as ColumnBuilderBaseConfig, N as OrmWriter, Nt as AnyRelationsBuilderConfig, Or as SystemFields, P as CascadeMode, Pt as ExtractTablesFromSchema, Qt as OrmLifecycleChange, R as getForeignKeys, Rr as HasDefault, Rt as RelationsBuilder, St as OrderByClause, Ut as TableRelationalConfig, Vt as RelationsBuilderConfigValue, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yt as ConvexTable, Zn as OrmSchemaTriggers, b as MigrationSet, ft as InferSelectModel, in as RlsPolicy, jr as ColumnBuilder, jt as VectorSearchProvider, k as CreateDatabaseOptions, kr as $Type, nr as FilterExpression$1, r as OrmCapability, ut as InferInsertModel, z as getUniqueIndexes } from "./capabilities-QNGgWHQd.js";
+import { Bn as ConvexTextBuilderInitial, Dr as SystemFieldAliases, F as DeleteMode, Gn as OrmRuntimeDefaults, H as EdgeMetadata, Hn as ConvexColumnBuilder, Hr as entityKind, Ht as RelationsConfigWithSchema, I as SerializedFilterExpression, Jn as OrmSchemaExtensionTriggers, Kn as OrmSchemaExtensionRelations, L as getChecks, M as OrmReader, Mr as ColumnBuilderBaseConfig, N as OrmWriter, Nt as AnyRelationsBuilderConfig, Or as SystemFields, P as CascadeMode, Pt as ExtractTablesFromSchema, Qt as OrmLifecycleChange, R as getForeignKeys, Rr as HasDefault, Rt as RelationsBuilder, St as OrderByClause, Ut as TableRelationalConfig, Vt as RelationsBuilderConfigValue, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yt as ConvexTable, Zn as OrmSchemaTriggers, b as MigrationSet, ft as InferSelectModel, in as RlsPolicy, jr as ColumnBuilder, jt as VectorSearchProvider, k as CreateDatabaseOptions, kr as $Type, nr as FilterExpression$1, r as OrmCapability, ut as InferInsertModel, z as getUniqueIndexes } from "./capabilities-CLCYgRdY.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 } from "convex/server";
@@ -120,19 +120,6 @@ declare const migrationStorageTables: {
           fieldName: "direction";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "migration_state";
-        };
-      } & {
-        _: {
-          fieldName: "updatedAt";
-        };
-      };
       migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -203,6 +190,19 @@ declare const migrationStorageTables: {
           fieldName: "startedAt";
         };
       };
+      updatedAt: ConvexNumberBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "migration_state";
+        };
+      } & {
+        _: {
+          fieldName: "updatedAt";
+        };
+      };
       completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
@@ -269,7 +269,7 @@ declare const migrationStorageTables: {
           fieldName: "direction";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -279,10 +279,10 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "runId";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -292,10 +292,10 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "startedAt";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -305,7 +305,7 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "updatedAt";
         };
       };
       completedAt: ConvexNumberBuilderInitial<""> & {
@@ -1008,7 +1008,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      count: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1018,10 +1018,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1031,10 +1031,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "count";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1044,10 +1044,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1057,7 +1057,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1159,7 +1159,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1169,10 +1169,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1182,7 +1182,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1340,7 +1340,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "value";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1350,10 +1350,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1363,10 +1363,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "count";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1376,10 +1376,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1389,7 +1389,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -1611,7 +1611,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1621,10 +1621,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "processed";
         };
       };
-      processed: ConvexNumberBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1634,10 +1634,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "processed";
+          fieldName: "startedAt";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1647,7 +1647,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "updatedAt";
         };
       };
       completedAt: ConvexNumberBuilderInitial<""> & {
@@ -1668,7 +1668,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "lastError";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1678,10 +1678,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "tableKey";
         };
       };
-      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1691,10 +1691,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyDefinitionHash";
+          fieldName: "indexName";
         };
       };
-      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
+      keyDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1704,10 +1704,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "metricDefinitionHash";
+          fieldName: "keyDefinitionHash";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      metricDefinitionHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1717,7 +1717,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "metricDefinitionHash";
         };
       };
     };
@@ -1762,19 +1762,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "direction";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "migration_state";
-        };
-      } & {
-        _: {
-          fieldName: "updatedAt";
-        };
-      };
       migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1845,6 +1832,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "startedAt";
         };
       };
+      updatedAt: ConvexNumberBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "migration_state";
+        };
+      } & {
+        _: {
+          fieldName: "updatedAt";
+        };
+      };
       completedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
@@ -1911,7 +1911,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "direction";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1921,10 +1921,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "runId";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      startedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1934,10 +1934,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "startedAt";
         };
       };
-      startedAt: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1947,7 +1947,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "startedAt";
+          fieldName: "updatedAt";
         };
       };
       completedAt: ConvexNumberBuilderInitial<""> & {

package/package.json

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

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

@@ -211,6 +211,38 @@ const users = await ctx.orm.query.users.findMany({
 
 Works on `findMany`, `findFirst`, `findFirstOrThrow`. Access via `row._count?.relation ?? 0`.
 
+`_count` reads an aggregate index rather than the rows, so it resolves at every level of a nested `with:`, including the deepest level returned. Ask for it there instead of re-reading the returned tree to attach counts — that second pass costs one read per node the caller already holds:
+
+```ts
+// ❌ BAD: second pass over nodes already in hand
+const roots = await ctx.orm.query.comments.findMany({
+  where: { parentId: { isNull: true } },
+  limit: 20,
+  with: { replies: { limit: 10 } },
+});
+const ids = collectIds(roots);
+const counts = await ctx.orm.query.comments.findMany({
+  where: { id: { in: ids } },
+  limit: ids.length,
+  columns: { id: true },
+  with: { _count: { replies: true } },
+});
+
+// ✅ GOOD: counted inline, at every level
+const roots = await ctx.orm.query.comments.findMany({
+  where: { parentId: { isNull: true } },
+  limit: 20,
+  with: {
+    _count: { replies: true },
+    replies: {
+      limit: 10,
+      with: { _count: { replies: true } },
+    },
+  },
+});
+// roots[0].replies[0]._count?.replies => replies not in this page
+```
+
 ### Mutation `returning({ _count })`
 
 ```ts

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

@@ -261,6 +261,14 @@ orders by creation time, so `with: { posts: { limit: 5, orderBy: { createdAt:
 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.
 
+### Nested `with` depth
+
+Nested `with:` loads every level it is given, up to 10. A tree that still has
+rows to expand past that throws `RELATION_DEPTH_EXCEEDED` rather than coming back
+shorter than requested — which is how a `with` object that references itself
+surfaces. Fan-out per level is bounded by that level's `limit`, not by the depth
+ceiling.
+
 ## Schema Definition
 
 ```ts

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

@@ -235,11 +235,20 @@ useQuery(crpc.user.get.queryOptions(userId ? { id: userId } : skipToken));
 
 ### Query Keys & Filters
 
+`queryKey(args)` is the exact cache key — use it for `getQueryData`/`setQueryData`.
+`queryFilter(args?)` matches on prefix — use it for `invalidateQueries`/`cancelQueries`/`removeQueries`.
+
 ```ts
 const queryKey = crpc.user.list.queryKey({}); // ['convexQuery', 'user:list', {}]
 const data = queryClient.getQueryData(queryKey);
 
-const filter = crpc.user.list.queryFilter({}, { predicate: (q) => q.state.dataUpdatedAt > Date.now() - 60000 });
+// Omit args to match every args variant: ['convexQuery', 'user:list']
+queryClient.invalidateQueries(crpc.user.list.queryFilter());
+
+// Partial args match every query whose args contain them
+queryClient.invalidateQueries(crpc.user.list.queryFilter({ status: 'active' }));
+
+const filter = crpc.user.list.queryFilter({ status: 'active' }, { predicate: (q) => q.state.dataUpdatedAt > Date.now() - 60000 });
 queryClient.invalidateQueries(filter);
 ```