appflare 0.0.9 → 0.0.10

package/cli/generators/generate-db-handlers/templates.ts

@@ -13,6 +13,8 @@ export const buildHandlerFileContent = (
 ): string => {
 	const findFn = `find${params.pascalName}`;
 	const findOneFn = `findOne${params.pascalName}`;
+	const sumFn = `sum${params.pascalName}`;
+	const avgFn = `avg${params.pascalName}`;
 	const insertFn = `insert${params.pascalName}`;
 	const updateFn = `update${params.pascalName}`;
 	const deleteFn = `delete${params.pascalName}`;
@@ -26,7 +28,9 @@ import { z } from "zod";
 import {
 	internalMutation,
 	internalQuery,
+	type AppflareInclude,
 	type EditableDoc,
+	type Doc,
 	type Id,
 	type QuerySort,
 	type QueryWhere,
@@ -40,6 +44,8 @@ export const ${findFn} = internalQuery({
 			.optional(),
 		limit: z.number().int().nonnegative().optional(),
 		offset: z.number().int().nonnegative().optional(),
+		include: z.custom<AppflareInclude<Doc<${JSON.stringify(params.tableName)}>>>()
+			.optional(),
 	},
 	handler: async (ctx, args) => {
 		return ctx.db[${JSON.stringify(params.tableName)} as any].findMany({
@@ -47,6 +53,7 @@ export const ${findFn} = internalQuery({
 			orderBy: args.sort as any,
 			skip: args.offset,
 			take: args.limit,
+				include: args.include as any,
 		});
 	},
 });
@@ -58,6 +65,8 @@ export const ${findOneFn} = internalQuery({
 		sort: z.custom<QuerySort<${JSON.stringify(params.tableName)}>>()
 			.optional(),
 		offset: z.number().int().nonnegative().optional(),
+		include: z.custom<AppflareInclude<Doc<${JSON.stringify(params.tableName)}>>>()
+			.optional(),
 	},
 	handler: async (ctx, args) => {
 		return ctx.db[${JSON.stringify(params.tableName)} as any].findFirst({
@@ -65,6 +74,45 @@ export const ${findOneFn} = internalQuery({
 			orderBy: args.sort as any,
 			skip: args.offset,
 			take: 1,
+				include: args.include as any,
+		});
+	},
+});
+
+export const ${sumFn} = internalQuery({
+	args: {
+		fields: z.array(z.string()).min(1),
+		where: z.custom<QueryWhere<${JSON.stringify(params.tableName)}>>()
+			.optional(),
+		groupBy: z.union([z.string(), z.array(z.string())]).optional(),
+		populate: z.custom<AppflareInclude<Doc<${JSON.stringify(params.tableName)}>>>()
+			.optional(),
+	},
+	handler: async (ctx, args) => {
+		return ctx.db[${JSON.stringify(params.tableName)} as any].aggregate({
+			where: args.where as any,
+			groupBy: args.groupBy as any,
+			sum: args.fields as any,
+			populate: args.populate as any,
+		});
+	},
+});
+
+export const ${avgFn} = internalQuery({
+	args: {
+		fields: z.array(z.string()).min(1),
+		where: z.custom<QueryWhere<${JSON.stringify(params.tableName)}>>()
+			.optional(),
+		groupBy: z.union([z.string(), z.array(z.string())]).optional(),
+		populate: z.custom<AppflareInclude<Doc<${JSON.stringify(params.tableName)}>>>()
+			.optional(),
+	},
+	handler: async (ctx, args) => {
+		return ctx.db[${JSON.stringify(params.tableName)} as any].aggregate({
+			where: args.where as any,
+			groupBy: args.groupBy as any,
+			avg: args.fields as any,
+			populate: args.populate as any,
 		});
 	},
 });
@@ -121,11 +169,13 @@ export const ${deleteFn} = internalMutation({
 export const buildExportLine = (params: ExportLineParams): string => {
 	const findFn = `find${params.pascalName}`;
 	const findOneFn = `findOne${params.pascalName}`;
+	const sumFn = `sum${params.pascalName}`;
+	const avgFn = `avg${params.pascalName}`;
 	const insertFn = `insert${params.pascalName}`;
 	const updateFn = `update${params.pascalName}`;
 	const deleteFn = `delete${params.pascalName}`;
 
-	return `export { ${findFn}, ${findOneFn}, ${insertFn}, ${updateFn}, ${deleteFn} } from "./${params.tableName}";`;
+	return `export { ${findFn}, ${findOneFn}, ${sumFn}, ${avgFn}, ${insertFn}, ${updateFn}, ${deleteFn} } from "./${params.tableName}";`;
 };
 
 export const buildIndexFileContent = (

package/cli/schema/schema-static-types.ts

@@ -9,6 +9,11 @@ type ExtractIdTableName<T> = NonNil<T> extends Id<infer TTable>
 		? ExtractIdTableName<TItem>
 		: never;
 
+type NumericKeys<T> =
+	{
+		[K in keyof T]: NonNil<T[K]> extends number | bigint ? K : never;
+	}[keyof T] & string;
+
 type PopulateValue<T> = T extends Id<infer TTable>
 	? (TTable extends TableNames ? Doc<TTable> : never)
 	: T extends Array<infer TItem>
@@ -52,6 +57,100 @@ export type QuerySort<TableName extends TableNames> =
 	| Record<string, SortDirection>
 	| Array<[string, SortDirection]>;
 
+type GeoCoordinates = readonly [number, number];
+
+export type GeoPoint = {
+	type: "Point";
+	coordinates: GeoCoordinates;
+};
+
+type GeoPointInput = GeoPoint | GeoCoordinates;
+
+const GEO_EARTH_RADIUS_METERS = 6_378_100;
+
+const __geoNormalizePoint = (point: GeoPointInput): GeoPoint =>
+	Array.isArray(point)
+		? { type: "Point", coordinates: [point[0], point[1]] }
+		: point;
+
+export const geo = {
+	point(lng: number, lat: number): GeoPoint {
+		return { type: "Point", coordinates: [lng, lat] };
+	},
+	near(
+		field: string,
+		point: GeoPointInput,
+		options: { maxDistanceMeters?: number; minDistanceMeters?: number } = {}
+	): Record<string, unknown> {
+		const $near: Record<string, unknown> = {
+			$geometry: __geoNormalizePoint(point),
+		};
+		if (options.maxDistanceMeters !== undefined)
+			$near.$maxDistance = options.maxDistanceMeters;
+		if (options.minDistanceMeters !== undefined)
+			$near.$minDistance = options.minDistanceMeters;
+		return { [field]: { $near } };
+	},
+	withinRadius(
+		field: string,
+		center: GeoPointInput,
+		radiusMeters: number
+	): Record<string, unknown> {
+		return {
+			[field]: {
+				$geoWithin: {
+					$centerSphere: [
+						__geoNormalizePoint(center).coordinates,
+						radiusMeters / GEO_EARTH_RADIUS_METERS,
+					],
+				},
+			},
+		};
+	},
+	withinBox(
+		field: string,
+		southwest: GeoPointInput,
+		northeast: GeoPointInput
+	): Record<string, unknown> {
+		return {
+			[field]: {
+				$geoWithin: {
+					$box: [
+						__geoNormalizePoint(southwest).coordinates,
+						__geoNormalizePoint(northeast).coordinates,
+					],
+				},
+			},
+		};
+	},
+	withinPolygon(
+		field: string,
+		polygon: ReadonlyArray<GeoPointInput>
+	): Record<string, unknown> {
+		return {
+			[field]: {
+				$geoWithin: {
+					$polygon: polygon.map((p) =>
+						__geoNormalizePoint(p).coordinates
+					),
+				},
+			},
+		};
+	},
+	intersects(
+		field: string,
+		geometry: { type: string; coordinates: unknown }
+	): Record<string, unknown> {
+		return {
+			[field]: {
+				$geoIntersects: {
+					$geometry: geometry,
+				},
+			},
+		};
+	},
+};
+
 type SelectedKeys<TDoc, TSelect> =
 	TSelect extends readonly (infer TKey)[]
 		? Extract<TKey, Keys<TDoc>>
@@ -70,14 +169,70 @@ export type AppflareSelect<TDoc> =
 	| ReadonlyArray<Keys<TDoc>>
 	| Partial<Record<Keys<TDoc>, boolean>>;
 
+type PopulatedDocForKey<TDoc, TKey extends Keys<TDoc>> =
+	NonNil<PopulateValue<TDoc[TKey]>> extends Array<infer TItem>
+		? NonNil<TItem>
+		: NonNil<PopulateValue<TDoc[TKey]>>;
+
+type AggregateSpec<TDoc> = {
+	count?: boolean;
+	sum?: ReadonlyArray<NumericKeys<TDoc>>;
+	avg?: ReadonlyArray<NumericKeys<TDoc>>;
+};
+
+type AppflareIncludeRecord<TDoc> = {
+	[K in PopulatableKeys<TDoc>]?:
+		| boolean
+		| {
+			aggregate?: AggregateSpec<PopulatedDocForKey<TDoc, K>>;
+			includeDocs?: boolean;
+		};
+};
+
 export type AppflareInclude<TDoc> =
 	| ReadonlyArray<PopulatableKeys<TDoc>>
-	| Partial<Record<PopulatableKeys<TDoc>, boolean>>;
-
-type AppflareResultDoc<TDoc, TSelect, TInclude> = WithSelected<
-	WithPopulatedMany<TDoc, IncludedKeys<TDoc, TInclude>>,
-	SelectedKeys<TDoc, TSelect>
->;
+	| AppflareIncludeRecord<TDoc>;
+
+type ExtractAggregateSpec<T> = T extends { aggregate?: infer TSpec } ? TSpec : never;
+
+type AggregateResultFromSpec<TDoc, TSpec> = (TSpec extends { count: true }
+	? { count: number }
+	: {}) &
+	(TSpec extends { sum: infer TSum }
+		? TSum extends ReadonlyArray<infer K>
+			? { [P in Extract<K, NumericKeys<TDoc>> as \`sum_\${P}\`]: number }
+			: {}
+		: {}) &
+	(TSpec extends { avg: infer TAvg }
+		? TAvg extends ReadonlyArray<infer K>
+			? { [P in Extract<K, NumericKeys<TDoc>> as \`avg_\${P}\`]: number }
+			: {}
+		: {});
+
+type AggregateMapForInclude<TDoc, TInclude> = TInclude extends ReadonlyArray<any>
+	? {}
+	: {
+		[K in keyof TInclude as ExtractAggregateSpec<TInclude[K]> extends never
+			? never
+			: K]: AggregateResultFromSpec<
+			PopulatedDocForKey<TDoc, Extract<K, Keys<TDoc>>>,
+			ExtractAggregateSpec<TInclude[K]>
+		>;
+	};
+
+type WithAggregatesForInclude<TDoc, TInclude> = keyof AggregateMapForInclude<
+	TDoc,
+	TInclude
+> extends never
+	? {}
+	: { _aggregates: AggregateMapForInclude<TDoc, TInclude> };
+
+type AppflareResultDoc<TDoc, TSelect, TInclude> =
+	WithSelected<
+		WithPopulatedMany<TDoc, IncludedKeys<TDoc, TInclude>>,
+		SelectedKeys<TDoc, TSelect>
+	> &
+		WithAggregatesForInclude<TDoc, TInclude>;
 
 export type AppflareFindManyArgs<TableName extends TableNames> = {
 	where?: QueryWhere<TableName>;
@@ -130,6 +285,55 @@ export type AppflareCountArgs<TableName extends TableNames> = {
 	where?: QueryWhere<TableName>;
 };
 
+type AggregateGroupInput<TDoc> =
+	| ReadonlyArray<keyof TDoc & string>
+	| (keyof TDoc & string);
+
+type NormalizeGroupInput<TDoc, TGroup> =
+	TGroup extends readonly (infer K)[]
+		? ReadonlyArray<Extract<K, keyof TDoc & string>>
+		: TGroup extends string
+			? ReadonlyArray<Extract<TGroup, keyof TDoc & string>>
+			: ReadonlyArray<never>;
+
+type AggregateId<TDoc, TGroup extends ReadonlyArray<keyof TDoc & string>> =
+	TGroup extends readonly []
+		? null
+		: TGroup extends readonly [infer K]
+			? TDoc[Extract<K, keyof TDoc>]
+			: { [K in TGroup[number]]: TDoc[K] };
+
+type AggregateResult<
+	TDoc,
+	TGroup extends ReadonlyArray<keyof TDoc & string>,
+	TSum extends ReadonlyArray<NumericKeys<TDoc>>,
+	TAvg extends ReadonlyArray<NumericKeys<TDoc>>,
+> = {
+		_id: AggregateId<TDoc, TGroup>;
+	} & (TSum[number] extends never ? {} : { [K in TSum[number] as \`sum_\${K}\`]: number }) &
+	(TAvg[number] extends never ? {} : { [K in TAvg[number] as \`avg_\${K}\`]: number });
+
+export type AppflareAggregateArgs<
+	TableName extends TableNames,
+	TGroup = AggregateGroupInput<TableDocMap[TableName]>,
+	TSum extends ReadonlyArray<NumericKeys<TableDocMap[TableName]>> = ReadonlyArray<
+		NumericKeys<TableDocMap[TableName]>
+	>,
+	TAvg extends ReadonlyArray<NumericKeys<TableDocMap[TableName]>> = ReadonlyArray<
+		NumericKeys<TableDocMap[TableName]>
+	>,
+> = {
+	where?: QueryWhere<TableName>;
+	groupBy?: TGroup;
+	sum?: TSum;
+	avg?: TAvg;
+	/**
+	 * Populate aggregated group keys that are references to other tables.
+	 * Only keys present in groupBy are eligible for populate.
+	 */
+	populate?: AppflareInclude<TableDocMap[TableName]>;
+};
+
 export type AppflareTableClient<TableName extends TableNames> = {
 	findMany<TSelect = AppflareSelect<TableDocMap[TableName]>, TInclude = never>(
 		args?: AppflareFindManyArgs<TableName> & {
@@ -197,6 +401,26 @@ export type AppflareTableClient<TableName extends TableNames> = {
 	>;
 	deleteMany(args?: AppflareDeleteManyArgs<TableName>): Promise<{ count: number }>;
 	count(args?: AppflareCountArgs<TableName>): Promise<number>;
+	aggregate<
+		TGroup = AggregateGroupInput<TableDocMap[TableName]>,
+		TSum extends ReadonlyArray<NumericKeys<TableDocMap[TableName]>> = ReadonlyArray<
+			NumericKeys<TableDocMap[TableName]>
+		>,
+		TAvg extends ReadonlyArray<NumericKeys<TableDocMap[TableName]>> = ReadonlyArray<
+			NumericKeys<TableDocMap[TableName]>
+		>,
+	>(
+		args: AppflareAggregateArgs<TableName, TGroup, TSum, TAvg>
+	): Promise<
+		Array<
+			AggregateResult<
+				TableDocMap[TableName],
+				NormalizeGroupInput<TableDocMap[TableName], TGroup>,
+				TSum,
+				TAvg
+			>
+		>
+	>;
 };
 
 export type AppflareModelMap = {

package/cli/utils/zod-utils.ts

@@ -37,6 +37,12 @@ function renderField(fieldName: string, schema: any): string {
 function renderType(schema: any): { tsType: string; optional: boolean } {
 	const def = schema?._def;
 	const typeName: string | undefined = def?.typeName ?? def?.type;
+	const description: string | undefined =
+		schema?.description ?? def?.description;
+
+	if (description === "geo:point") {
+		return { tsType: "GeoPoint", optional: false };
+	}
 
 	if (typeName === "ZodOptional" || typeName === "optional") {
 		const inner = def?.innerType ?? def?.schema ?? schema?._def?.innerType;

package/index.ts

@@ -1,3 +1,4 @@
 export * from "./lib/db";
 export * from "./lib/values";
+export * from "./lib/location";
 export { AppflareConfig } from "./cli/utils/utils";

package/lib/README.md

@@ -19,10 +19,16 @@ Docs for the shared library helpers in `lib/`
 
 - Primitives: `v.string()`, `v.number()`, `v.boolean()`, `v.date()`.
 - Relations/ids: `v.id(table)` creates a string with an ObjectId regex and a `ref:<table>` description for downstream typing.
+- Location: `v.point()`/`v.location()` yields a GeoJSON Point schema for geospatial queries.
 - Collections/objects: `v.array(item)`, `v.object(shape)`.
 - Modifiers: `v.optional(schema)`, `v.nullable(schema)`, `v.union(...schemas)`, `v.literal(value)`.
 - Misc: `v.buffer()` (string placeholder), `v.any()`, `v.unknown()`.
 
+**Location helpers** ([packages/appflare/lib/location.ts](packages/appflare/lib/location.ts))
+
+- Builders: `point(lng, lat)` returns a GeoJSON Point; `geo.point` is the same alias.
+- Queries: `geo.near("location", pointLngLat, { maxDistanceMeters })`, `geo.withinRadius("location", center, radiusMeters)`, `geo.withinBox(...)`, `geo.withinPolygon(...)`, `geo.intersects(...)` produce Mongo-ready filters you can pass to `where`.
+
 **Example: define a schema**
 
 ```ts
@@ -35,6 +41,7 @@ export default defineSchema({
 		email: v.string(),
 		age: v.number().optional(),
 		orgId: v.id("orgs"),
+		location: v.point(),
 	}),
 	orgs: defineTable({
 		name: v.string(),

package/lib/location.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+
+export type GeoCoordinates = readonly [number, number];
+
+export type GeoPoint = {
+	type: "Point";
+	coordinates: GeoCoordinates;
+};
+
+export const geoPointSchema = z
+	.object({
+		type: z.literal("Point"),
+		coordinates: z.tuple([z.number(), z.number()]),
+	})
+	.describe("geo:point");
+
+export const EARTH_RADIUS_METERS = 6_378_100;
+
+const normalizePoint = (point: GeoPoint | GeoCoordinates): GeoPoint =>
+	Array.isArray(point)
+		? { type: "Point", coordinates: [point[0], point[1]] }
+		: (point as GeoPoint);
+
+export const point = (lng: number, lat: number): GeoPoint => ({
+	type: "Point",
+	coordinates: [lng, lat],
+});
+
+export type NearQueryOptions = {
+	maxDistanceMeters?: number;
+	minDistanceMeters?: number;
+};
+
+export const near = (
+	field: string,
+	geometry: GeoPoint | GeoCoordinates,
+	options: NearQueryOptions = {}
+): Record<string, unknown> => {
+	const $near: Record<string, unknown> = {
+		$geometry: normalizePoint(geometry),
+	};
+	if (options.maxDistanceMeters !== undefined) {
+		$near.$maxDistance = options.maxDistanceMeters;
+	}
+	if (options.minDistanceMeters !== undefined) {
+		$near.$minDistance = options.minDistanceMeters;
+	}
+	return { [field]: { $near } };
+};
+
+export const withinRadius = (
+	field: string,
+	center: GeoPoint | GeoCoordinates,
+	radiusMeters: number
+): Record<string, unknown> => ({
+	[field]: {
+		$geoWithin: {
+			$centerSphere: [
+				normalizePoint(center).coordinates,
+				radiusMeters / EARTH_RADIUS_METERS,
+			],
+		},
+	},
+});
+
+export const withinBox = (
+	field: string,
+	southwest: GeoPoint | GeoCoordinates,
+	northeast: GeoPoint | GeoCoordinates
+): Record<string, unknown> => ({
+	[field]: {
+		$geoWithin: {
+			$box: [
+				normalizePoint(southwest).coordinates,
+				normalizePoint(northeast).coordinates,
+			],
+		},
+	},
+});
+
+export const withinPolygon = (
+	field: string,
+	polygon: ReadonlyArray<GeoPoint | GeoCoordinates>
+): Record<string, unknown> => ({
+	[field]: {
+		$geoWithin: {
+			$polygon: polygon.map((p) => normalizePoint(p).coordinates),
+		},
+	},
+});
+
+export const intersects = (
+	field: string,
+	geometry: { type: string; coordinates: unknown }
+): Record<string, unknown> => ({
+	[field]: {
+		$geoIntersects: {
+			$geometry: geometry,
+		},
+	},
+});
+
+export const geo = {
+	point,
+	near,
+	withinRadius,
+	withinBox,
+	withinPolygon,
+	intersects,
+};

package/lib/values.ts

@@ -1,10 +1,13 @@
 import { z } from "zod";
+import { geoPointSchema } from "./location";
 
 export const v = {
 	string: () => z.string(),
 	number: () => z.number(),
 	boolean: () => z.boolean(),
 	date: () => z.date(),
+	point: () => geoPointSchema,
+	location: () => geoPointSchema,
 	id: (table: string) =>
 		z
 			.string()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "appflare",
-	"version": "0.0.9",
+	"version": "0.0.10",
 	"bin": {
 		"appflare": "./cli/index.ts"
 	},
@@ -8,6 +8,7 @@
 		".": "./index.ts",
 		"./db": "./lib/db.ts",
 		"./values": "./lib/values.ts",
+		"./location": "./lib/location.ts",
 		"./*": "./*.ts",
 		"./react/*": "./react/*.ts",
 		"./react": "./react/index.ts",

package/server/database/context.ts

@@ -110,6 +110,7 @@ export function createMongoDbContext<
 
 function toKeyList(arg: unknown): string[] | undefined {
 	if (!arg) return undefined;
+	if (typeof arg === "string" || typeof arg === "number") return [String(arg)];
 	if (Array.isArray(arg)) return arg.map((k) => String(k));
 	if (typeof arg === "object") {
 		return Object.entries(arg as Record<string, unknown>)
@@ -130,7 +131,26 @@ function createAppflareTableClient<
 	getCollection: (table: string) => Collection<Document>;
 }): AppflareTableClient<TableName, TTableDocMap> {
 	const selectKeys = (select: unknown) => toKeyList(select);
-	const includeKeys = (include: unknown) => toKeyList(include);
+
+	const toArray = <T>(value: T | T[] | undefined): T[] => {
+		if (value === undefined) return [];
+		return Array.isArray(value) ? value : [value];
+	};
+
+	const stringifyAggregateValue = (value: unknown): unknown => {
+		if (value instanceof ObjectId) return value.toHexString();
+		if (Array.isArray(value)) return value.map(stringifyAggregateValue);
+		if (value && typeof value === "object") {
+			const out: Record<string, unknown> = {};
+			for (const [key, val] of Object.entries(
+				value as Record<string, unknown>
+			)) {
+				out[key] = stringifyAggregateValue(val);
+			}
+			return out;
+		}
+		return value;
+	};
 
 	const buildQuery = (args?: {
 		where?: any;
@@ -149,8 +169,7 @@ function createAppflareTableClient<
 		if (args?.take !== undefined) q = q.limit(args.take);
 		const s = selectKeys(args?.select);
 		if (s?.length) q = q.select(s as any);
-		const i = includeKeys(args?.include);
-		if (i?.length) q = q.populate(i as any);
+		if (args?.include) q = q.populate(args.include as any);
 		return q;
 	};
 
@@ -235,5 +254,72 @@ function createAppflareTableClient<
 			const filter = normalizeIdFilter(toMongoFilter(args?.where ?? {}));
 			return coll.countDocuments(filter ?? {});
 		},
+		aggregate: async (args) => {
+			const coll = params.getCollection(params.table as string);
+			const pipeline: Document[] = [];
+
+			const normalizedWhere = args.where
+				? normalizeIdFilter(
+						normalizeRefFields(
+							params.table as string,
+							args.where as Record<string, unknown>,
+							params.refs
+						) as any
+					)
+				: undefined;
+			if (normalizedWhere && Object.keys(normalizedWhere).length > 0) {
+				pipeline.push({ $match: normalizedWhere });
+			}
+
+			const sumFields = toArray(args.sum).filter(Boolean) as string[];
+			const avgFields = toArray(args.avg).filter(Boolean) as string[];
+			if (sumFields.length === 0 && avgFields.length === 0) {
+				throw new Error("aggregate requires at least one sum or avg field");
+			}
+
+			const groupKeys = toArray(args.groupBy).filter(Boolean) as string[];
+			const groupId =
+				groupKeys.length === 0
+					? null
+					: groupKeys.length === 1
+						? `$${groupKeys[0]}`
+						: Object.fromEntries(groupKeys.map((k) => [k, `$${k}`]));
+
+			const groupStage: Record<string, unknown> = { _id: groupId };
+			for (const field of sumFields) {
+				groupStage[`sum_${field}`] = { $sum: `$${field}` };
+			}
+			for (const field of avgFields) {
+				groupStage[`avg_${field}`] = { $avg: `$${field}` };
+			}
+			pipeline.push({ $group: groupStage });
+
+			const tableRefs = params.refs.get(params.table as string) ?? new Map();
+			const populateKeys = toKeyList(args.populate) ?? [];
+			for (const key of populateKeys) {
+				if (!groupKeys.includes(key)) continue;
+				const target = tableRefs.get(key);
+				if (!target) continue;
+				const useRootId = groupKeys.length === 1 && groupKeys[0] === key;
+				const localField = useRootId ? "_id" : `_id.${key}`;
+				pipeline.push({
+					$lookup: {
+						from: target,
+						localField,
+						foreignField: "_id",
+						as: key,
+					},
+				});
+				pipeline.push({
+					$unwind: {
+						path: `$${key}`,
+						preserveNullAndEmptyArrays: true,
+					},
+				});
+			}
+
+			const results = await coll.aggregate(pipeline as any).toArray();
+			return results.map((doc) => stringifyAggregateValue(doc)) as any;
+		},
 	};
 }

package/server/database/populate.ts

@@ -7,11 +7,18 @@ export async function applyPopulate(params: {
 	docs: Array<Record<string, unknown>>;
 	currentTable: string;
 	populateKeys: string[];
+	aggregate?: Record<
+		string,
+		{ count?: boolean; sum?: string[]; avg?: string[] }
+	>;
+	includeDocs?: Record<string, boolean>;
 	selectedKeys: string[] | undefined;
 	refs: SchemaRefMap;
 	getCollection: (table: string) => Collection<Document>;
 }) {
 	const tableRefs = params.refs.get(params.currentTable) ?? new Map();
+	const aggregateConfig = params.aggregate ?? {};
+	const includeDocsConfig = params.includeDocs ?? {};
 
 	const ensureStringId = (val: unknown): string | null => {
 		if (!val) return null;
@@ -60,10 +67,53 @@ export async function applyPopulate(params: {
 		return byId;
 	};
 
+	const computeAggregates = (
+		value: unknown,
+		spec: { count?: boolean; sum?: string[]; avg?: string[] }
+	): Record<string, number> | null => {
+		const items = Array.isArray(value)
+			? value
+			: value === undefined || value === null
+				? []
+				: [value];
+
+		const out: Record<string, number> = {};
+		const numericSum = (field: string) => {
+			let total = 0;
+			let found = 0;
+			for (const item of items) {
+				if (!item || typeof item !== "object") continue;
+				const raw = (item as Record<string, unknown>)[field];
+				if (typeof raw === "number" || typeof raw === "bigint") {
+					total += Number(raw);
+					found += 1;
+				}
+			}
+			return { total, found };
+		};
+
+		if (spec.count) out.count = items.length;
+
+		for (const field of spec.sum ?? []) {
+			const { total, found } = numericSum(String(field));
+			if (found > 0) out[`sum_${String(field)}`] = total;
+		}
+
+		for (const field of spec.avg ?? []) {
+			const { total, found } = numericSum(String(field));
+			if (found > 0) out[`avg_${String(field)}`] = total / found;
+		}
+
+		return Object.keys(out).length ? out : null;
+	};
+
 	for (const key of params.populateKeys) {
 		const forwardTarget = tableRefs.get(key);
 		const backwardCandidates = reverseRefs.get(params.currentTable) ?? [];
 		const backward = backwardCandidates.find((c) => c.table === key);
+		const includeDocs = includeDocsConfig[key] ?? true;
+		let valueById: Map<string, Record<string, unknown>[]> | undefined;
+		let handled = false;
 
 		// Prefer forward populate via $lookup when the table carries the ref.
 		if (forwardTarget) {
@@ -94,33 +144,37 @@ export async function applyPopulate(params: {
 					.toArray()) as Array<Record<string, unknown>>;
 
 				const byId = buildLookupMap(populated);
-
-				for (const doc of params.docs) {
-					const docId = ensureStringId(doc._id);
-					if (!docId) continue;
-					const populatedDocs = byId.get(docId) ?? [];
-					const currentValue = doc[key];
-
-					if (Array.isArray(currentValue)) {
-						const byRelId = new Map<string, Record<string, unknown>>();
-						for (const rel of populatedDocs) {
-							const relId = ensureStringId(rel._id);
-							if (relId) byRelId.set(relId, rel);
+				valueById = byId;
+				handled = true;
+
+				if (includeDocs) {
+					for (const doc of params.docs) {
+						const docId = ensureStringId(doc._id);
+						if (!docId) continue;
+						const populatedDocs = byId.get(docId) ?? [];
+						const currentValue = doc[key];
+
+						if (Array.isArray(currentValue)) {
+							const byRelId = new Map<string, Record<string, unknown>>();
+							for (const rel of populatedDocs) {
+								const relId = ensureStringId(rel._id);
+								if (relId) byRelId.set(relId, rel);
+							}
+							doc[key] = currentValue
+								.map((v) => {
+									const relId = ensureStringId(v);
+									return relId ? (byRelId.get(relId) ?? null) : null;
+								})
+								.filter((v): v is Record<string, unknown> => Boolean(v));
+							continue;
 						}
-						doc[key] = currentValue
-							.map((v) => {
-								const relId = ensureStringId(v);
-								return relId ? (byRelId.get(relId) ?? null) : null;
-							})
-							.filter((v): v is Record<string, unknown> => Boolean(v));
-						continue;
-					}
 
-					const relId = ensureStringId(currentValue);
-					doc[key] = relId
-						? (populatedDocs.find((v) => ensureStringId(v._id) === relId) ??
-							currentValue)
-						: (populatedDocs[0] ?? currentValue);
+						const relId = ensureStringId(currentValue);
+						doc[key] = relId
+							? (populatedDocs.find((v) => ensureStringId(v._id) === relId) ??
+								currentValue)
+							: (populatedDocs[0] ?? currentValue);
+					}
 				}
 
 				continue;
@@ -144,16 +198,36 @@ export async function applyPopulate(params: {
 				},
 				{ $project: { _id: 1, __pop: 1 } },
 			];
-
 			const populated = (await coll
 				.aggregate(pipeline as any)
 				.toArray()) as Array<Record<string, unknown>>;
+			if (!handled && backward) {
+				const grouped = buildLookupMap(populated);
+				valueById = grouped;
+
+				if (includeDocs) {
+					for (const doc of params.docs) {
+						const id = ensureStringId(doc._id);
+						if (!id) continue;
+						doc[key] = grouped.get(id) ?? [];
+					}
+				}
+			}
+		}
 
-			const grouped = buildLookupMap(populated);
+		const aggregateSpec = aggregateConfig[key];
+		if (aggregateSpec) {
 			for (const doc of params.docs) {
-				const id = ensureStringId(doc._id);
-				if (!id) continue;
-				doc[key] = grouped.get(id) ?? [];
+				const docId = ensureStringId(doc._id);
+				if (!docId) continue;
+				const aggregateSource = valueById?.get(docId) ?? doc[key];
+				const aggregated = computeAggregates(aggregateSource, aggregateSpec);
+				if (!aggregated) continue;
+				const existing = (doc as any)._aggregates as
+					| Record<string, unknown>
+					| undefined;
+				const target = existing ?? ((doc as any)._aggregates = {});
+				target[key] = aggregated;
 			}
 		}
 	}

package/server/database/query-builder.ts

@@ -19,6 +19,41 @@ export function createQueryBuilder<
 	let offset: number | undefined;
 	let selectedKeys: string[] | undefined;
 	let populateKeys: string[] = [];
+	let populateAggregates: Record<
+		string,
+		{
+			count?: boolean;
+			sum?: string[];
+			avg?: string[];
+		}
+	> = {};
+	let populateIncludeDocs: Record<string, boolean> = {};
+
+	const normalizeAggregate = (
+		value: unknown
+	): { count?: boolean; sum?: string[]; avg?: string[] } | undefined => {
+		if (!value || typeof value !== "object") return undefined;
+		const spec = value as Record<string, unknown>;
+		const out: { count?: boolean; sum?: string[]; avg?: string[] } = {};
+		if (spec.count) out.count = true;
+		if (Array.isArray(spec.sum)) out.sum = spec.sum.map((k) => String(k));
+		if (Array.isArray(spec.avg)) out.avg = spec.avg.map((k) => String(k));
+		return Object.keys(out).length ? out : undefined;
+	};
+
+	const addPopulateKey = (
+		key: string,
+		opts?: {
+			aggregate?: { count?: boolean; sum?: string[]; avg?: string[] };
+			includeDocs?: boolean;
+		}
+	) => {
+		const ks = String(key);
+		if (!populateKeys.includes(ks)) populateKeys.push(ks);
+		if (opts?.aggregate) populateAggregates[ks] = opts.aggregate;
+		if (opts?.includeDocs !== undefined)
+			populateIncludeDocs[ks] = opts.includeDocs;
+	};
 
 	const api: MongoDbQuery<any, any, any> = {
 		where(next) {
@@ -50,11 +85,28 @@ export function createQueryBuilder<
 			return api;
 		},
 		populate(arg: any) {
-			const keys = Array.isArray(arg) ? arg : [arg];
-			for (const k of keys) {
-				const ks = String(k);
-				if (!populateKeys.includes(ks)) populateKeys.push(ks);
+			if (Array.isArray(arg)) {
+				for (const k of arg) addPopulateKey(k as any);
+				return api;
 			}
+
+			if (arg && typeof arg === "object") {
+				for (const [key, value] of Object.entries(
+					arg as Record<string, unknown>
+				)) {
+					if (!value) continue;
+					const includeObj =
+						typeof value === "object" && !Array.isArray(value)
+							? (value as Record<string, unknown>)
+							: undefined;
+					const aggregate = normalizeAggregate(includeObj?.aggregate);
+					const includeDocs = includeObj?.includeDocs;
+					addPopulateKey(key, { aggregate, includeDocs });
+				}
+				return api;
+			}
+
+			if (arg !== undefined) addPopulateKey(arg as any);
 			return api;
 		},
 		async find() {
@@ -80,6 +132,8 @@ export function createQueryBuilder<
 					docs,
 					currentTable: params.table as string,
 					populateKeys,
+					aggregate: populateAggregates,
+					includeDocs: populateIncludeDocs,
 					selectedKeys,
 					refs: params.refs,
 					getCollection: params.getCollection,

package/server/types/types.ts

@@ -35,12 +35,87 @@ export type AppflareSelect<TDoc> =
 	| ReadonlyArray<Keys<TDoc>>
 	| Partial<Record<Keys<TDoc>, boolean>>;
 
+type PopulatedDocForKey<
+	TDoc,
+	TTableDocMap extends Record<string, TableDocBase>,
+	TKey extends Keys<TDoc>,
+> =
+	NonNil<PopulateValue<TDoc[TKey], TTableDocMap>> extends Array<infer TItem>
+		? NonNil<TItem>
+		: NonNil<PopulateValue<TDoc[TKey], TTableDocMap>>;
+
+type AggregateSpec<TDoc> = {
+	count?: boolean;
+	sum?: ReadonlyArray<NumericKeys<TDoc>>;
+	avg?: ReadonlyArray<NumericKeys<TDoc>>;
+};
+
+type AggregateSpecForKey<
+	TDoc,
+	TTableDocMap extends Record<string, TableDocBase>,
+	TKey extends Keys<TDoc>,
+> = AggregateSpec<PopulatedDocForKey<TDoc, TTableDocMap, TKey>>;
+
+type AppflareIncludeRecord<
+	TDoc,
+	TTableDocMap extends Record<string, TableDocBase>,
+> = {
+	[K in PopulatableKeys<TDoc, TTableDocMap>]?:
+		| boolean
+		| {
+				aggregate?: AggregateSpecForKey<TDoc, TTableDocMap, K>;
+				includeDocs?: boolean;
+		  };
+};
+
 export type AppflareInclude<
 	TDoc,
 	TTableDocMap extends Record<string, TableDocBase>,
 > =
 	| ReadonlyArray<PopulatableKeys<TDoc, TTableDocMap>>
-	| Partial<Record<PopulatableKeys<TDoc, TTableDocMap>, boolean>>;
+	| AppflareIncludeRecord<TDoc, TTableDocMap>;
+
+type ExtractAggregateSpec<T> = T extends { aggregate?: infer TSpec }
+	? TSpec
+	: never;
+
+type AggregateResultFromSpec<TDoc, TSpec> = (TSpec extends { count: true }
+	? { count: number }
+	: {}) &
+	(TSpec extends { sum: infer TSum }
+		? TSum extends ReadonlyArray<infer K>
+			? { [P in Extract<K, NumericKeys<TDoc>> as `sum_${P}`]: number }
+			: {}
+		: {}) &
+	(TSpec extends { avg: infer TAvg }
+		? TAvg extends ReadonlyArray<infer K>
+			? { [P in Extract<K, NumericKeys<TDoc>> as `avg_${P}`]: number }
+			: {}
+		: {});
+
+type AggregateMapForInclude<
+	TDoc,
+	TTableDocMap extends Record<string, TableDocBase>,
+	TInclude,
+> =
+	TInclude extends ReadonlyArray<any>
+		? {}
+		: {
+				[K in keyof TInclude as ExtractAggregateSpec<TInclude[K]> extends never
+					? never
+					: K]: AggregateResultFromSpec<
+					PopulatedDocForKey<TDoc, TTableDocMap, Extract<K, Keys<TDoc>>>,
+					ExtractAggregateSpec<TInclude[K]>
+				>;
+			};
+
+type WithAggregatesForInclude<
+	TDoc,
+	TTableDocMap extends Record<string, TableDocBase>,
+	TInclude,
+> = keyof AggregateMapForInclude<TDoc, TTableDocMap, TInclude> extends never
+	? {}
+	: { _aggregates: AggregateMapForInclude<TDoc, TTableDocMap, TInclude> };
 
 export type AppflareResultDoc<
 	TDoc,
@@ -54,7 +129,8 @@ export type AppflareResultDoc<
 		TTableDocMap
 	>,
 	SelectedKeys<TDoc, TSelect>
->;
+> &
+	WithAggregatesForInclude<TDoc, TTableDocMap, TInclude>;
 
 export type SortDirection = "asc" | "desc";
 
@@ -78,6 +154,11 @@ export type ExtractIdTableName<T> =
 			? ExtractIdTableName<TItem>
 			: never;
 
+export type NumericKeys<T> = {
+	[K in keyof T]: NonNil<T[K]> extends number | bigint ? K : never;
+}[keyof T] &
+	string;
+
 export type PopulateValue<
 	T,
 	TTableDocMap extends Record<string, TableDocBase>,
@@ -166,6 +247,18 @@ export type MongoDbQuery<
 		TTableDocMap,
 		WithPopulatedMany<TResultDoc, TKeys[number], TTableDocMap>
 	>;
+	populate<TInclude extends AppflareInclude<TResultDoc, TTableDocMap>>(
+		include: TInclude
+	): MongoDbQuery<
+		TableName,
+		TTableDocMap,
+		WithPopulatedMany<
+			TResultDoc,
+			IncludedKeys<TResultDoc, TInclude, TTableDocMap>,
+			TTableDocMap
+		> &
+			WithAggregatesForInclude<TResultDoc, TTableDocMap, TInclude>
+	>;
 
 	find(): Promise<Array<TResultDoc>>;
 	findOne(): Promise<TResultDoc | null>;
@@ -310,6 +403,59 @@ export type AppflareCountArgs<
 	where?: QueryWhere<TTableDocMap[TableName]>;
 };
 
+type AggregateGroupInput<TDoc> =
+	| ReadonlyArray<keyof TDoc & string>
+	| (keyof TDoc & string);
+
+type NormalizeGroupInput<TDoc, TGroup> = TGroup extends readonly (infer K)[]
+	? ReadonlyArray<Extract<K, keyof TDoc & string>>
+	: TGroup extends string
+		? ReadonlyArray<Extract<TGroup, keyof TDoc & string>>
+		: ReadonlyArray<never>;
+
+type AggregateId<
+	TDoc,
+	TGroup extends ReadonlyArray<keyof TDoc & string>,
+> = TGroup extends readonly []
+	? null
+	: TGroup extends readonly [infer K]
+		? TDoc[Extract<K, keyof TDoc>]
+		: { [K in TGroup[number]]: TDoc[K] };
+
+type AggregateResult<
+	TDoc,
+	TGroup extends ReadonlyArray<keyof TDoc & string>,
+	TSum extends ReadonlyArray<NumericKeys<TDoc>>,
+	TAvg extends ReadonlyArray<NumericKeys<TDoc>>,
+> = {
+	_id: AggregateId<TDoc, TGroup>;
+} & (TSum[number] extends never
+	? {}
+	: { [K in TSum[number] as `sum_${K}`]: number }) &
+	(TAvg[number] extends never
+		? {}
+		: { [K in TAvg[number] as `avg_${K}`]: number });
+
+export type AppflareAggregateArgs<
+	TableName extends string,
+	TTableDocMap extends Record<TableName, TableDocBase>,
+	TGroup = AggregateGroupInput<TTableDocMap[TableName]>,
+	TSum extends ReadonlyArray<NumericKeys<TTableDocMap[TableName]>> =
+		ReadonlyArray<NumericKeys<TTableDocMap[TableName]>>,
+	TAvg extends ReadonlyArray<NumericKeys<TTableDocMap[TableName]>> =
+		ReadonlyArray<NumericKeys<TTableDocMap[TableName]>>,
+> = {
+	where?: QueryWhere<TTableDocMap[TableName]>;
+	groupBy?: TGroup;
+	sum?: TSum;
+	avg?: TAvg;
+	/**
+	 * Populate aggregated group keys that are references to other tables.
+	 * Only keys present in groupBy are eligible for populate.
+	 */
+	populate?: AppflareInclude<TTableDocMap[TableName], TTableDocMap>;
+};
+
 export type AppflareTableClient<
 	TableName extends string,
 	TTableDocMap extends Record<TableName, TableDocBase>,
@@ -394,6 +540,24 @@ export type AppflareTableClient<
 		args?: AppflareDeleteManyArgs<TableName, TTableDocMap>
 	): Promise<{ count: number }>;
 	count(args?: AppflareCountArgs<TableName, TTableDocMap>): Promise<number>;
+	aggregate<
+		TGroup = AggregateGroupInput<TTableDocMap[TableName]>,
+		TSum extends ReadonlyArray<NumericKeys<TTableDocMap[TableName]>> =
+			ReadonlyArray<NumericKeys<TTableDocMap[TableName]>>,
+		TAvg extends ReadonlyArray<NumericKeys<TTableDocMap[TableName]>> =
+			ReadonlyArray<NumericKeys<TTableDocMap[TableName]>>,
+	>(
+		args: AppflareAggregateArgs<TableName, TTableDocMap, TGroup, TSum, TAvg>
+	): Promise<
+		Array<
+			AggregateResult<
+				TTableDocMap[TableName],
+				NormalizeGroupInput<TTableDocMap[TableName], TGroup>,
+				TSum,
+				TAvg
+			>
+		>
+	>;
 };
 
 export type AppflareModelMap<