appflare 0.0.13 → 0.0.15

package/cli/generators/generate-hono-server/imports.ts

@@ -1,3 +1,4 @@
+import path from "node:path";
 import {
 	DiscoveredHandler,
 	groupBy,
@@ -18,9 +19,10 @@ export function buildImportSection(params: {
 	schemaPathAbs: string;
 	configPathAbs: string;
 }): ImportSection {
+	const generatedSchemaAbs = path.join(params.outDirAbs, "src", "schema.ts");
 	const schemaImportPath = toImportPathFromGeneratedServer(
 		params.outDirAbs,
-		params.schemaPathAbs
+		generatedSchemaAbs
 	);
 	const configImportPath = toImportPathFromGeneratedServer(
 		params.outDirAbs,
@@ -28,7 +30,7 @@ export function buildImportSection(params: {
 	);
 	const configImportLine = `import appflareConfig from ${JSON.stringify(configImportPath)};`;
 	const localNameFor = (handler: DiscoveredHandler): string =>
-		`__appflare_${pascalCase(handler.fileName)}_${handler.name}`;
+		`__appflare_${pascalCase(handler.routePath)}_${handler.name}`;
 	const grouped = groupBy(params.handlers, (handler) => handler.sourceFileAbs);
 	const handlerImports: string[] = [];
 	for (const [fileAbs, list] of Array.from(grouped.entries())) {

package/cli/generators/generate-hono-server/routes.ts

@@ -10,13 +10,21 @@ export function buildRouteLines(params: {
 		const local = params.localNameFor(query);
 		routeLines.push(
 			`app.get(\n` +
-				`\t${JSON.stringify(`/queries/${query.fileName}/${query.name}`)},\n` +
+				`	${JSON.stringify(`/queries/${query.routePath}/${query.name}`)},\n` +
 				`\tsValidator("query", z.object(${local}.args as any)),\n` +
 				`\tasync (c) => {\n` +
 				`\t\ttry {\n` +
 				`\t\t\tconst query = c.req.valid("query");\n` +
 				`\t\t\tconst ctx = await resolveContext(c);\n` +
-				`\t\t\tconst result = await ${local}.handler(ctx as any, query as any);\n` +
+				`\t\t\tconst result = await runHandlerWithMiddleware(\n` +
+				`\t\t\t\t${local} as any,\n` +
+				`\t\t\t\tctx as any,\n` +
+				`\t\t\t\tquery as any\n` +
+				`\t\t\t);\n` +
+				`\t\t\tif (isHandlerError(result)) {\n` +
+				`\t\t\t\tconst { status, body } = formatHandlerError(result);\n` +
+				`\t\t\t\treturn c.json(body as any, status);\n` +
+				`\t\t\t}\n` +
 				`\t\t\treturn c.json(result, 200);\n` +
 				`\t\t} catch (err) {\n` +
 				`\t\t\tconst { status, body } = formatHandlerError(err);\n` +
@@ -31,18 +39,26 @@ export function buildRouteLines(params: {
 		const local = params.localNameFor(mutation);
 		routeLines.push(
 			`app.post(\n` +
-				`\t${JSON.stringify(`/mutations/${mutation.fileName}/${mutation.name}`)},\n` +
+				`\t${JSON.stringify(`/mutations/${mutation.routePath}/${mutation.name}`)},\n` +
 				`\tsValidator("json", z.object(${local}.args as any)),\n` +
 				`\tasync (c) => {\n` +
 				`\t\ttry {\n` +
 				`\t\t\tconst body = c.req.valid("json");\n` +
 				`\t\t\tconst ctx = await resolveContext(c);\n` +
-				`\t\t\tconst result = await ${local}.handler(ctx as any, body as any);\n` +
+				`\t\t\tconst result = await runHandlerWithMiddleware(\n` +
+				`\t\t\t\t${local} as any,\n` +
+				`\t\t\t\tctx as any,\n` +
+				`\t\t\t\tbody as any\n` +
+				`\t\t\t);\n` +
+				`\t\t\tif (isHandlerError(result)) {\n` +
+				`\t\t\t\tconst { status, body } = formatHandlerError(result);\n` +
+				`\t\t\t\treturn c.json(body as any, status);\n` +
+				`\t\t\t}\n` +
 				`\t\t\tif (notifyMutation) {\n` +
 				`\t\t\t\ttry {\n` +
 				`\t\t\t\t\tawait notifyMutation({\n` +
 				`\t\t\t\t\t table: normalizeTableName(${JSON.stringify(mutation.fileName)}),\n` +
-				`\t\t\t\t\t handler: { file: ${JSON.stringify(mutation.fileName)}, name: ${JSON.stringify(mutation.name)} },\n` +
+				`\t\t\t\t\t handler: { file: ${JSON.stringify(mutation.routePath)}, name: ${JSON.stringify(mutation.name)} },\n` +
 				`\t\t\t\t\t args: body,\n` +
 				`\t\t\t\t\t result,\n` +
 				`\t\t\t\t});\n` +

package/cli/generators/generate-hono-server/template.ts

@@ -50,8 +50,74 @@ export type AppflareDbContext = MongoDbContext<TableNames, TableDocMap>;
 export type AppflareServerContext = AppflareAuthContext & {
 	db: AppflareDbContext;
 	scheduler?: Scheduler;
+	error: AppflareErrorFactory;
 };
 
+export type AppflareHandlerError = Error & {
+	status: number;
+	details?: unknown;
+	__appflareHandlerError: true;
+};
+
+export type AppflareErrorFactory = (
+	status: number,
+	message?: string,
+	details?: unknown
+) => AppflareHandlerError;
+
+const createHandlerError: AppflareErrorFactory = (
+	status,
+	message,
+	details
+) => {
+	const err = new Error(message ?? \`HTTP \${status}\`);
+	err.name = "AppflareHandlerError";
+	const typed = err as AppflareHandlerError;
+	typed.status = status;
+	typed.details = details;
+	typed.__appflareHandlerError = true;
+	return typed;
+};
+
+const isHandlerError = (value: unknown): value is AppflareHandlerError =>
+	!!value &&
+	typeof value === "object" &&
+	(value as any).__appflareHandlerError === true &&
+	Number.isFinite((value as any).status);
+
+const handlerErrorBody = (
+	err: AppflareHandlerError
+): { error: string; details?: unknown } => {
+	const includeDetails =
+		err.details !== undefined &&
+		(err.details && typeof err.details === "object"
+			? !(err.details instanceof Error) && !Array.isArray(err.details)
+			: true);
+	return includeDetails
+		? { error: err.message, details: err.details }
+		: { error: err.message };
+};
+
+async function runHandlerWithMiddleware<TArgs, TResult>(
+	handler: {
+		handler: (ctx: AppflareServerContext, args: TArgs) => Promise<TResult>;
+		middleware?: (
+			ctx: AppflareServerContext,
+			args: TArgs
+		) => Promise<TResult | void>;
+	},
+	ctx: AppflareServerContext,
+	args: TArgs
+): Promise<TResult> {
+	if (handler.middleware) {
+		const middlewareResult = await handler.middleware(ctx, args);
+		if (typeof middlewareResult !== "undefined") {
+			return middlewareResult as TResult;
+		}
+	}
+	return handler.handler(ctx, args);
+}
+
 export function createAppflareDbContext(params: {
 \tdb: import("mongodb").Db;
 \tcollectionName?: (table: TableNames) => string;
@@ -105,7 +171,8 @@ export type AppflareHonoServerOptions = {
 		c: HonoContext,
 		db: AppflareDbContext,
 		auth: AppflareAuthContext,
-		scheduler?: Scheduler
+		scheduler?: Scheduler,
+		error?: AppflareErrorFactory
 	) => AppflareServerContext | Promise<AppflareServerContext>;
 \tcollectionName?: (table: TableNames) => string;
 \tcorsOrigin?: string | string[];
@@ -135,6 +202,9 @@ function formatHandlerError(err: unknown): {
 \tstatus: number;
 \tbody: { error: string; details?: unknown };
 } {
+	if (isHandlerError(err)) {
+		return { status: err.status, body: handlerErrorBody(err) };
+	}
 \tconst statusCandidate =
 \t\ttypeof err === "object" && err !== null
 \t\t\t? Number((err as any).status ?? (err as any).statusCode)
@@ -192,8 +262,13 @@ export function createAppflareHonoServer(options: AppflareHonoServerOptions): Ho
 
 	const createContext =
 		options.createContext ??
-		((_c, db, auth, scheduler) =>
-			({ db, scheduler, ...auth } as AppflareServerContext));
+		((_c, db, auth, scheduler, error) =>
+			({
+				db,
+				scheduler,
+				error: error ?? createHandlerError,
+				...auth,
+			} as AppflareServerContext));
 \tconst notifyMutation = createMutationNotifier(options.realtime);
 \tconst app = new Hono();
 \tapp.use(
@@ -250,8 +325,17 @@ ${params.authSetupBlock}${params.authMountBlock}${params.authResolverBlock}\tcon
 		const db = await resolveDb(c);
 		const auth = await resolveAuthContext(c);
 		const scheduler = await resolveScheduler(c);
-		const ctx = await createContext(c, db, auth, scheduler);
-		return ctx ?? ({ db, scheduler, ...auth } as AppflareServerContext);
+		const error = createHandlerError;
+		const ctx = await createContext(c, db, auth, scheduler, error);
+		const merged = {
+			db,
+			scheduler,
+			error,
+			...auth,
+			...(ctx ?? {}),
+			error: (ctx as any)?.error ?? error,
+		};
+		return merged as AppflareServerContext;
 	};
 
 \t${params.routeLines.join("\n\n\t")}

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

@@ -9,10 +9,10 @@ export const buildHandlerEntries = (params: {
 	return params.handlers
 		.map((handler) => {
 			const local = params.localNameFor(handler);
-			const task = `${handler.fileName}/${handler.name}`;
+			const task = `${handler.routePath}/${handler.name}`;
 			return (
 				`\t${JSON.stringify(task)}: {\n` +
-				`\t\tfile: ${JSON.stringify(handler.fileName)},\n` +
+				`	\tfile: ${JSON.stringify(handler.routePath)},\n` +
 				`\t\tname: ${JSON.stringify(handler.name)},\n` +
 				`\t\trun: ${local}.handler,\n` +
 				`\t},`

package/cli/generators/generate-websocket-durable-object/imports.ts

@@ -28,7 +28,7 @@ export function buildImportSection(params: {
 	);
 
 	const localNameFor = (handler: DiscoveredHandler): string =>
-		`__appflare_${pascalCase(handler.fileName)}_${handler.name}`;
+		`__appflare_${pascalCase(handler.routePath)}_${handler.name}`;
 
 	const grouped = groupBy(params.queries, (handler) => handler.sourceFileAbs);
 	const handlerImports: string[] = [];

package/cli/generators/generate-websocket-durable-object/query-handlers.ts

@@ -7,12 +7,12 @@ export function buildQueryHandlerEntries(params: {
 	return params.queries
 		.slice()
 		.sort((a, b) => {
-			if (a.fileName === b.fileName) return a.name.localeCompare(b.name);
-			return a.fileName.localeCompare(b.fileName);
+			if (a.routePath === b.routePath) return a.name.localeCompare(b.name);
+			return a.routePath.localeCompare(b.routePath);
 		})
 		.map(
 			(query) =>
-				`\t${JSON.stringify(`${query.fileName}/${query.name}`)}: { file: ${JSON.stringify(query.fileName)}, name: ${JSON.stringify(query.name)}, definition: ${params.localNameFor(query)} },`
+				`	${JSON.stringify(`${query.routePath}/${query.name}`)}: { file: ${JSON.stringify(query.routePath)}, name: ${JSON.stringify(query.name)}, definition: ${params.localNameFor(query)} },`
 		)
 		.join("\n");
 }

package/cli/generators/generate-websocket-durable-object/template.ts

@@ -107,6 +107,10 @@ type QueryArgsParser = { parse?: (value: unknown) => unknown };
 
 type QueryHandlerDefinition = {
 \targs?: QueryArgsParser | unknown;
+	middleware?: (
+		ctx: import("./server").AppflareServerContext,
+		args: unknown
+	) => unknown | Promise<unknown>;
 \thandler: (
 \t\tctx: import("./server").AppflareServerContext,
 \t\targs: unknown
@@ -133,10 +137,17 @@ const defaultHandlerForTable = (
 \t\tpossible.push(tableStr.slice(0, -1));
 \t}
 \tfor (const candidate of possible) {
-\t\tconst key = candidate + "/get" + pascalCase(candidate);
-\t\tif (key in queryHandlers) {
-\t\t\treturn { file: candidate, name: "get" + pascalCase(candidate) };
-\t\t}
+		const handlerName = "get" + pascalCase(candidate);
+		const suffix = "/" + handlerName;
+		const matchKey = Object.keys(queryHandlers).find((key) => {
+			if (!key.endsWith(suffix)) return false;
+			const segments = key.split("/");
+			return segments.length >= 2 && segments[segments.length - 2] === candidate;
+		});
+		if (matchKey) {
+			const file = matchKey.slice(0, matchKey.length - suffix.length);
+			return { file, name: handlerName };
+		}
 \t}
 \treturn null;
 };
@@ -147,9 +158,77 @@ const resolveDatabase = (env: any) => {
 \treturn db;
 };
 
+type AppflareHandlerError = Error & {
+	status: number;
+	details?: unknown;
+	__appflareHandlerError: true;
+};
+
+type AppflareErrorFactory = (
+	status: number,
+	message?: string,
+	details?: unknown
+) => AppflareHandlerError;
+
+const createHandlerError: AppflareErrorFactory = (
+	status,
+	message,
+	details
+) => {
+	const err = new Error(message ?? \`HTTP \${status}\`);
+	err.name = "AppflareHandlerError";
+	const typed = err as AppflareHandlerError;
+	typed.status = status;
+	typed.details = details;
+	typed.__appflareHandlerError = true;
+	return typed;
+};
+
+const isHandlerError = (value: unknown): value is AppflareHandlerError =>
+	!!value &&
+	typeof value === "object" &&
+	(value as any).__appflareHandlerError === true &&
+	Number.isFinite((value as any).status);
+
+const handlerErrorBody = (
+	err: AppflareHandlerError
+): { error: string; details?: unknown } => {
+	const includeDetails =
+		err.details !== undefined &&
+		(err.details && typeof err.details === "object"
+			? !(err.details instanceof Error) && !Array.isArray(err.details)
+			: true);
+	return includeDetails
+		? { error: err.message, details: err.details }
+		: { error: err.message };
+};
+
+async function runHandlerWithMiddleware<TArgs, TResult>(
+	handler: {
+		handler: (ctx: AppflareServerContext, args: TArgs) => Promise<TResult> | TResult;
+		middleware?: (
+			ctx: AppflareServerContext,
+			args: TArgs
+		) => Promise<TResult | void> | TResult | void;
+	},
+	ctx: AppflareServerContext,
+	args: TArgs
+): Promise<TResult> {
+	if (handler.middleware) {
+		const middlewareResult = await handler.middleware(ctx, args);
+		if (typeof middlewareResult !== "undefined") {
+			return middlewareResult as TResult;
+		}
+	}
+	return handler.handler(ctx, args) as Promise<TResult>;
+}
+
 const formatHandlerError = (
 \terr: unknown
 ): { error: string; details?: unknown } => {
+	if (isHandlerError(err)) {
+		return handlerErrorBody(err);
+	}
 \tconst message =
 \t\terr instanceof Error
 \t\t\t? err.message
@@ -540,30 +619,38 @@ export class WebSocketHibernationServer extends DurableObject {
 \t\treturn true;
 \t}
 
-\tprivate async fetchData(sub: Subscription): Promise<unknown> {
-\t\tconst subWithAuth = await this.withAuth(sub);
-\t\tconst query = resolveQueryHandler(subWithAuth.handler);
-\t\tif (query) {
-\t\t\tconst ctx = this.createHandlerContext(subWithAuth.auth);
-\t\t\tconst parsedArgs = this.parseHandlerArgs(query, subWithAuth.where);
-\t\t\treturn await query.handler(ctx, parsedArgs);
-\t\t}
-
-\t\tconst db = this.getDb();
-\t\tconst table = db[subWithAuth.table] as any;
-\t\tif (!table || typeof table.findMany !== "function") {
-\t\t\tthrow new Error("Unknown table: " + subWithAuth.table);
-\t\t}
-\t\tconst data = await table.findMany({
-\t\t\twhere: subWithAuth.where as any,
-\t\t\torderBy: subWithAuth.orderBy as any,
-\t\t\tskip: subWithAuth.skip,
-\t\t\ttake: subWithAuth.take,
-\t\t\tselect: subWithAuth.select as any,
-\t\t\tinclude: subWithAuth.include as any,
-\t\t});
-\t\treturn data ?? [];
-\t}
+	private async fetchData(sub: Subscription): Promise<unknown> {
+		const subWithAuth = await this.withAuth(sub);
+		const query = resolveQueryHandler(subWithAuth.handler);
+		if (query) {
+			const ctx = this.createHandlerContext(subWithAuth.auth);
+			const parsedArgs = this.parseHandlerArgs(query, subWithAuth.where);
+			const result = await runHandlerWithMiddleware(
+				query,
+				ctx,
+				parsedArgs as any
+			);
+			if (isHandlerError(result)) {
+				throw result;
+			}
+			return result;
+		}
+
+		const db = this.getDb();
+		const table = db[subWithAuth.table] as any;
+		if (!table || typeof table.findMany !== "function") {
+			throw new Error("Unknown table: " + subWithAuth.table);
+		}
+		const data = await table.findMany({
+			where: subWithAuth.where as any,
+			orderBy: subWithAuth.orderBy as any,
+			skip: subWithAuth.skip,
+			take: subWithAuth.take,
+			select: subWithAuth.select as any,
+			include: subWithAuth.include as any,
+		});
+		return data ?? [];
+	}
 
 \tprivate parseHandlerArgs(
 \t\tquery: QueryHandlerDefinition,
@@ -586,7 +673,8 @@ export class WebSocketHibernationServer extends DurableObject {
 \t\treturn {
 \t\t\tdb: this.getDb(),
 \t\t\tsession: auth?.session ?? null,
-\t\t\tuser: auth?.user ?? null,
+			user: auth?.user ?? null,
+			error: createHandlerError,
 \t\t} as AppflareServerContext;
 \t}
 

package/cli/index.ts

@@ -24,6 +24,7 @@ import {
 	AppflareConfig,
 	assertDirExists,
 	assertFileExists,
+	toImportPathFromGeneratedSrc,
 } from "./utils/utils";
 
 type WatchConfig = {
@@ -139,6 +140,17 @@ async function buildFromConfig(params: {
 	await fs.mkdir(path.join(outDirAbs, "src"), { recursive: true });
 	await fs.mkdir(path.join(outDirAbs, "server"), { recursive: true });
 
+	// Re-export the user schema inside the generated output so downstream code can import it from the build directory.
+	const schemaImportPathForGeneratedSrc = toImportPathFromGeneratedSrc(
+		outDirAbs,
+		schemaPathAbs
+	);
+	const schemaReexport = `import schema from ${JSON.stringify(schemaImportPathForGeneratedSrc)};
+export type AppflareGeneratedSchema = typeof schema;
+export default schema;
+`;
+	await fs.writeFile(path.join(outDirAbs, "src", "schema.ts"), schemaReexport);
+
 	const schemaTypesTs = await generateSchemaTypes({
 		schemaPathAbs,
 		configPathAbs,

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

@@ -44,9 +44,60 @@ type WithSelected<TDoc, TKeys extends Keys<TDoc>> = Pick<TDoc, TKeys>;
 
 export type SortDirection = "asc" | "desc";
 
+type Comparable<T> = NonNil<T> extends number | bigint | Date ? NonNil<T> : never;
+
+type RegexOperand<T> = NonNil<T> extends string
+	? string | RegExp | { pattern: string; options?: string }
+	: never;
+
+type ArrayOperand<T> = ReadonlyArray<NonNil<T>>;
+
+type QueryWhereField<T> =
+	| NonNil<T>
+	| {
+			eq?: NonNil<T>;
+			$eq?: NonNil<T>;
+			ne?: NonNil<T>;
+			$ne?: NonNil<T>;
+			in?: ArrayOperand<T>;
+			$in?: ArrayOperand<T>;
+			nin?: ArrayOperand<T>;
+			$nin?: ArrayOperand<T>;
+			gt?: Comparable<T>;
+			$gt?: Comparable<T>;
+			gte?: Comparable<T>;
+			$gte?: Comparable<T>;
+			lt?: Comparable<T>;
+			$lt?: Comparable<T>;
+			lte?: Comparable<T>;
+			$lte?: Comparable<T>;
+			exists?: boolean;
+			$exists?: boolean;
+			regex?: RegexOperand<T>;
+			$regex?: RegexOperand<T>;
+			$options?: string;
+	  };
+
+type LogicalWhere<TableName extends TableNames> = {
+	$and?: ReadonlyArray<QueryWhere<TableName>>;
+	and?: ReadonlyArray<QueryWhere<TableName>>;
+	$or?: ReadonlyArray<QueryWhere<TableName>>;
+	or?: ReadonlyArray<QueryWhere<TableName>>;
+	$nor?: ReadonlyArray<QueryWhere<TableName>>;
+	nor?: ReadonlyArray<QueryWhere<TableName>>;
+	$not?: QueryWhere<TableName>;
+	not?: QueryWhere<TableName>;
+};
+
 export type QueryWhere<TableName extends TableNames> = Partial<
-	TableDocMap[TableName]
-> & Record<string, unknown>;
+	{
+		[K in keyof TableDocMap[TableName]]?: QueryWhereField<
+			TableDocMap[TableName][K]
+		>;
+	}
+> &
+	LogicalWhere<TableName> &
+	Record<string, unknown>;
 
 export type QuerySortKey<TableName extends TableNames> = keyof TableDocMap[TableName] &
 	string;
@@ -71,7 +122,7 @@ const GEO_EARTH_RADIUS_METERS = 6_378_100;
 const __geoNormalizePoint = (point: GeoPointInput): GeoPoint =>
 	Array.isArray(point)
 		? { type: "Point", coordinates: [point[0], point[1]] }
-		: point;
+		: (point as GeoPoint);
 
 export const geo = {
 	point(lng: number, lat: number): GeoPoint {
@@ -509,9 +560,22 @@ export const cron = <Env = unknown>(
 	definition: CronDefinition<Env>
 ): CronDefinition<Env> => definition;
 
+export type AppflareHandlerError = Error & {
+	status: number;
+	details?: unknown;
+	__appflareHandlerError: true;
+};
+
+export type AppflareErrorFactory = (
+	status: number,
+	message?: string,
+	details?: unknown
+) => AppflareHandlerError;
+
 export interface QueryContext extends AppflareAuthContext {
 	db: DatabaseReader;
 	scheduler?: Scheduler;
+	error: AppflareErrorFactory;
 }
 
 export interface InternalQueryContext {
@@ -530,6 +594,10 @@ export type InferQueryArgs<TArgs extends QueryArgsShape> = {
 
 export interface QueryDefinition<TArgs extends QueryArgsShape, TResult> {
 	args: TArgs;
+	middleware?: (
+		ctx: QueryContext,
+		args: InferQueryArgs<TArgs>
+	) => Promise<TResult | void>;
 	handler: (ctx: QueryContext, args: InferQueryArgs<TArgs>) => Promise<TResult>;
 }
 
@@ -547,10 +615,15 @@ export interface DatabaseWriter extends DatabaseReader {}
 export interface MutationContext extends AppflareAuthContext {
 	db: DatabaseWriter;
 	scheduler?: Scheduler;
+	error: AppflareErrorFactory;
 }
 
 export interface MutationDefinition<TArgs extends QueryArgsShape, TResult> {
 	args: TArgs;
+	middleware?: (
+		ctx: MutationContext,
+		args: InferQueryArgs<TArgs>
+	) => Promise<TResult | void>;
 	handler: (
 		ctx: MutationContext,
 		args: InferQueryArgs<TArgs>
@@ -571,6 +644,10 @@ export interface InternalQueryDefinition<
 	TResult,
 > {
 	args: TArgs;
+	middleware?: (
+		ctx: InternalQueryContext,
+		args: InferQueryArgs<TArgs>
+	) => Promise<TResult | void>;
 	handler: (
 		ctx: InternalQueryContext,
 		args: InferQueryArgs<TArgs>
@@ -586,6 +663,10 @@ export interface InternalMutationDefinition<
 	TResult,
 > {
 	args: TArgs;
+	middleware?: (
+		ctx: InternalMutationContext,
+		args: InferQueryArgs<TArgs>
+	) => Promise<TResult | void>;
 	handler: (
 		ctx: InternalMutationContext,
 		args: InferQueryArgs<TArgs>

package/cli/utils/tsc.ts

@@ -34,17 +34,18 @@ export async function writeEmitTsconfig(params: {
 			declaration: true,
 			emitDeclarationOnly: false,
 			outDir: `./${outDirRel}/dist`,
-			rootDir: `./${outDirRel}/src`,
+			rootDir: `.`,
 			sourceMap: false,
 			declarationMap: false,
 			skipLibCheck: true,
 			target: "ES2022",
 			module: "ES2022",
 			moduleResolution: "Bundler",
-			types: [],
+			types: ["node"],
 		},
 		include: [
 			`./${outDirRel}/src/schema-types.ts`,
+			`./${outDirRel}/src/schema.ts`,
 			`./${outDirRel}/src/handlers/**/*`,
 		],
 	};

package/cli/utils/utils.ts

@@ -52,6 +52,8 @@ export type HandlerKind =
 
 export type DiscoveredHandler = {
 	fileName: string;
+	/** Path relative to project root without .ts extension, using forward slashes. */
+	routePath: string;
 	name: string;
 	kind: HandlerKind;
 	sourceFileAbs: string;

package/cli/utils/zod-utils.ts

@@ -63,8 +63,8 @@ function renderType(schema: any): { tsType: string; optional: boolean } {
 		const description: string | undefined =
 			schema?.description ?? def?.description;
 		if (typeof description === "string" && description.startsWith("ref:")) {
-			const table = description.slice("ref:".length);
-			return { tsType: `Id<${JSON.stringify(table)}>`, optional: false };
+			// Treat reference fields as plain strings in generated types for friendlier typing/UX.
+			return { tsType: "string", optional: false };
 		}
 		return { tsType: "string", optional: false };
 	}

package/lib/db.ts

@@ -1,9 +1,19 @@
 import { z } from "zod";
 
-export function defineTable(shape: Record<string, z.ZodTypeAny>) {
+export type AppflareTable<TShape extends Record<string, z.ZodTypeAny>> =
+	z.ZodObject<TShape>;
+
+export type AppflareSchema<TTables extends Record<string, AppflareTable<any>>> =
+	TTables;
+
+export function defineTable<TShape extends Record<string, z.ZodTypeAny>>(
+	shape: TShape
+): AppflareTable<TShape> {
 	return z.object(shape);
 }
 
-export function defineSchema(tables: Record<string, z.ZodTypeAny>) {
+export function defineSchema<
+	TTables extends Record<string, AppflareTable<any>>,
+>(tables: TTables): AppflareSchema<TTables> {
 	return tables;
 }