kitcn 0.25.2 → 0.25.3

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-Bke7ULoY.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-SzH57bhp.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-SzH57bhp.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";
@@ -134,8 +134,8 @@ declare const adapterArgsValidator: convex_values0.VObject<{
   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", "model" | "select" | "where" | "limit" | "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-SzH57bhp.d.ts}

@@ -235,8 +235,8 @@ declare const createApi: <Schema extends SchemaDefinition<any, any>, DataModel e
     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

@@ -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-Bke7ULoY.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

@@ -3218,7 +3218,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 +3267,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 +3667,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 +3705,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
 			};
 		});

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-Bke7ULoY.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-TMNQB6US.d.ts → where-clause-compiler-Bke7ULoY.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";
@@ -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<""> & {
@@ -1021,7 +1021,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1031,10 +1031,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "count";
         };
       };
-      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;
-        };
-      } & {
+      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,10 +1350,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "value";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1363,10 +1363,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "count";
         };
       };
-      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;
@@ -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.25.2",
+  "version": "0.25.3",
   "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