appflare 0.0.8 → 0.0.10

package/cli/core/build.ts

@@ -14,6 +14,7 @@ import {
 	generateHonoServer,
 	generateWebsocketDurableObject,
 	generateSchedulerHandlers,
+	generateCronHandlers,
 } from "./handlers";
 
 export async function buildFromConfig(params: {
@@ -100,6 +101,14 @@ export async function buildFromConfig(params: {
 		schedulerTs
 	);
 
+	const { code: cronTs } = generateCronHandlers({
+		handlers,
+		outDirAbs,
+		schemaPathAbs,
+		configPathAbs,
+	});
+	await fs.writeFile(path.join(outDirAbs, "server", "cron.ts"), cronTs);
+
 	if (emit) {
 		// Remove previous emit output to avoid stale files lingering.
 		await fs.rm(path.join(outDirAbs, "dist"), { recursive: true, force: true });

package/cli/core/discover-handlers.ts

@@ -1,5 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import * as ts from "typescript";
 import {
 	DiscoveredHandler,
 	HandlerKind,
@@ -29,15 +30,19 @@ export async function discoverHandlers(params: {
 		if (path.resolve(fileAbs) === path.resolve(params.configPathAbs)) continue;
 
 		const content = await fs.readFile(fileAbs, "utf8");
+		const cronTriggersByHandler = extractCronTriggers(content);
 		const regex =
-			/export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(query|mutation|internalQuery|internalMutation|scheduler)\s*\(/g;
+			/export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(query|mutation|internalQuery|internalMutation|scheduler|cron)\s*\(/g;
 		let match: RegExpExecArray | null;
 		while ((match = regex.exec(content)) !== null) {
+			const kind = match[2] as HandlerKind;
 			handlers.push({
 				fileName: path.basename(fileAbs, ".ts"),
 				name: match[1],
-				kind: match[2] as HandlerKind,
+				kind,
 				sourceFileAbs: fileAbs,
+				cronTriggers:
+					kind === "cron" ? cronTriggersByHandler.get(match[1]) : undefined,
 			});
 		}
 	}
@@ -59,3 +64,70 @@ export async function discoverHandlers(params: {
 
 	return unique;
 }
+
+const cronPropertyNames = new Set(["cronTrigger", "cronTriggers"]);
+
+const isExported = (node: ts.Node): boolean => {
+	return Boolean(
+		ts.canHaveModifiers(node) &&
+		node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+	);
+};
+
+const extractCronTriggers = (sourceText: string): Map<string, string[]> => {
+	const sourceFile = ts.createSourceFile(
+		"cron-handlers.ts",
+		sourceText,
+		ts.ScriptTarget.Latest,
+		true
+	);
+	const triggersByHandler = new Map<string, string[]>();
+
+	const visit = (node: ts.Node): void => {
+		if (ts.isVariableStatement(node) && isExported(node)) {
+			for (const decl of node.declarationList.declarations) {
+				if (!ts.isIdentifier(decl.name)) continue;
+				const initializer = decl.initializer;
+				if (!initializer || !ts.isCallExpression(initializer)) continue;
+				const callee = initializer.expression;
+				if (!ts.isIdentifier(callee) || callee.text !== "cron") continue;
+				const cronTriggers = parseCronTriggerArg(initializer.arguments[0]);
+				if (cronTriggers && cronTriggers.length > 0) {
+					triggersByHandler.set(decl.name.text, cronTriggers);
+				}
+			}
+		}
+		ts.forEachChild(node, visit);
+	};
+
+	visit(sourceFile);
+	return triggersByHandler;
+};
+
+const parseCronTriggerArg = (arg?: ts.Expression): string[] | undefined => {
+	if (!arg || !ts.isObjectLiteralExpression(arg)) return undefined;
+	const cronProp = arg.properties.find((prop) => {
+		if (!ts.isPropertyAssignment(prop)) return false;
+		if (ts.isIdentifier(prop.name))
+			return cronPropertyNames.has(prop.name.text);
+		if (ts.isStringLiteralLike(prop.name))
+			return cronPropertyNames.has(prop.name.text);
+		return false;
+	});
+
+	if (!cronProp || !ts.isPropertyAssignment(cronProp)) return undefined;
+	const value = cronProp.initializer;
+	const triggers: string[] = [];
+	if (ts.isArrayLiteralExpression(value)) {
+		for (const element of value.elements) {
+			if (ts.isStringLiteralLike(element)) {
+				triggers.push(element.text.trim());
+			}
+		}
+	} else if (ts.isStringLiteralLike(value)) {
+		triggers.push(value.text.trim());
+	}
+
+	const unique = Array.from(new Set(triggers.filter(Boolean)));
+	return unique.length > 0 ? unique : undefined;
+};

package/cli/core/handlers.ts

@@ -4,3 +4,4 @@ export { generateApiClient } from "../generators/generate-api-client";
 export { generateHonoServer } from "../generators/generate-hono-server";
 export { generateWebsocketDurableObject } from "../generators/generate-websocket-durable-object";
 export { generateSchedulerHandlers } from "../generators/generate-scheduler-handlers";
+export { generateCronHandlers } from "../generators/generate-cron-handlers";

package/cli/generators/generate-cloudflare-worker/worker.ts

@@ -2,9 +2,16 @@ import { resolveAllowedOrigins } from "./helpers";
 
 export function generateCloudflareWorkerIndex(params: {
 	allowedOrigins?: string[];
+	hasCronHandlers?: boolean;
 }): string {
 	const allowedOrigins = resolveAllowedOrigins(params.allowedOrigins);
 	const allowedOriginsCsv = allowedOrigins.join(",");
+	const cronImports = params.hasCronHandlers
+		? 'import { handleCron } from "./cron";\n'
+		: "";
+	const scheduledBlock = params.hasCronHandlers
+		? `\n\tasync scheduled(controller, env, ctx): Promise<void> {\n\t\tawait handleCron({ controller, env, ctx });\n\t},\n`
+		: "";
 
 	return `/* eslint-disable */
 /**
@@ -15,7 +22,7 @@ export function generateCloudflareWorkerIndex(params: {
 import { createAppflareHonoServer } from "./server";
 import { WebSocketHibernationServer } from "./websocket-hibernation-server";
 import { createScheduler, handleSchedulerBatch } from "./scheduler";
-import { getDatabase } from "cloudflare-do-mongo";
+${cronImports}import { getDatabase } from "cloudflare-do-mongo";
 import { MONGO_DURABLE_OBJECT } from "cloudflare-do-mongo/do";
 import type { Hono } from "hono";
 import { cors } from "hono/cors";
@@ -130,9 +137,10 @@ export default {
 		return response;
 	},
 
-		async queue(batch, env): Promise<void> {
-			await handleSchedulerBatch({ batch, env });
-		},
+${scheduledBlock}
+	async queue(batch, env): Promise<void> {
+		await handleSchedulerBatch({ batch, env });
+	},
 } satisfies ExportedHandler<Env>;
 
 export { MONGO_DURABLE_OBJECT, WebSocketHibernationServer };

package/cli/generators/generate-cloudflare-worker/wrangler.ts

@@ -11,6 +11,7 @@ export function generateWranglerJson(params: {
 	config: AppflareConfig;
 	configDirAbs: string;
 	allowedOrigins?: string[];
+	cronTriggers?: string[];
 }): string {
 	const allowedOrigins = resolveAllowedOrigins(params.allowedOrigins);
 	const bucketBinding =
@@ -82,5 +83,11 @@ export function generateWranglerJson(params: {
 		};
 	}
 
+	if (params.cronTriggers && params.cronTriggers.length > 0) {
+		wrangler.triggers = {
+			crons: Array.from(new Set(params.cronTriggers)),
+		};
+	}
+
 	return `${JSON.stringify(wrangler, null, 2)}\n`;
 }

package/cli/generators/generate-cron-handlers/cron-handlers-block.ts

@@ -0,0 +1,2 @@
+export const buildCronHandlersBlock = (handlerEntries: string): string =>
+	`const cronHandlers = {\n${handlerEntries}\n} as const;`;

package/cli/generators/generate-cron-handlers/handler-entries.ts

@@ -0,0 +1,29 @@
+import type { DiscoveredHandler } from "../../utils/utils";
+
+const stringifyTriggers = (triggers?: string[]): string => {
+	if (!triggers || triggers.length === 0) return "[]";
+	return `[${triggers.map((value) => JSON.stringify(value)).join(", ")}]`;
+};
+
+export const buildCronHandlerEntries = (params: {
+	handlers: DiscoveredHandler[];
+	localNameFor: (handler: DiscoveredHandler) => string;
+}): string => {
+	if (params.handlers.length === 0) return "";
+
+	return params.handlers
+		.map((handler) => {
+			const local = params.localNameFor(handler);
+			const task = `${handler.fileName}/${handler.name}`;
+			const fallbackTriggers = stringifyTriggers(handler.cronTriggers);
+			return (
+				`\t${JSON.stringify(task)}: {\n` +
+				`\t\tfile: ${JSON.stringify(handler.fileName)},\n` +
+				`\t\tname: ${JSON.stringify(handler.name)},\n` +
+				`\t\tcronTrigger: ${local}.cronTrigger ?? ${fallbackTriggers},\n` +
+				`\t\trun: ${local}.handler,\n` +
+				`\t},`
+			);
+		})
+		.join("\n");
+};

package/cli/generators/generate-cron-handlers/index.ts

@@ -0,0 +1,61 @@
+import { buildImportSection } from "../generate-hono-server/imports";
+import type { DiscoveredHandler } from "../../utils/utils";
+import {
+	schemaTypesImportPath,
+	serverImportPath,
+	filePreamble,
+} from "../generate-scheduler-handlers/constants";
+import { buildCronHandlerEntries } from "./handler-entries";
+import { buildCronHandlersBlock } from "./cron-handlers-block";
+import { buildTypeHelpersBlock } from "./type-helpers-block";
+import { buildRuntimeBlock } from "./runtime-block";
+
+export function generateCronHandlers(params: {
+	handlers: DiscoveredHandler[];
+	outDirAbs: string;
+	schemaPathAbs: string;
+	configPathAbs: string;
+}): { code: string; cronTriggers: string[] } {
+	const cronHandlers = params.handlers.filter(
+		(handler) => handler.kind === "cron"
+	);
+
+	const imports = buildImportSection({
+		handlers: cronHandlers,
+		outDirAbs: params.outDirAbs,
+		schemaPathAbs: params.schemaPathAbs,
+		configPathAbs: params.configPathAbs,
+	});
+
+	const handlerImportBlock =
+		imports.handlerImports.length > 0
+			? `${imports.handlerImports.join("\n")}\n\n`
+			: "";
+
+	const handlerEntries = buildCronHandlerEntries({
+		handlers: cronHandlers,
+		localNameFor: imports.localNameFor,
+	});
+
+	const importsBlock = `import { createAppflareDbContext, type AppflareDbContext } from ${JSON.stringify(serverImportPath)};\nimport type {\n\tScheduler,\n\tSchedulerEnqueueOptions,\n\tSchedulerPayload,\n\tSchedulerTaskName,\n\tAppflareAuthContext,\n\tAppflareAuthSession,\n\tAppflareAuthUser,\n} from ${JSON.stringify(schemaTypesImportPath)};\nimport { createScheduler } from "./scheduler";\nimport { getDatabase } from "cloudflare-do-mongo";\nimport { Db } from "mongodb";\n${handlerImportBlock}`;
+
+	const code = [
+		filePreamble,
+		"",
+		importsBlock,
+		buildCronHandlersBlock(handlerEntries),
+		buildTypeHelpersBlock(),
+		buildRuntimeBlock(),
+		"export type { CronTaskName };\n",
+	].join("\n");
+
+	const cronTriggers = Array.from(
+		new Set(
+			cronHandlers
+				.flatMap((handler) => handler.cronTriggers ?? [])
+				.filter((value): value is string => Boolean(value))
+		)
+	);
+
+	return { code, cronTriggers };
+}

package/cli/generators/generate-cron-handlers/runtime-block.ts

@@ -0,0 +1,49 @@
+export const buildRuntimeBlock = (): string => `
+ const normalizeCronTrigger = (value: CronTriggerValue): string[] => {
+ 	if (!value) return [];
+ 	if (typeof value === "string") return [value.trim()].filter(Boolean);
+ 	return value.map((entry) => String(entry).trim()).filter(Boolean);
+ };
+ 
+ export async function handleCron(params: {
+ 	controller: { cron: string };
+ 	env: Env;
+ 	ctx: { waitUntil(promise: Promise<unknown>): void };
+ }): Promise<void> {
+ 	const { controller, env, ctx } = params;
+ 	const db = createAppflareDbContext({
+ 		db: getDatabase(env.MONGO_DB) as unknown as Db,
+ 	});
+ 
+ 	const scheduler = env.APPFLARE_SCHEDULER_QUEUE
+ 		? createScheduler(env.APPFLARE_SCHEDULER_QUEUE)
+ 		: undefined;
+ 
+ 	const baseContext: CronHandlerContext = {
+ 		...emptyAuthContext,
+ 		db,
+ 		env,
+ 		scheduler,
+ 		controller: {
+ 			cron: controller.cron,
+ 			scheduledTime: (controller as { scheduledTime?: number }).scheduledTime,
+ 			nextScheduledTime: (controller as { nextScheduledTime?: number })
+ 				.nextScheduledTime,
+ 		},
+ 		ctx,
+ 	};
+ 
+ 	const handlerLookup = cronHandlers as unknown as CronHandlerLookup;
+ 	const cronValue = controller.cron;
+ 
+ 	for (const [task, handler] of Object.entries(handlerLookup)) {
+ 		const triggers = normalizeCronTrigger(handler.cronTrigger);
+ 		if (!triggers.includes(cronValue)) continue;
+ 		try {
+ 			await handler.run(baseContext);
+ 		} catch (err) {
+ 			console.error("Cron task failed", task, err);
+ 		}
+ 	}
+ }
+ `;

package/cli/generators/generate-cron-handlers/type-helpers-block.ts

@@ -0,0 +1,60 @@
+export const buildTypeHelpersBlock = (): string => `
+ type CronHandlers = typeof cronHandlers;
+ 
+ type CronTaskName = keyof CronHandlers extends never
+ 	? string
+ 	: keyof CronHandlers;
+ 
+ type CronTriggerValue = string | readonly string[] | undefined;
+ 
+ type Env = {
+ 	MONGO_DB: unknown;
+ 	APPFLARE_SCHEDULER_QUEUE?: {
+ 		send: (body: unknown, options?: { delaySeconds?: number }) => Promise<void>;
+ 	};
+ } & Record<string, unknown>;
+ 
+ const emptyAuthContext: AppflareAuthContext = {
+ 	session: null as AppflareAuthSession,
+ 	user: null as AppflareAuthUser,
+ };
+ 
+ type SchedulerEnqueue = {
+ 	<TTask extends SchedulerTaskName>(
+ 		task: TTask,
+ 		...args: SchedulerPayload<TTask> extends undefined
+ 			? [payload?: SchedulerPayload<TTask>, options?: SchedulerEnqueueOptions]
+ 			: [payload: SchedulerPayload<TTask>, options?: SchedulerEnqueueOptions]
+ 	): Promise<void>;
+ };
+ 
+ type TypedScheduler = Omit<Scheduler, "enqueue"> & {
+ 	enqueue: SchedulerEnqueue;
+ };
+ 
+ type ScheduledController = {
+ 	cron: string;
+ 	scheduledTime?: number;
+ 	nextScheduledTime?: number;
+ };
+ 
+ type ExecutionContext = {
+ 	waitUntil(promise: Promise<unknown>): void;
+ };
+ 
+ type CronHandlerContext = AppflareAuthContext & {
+ 	db: AppflareDbContext;
+ 	env: Env;
+ 	scheduler?: TypedScheduler;
+ 	controller: ScheduledController;
+ 	ctx: ExecutionContext;
+ };
+ 
+ type CronHandlerLookup = Record<
+ 	string,
+ 	{
+ 		cronTrigger: CronTriggerValue;
+ 		run: (ctx: CronHandlerContext) => Promise<void>;
+ 	}
+ >;
+ `;

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/index.ts

@@ -12,6 +12,7 @@ import {
 	generateHonoServer,
 	generateWebsocketDurableObject,
 	generateSchedulerHandlers,
+	generateCronHandlers,
 } from "./core/handlers";
 import {
 	generateCloudflareWorkerIndex,
@@ -19,22 +20,11 @@ import {
 } from "./generators/generate-cloudflare-worker";
 import { generateSchemaTypes, getSchemaTableNames } from "./schema/schema";
 import { runTscEmit, writeEmitTsconfig } from "./utils/tsc";
-import { assertDirExists, assertFileExists } from "./utils/utils";
-
-type AppflareConfig = {
-	dir: string;
-	schema: string;
-	outDir: string;
-	/** Optional override for where wrangler.json is written. Resolved relative to the config file. */
-	wranglerOutPath?: string;
-	/** Optional override for wrangler.json main entrypoint. Defaults to ./server/index.ts in the generated worker. */
-	wranglerMain?: string;
-	corsOrigin?: string | string[];
-	auth?: {
-		enabled?: boolean;
-		basePath?: string;
-	};
-};
+import {
+	AppflareConfig,
+	assertDirExists,
+	assertFileExists,
+} from "./utils/utils";
 
 type WatchConfig = {
 	targets: string[];
@@ -212,18 +202,33 @@ async function buildFromConfig(params: {
 		schedulerTs
 	);
 
+	const cronHandlersPresent = handlers.some(
+		(handler) => handler.kind === "cron"
+	);
+	const { code: cronTs, cronTriggers } = generateCronHandlers({
+		handlers,
+		outDirAbs,
+		schemaPathAbs,
+		configPathAbs,
+	});
+	await fs.writeFile(path.join(outDirAbs, "server", "cron.ts"), cronTs);
+
 	const allowedOrigins = normalizeAllowedOrigins(
 		process.env.APPFLARE_ALLOWED_ORIGINS ??
 			config.corsOrigin ??
 			"http://localhost:3000"
 	);
-	const workerIndexTs = generateCloudflareWorkerIndex({ allowedOrigins });
+	const workerIndexTs = generateCloudflareWorkerIndex({
+		allowedOrigins,
+		hasCronHandlers: cronHandlersPresent,
+	});
 	await fs.writeFile(path.join(outDirAbs, "server", "index.ts"), workerIndexTs);
 
 	const wranglerJson = generateWranglerJson({
 		config,
 		configDirAbs,
 		allowedOrigins,
+		cronTriggers,
 	});
 	const wranglerOutPath =
 		config.wranglerOutPath ?? path.join(config.outDir, "wrangler.json");