kitcn 0.26.2 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # kitcn
 
+## 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
+
+- [#394](https://github.com/udecode/kitcn/pull/394) [`1317349`](https://github.com/udecode/kitcn/commit/13173495fa8db3d8a0568642981c1cdef4dcdf2b) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Features
+
+  - Support a per-source `index: { name, range }` on `select().union([...])`, so each source walks its own index range instead of re-walking one shared range and filtering the misses in JS.
+
+  ```ts
+  const page = await db.query.messages
+    .select()
+    .union([
+      {
+        index: {
+          name: "by_from_to",
+          range: (q) => q.eq("from", me).eq("to", them),
+        },
+      },
+      {
+        index: {
+          name: "by_from_to",
+          range: (q) => q.eq("from", them).eq("to", me),
+        },
+      },
+    ])
+    .interleaveBy(["createdAt", "id"])
+    .paginate({ cursor: null, limit: 20 });
+  ```
+
+  - Support union sources anchored on different indexes, as long as each source pins its leading fields with `eq` and ends up ordered by the `interleaveBy` fields.
+
 ## 0.26.2
 
 ### Patch Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
-import { Bn as ConvexTextBuilderInitial, Xt as ConvexTableWithColumns } from "../capabilities-DtDfpdcH.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-eTewPUGq.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-DAPEBp1y.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/auth/generated/index.d.ts

@@ -1,2 +1,2 @@
-import { S as defineAuth, _ as GenericAuthBeforeResult, b as GenericAuthTriggerHandlers, g as BetterAuthOptionsWithoutDatabase, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, v as GenericAuthDefinition, x as GenericAuthTriggers, y as GenericAuthTriggerChange } from "../../generated-contract-disabled-BEc4d98x.js";
+import { S as defineAuth, _ as GenericAuthBeforeResult, b as GenericAuthTriggerHandlers, g as BetterAuthOptionsWithoutDatabase, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, v as GenericAuthDefinition, x as GenericAuthTriggers, y as GenericAuthTriggerChange } from "../../generated-contract-disabled-DwYwySy3.js";
 export { type AuthRuntime, BetterAuthOptionsWithoutDatabase, type GeneratedAuthDisabledReasonKind, GenericAuthBeforeResult, GenericAuthDefinition, GenericAuthTriggerChange, GenericAuthTriggerHandlers, GenericAuthTriggers, createDisabledAuthRuntime, defineAuth, getGeneratedAuthDisabledReason };

package/dist/auth/index.d.ts

@@ -1,7 +1,7 @@
 import { a as QueryCtxWithPreferredOrmQueryTable, n as LookupByIdResultByCtx, t as DocByCtx } from "../query-context-DJONf8X5.js";
 import { t as GetAuth } from "../types-Bf3XQex5.js";
 import { t as GenericCtx } from "../context-utils-DwZ3Cam1.js";
-import { S as defineAuth, _ as GenericAuthBeforeResult, a as AuthFunctions, b as GenericAuthTriggerHandlers, c as createApi, d as deleteOneHandler, f as findManyHandler, g as BetterAuthOptionsWithoutDatabase, h as updateOneHandler, i as getGeneratedAuthDisabledReason, l as createHandler, m as updateManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as findOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as deleteManyHandler, v as GenericAuthDefinition, x as GenericAuthTriggers, y as GenericAuthTriggerChange } from "../generated-contract-disabled-BEc4d98x.js";
+import { S as defineAuth, _ as GenericAuthBeforeResult, a as AuthFunctions, b as GenericAuthTriggerHandlers, c as createApi, d as deleteOneHandler, f as findManyHandler, g as BetterAuthOptionsWithoutDatabase, h as updateOneHandler, i as getGeneratedAuthDisabledReason, l as createHandler, m as updateManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as findOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as deleteManyHandler, v as GenericAuthDefinition, x as GenericAuthTriggers, y as GenericAuthTriggerChange } from "../generated-contract-disabled-DwYwySy3.js";
 import * as convex_values0 from "convex/values";
 import { Infer } from "convex/values";
 import { AuthConfig, DocumentByName, GenericDataModel, GenericMutationCtx, GenericQueryCtx, GenericSchema, PaginationOptions, PaginationResult, SchemaDefinition, TableNamesInDataModel } from "convex/server";
@@ -123,6 +123,7 @@ declare const adapterWhereValidator: convex_values0.VObject<{
   value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
 }, "required", "mode" | "value" | "connector" | "field" | "operator">;
 declare const adapterArgsValidator: convex_values0.VObject<{
+  limit?: number | undefined;
   select?: string[] | undefined;
   where?: {
     mode?: "sensitive" | "insensitive" | undefined;
@@ -131,11 +132,10 @@ declare const adapterArgsValidator: convex_values0.VObject<{
     value: string | number | boolean | string[] | number[] | null;
     field: string;
   }[] | undefined;
-  limit?: number | undefined;
   offset?: number | undefined;
   sortBy?: {
-    field: string;
     direction: "asc" | "desc";
+    field: string;
   } | undefined;
   model: string;
 }, {
@@ -144,12 +144,12 @@ declare const adapterArgsValidator: convex_values0.VObject<{
   offset: convex_values0.VFloat64<number | undefined, "optional">;
   select: convex_values0.VArray<string[] | undefined, convex_values0.VString<string, "required">, "optional">;
   sortBy: convex_values0.VObject<{
-    field: string;
     direction: "asc" | "desc";
+    field: string;
   } | undefined, {
     direction: convex_values0.VUnion<"asc" | "desc", [convex_values0.VLiteral<"asc", "required">, convex_values0.VLiteral<"desc", "required">], "required", never>;
     field: convex_values0.VString<string, "required">;
-  }, "optional", "field" | "direction">;
+  }, "optional", "direction" | "field">;
   where: convex_values0.VArray<{
     mode?: "sensitive" | "insensitive" | undefined;
     connector?: "AND" | "OR" | undefined;
@@ -169,7 +169,7 @@ declare const adapterArgsValidator: convex_values0.VObject<{
     operator: convex_values0.VUnion<"lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
     value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
   }, "required", "mode" | "value" | "connector" | "field" | "operator">, "optional">;
-}, "required", "model" | "select" | "where" | "limit" | "offset" | "sortBy" | "sortBy.field" | "sortBy.direction">;
+}, "required", "limit" | "model" | "select" | "where" | "offset" | "sortBy" | "sortBy.direction" | "sortBy.field">;
 declare const hasUniqueFields: (betterAuthSchema: BetterAuthDBSchema, model: string, input: Record<string, any>) => boolean;
 declare const checkUniqueFields: <Schema extends SchemaDefinition<any, any>>(ctx: GenericQueryCtx<GenericDataModel>, schema: Schema, betterAuthSchema: BetterAuthDBSchema, table: string, input: Record<string, any>, doc?: Record<string, any>) => Promise<void>;
 declare const selectFields: <T extends TableNamesInDataModel<GenericDataModel>, D extends DocumentByName<GenericDataModel, T>>(doc: D | null, select?: string[]) => D | null;

package/dist/{capabilities-DtDfpdcH.d.ts → capabilities-CLCYgRdY.d.ts}

@@ -1430,6 +1430,16 @@ type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y
 type Merge<A, B> = { [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never };
 type IndexKey = (Value | undefined)[];
 type FindManyUnionSource<TTableConfig extends TableRelationalConfig = TableRelationalConfig> = {
+  /**
+   * Index anchor for this source alone. Overrides the chain-level
+   * `.withIndex(...)`, so each source can walk its own range instead of
+   * re-walking one shared range and discarding the misses in JS.
+   *
+   * Sources may pin different indexes: `interleaveBy` re-orders every source by
+   * the same trailing fields before merging, so what has to match across
+   * sources is that ordering suffix, not the index name.
+   */
+  index?: PredicateWhereIndexConfig<TTableConfig>;
   where?: RelationsFilter<TTableConfig, any> | WhereCallback<TTableConfig>;
 };
 type PipelineRelationName<TTableConfig extends TableRelationalConfig> = Extract<keyof TTableConfig['relations'], string>;
@@ -3121,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;
@@ -3132,6 +3142,7 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
    */
   private _loadSingleRelation;
   private _createRelationCountError;
+  private _createRelationDepthError;
   private _remapRelationCountError;
   private _coerceRelationCountWhere;
   private _getRelationCountParentKey;

package/dist/{generated-contract-disabled-BEc4d98x.d.ts → generated-contract-disabled-DwYwySy3.d.ts}

@@ -224,6 +224,7 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
     };
   }, Promise<Record<string, unknown> | undefined>>;
   findMany: convex_server0.RegisteredQuery<"internal", {
+    limit?: number | undefined;
     join?: any;
     where?: {
       mode?: "sensitive" | "insensitive" | undefined;
@@ -232,11 +233,10 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
       value: string | number | boolean | string[] | number[] | null;
       field: string;
     }[] | undefined;
-    limit?: number | undefined;
     offset?: number | undefined;
     sortBy?: {
-      field: string;
       direction: "asc" | "desc";
+      field: string;
     } | undefined;
     model: string;
     paginationOpts: {

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-DtDfpdcH.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-DtDfpdcH.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-eTewPUGq.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-DAPEBp1y.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);
@@ -2675,16 +2687,16 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		return streamQuery;
 	}
 	_buildUnionSourceStream(source, fallbackOrder) {
-		const configuredIndex = this.configuredIndex;
+		const sourceIndex = source.index ?? this.configuredIndex;
 		this._assertWhereIndexRequirement({
 			where: source.where,
 			tableConfig: this.tableConfig,
-			hasConfiguredIndex: Boolean(configuredIndex?.name),
+			hasConfiguredIndex: Boolean(sourceIndex?.name),
 			context: "pipeline.union source"
 		});
 		const schemaDefinition = this._getSchemaDefinitionOrThrow();
 		let sourceStream = stream(this.db, schemaDefinition).query(this.tableConfig.name);
-		if (configuredIndex?.name) sourceStream = sourceStream.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
+		if (sourceIndex?.name) sourceStream = sourceStream.withIndex(sourceIndex.name, sourceIndex.range ? sourceIndex.range : (q) => q);
 		sourceStream = sourceStream.order(fallbackOrder);
 		const sourcePredicate = this._buildTableFilterPredicate(source.where, this.tableConfig);
 		if (sourcePredicate) sourceStream = sourceStream.filterWith(sourcePredicate);
@@ -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-DtDfpdcH.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-eTewPUGq.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-DAPEBp1y.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/{where-clause-compiler-eTewPUGq.d.ts → where-clause-compiler-DAPEBp1y.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-DtDfpdcH.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";
@@ -102,25 +102,20 @@ declare const migrationStorageTables: {
           fieldName: "status";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      migrationId: ConvexTextBuilderInitial<""> & {
         _: {
-          tableName: "migration_state";
+          notNull: true;
         };
       } & {
-        _: {
-          fieldName: "cursor";
-        };
-      };
-      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "migrationId";
         };
       };
-      migrationId: ConvexTextBuilderInitial<""> & {
+      checksum: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -130,10 +125,10 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "migrationId";
+          fieldName: "checksum";
         };
       };
-      checksum: ConvexTextBuilderInitial<""> & {
+      applied: ConvexBooleanBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -143,29 +138,34 @@ declare const migrationStorageTables: {
         };
       } & {
         _: {
-          fieldName: "checksum";
+          fieldName: "applied";
         };
       };
-      applied: ConvexBooleanBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
-          notNull: true;
+          tableName: "migration_state";
         };
       } & {
+        _: {
+          fieldName: "direction";
+        };
+      };
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "applied";
+          fieldName: "runId";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "cursor";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {
@@ -1133,7 +1133,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_member: ConvexTableWithColumns<{
     name: "aggregate_member";
     columns: {
-      kind: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1143,10 +1143,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "kind";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      kind: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1156,7 +1156,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "kind";
         };
       };
       indexName: ConvexTextBuilderInitial<""> & {
@@ -1323,11 +1323,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_extrema: ConvexTableWithColumns<{
     name: "aggregate_extrema";
     columns: {
-      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
-        _: {
-          $type: convex_values0.Value;
-        };
-      } & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1337,10 +1333,14 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "value";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
+        _: {
+          $type: convex_values0.Value;
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -1350,7 +1350,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "value";
         };
       };
       count: ConvexNumberBuilderInitial<""> & {
@@ -1589,19 +1589,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
-      kind: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_state";
-        };
-      } & {
-        _: {
-          fieldName: "kind";
-        };
-      };
       cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
@@ -1668,6 +1655,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "lastError";
         };
       };
+      kind: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "kind";
+        };
+      };
       indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1744,25 +1744,20 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
-      cursor: ConvexTextBuilderInitial<""> & {
+      migrationId: ConvexTextBuilderInitial<""> & {
         _: {
-          tableName: "migration_state";
+          notNull: true;
         };
       } & {
-        _: {
-          fieldName: "cursor";
-        };
-      };
-      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "migrationId";
         };
       };
-      migrationId: ConvexTextBuilderInitial<""> & {
+      checksum: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1772,10 +1767,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "migrationId";
+          fieldName: "checksum";
         };
       };
-      checksum: ConvexTextBuilderInitial<""> & {
+      applied: ConvexBooleanBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1785,29 +1780,34 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "checksum";
+          fieldName: "applied";
         };
       };
-      applied: ConvexBooleanBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
-          notNull: true;
+          tableName: "migration_state";
         };
       } & {
+        _: {
+          fieldName: "direction";
+        };
+      };
+      runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "applied";
+          fieldName: "runId";
         };
       };
-      runId: ConvexTextBuilderInitial<""> & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "runId";
+          fieldName: "cursor";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.26.2",
+  "version": "0.27.0",
   "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
@@ -543,45 +551,47 @@ return await ctx.orm.query.articles.findMany({
 
 ```ts
 return await ctx.orm.query.messages
-  .withIndex("by_from_to")
-  .select()
-  .union([
-    { where: { from: input.me, to: input.them } },
-    { where: { from: input.them, to: input.me } },
-  ])
-  .interleaveBy(["createdAt", "id"])
-  .filter(async (m) => !m.deletedAt)
-  .map(async (m) => ({ ...m, body: m.body.slice(0, 240) }))
-  .paginate({
-    cursor: input.cursor,
-    limit: input.limit,
-    maxScan: 500,
-  });
-```
-
-### Union with index ranges
-
-```ts
-const page = await ctx.orm.query.messages
   .select()
   .union([
     {
       index: {
         name: "by_from_to",
-        range: (q) => q.eq("from", me).eq("to", them),
+        range: (q) => q.eq("from", input.me).eq("to", input.them),
       },
     },
     {
       index: {
         name: "by_from_to",
-        range: (q) => q.eq("from", them).eq("to", me),
+        range: (q) => q.eq("from", input.them).eq("to", input.me),
       },
     },
   ])
   .interleaveBy(["createdAt", "id"])
-  .paginate({ cursor: null, limit: 20 });
+  .filter(async (m) => !m.deletedAt)
+  .map(async (m) => ({ ...m, body: m.body.slice(0, 240) }))
+  .paginate({
+    cursor: input.cursor,
+    limit: input.limit,
+    maxScan: 500,
+  });
 ```
 
+Per source:
+
+- `index: { name, range }` anchors that source on its own range. It overrides
+  the chain-level `.withIndex(...)`; sources that omit it use the chain index.
+- `where` filters that source's rows after the read.
+
+`interleaveBy` fields must be the trailing fields each source is already ordered
+by, so every field before them has to be pinned with `eq` in that source's
+range. Sources may name different indexes when they land on the same trailing
+fields — e.g. `by_author_likes` (authorId, numLikes) with `eq("authorId", ...)`
+merges with `numLikesAndType` (type, numLikes) with `eq("type", ...)` under
+`interleaveBy(["numLikes"])`.
+
+Anchor every source. A shared `.withIndex(...)` plus per-source `where` makes
+each source walk the same range and discard the misses after reading them.
+
 ### Pre-pagination transforms
 
 ```ts