kitcn 0.25.2 → 0.25.4

package/dist/aggregate/index.d.ts

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

@@ -2139,7 +2139,7 @@ declare const createAggregateError: (code: AggregateErrorCode, message: string)
 declare const ensureCountAllowedForRls: (tableConfig: TableRelationalConfig, rlsMode: "skip" | "default" | undefined) => void;
 declare const ensureAggregateAllowedForRls: (tableConfig: TableRelationalConfig, rlsMode: "skip" | "default" | undefined, methodName: string) => void;
 declare namespace runtime_d_exports$1 {
-  export { AGGREGATE_ERROR, AGGREGATE_STATE_KIND_METRIC, AGGREGATE_STATE_KIND_RANK, AggregateBucketDelta, AggregateErrorCode, AggregateExtremaDelta, AggregateIndexDefinition, AggregateMemberWrite, AggregateMembershipDelta, AggregateQueryPlan, AggregateRangeConstraint, COUNT_ERROR, COUNT_STATUS_BUILDING, COUNT_STATUS_CLEARING, COUNT_STATUS_READY, ClearIndexChunkResult, CountErrorCode, CountIndexDefinition, CountQueryPlan, CountState, PlanBucketReadCache, applyAggregateIndexesForChange, applyCountIndexesForChange, asUnknownArray, assertAggregateIndexesWritable, clearCountIndexChunk, compileAggregateQueryPlan, compileCountFieldQueryPlan, compileCountQueryPlan, computeAggregateMembershipDelta, computeAggregateMetricValues, computeCountKeyParts, createAggregateError, createCountError, ensureAggregateAllowedForRls, ensureAggregateIndexReady, ensureCountAllowedForRls, ensureCountIndexReady, flushAggregateMembershipDeltas, getAggregateIndexDefinitions, getCountIndexDefinitions, getCountIndexValuesForFields, getCountState, isAggregatePlanZero, isIndexCountZero, listCountStates, listSchemaAggregateIndexes, listSchemaCountIndexes, parseAggregateWhere, parseCountWhere, readAverageFromBuckets, readCountFieldFromBuckets, readCountFromBuckets, readExtremaFromBuckets, readPlanBuckets, readSumFromBuckets, reconcileAggregateMembership, serializeCountKeyParts, setCountState, setCountStateError };
+  export { AGGREGATE_ERROR, AGGREGATE_STATE_KIND_METRIC, AGGREGATE_STATE_KIND_RANK, AggregateBucketDelta, AggregateErrorCode, AggregateExtremaDelta, AggregateIndexDefinition, AggregateMemberWrite, AggregateMembershipDelta, AggregateQueryPlan, AggregateRangeConstraint, COUNT_ERROR, COUNT_STATUS_BUILDING, COUNT_STATUS_CLEARING, COUNT_STATUS_READY, ClearIndexChunkResult, CountErrorCode, CountIndexDefinition, CountQueryPlan, CountState, NULLISH_PROBE_VALUES, PlanBucketReadCache, applyAggregateIndexesForChange, applyCountIndexesForChange, asUnknownArray, assertAggregateIndexesWritable, clearCountIndexChunk, compileAggregateQueryPlan, compileCountFieldQueryPlan, compileCountQueryPlan, computeAggregateMembershipDelta, computeAggregateMetricValues, computeCountKeyParts, createAggregateError, createCountError, ensureAggregateAllowedForRls, ensureAggregateIndexReady, ensureCountAllowedForRls, ensureCountIndexReady, flushAggregateMembershipDeltas, getAggregateIndexDefinitions, getCountIndexDefinitions, getCountIndexValuesForFields, getCountState, isAggregatePlanZero, isIndexCountZero, listCountStates, listSchemaAggregateIndexes, listSchemaCountIndexes, parseAggregateWhere, parseCountWhere, readAverageFromBuckets, readCountFieldFromBuckets, readCountFromBuckets, readExtremaFromBuckets, readPlanBuckets, readSumFromBuckets, reconcileAggregateMembership, serializeCountKeyParts, setCountState, setCountStateError };
 }
 declare const AGGREGATE_STATE_KIND_METRIC = "metric";
 declare const AGGREGATE_STATE_KIND_RANK = "rank";
@@ -2216,6 +2216,17 @@ type AggregateQueryPlan = {
   metric: AggregateMetricRequest;
 };
 type PlanBucketReadCache = Map<string, Promise<unknown[]>>;
+/**
+ * A nullable column is `v.optional(v.union(v.null(), ...))`, so a row that
+ * never had the column written stores it absent, and `computeCountKeyParts`
+ * encodes absent as the `__kitcnUndefined` sentinel — a different bucket from
+ * the one an explicit `null` lands in. `isNull` means null-or-absent
+ * everywhere else in the ORM, so probing only the `null` bucket silently
+ * undercounts every row written before the column existed. Both probes are
+ * looked up through `serializeStable`, which maps `undefined` onto the same
+ * sentinel the write path stored.
+ */
+declare const NULLISH_PROBE_VALUES: readonly unknown[];
 declare const serializeCountKeyParts: (parts: unknown[]) => string;
 declare const compileCountQueryPlan: (tableConfig: TableRelationalConfig, where: unknown) => CountQueryPlan;
 declare const compileCountFieldQueryPlan: (tableConfig: TableRelationalConfig, where: unknown, field: string) => AggregateQueryPlan;
@@ -3030,6 +3041,14 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _pushGroupByConstraint;
   private _parseGroupByFieldConstraint;
   private _collectGroupByFieldValues;
+  /**
+   * One group per distinct value, where `null` and absent count as the same
+   * value. They occupy different aggregate buckets, so the emitted group key
+   * and the filter that reads it diverge: the key reports `null` while the
+   * filter keeps `isNull` so the aggregate compiler reads both buckets and
+   * combines their metrics into a single row.
+   */
+  private _buildGroupBySlots;
   private _buildGroupByCandidates;
   private _coerceGroupByByFields;
   private _isGroupByOrderDirection;

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-Bem7xvGK.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-DtDfpdcH.js";
 
 //#region src/orm/aggregate-index/capability.d.ts
 /**

package/dist/orm/aggregate-index/index.js

@@ -1,6 +1,6 @@
 import { t as DirectAggregate } from "../../runtime-BdqTbgKh.js";
 import { a as Columns } from "../../table-CX2lnX7e.js";
-import { Y as normalizeTemporalComparableValue, _t as PUBLIC_CREATED_AT_FIELD, c as AGGREGATE_ERROR, f as createError, gt as INTERNAL_CREATION_TIME_FIELD, i as AGGREGATE_STATE_TABLE, l as COUNT_ERROR, n as AGGREGATE_EXTREMA_TABLE, o as getAggregateIndexDefinitions, ot as mapWithConcurrency, r as AGGREGATE_MEMBER_TABLE, s as getRankIndexDefinitions, t as AGGREGATE_BUCKET_TABLE, vt as usesSystemCreatedAtAlias } from "../../schema-D8sVYuYO.js";
+import { Y as normalizeTemporalComparableValue, bt as PUBLIC_CREATED_AT_FIELD, c as AGGREGATE_ERROR, f as createError, i as AGGREGATE_STATE_TABLE, l as COUNT_ERROR, lt as mapWithConcurrency, n as AGGREGATE_EXTREMA_TABLE, o as getAggregateIndexDefinitions, r as AGGREGATE_MEMBER_TABLE, s as getRankIndexDefinitions, t as AGGREGATE_BUCKET_TABLE, xt as usesSystemCreatedAtAlias, yt as INTERNAL_CREATION_TIME_FIELD } from "../../schema-e0wbZ_Ax.js";
 
 //#region src/orm/aggregate-index/runtime.ts
 const UNDEFINED_SENTINEL = "__kitcnUndefined";
@@ -27,6 +27,17 @@ const normalizeUndefined = (value) => {
 	return value;
 };
 const serializeStable = (value) => JSON.stringify(normalizeUndefined(value));
+/**
+* A nullable column is `v.optional(v.union(v.null(), ...))`, so a row that
+* never had the column written stores it absent, and `computeCountKeyParts`
+* encodes absent as the `__kitcnUndefined` sentinel — a different bucket from
+* the one an explicit `null` lands in. `isNull` means null-or-absent
+* everywhere else in the ORM, so probing only the `null` bucket silently
+* undercounts every row written before the column existed. Both probes are
+* looked up through `serializeStable`, which maps `undefined` onto the same
+* sentinel the write path stored.
+*/
+const NULLISH_PROBE_VALUES = [null, void 0];
 const toConstraintSet = (values) => {
 	const set = /* @__PURE__ */ new Map();
 	for (const value of values) set.set(serializeStable(value), value);
@@ -138,7 +149,7 @@ const parseFieldFilter = (tableConfig, fieldName, value, target, codes, methodNa
 	if (Object.hasOwn(filter, "isNull")) {
 		hasRecognizedOperator = true;
 		if (filter.isNull !== true) throw createFilterError(codes, methodName, `field '${fieldName}'.isNull only supports true.`);
-		pushConstraint(target, fieldName, [null]);
+		pushConstraint(target, fieldName, [...NULLISH_PROBE_VALUES]);
 	}
 	for (const operator of [
 		"gt",
@@ -405,9 +416,9 @@ const enforceCartesianExpansionGuards = (options) => {
 	const maxTrackedCombinations = Math.max(cartesianMaxKeys, maxCombinationsByWork);
 	const combinations = countCartesianCombinations(options.fields, options.fieldValues, maxTrackedCombinations);
 	if (combinations === 0) return;
-	if (combinations > cartesianMaxKeys) throw createFilterError(options.codes, options.methodName, `expands IN filters to ${combinations} key combinations on aggregateIndex '${options.indexName}', exceeding aggregateCartesianMaxKeys (${cartesianMaxKeys}). Reduce IN list sizes, split the query, add a narrower aggregateIndex, or increase defineSchema(..., { defaults: { aggregateCartesianMaxKeys } }).`);
+	if (combinations > cartesianMaxKeys) throw createFilterError(options.codes, options.methodName, `expands to ${combinations} key combinations on aggregateIndex '${options.indexName}', exceeding aggregateCartesianMaxKeys (${cartesianMaxKeys}). Each 'in' value and each 'isNull' field (which reads both the null and the absent key) multiplies the combinations. Reduce IN list sizes, split the query, add a narrower aggregateIndex, or increase defineSchema(..., { defaults: { aggregateCartesianMaxKeys } }).`);
 	const estimatedWork = combinations * workUnitsPerCombination;
-	if (estimatedWork > workBudget) throw createFilterError(options.codes, options.methodName, `estimated ${options.workLabel} is ${estimatedWork} units on aggregateIndex '${options.indexName}', exceeding aggregateWorkBudget (${workBudget}). Reduce IN fan-out, split the query, or increase defineSchema(..., { defaults: { aggregateWorkBudget } }).`);
+	if (estimatedWork > workBudget) throw createFilterError(options.codes, options.methodName, `estimated ${options.workLabel} is ${estimatedWork} units on aggregateIndex '${options.indexName}', exceeding aggregateWorkBudget (${workBudget}). Reduce IN or isNull fan-out, split the query, or increase defineSchema(..., { defaults: { aggregateWorkBudget } }).`);
 };
 const hasLogicalOr = (where) => {
 	if (Object.hasOwn(where, "OR")) return true;

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-Bem7xvGK.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-TMNQB6US.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-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-CCMtAIdx.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

@@ -4,7 +4,7 @@ import { a as pretendRequired, i as pretend, n as deprecated } from "../validato
 import { t as id } from "../id-CuSfWa5q.js";
 import { A as or, C as matchLikePattern, D as notIlike, E as notBetween, O as notInArray, S as lte, T as not, _ as isFieldReference, a as between, b as like, c as endsWith, d as filterValueInList, f as filterValuesEqual, g as inArray, h as ilike, i as arrayOverlaps, j as startsWith, k as notLike, l as eq, m as gte, n as arrayContained, o as column, p as gt, r as arrayContains, s as contains, t as and, u as fieldRef, v as isNotNull, w as ne, x as lt, y as isNull } from "../filter-expression-Dydt8wS0.js";
 import { a as indexKeyWithinBounds, c as streamIndexRange, i as getIndexFields, l as isUnsetToken, n as EmptyStream, o as mergedStream, r as QueryStream, s as stream, t as getByIdWithOrmQueryFallback, u as unsetToken } from "../query-context-DOm5Xm3H.js";
-import { $ as serializeFilterExpression, A as ensureNonNullValues, B as getMutationExecutionMode, C as deserializeFilterExpression, D as enforcePolymorphicWrite, E as enforceForeignKeys, F as getChecks, G as getUniqueIndexes, H as getTableColumns$2, I as getColumnName$1, J as normalizeDateFieldsForWrite, K as hardDeleteRow, L as getForeignKeys, M as evaluateCheckConstraintTriState, N as evaluateFilter, O as enforceUniqueIndexes, P as extractPrimaryIdLookup, Q as selectReturningRowWithHydration, R as getMutationAsyncDelayMs, S as decodeUndefinedDeep, T as enforceCheckConstraints, U as getTableDeleteConfig, V as getOrmContext, W as getTableName, X as patchReferencingRows, Y as normalizeTemporalComparableValue, Z as resolveOrmRuntimeDefaults, _ as applyIncomingForeignKeyActionsOnUpdate, _t as PUBLIC_CREATED_AT_FIELD, a as aggregateExtension, at as markLifecycleHookedTables, b as collectMutationRowsBounded, c as AGGREGATE_ERROR, ct as findRelationIndex, d as createCountError, dt as getAggregateIndexes, et as softDeleteRow, ft as getIndexes, g as applyIncomingForeignKeyActionsOnDelete, gt as INTERNAL_CREATION_TIME_FIELD, h as applyDefaults, ht as CREATED_AT_MIGRATION_MESSAGE, it as hasLifecycleHooks, j as ensureNullableColumns, k as ensureDefaultColumns, l as COUNT_ERROR, lt as findSearchIndexByName, m as ensureCountAllowedForRls, mt as resolveIndexOrderPushdown, nt as takeRowsWithinByteBudget, o as getAggregateIndexDefinitions, ot as mapWithConcurrency, p as ensureAggregateAllowedForRls, pt as getRankIndexes, q as hydrateDateFieldsForRead, rt as toConvexFilter, s as getRankIndexDefinitions, st as findIndexForColumns, tt as splitReturningSelection, u as createAggregateError, ut as findVectorIndexByName, v as buildForeignKeyGraph, vt as usesSystemCreatedAtAlias, w as encodeUndefinedDeep, x as collectPrimaryIdLookupRows, y as canUsePrimaryIdLookupCursor, z as getMutationCollectionLimits } from "../schema-D8sVYuYO.js";
+import { $ as serializeFilterExpression, A as ensureNonNullValues, B as getMutationExecutionMode, C as deserializeFilterExpression, D as enforcePolymorphicWrite, E as enforceForeignKeys, F as getChecks, G as getUniqueIndexes, H as getTableColumns$2, I as getColumnName$1, J as normalizeDateFieldsForWrite, K as hardDeleteRow, L as getForeignKeys, M as evaluateCheckConstraintTriState, N as evaluateFilter, O as enforceUniqueIndexes, P as extractPrimaryIdLookup, Q as selectReturningRowWithHydration, R as getMutationAsyncDelayMs, S as decodeUndefinedDeep, T as enforceCheckConstraints, U as getTableDeleteConfig, V as getOrmContext, W as getTableName, X as patchReferencingRows, Y as normalizeTemporalComparableValue, Z as resolveOrmRuntimeDefaults, _ as applyIncomingForeignKeyActionsOnUpdate, _t as resolveIndexOrderPushdown, a as aggregateExtension, at as markLifecycleHookedTables, b as collectMutationRowsBounded, bt as PUBLIC_CREATED_AT_FIELD, c as AGGREGATE_ERROR, ct as isConvexEnforceableFilter, d as createCountError, dt as findRelationIndex, et as softDeleteRow, ft as findSearchIndexByName, g as applyIncomingForeignKeyActionsOnDelete, gt as getRankIndexes, h as applyDefaults, ht as getIndexes, it as hasLifecycleHooks, j as ensureNullableColumns, k as ensureDefaultColumns, l as COUNT_ERROR, lt as mapWithConcurrency, m as ensureCountAllowedForRls, mt as getAggregateIndexes, nt as takeRowsWithinByteBudget, o as getAggregateIndexDefinitions, ot as compileConvexFilter, p as ensureAggregateAllowedForRls, pt as findVectorIndexByName, q as hydrateDateFieldsForRead, rt as toConvexFilter, s as getRankIndexDefinitions, st as convexAnd, tt as splitReturningSelection, u as createAggregateError, ut as findIndexForColumns, v as buildForeignKeyGraph, vt as CREATED_AT_MIGRATION_MESSAGE, w as encodeUndefinedDeep, x as collectPrimaryIdLookupRows, xt as usesSystemCreatedAtAlias, y as canUsePrimaryIdLookupCursor, yt as INTERNAL_CREATION_TIME_FIELD, z as getMutationCollectionLimits } from "../schema-e0wbZ_Ax.js";
 import { t as defineSchemaExtension } from "../extensions-Blzsyekm.js";
 import { compareValues, v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric } from "convex/server";
@@ -1270,24 +1270,6 @@ var WhereClauseCompiler = class {
 
 //#endregion
 //#region src/orm/query.ts
-/**
-* Operators that Convex's `.filter()` cannot express, so `_toConvexExpression`
-* compiles them to a `() => true` placeholder and `_evaluatePostFetchFilter`
-* applies the real predicate in JavaScript after the rows are read.
-* Keep in sync with the string/array cases in `_toConvexExpression`.
-*/
-const POST_FETCH_ONLY_OPERATORS = new Set([
-	"like",
-	"ilike",
-	"notLike",
-	"notIlike",
-	"startsWith",
-	"endsWith",
-	"contains",
-	"arrayContains",
-	"arrayContained",
-	"arrayOverlaps"
-]);
 const DEFAULT_RELATION_FAN_OUT_MAX_KEYS = 1e3;
 /**
 * How many child rows the bounded relation stream filters at a time. Batching
@@ -1743,14 +1725,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* expression before relying on it.
 	*/
 	_isConvexEnforceableFilter(filter) {
-		if (filter.type === "binary") return !POST_FETCH_ONLY_OPERATORS.has(filter.operator);
-		if (filter.type === "unary") {
-			const [operand] = filter.operands;
-			if (isFieldReference(operand)) return true;
-			return this._isConvexEnforceableFilter(operand);
-		}
-		if (filter.type === "logical") return filter.operands.every((operand) => this._isConvexEnforceableFilter(operand));
-		return true;
+		return isConvexEnforceableFilter(filter);
 	}
 	/**
 	* Evaluate a filter expression against a fetched row
@@ -3218,7 +3193,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		if (Object.hasOwn(filter, "isNull")) {
 			hasRecognized = true;
 			if (filter.isNull !== true) throw createAggregateError(AGGREGATE_ERROR.FILTER_UNSUPPORTED, `groupBy() field '${fieldName}'.isNull only supports true.`);
-			this._pushGroupByConstraint(constraints, fieldName, [null]);
+			this._pushGroupByConstraint(constraints, fieldName, [null, void 0]);
 		}
 		if (Object.hasOwn(filter, "gt") || Object.hasOwn(filter, "gte") || Object.hasOwn(filter, "lt") || Object.hasOwn(filter, "lte")) throw createAggregateError(AGGREGATE_ERROR.FILTER_UNSUPPORTED, `groupBy() requires finite eq/in/isNull constraints for 'by' field '${fieldName}'. Range operators are unsupported for group keys.`);
 		const unsupportedKeys = Object.keys(filter).filter((key) => ![
@@ -3267,24 +3242,60 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		}
 		return output;
 	}
+	/**
+	* One group per distinct value, where `null` and absent count as the same
+	* value. They occupy different aggregate buckets, so the emitted group key
+	* and the filter that reads it diverge: the key reports `null` while the
+	* filter keeps `isNull` so the aggregate compiler reads both buckets and
+	* combines their metrics into a single row.
+	*/
+	_buildGroupBySlots(values) {
+		const nullishValues = values.filter((value) => value === null || value === void 0);
+		const slots = [];
+		let mergedNullish = false;
+		for (const value of values) {
+			if (value !== null && value !== void 0) {
+				slots.push({
+					key: value,
+					filter: value,
+					probeCount: 1
+				});
+				continue;
+			}
+			if (mergedNullish) continue;
+			mergedNullish = true;
+			slots.push({
+				key: null,
+				filter: nullishValues.length > 1 ? { isNull: true } : value,
+				probeCount: nullishValues.length
+			});
+		}
+		return slots;
+	}
 	_buildGroupByCandidates(byFields, byFieldValues) {
 		if (byFields.length === 0) return [];
 		const output = [];
-		const current = {};
-		const build = (index) => {
+		const key = {};
+		const where = {};
+		const build = (index, probeCount) => {
 			if (index >= byFields.length) {
-				output.push({ ...current });
+				output.push({
+					key: { ...key },
+					probeCount,
+					where: { ...where }
+				});
 				return;
 			}
 			const field = byFields[index];
-			const values = byFieldValues[field] ?? [];
-			for (const value of values) {
-				current[field] = value;
-				build(index + 1);
+			for (const slot of this._buildGroupBySlots(byFieldValues[field] ?? [])) {
+				key[field] = slot.key;
+				where[field] = slot.filter;
+				build(index + 1, probeCount * slot.probeCount);
 			}
-			delete current[field];
+			delete key[field];
+			delete where[field];
 		};
-		build(0);
+		build(0, 1);
 		return output;
 	}
 	_coerceGroupByByFields(by) {
@@ -3631,9 +3642,11 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const orderSpecs = this._coerceGroupByOrderSpecs(config.orderBy, by, aggregate);
 		const window = this._coerceGroupByWindowConfig(config, orderSpecs);
 		const maxKeys = this._getAggregateCartesianMaxKeys();
-		if (candidates.length > maxKeys) throw createAggregateError(AGGREGATE_ERROR.ARGS_UNSUPPORTED, `groupBy() expands to ${candidates.length} groups, exceeding aggregateCartesianMaxKeys (${maxKeys}). Reduce IN fan-out or increase defineSchema(..., { defaults: { aggregateCartesianMaxKeys } }).`);
+		let candidateProbeCount = 0;
+		for (const candidate of candidates) candidateProbeCount += candidate.probeCount;
+		if (candidateProbeCount > maxKeys) throw createAggregateError(AGGREGATE_ERROR.ARGS_UNSUPPORTED, `groupBy() expands to ${candidateProbeCount} aggregate key probes, exceeding aggregateCartesianMaxKeys (${maxKeys}). Reduce IN/isNull fan-out or increase defineSchema(..., { defaults: { aggregateCartesianMaxKeys } }).`);
 		const metricReads = (aggregate.count === true ? 1 : aggregate.count ? (aggregate.count.all ? 1 : 0) + aggregate.count.fields.length : 0) + aggregate.sumFields.length + aggregate.avgFields.length + aggregate.minFields.length + aggregate.maxFields.length;
-		const estimatedWork = candidates.length * Math.max(1, metricReads);
+		const estimatedWork = candidateProbeCount * Math.max(1, metricReads);
 		const workBudget = this._getAggregateWorkBudget();
 		if (estimatedWork > workBudget) throw createAggregateError(AGGREGATE_ERROR.ARGS_UNSUPPORTED, `groupBy() estimated work is ${estimatedWork} units, exceeding aggregateWorkBudget (${workBudget}). Reduce group fan-out or increase defineSchema(..., { defaults: { aggregateWorkBudget } }).`);
 		return {
@@ -3667,13 +3680,13 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const metricConfig = this._buildAggregateMetricConfig(normalized.aggregate);
 		const byOutputKeys = new Set(normalized.by.map((entry) => entry.raw));
 		let rows = await this._mapWithConcurrency(normalized.candidates, async (candidate) => {
-			const groupWhere = this._isEmptyWhere(normalized.aggregate.where) ? candidate : { AND: [normalized.aggregate.where, candidate] };
+			const groupWhere = this._isEmptyWhere(normalized.aggregate.where) ? candidate.where : { AND: [normalized.aggregate.where, candidate.where] };
 			const aggregateRow = await this._executeAggregate({
 				...metricConfig,
 				where: groupWhere
 			});
 			return {
-				...Object.fromEntries(normalized.by.map((entry) => [entry.raw, this._coerceAggregateReturnValue(entry.field, candidate[entry.field])])),
+				...Object.fromEntries(normalized.by.map((entry) => [entry.raw, this._coerceAggregateReturnValue(entry.field, candidate.key[entry.field])])),
 				...aggregateRow
 			};
 		});
@@ -4060,14 +4073,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					return indexQuery;
 				});
 				if (probeBound !== void 0 && probeOrderDirection) probeQuery = probeQuery.order(probeOrderDirection);
-				if (convexProbeFilters.length > 0) probeQuery = probeQuery.filter((q) => {
-					let result = null;
-					for (const filter of convexProbeFilters) {
-						const expr = this._toConvexExpression(filter)(q);
-						result = result ? q.and(result, expr) : expr;
-					}
-					return result ?? q;
-				});
+				if (convexProbeFilters.length > 0) probeQuery = probeQuery.filter((q) => convexAnd(q, convexProbeFilters.map((filter) => this._toConvexExpression(filter)(q))));
 				return probeBound === void 0 ? await probeQuery.collect() : await probeQuery.take(probeBound);
 			}));
 			let rows = Array.from(new Map(probeRows.flat().map((row) => [String(row._id), row])).values());
@@ -4182,14 +4188,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 					splitCursor: paginationResult.splitCursor
 				};
 			}
-			if (convexPostFilters.length > 0) query = query.filter((q) => {
-				let result = null;
-				for (const filter of convexPostFilters) {
-					const expr = this._toConvexExpression(filter)(q);
-					result = result ? q.and(result, expr) : expr;
-				}
-				return result ?? q;
-			});
+			if (convexPostFilters.length > 0) query = query.filter((q) => convexAnd(q, convexPostFilters.map((filter) => this._toConvexExpression(filter)(q))));
 			if (queryConfig.order && primaryOrder) {
 				if (needsPostFetchSortForPrimary) {
 					if (strict) throw new Error(`Pagination: Field '${primaryOrder.field}' has no index. Add an index or disable strict.`);
@@ -4214,14 +4213,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		const convexPostFilters = queryConfig.postFilters.filter((filter) => this._isConvexEnforceableFilter(filter));
 		const hasResidualPostFilter = convexPostFilters.length !== queryConfig.postFilters.length;
 		const hasPostFetchMembership = this._hasSearchDisallowedRelationFilter(whereFilter, this.tableConfig) || this.rls?.mode !== "skip" && isRlsEnabled(this.tableConfig.table);
-		if (convexPostFilters.length > 0) query = query.filter((q) => {
-			let result = null;
-			for (const filter of convexPostFilters) {
-				const expr = this._toConvexExpression(filter)(q);
-				result = result ? q.and(result, expr) : expr;
-			}
-			return result ?? q;
-		});
+		if (convexPostFilters.length > 0) query = query.filter((q) => convexAnd(q, convexPostFilters.map((filter) => this._toConvexExpression(filter)(q))));
 		const offset = config.offset ?? 0;
 		if (typeof offset !== "number") throw new Error("Only numeric offset is supported in kitcn ORM.");
 		const limit = this._resolveNonPaginatedLimit(config);
@@ -4337,9 +4329,7 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		return builder;
 	}
 	_buildFilterPredicate(q, fields, values) {
-		let expression = q.eq(q.field(fields[0]), values[0]);
-		for (let i = 1; i < fields.length; i += 1) expression = q.and(expression, q.eq(q.field(fields[i]), values[i]));
-		return expression;
+		return convexAnd(q, fields.map((field, index) => q.eq(q.field(field), values[index])));
 	}
 	_queryByFields(query, fields, values, indexName) {
 		if (indexName) return query.withIndex(indexName, (q) => this._buildIndexPredicate(q, fields, values));
@@ -4383,79 +4373,10 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 	* Uses visitor pattern to traverse expression tree
 	*/
 	_toConvexExpression(expression) {
-		const visitor = {
-			visitBinary: (expr) => {
-				const [field, value] = expr.operands;
-				if (!isFieldReference(field)) throw new Error("Binary expression must have FieldReference as first operand");
-				const fieldName = field.fieldName;
-				const normalizedValue = this._normalizeComparableValue(fieldName, value);
-				switch (expr.operator) {
-					case "eq": return (q) => q.eq(q.field(fieldName), normalizedValue);
-					case "ne": return (q) => q.neq(q.field(fieldName), normalizedValue);
-					case "gt": return (q) => q.gt(q.field(fieldName), normalizedValue);
-					case "gte": return (q) => q.gte(q.field(fieldName), normalizedValue);
-					case "lt": return (q) => q.lt(q.field(fieldName), normalizedValue);
-					case "lte": return (q) => q.lte(q.field(fieldName), normalizedValue);
-					case "inArray": {
-						const values = normalizedValue;
-						return (q) => {
-							if (values.length === 0) return q.eq(q.field("_id"), "__better_convex_never__");
-							return values.map((v) => q.eq(q.field(fieldName), v)).reduce((acc, cond) => q.or(acc, cond));
-						};
-					}
-					case "notInArray": {
-						const values = normalizedValue;
-						return (q) => {
-							return values.map((v) => q.neq(q.field(fieldName), v)).reduce((acc, cond) => q.and(acc, cond));
-						};
-					}
-					case "like":
-					case "ilike":
-					case "notLike":
-					case "notIlike":
-					case "startsWith":
-					case "endsWith":
-					case "contains":
-					case "arrayContains":
-					case "arrayContained":
-					case "arrayOverlaps": return () => true;
-					default: throw new Error(`Unsupported binary operator: ${expr.operator}`);
-				}
-			},
-			visitLogical: (expr) => {
-				const operandFns = expr.operands.map((op) => op.accept(visitor));
-				if (expr.operator === "and") return (q) => {
-					let result = operandFns[0](q);
-					for (let i = 1; i < operandFns.length; i++) result = q.and(result, operandFns[i](q));
-					return result;
-				};
-				if (expr.operator === "or") return (q) => {
-					let result = operandFns[0](q);
-					for (let i = 1; i < operandFns.length; i++) result = q.or(result, operandFns[i](q));
-					return result;
-				};
-				throw new Error(`Unsupported logical operator: ${expr.operator}`);
-			},
-			visitUnary: (expr) => {
-				const operand = expr.operands[0];
-				if (expr.operator === "not") {
-					const operandFn = operand.accept(visitor);
-					return (q) => q.not(operandFn(q));
-				}
-				if (expr.operator === "isNull") {
-					if (!isFieldReference(operand)) throw new Error("isNull must operate on a field reference");
-					const fieldName = operand.fieldName;
-					return (q) => q.or(q.eq(q.field(fieldName), null), q.eq(q.field(fieldName), void 0));
-				}
-				if (expr.operator === "isNotNull") {
-					if (!isFieldReference(operand)) throw new Error("isNotNull must operate on a field reference");
-					const fieldName = operand.fieldName;
-					return (q) => q.and(q.neq(q.field(fieldName), null), q.neq(q.field(fieldName), void 0));
-				}
-				throw new Error(`Unsupported unary operator: ${expr.operator}`);
-			}
-		};
-		return expression.accept(visitor);
+		return compileConvexFilter(expression, {
+			normalizeValue: (fieldName, value) => this._normalizeComparableValue(fieldName, value),
+			nullMatchesUndefined: true
+		});
 	}
 	/**
 	* Get edge metadata for a target table
@@ -5717,14 +5638,7 @@ var ConvexInsertBuilder = class extends QueryPromise {
 		else {
 			if (!allowFullScan) throw new Error("onConflict requires allowFullScan: true when no index is available.");
 			if (strict) console.warn("onConflict running without index (allowFullScan: true).");
-			query = query.filter((q) => {
-				let expr = q.eq(q.field(filterValuePairs[0][0]), filterValuePairs[0][1]);
-				for (let i = 1; i < filterValuePairs.length; i++) {
-					const [field, fieldValue] = filterValuePairs[i];
-					expr = q.and(expr, q.eq(q.field(field), fieldValue));
-				}
-				return expr;
-			});
+			query = query.filter((q) => convexAnd(q, filterValuePairs.map(([field, fieldValue]) => q.eq(q.field(field), fieldValue))));
 		}
 		const row = await query.first();
 		return row ? row : null;

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-Bem7xvGK.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-TMNQB6US.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-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-CCMtAIdx.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/{schema-D8sVYuYO.js → schema-e0wbZ_Ax.js}

@@ -125,6 +125,138 @@ async function mapWithConcurrency(items, limit, worker) {
 	return results;
 }
 
+//#endregion
+//#region src/orm/convex-filter-compiler.ts
+/**
+* Operators Convex's `.filter()` cannot express, so they compile to a
+* `() => true` placeholder and the real predicate runs in JavaScript after the
+* rows are read. Callers that push a compiled expression into Convex must
+* first check `isConvexEnforceableFilter`: a `true` placeholder makes a
+* downstream `take()` spend its budget on unfiltered rows, and a surrounding
+* `NOT` turns it into `q.not(true)`, which matches nothing.
+*/
+const POST_FETCH_ONLY_OPERATORS = new Set([
+	"like",
+	"ilike",
+	"notLike",
+	"notIlike",
+	"startsWith",
+	"endsWith",
+	"contains",
+	"arrayContains",
+	"arrayContained",
+	"arrayOverlaps"
+]);
+/**
+* Compared against `_id`, which is a Convex id and can never equal a plain
+* string, so `eq` against it is unsatisfiable. Convex's expression grammar has
+* no literal boolean, so this is how `in []` says "match nothing".
+*/
+const NEVER_MATCH_SENTINEL = "__better_convex_never__";
+/**
+* Convex's `q.or` / `q.and` are variadic — `or(...exprs)` serializes to a flat
+* `{ $or: [...] }` (see `convex/src/server/impl/filter_builder_impl.ts`).
+* Folding them pairwise instead nests one `$or` per operand, so the serialized
+* filter's JSON depth grows as `2N + 1` and the backend rejects the whole query
+* with `Received invalid json: recursion limit exceeded` once the list passes a
+* few dozen entries. Always combine in one variadic call.
+*/
+function convexOr(q, expressions) {
+	return expressions.length === 1 ? expressions[0] : q.or(...expressions);
+}
+/** Flat `$and` counterpart of {@link convexOr}. */
+function convexAnd(q, expressions) {
+	return expressions.length === 1 ? expressions[0] : q.and(...expressions);
+}
+/**
+* Whether Convex can carry the whole expression in `.filter()`, or some part of
+* it compiles to a `() => true` placeholder that only JavaScript can enforce.
+*/
+function isConvexEnforceableFilter(filter) {
+	if (filter.type === "binary") return !POST_FETCH_ONLY_OPERATORS.has(filter.operator);
+	if (filter.type === "unary") {
+		const [operand] = filter.operands;
+		if (isFieldReference(operand)) return true;
+		return isConvexEnforceableFilter(operand);
+	}
+	if (filter.type === "logical") return filter.operands.every((operand) => isConvexEnforceableFilter(operand));
+	return true;
+}
+/**
+* Compile a filter expression to a Convex `.filter()` callback.
+*
+* @param expression - Filter expression tree
+* @param options - Per-lane semantics; see {@link ConvexFilterCompilerOptions}
+*/
+function compileConvexFilter(expression, options = {}) {
+	const { normalizeValue, nullMatchesUndefined = false } = options;
+	const visitor = {
+		visitBinary: (expr) => {
+			const [field, value] = expr.operands;
+			if (!isFieldReference(field)) throw new Error("Binary expression must have FieldReference as first operand");
+			const fieldName = field.fieldName;
+			const normalizedValue = normalizeValue ? normalizeValue(fieldName, value) : value;
+			switch (expr.operator) {
+				case "eq": return (q) => q.eq(q.field(fieldName), normalizedValue);
+				case "ne": return (q) => q.neq(q.field(fieldName), normalizedValue);
+				case "gt": return (q) => q.gt(q.field(fieldName), normalizedValue);
+				case "gte": return (q) => q.gte(q.field(fieldName), normalizedValue);
+				case "lt": return (q) => q.lt(q.field(fieldName), normalizedValue);
+				case "lte": return (q) => q.lte(q.field(fieldName), normalizedValue);
+				case "inArray": {
+					const values = normalizedValue;
+					return (q) => {
+						if (values.length === 0) return q.eq(q.field("_id"), NEVER_MATCH_SENTINEL);
+						return convexOr(q, values.map((v) => q.eq(q.field(fieldName), v)));
+					};
+				}
+				case "notInArray": {
+					const values = normalizedValue;
+					return (q) => convexAnd(q, values.map((v) => q.neq(q.field(fieldName), v)));
+				}
+				case "like":
+				case "ilike":
+				case "notLike":
+				case "notIlike":
+				case "startsWith":
+				case "endsWith":
+				case "contains":
+				case "arrayContains":
+				case "arrayContained":
+				case "arrayOverlaps": return () => true;
+				default: throw new Error(`Unsupported binary operator: ${expr.operator}`);
+			}
+		},
+		visitLogical: (expr) => {
+			const operandFns = expr.operands.map((op) => op.accept(visitor));
+			if (expr.operator === "and") return (q) => convexAnd(q, operandFns.map((fn) => fn(q)));
+			if (expr.operator === "or") return (q) => convexOr(q, operandFns.map((fn) => fn(q)));
+			throw new Error(`Unsupported logical operator: ${expr.operator}`);
+		},
+		visitUnary: (expr) => {
+			const operand = expr.operands[0];
+			if (expr.operator === "not") {
+				const operandFn = operand.accept(visitor);
+				return (q) => q.not(operandFn(q));
+			}
+			if (expr.operator === "isNull") {
+				if (!isFieldReference(operand)) throw new Error("isNull must operate on a field reference");
+				const fieldName = operand.fieldName;
+				if (!nullMatchesUndefined) return (q) => q.eq(q.field(fieldName), null);
+				return (q) => q.or(q.eq(q.field(fieldName), null), q.eq(q.field(fieldName), void 0));
+			}
+			if (expr.operator === "isNotNull") {
+				if (!isFieldReference(operand)) throw new Error("isNotNull must operate on a field reference");
+				const fieldName = operand.fieldName;
+				if (!nullMatchesUndefined) return (q) => q.neq(q.field(fieldName), null);
+				return (q) => q.and(q.neq(q.field(fieldName), null), q.neq(q.field(fieldName), void 0));
+			}
+			throw new Error(`Unsupported unary operator: ${expr.operator}`);
+		}
+	};
+	return expression.accept(visitor);
+}
+
 //#endregion
 //#region src/orm/write-fanout.ts
 /**
@@ -385,7 +517,9 @@ const deserializeFilterExpression = (expression) => {
 	}
 	if (expression.type === "logical") {
 		const logical = expression;
-		return createLogicalExpression(logical.operator, logical.operands.map((operand) => deserializeFilterExpression(operand)).filter((operand) => !!operand));
+		const operands = logical.operands.map((operand) => deserializeFilterExpression(operand)).filter((operand) => !!operand);
+		if (operands.length === 0) throw new Error("Serialized logical expression requires at least one operand.");
+		return createLogicalExpression(logical.operator, operands);
 	}
 	const unary = expression;
 	const operand = unary.operand;
@@ -754,9 +888,7 @@ function buildIndexPredicate(q, columns, values) {
 	return builder;
 }
 function buildFilterPredicate(q, columns, values) {
-	let expr = q.eq(q.field(columns[0]), values[0]);
-	for (let i = 1; i < columns.length; i++) expr = q.and(expr, q.eq(q.field(columns[i]), values[i]));
-	return expr;
+	return convexAnd(q, columns.map((column, index) => q.eq(q.field(column), values[index])));
 }
 function ensureNullableColumns(table, columns, context) {
 	for (const columnName of columns) {
@@ -1197,78 +1329,7 @@ function enforceCheckConstraints(table, candidate) {
 	for (const check of checks) if (evaluateCheckConstraintTriState(candidate, check.expression) === false) throw new Error(`Check constraint '${check.name}' violation on '${tableName}'.`);
 }
 function toConvexFilter(expression) {
-	const visitor = {
-		visitBinary: (expr) => {
-			const [field, value] = expr.operands;
-			if (!isFieldReference(field)) throw new Error("Binary expression must have FieldReference as first operand");
-			const fieldName = field.fieldName;
-			switch (expr.operator) {
-				case "eq": return (q) => q.eq(q.field(fieldName), value);
-				case "ne": return (q) => q.neq(q.field(fieldName), value);
-				case "gt": return (q) => q.gt(q.field(fieldName), value);
-				case "gte": return (q) => q.gte(q.field(fieldName), value);
-				case "lt": return (q) => q.lt(q.field(fieldName), value);
-				case "lte": return (q) => q.lte(q.field(fieldName), value);
-				case "inArray": {
-					const values = value;
-					return (q) => {
-						if (values.length === 0) return q.eq(q.field("_id"), "__better_convex_never__");
-						return values.map((v) => q.eq(q.field(fieldName), v)).reduce((acc, cond) => q.or(acc, cond));
-					};
-				}
-				case "notInArray": {
-					const values = value;
-					return (q) => {
-						return values.map((v) => q.neq(q.field(fieldName), v)).reduce((acc, cond) => q.and(acc, cond));
-					};
-				}
-				case "like":
-				case "ilike":
-				case "notLike":
-				case "notIlike":
-				case "startsWith":
-				case "endsWith":
-				case "contains":
-				case "arrayContains":
-				case "arrayContained":
-				case "arrayOverlaps": return () => true;
-				default: throw new Error(`Unsupported binary operator: ${expr.operator}`);
-			}
-		},
-		visitLogical: (expr) => {
-			const operandFns = expr.operands.map((op) => op.accept(visitor));
-			if (expr.operator === "and") return (q) => {
-				let result = operandFns[0](q);
-				for (let i = 1; i < operandFns.length; i++) result = q.and(result, operandFns[i](q));
-				return result;
-			};
-			if (expr.operator === "or") return (q) => {
-				let result = operandFns[0](q);
-				for (let i = 1; i < operandFns.length; i++) result = q.or(result, operandFns[i](q));
-				return result;
-			};
-			throw new Error(`Unsupported logical operator: ${expr.operator}`);
-		},
-		visitUnary: (expr) => {
-			const operand = expr.operands[0];
-			if (expr.operator === "not") {
-				const operandFn = operand.accept(visitor);
-				return (q) => q.not(operandFn(q));
-			}
-			if (expr.operator === "isNull") {
-				if (!isFieldReference(operand)) throw new Error("isNull must operate on a field reference");
-				const fieldName = operand.fieldName;
-				return (q) => q.eq(q.field(fieldName), null);
-			}
-			if (expr.operator === "isNotNull") {
-				if (!isFieldReference(operand)) throw new Error("isNotNull must operate on a field reference");
-				const fieldName = operand.fieldName;
-				return (q) => q.neq(q.field(fieldName), null);
-			}
-			throw new Error(`Unsupported unary operator: ${expr.operator}`);
-		}
-	};
-	return expression.accept(visitor);
+	return compileConvexFilter(expression);
 }
 
 //#endregion
@@ -1422,4 +1483,4 @@ function aggregateExtension() {
 }
 
 //#endregion
-export { serializeFilterExpression as $, ensureNonNullValues as A, getMutationExecutionMode as B, deserializeFilterExpression as C, enforcePolymorphicWrite as D, enforceForeignKeys as E, getChecks as F, getUniqueIndexes as G, getTableColumns as H, getColumnName as I, normalizeDateFieldsForWrite as J, hardDeleteRow as K, getForeignKeys as L, evaluateCheckConstraintTriState as M, evaluateFilter as N, enforceUniqueIndexes as O, extractPrimaryIdLookup as P, selectReturningRowWithHydration as Q, getMutationAsyncDelayMs as R, decodeUndefinedDeep as S, enforceCheckConstraints as T, getTableDeleteConfig as U, getOrmContext as V, getTableName as W, patchReferencingRows as X, normalizeTemporalComparableValue as Y, resolveOrmRuntimeDefaults as Z, applyIncomingForeignKeyActionsOnUpdate as _, PUBLIC_CREATED_AT_FIELD as _t, aggregateExtension as a, markLifecycleHookedTables as at, collectMutationRowsBounded as b, AGGREGATE_ERROR as c, findRelationIndex as ct, createCountError as d, getAggregateIndexes as dt, softDeleteRow as et, createError as f, getIndexes as ft, applyIncomingForeignKeyActionsOnDelete as g, INTERNAL_CREATION_TIME_FIELD as gt, applyDefaults as h, CREATED_AT_MIGRATION_MESSAGE as ht, AGGREGATE_STATE_TABLE as i, hasLifecycleHooks as it, ensureNullableColumns as j, ensureDefaultColumns as k, COUNT_ERROR as l, findSearchIndexByName as lt, ensureCountAllowedForRls as m, resolveIndexOrderPushdown as mt, AGGREGATE_EXTREMA_TABLE as n, takeRowsWithinByteBudget as nt, getAggregateIndexDefinitions as o, mapWithConcurrency as ot, ensureAggregateAllowedForRls as p, getRankIndexes as pt, hydrateDateFieldsForRead as q, AGGREGATE_MEMBER_TABLE as r, toConvexFilter as rt, getRankIndexDefinitions as s, findIndexForColumns as st, AGGREGATE_BUCKET_TABLE as t, splitReturningSelection as tt, createAggregateError as u, findVectorIndexByName as ut, buildForeignKeyGraph as v, usesSystemCreatedAtAlias as vt, encodeUndefinedDeep as w, collectPrimaryIdLookupRows as x, canUsePrimaryIdLookupCursor as y, getMutationCollectionLimits as z };
+export { serializeFilterExpression as $, ensureNonNullValues as A, getMutationExecutionMode as B, deserializeFilterExpression as C, enforcePolymorphicWrite as D, enforceForeignKeys as E, getChecks as F, getUniqueIndexes as G, getTableColumns as H, getColumnName as I, normalizeDateFieldsForWrite as J, hardDeleteRow as K, getForeignKeys as L, evaluateCheckConstraintTriState as M, evaluateFilter as N, enforceUniqueIndexes as O, extractPrimaryIdLookup as P, selectReturningRowWithHydration as Q, getMutationAsyncDelayMs as R, decodeUndefinedDeep as S, enforceCheckConstraints as T, getTableDeleteConfig as U, getOrmContext as V, getTableName as W, patchReferencingRows as X, normalizeTemporalComparableValue as Y, resolveOrmRuntimeDefaults as Z, applyIncomingForeignKeyActionsOnUpdate as _, resolveIndexOrderPushdown as _t, aggregateExtension as a, markLifecycleHookedTables as at, collectMutationRowsBounded as b, PUBLIC_CREATED_AT_FIELD as bt, AGGREGATE_ERROR as c, isConvexEnforceableFilter as ct, createCountError as d, findRelationIndex as dt, softDeleteRow as et, createError as f, findSearchIndexByName as ft, applyIncomingForeignKeyActionsOnDelete as g, getRankIndexes as gt, applyDefaults as h, getIndexes as ht, AGGREGATE_STATE_TABLE as i, hasLifecycleHooks as it, ensureNullableColumns as j, ensureDefaultColumns as k, COUNT_ERROR as l, mapWithConcurrency as lt, ensureCountAllowedForRls as m, getAggregateIndexes as mt, AGGREGATE_EXTREMA_TABLE as n, takeRowsWithinByteBudget as nt, getAggregateIndexDefinitions as o, compileConvexFilter as ot, ensureAggregateAllowedForRls as p, findVectorIndexByName as pt, hydrateDateFieldsForRead as q, AGGREGATE_MEMBER_TABLE as r, toConvexFilter as rt, getRankIndexDefinitions as s, convexAnd as st, AGGREGATE_BUCKET_TABLE as t, splitReturningSelection as tt, createAggregateError as u, findIndexForColumns as ut, buildForeignKeyGraph as v, CREATED_AT_MIGRATION_MESSAGE as vt, encodeUndefinedDeep as w, collectPrimaryIdLookupRows as x, usesSystemCreatedAtAlias as xt, canUsePrimaryIdLookupCursor as y, INTERNAL_CREATION_TIME_FIELD as yt, getMutationCollectionLimits as z };

package/dist/{where-clause-compiler-TMNQB6US.d.ts → where-clause-compiler-CCMtAIdx.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-Bem7xvGK.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-DtDfpdcH.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";
@@ -111,15 +111,6 @@ declare const migrationStorageTables: {
           fieldName: "cursor";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
-        _: {
-          tableName: "migration_state";
-        };
-      } & {
-        _: {
-          fieldName: "direction";
-        };
-      };
       migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -159,6 +150,15 @@ declare const migrationStorageTables: {
           fieldName: "applied";
         };
       };
+      direction: ConvexTextBuilderInitial<""> & {
+        _: {
+          tableName: "migration_state";
+        };
+      } & {
+        _: {
+          fieldName: "direction";
+        };
+      };
       runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
@@ -1008,7 +1008,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1018,10 +1018,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "count";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1031,10 +1031,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "updatedAt";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1044,10 +1044,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1057,7 +1057,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "tableKey";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -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;
-        };
-      } & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1337,7 +1333,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "value";
+          fieldName: "count";
         };
       };
       updatedAt: ConvexNumberBuilderInitial<""> & {
@@ -1353,7 +1349,11 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
+        _: {
+          $type: convex_values0.Value;
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -1363,10 +1363,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "value";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1376,10 +1376,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1389,7 +1389,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "tableKey";
         };
       };
       keyHash: ConvexTextBuilderInitial<""> & {
@@ -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;
@@ -1753,15 +1753,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
-        _: {
-          tableName: "migration_state";
-        };
-      } & {
-        _: {
-          fieldName: "direction";
-        };
-      };
       migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1801,6 +1792,15 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "applied";
         };
       };
+      direction: ConvexTextBuilderInitial<""> & {
+        _: {
+          tableName: "migration_state";
+        };
+      } & {
+        _: {
+          fieldName: "direction";
+        };
+      };
       runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";

package/package.json

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

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

@@ -67,6 +67,8 @@ const total = await ctx.orm.query.todos.count({ where: { projectId } });
 Unfiltered `count()` uses native Convex count syscall (no aggregateIndex required).
 Filtered `count()` accepts `eq`, `in`, `isNull`, `gt`, `gte`, `lt`, `lte`, conjunction via `AND`, and bounded finite DNF `OR` when every branch is index-plannable on one `aggregateIndex`. Requires matching `aggregateIndex`.
 
+`isNull: true` matches an explicitly-`null` column and an absent column (a nullable column is optional, so a row inserted without it stores it absent). Matching `null` exactly (`{ status: null }` or `{ status: { eq: null } }`) matches only explicitly-`null` rows. `count()`, `aggregate()`, `groupBy()`, and relation `_count` use the same null semantics as `findMany()`.
+
 Windowed count: `count({ where, orderBy, skip, take, cursor })` counts rows within a window.
 
 - `skip`/`take` for pagination windows, `cursor` for "after this value" counting (requires `orderBy`, single field in v1)
@@ -102,6 +104,7 @@ Windowed aggregate:
 
 - `by` is required
 - every `by` field must be constrained in `where` via `eq`/`in`/`isNull`
+- an `isNull`-constrained `by` field emits one group keyed `null`, covering both explicitly-`null` and absent rows
 - `orderBy` supports `by` fields and selected metric fields
 - `skip`/`take`/`cursor` require explicit `orderBy`
 - `having` supports conjunction filters on `by` fields and selected metrics