appflare 0.0.13 → 0.0.14

package/cli/core/build.ts

@@ -5,6 +5,7 @@ import {
 	AppflareConfig,
 	assertDirExists,
 	assertFileExists,
+	toImportPathFromGeneratedSrc,
 } from "../utils/utils";
 import { getSchemaTableNames, generateSchemaTypes } from "../schema/schema";
 import {
@@ -38,6 +39,17 @@ export 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,
@@ -140,17 +152,18 @@ 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/core/index.ts

@@ -14,12 +14,20 @@ import {
 } from "./handlers";
 import { generateSchemaTypes, getSchemaTableNames } from "../schema/schema";
 import { runTscEmit, writeEmitTsconfig } from "../utils/tsc";
-import { assertDirExists, assertFileExists } from "../utils/utils";
+import {
+	assertDirExists,
+	assertFileExists,
+	toImportPathFromGeneratedSrc,
+} from "../utils/utils";
 
 type AppflareConfig = {
 	dir: string;
 	schema: string;
 	outDir: string;
+	auth?: {
+		enabled?: boolean;
+		basePath?: string;
+	};
 };
 
 const program = new Command();
@@ -106,6 +114,16 @@ async function buildFromConfig(params: {
 	await fs.mkdir(path.join(outDirAbs, "src"), { recursive: true });
 	await fs.mkdir(path.join(outDirAbs, "server"), { recursive: true });
 
+	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/generators/generate-api-client/index.ts

@@ -369,6 +369,15 @@ export async function runInternalQuery<
 	args: HandlerArgsFromShape<TArgs>
 ): Promise<TResult> {
 	const parsed = parseHandlerArgs(handler as any, args as any);
+	if (handler.middleware) {
+		const middlewareResult = await handler.middleware(
+			ctx as any,
+			parsed as any
+		);
+		if (typeof middlewareResult !== "undefined") {
+			return middlewareResult as TResult;
+		}
+	}
 	return handler.handler(ctx as any, parsed as any);
 }
 
@@ -381,6 +390,15 @@ export async function runInternalMutation<
 	args: HandlerArgsFromShape<TArgs>
 ): Promise<TResult> {
 	const parsed = parseHandlerArgs(handler as any, args as any);
+	if (handler.middleware) {
+		const middlewareResult = await handler.middleware(
+			ctx as any,
+			parsed as any
+		);
+		if (typeof middlewareResult !== "undefined") {
+			return middlewareResult as TResult;
+		}
+	}
 	return handler.handler(ctx as any, parsed as any);
 }
 

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,

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

@@ -16,7 +16,15 @@ export function buildRouteLines(params: {
 				`\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` +
@@ -37,7 +45,15 @@ export function buildRouteLines(params: {
 				`\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` +

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-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
@@ -147,9 +151,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 +612,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 +666,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/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;
 }

package/lib/values.ts

@@ -12,12 +12,13 @@ export const v = {
 		z
 			.string()
 			.regex(/^[a-f\d]{24}$/i, "Invalid ObjectId")
-			.describe(`ref:${table}`),
-	array: (item: z.ZodTypeAny) => z.array(item),
+			.describe(`ref:${table}`) as z.ZodString,
+	array: <T extends z.ZodTypeAny>(item: T) => z.array(item),
 	object: (shape: Record<string, z.ZodTypeAny>) => z.object(shape),
-	optional: (schema: z.ZodTypeAny) => schema.optional(),
-	nullable: (schema: z.ZodTypeAny) => schema.nullable(),
-	union: (...schemas: z.ZodTypeAny[]) => z.union(schemas),
+	optional: <T extends z.ZodTypeAny>(schema: T) => schema.optional(),
+	nullable: <T extends z.ZodTypeAny>(schema: T) => schema.nullable(),
+	union: <T extends [z.ZodTypeAny, ...z.ZodTypeAny[]]>(...schemas: T) =>
+		z.union(schemas),
 	literal: (value: any) => z.literal(value),
 	buffer: () => z.string(), // or z.instanceof(Buffer) if using Buffer
 	any: () => z.any(),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "appflare",
-	"version": "0.0.13",
+	"version": "0.0.14",
 	"bin": {
 		"appflare": "./cli/index.ts"
 	},

package/server/database/context.ts

@@ -260,11 +260,13 @@ function createAppflareTableClient<
 
 			const normalizedWhere = args.where
 				? normalizeIdFilter(
-						normalizeRefFields(
-							params.table as string,
-							args.where as Record<string, unknown>,
-							params.refs
-						) as any
+						toMongoFilter(
+							normalizeRefFields(
+								params.table as string,
+								args.where as Record<string, unknown>,
+								params.refs
+							) as any
+						)
 					)
 				: undefined;
 			if (normalizedWhere && Object.keys(normalizedWhere).length > 0) {

package/server/database/query-builder.ts

@@ -1,6 +1,10 @@
 import type { Collection, Document, Filter, FindOptions, Sort } from "mongodb";
 import { applyPopulate } from "./populate";
-import { normalizeIdFilter, stringifyIdField } from "../utils/id-utils";
+import {
+	normalizeIdFilter,
+	stringifyIdField,
+	toMongoFilter,
+} from "../utils/id-utils";
 import type { MongoDbQuery, SchemaRefMap } from "../types/types";
 import { buildProjection, normalizeSort } from "./query-utils";
 
@@ -57,7 +61,9 @@ export function createQueryBuilder<
 
 	const api: MongoDbQuery<any, any, any> = {
 		where(next) {
-			const nextFilter = next as unknown as Filter<Document>;
+			const nextFilter = normalizeIdFilter(
+				toMongoFilter(next as unknown as Filter<Document>)
+			);
 			if (!filter) {
 				filter = nextFilter;
 			} else {

package/server/storage/auth.ts

@@ -4,11 +4,13 @@ import type {
 	StorageRule,
 } from "./types";
 
-const allowAnonymous: () => StorageAuthResult = () => ({ allow: true });
+const allowAnonymous = <Principal>(): StorageAuthResult<Principal> => ({
+	allow: true,
+});
 
 export async function authorizeRequest<Env, Principal>(
 	ctx: StorageBaseContext<Env, Principal>,
 	rule: StorageRule<Env, Principal>
 ): Promise<StorageAuthResult<Principal>> {
-	return rule.authorize ? rule.authorize(ctx) : allowAnonymous();
+	return rule.authorize ? rule.authorize(ctx) : allowAnonymous<Principal>();
 }

package/server/types/types.ts

@@ -140,7 +140,57 @@ export type QuerySort<TKey extends string> =
 	| Record<string, SortDirection>
 	| Array<[string, SortDirection]>;
 
-export type QueryWhere<TDoc extends Record<string, unknown>> = Partial<TDoc> &
+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<TDoc extends Record<string, unknown>> = {
+	$and?: ReadonlyArray<QueryWhere<TDoc>>;
+	and?: ReadonlyArray<QueryWhere<TDoc>>;
+	$or?: ReadonlyArray<QueryWhere<TDoc>>;
+	or?: ReadonlyArray<QueryWhere<TDoc>>;
+	$nor?: ReadonlyArray<QueryWhere<TDoc>>;
+	nor?: ReadonlyArray<QueryWhere<TDoc>>;
+	$not?: QueryWhere<TDoc>;
+	not?: QueryWhere<TDoc>;
+};
+
+export type QueryWhere<TDoc extends Record<string, unknown>> = Partial<{
+	[K in keyof TDoc]?: QueryWhereField<TDoc[K]>;
+}> &
+	LogicalWhere<TDoc> &
 	Record<string, unknown>;
 
 export type Keys<T> = keyof T;

package/server/utils/id-utils.ts

@@ -14,6 +14,104 @@ function ensureObjectId(value: string | ObjectId): ObjectId {
 	return new ObjectId(value);
 }
 
+const OPERATOR_ALIAS_MAP: Record<string, string> = {
+	eq: "$eq",
+	ne: "$ne",
+	gt: "$gt",
+	gte: "$gte",
+	lt: "$lt",
+	lte: "$lte",
+	in: "$in",
+	nin: "$nin",
+	regex: "$regex",
+	exists: "$exists",
+};
+
+const LOGICAL_ALIAS_MAP: Record<string, string> = {
+	and: "$and",
+	or: "$or",
+	nor: "$nor",
+	not: "$not",
+};
+
+type NormalizedRegex =
+	| { $regex: string | RegExp; $options?: string }
+	| RegExp
+	| string;
+
+function normalizeRegexOperand(value: unknown): NormalizedRegex | undefined {
+	if (value instanceof RegExp) return value;
+	if (typeof value === "string") return value;
+	if (value && typeof value === "object") {
+		const obj = value as Record<string, unknown>;
+		const pattern = obj.pattern ?? obj.regex ?? obj.$regex;
+		const options = obj.options ?? obj.$options;
+		if (pattern instanceof RegExp) return pattern;
+		if (typeof pattern === "string") {
+			const normalized: { $regex: string; $options?: string } = {
+				$regex: pattern,
+			};
+			if (typeof options === "string" && options.length > 0) {
+				normalized.$options = options;
+			}
+			return normalized;
+		}
+	}
+	return undefined;
+}
+
+function normalizeWhereOperators(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(normalizeWhereOperators);
+	if (value instanceof RegExp || value instanceof Date) return value;
+	if (value && typeof value === "object") {
+		const obj = value as Record<string, unknown>;
+		const out: Record<string, unknown> = {};
+		for (const [key, val] of Object.entries(obj)) {
+			const logicalKey = LOGICAL_ALIAS_MAP[key];
+			if (logicalKey) {
+				const normalizedLogical = Array.isArray(val)
+					? (val as unknown[]).map(normalizeWhereOperators)
+					: normalizeWhereOperators(val);
+				out[logicalKey] = normalizedLogical;
+				continue;
+			}
+
+			if (key.startsWith("$")) {
+				out[key] = normalizeWhereOperators(val);
+				continue;
+			}
+
+			const opKey = OPERATOR_ALIAS_MAP[key];
+			if (opKey) {
+				if (opKey === "$regex") {
+					const normalizedRegex = normalizeRegexOperand(val);
+					if (normalizedRegex === undefined) continue;
+					if (
+						normalizedRegex &&
+						typeof normalizedRegex === "object" &&
+						!Array.isArray(normalizedRegex) &&
+						!(normalizedRegex instanceof RegExp)
+					) {
+						out.$regex = normalizedRegex.$regex;
+						if (normalizedRegex.$options) {
+							out.$options = normalizedRegex.$options;
+						}
+					} else {
+						out[opKey] = normalizeWhereOperators(normalizedRegex);
+					}
+					continue;
+				}
+				out[opKey] = normalizeWhereOperators(val);
+				continue;
+			}
+
+			out[key] = normalizeWhereOperators(val);
+		}
+		return out;
+	}
+	return value;
+}
+
 export function toMongoFilter(
 	where: Id<any> | QueryWhere<any>
 ): Filter<Document> {
@@ -21,7 +119,8 @@ export function toMongoFilter(
 		return { _id: ensureObjectId(where) } satisfies Filter<Document> as any;
 	}
 	if (where && typeof where === "object") {
-		return where as Filter<Document>;
+		const normalized = normalizeWhereOperators(where);
+		return normalized as Filter<Document>;
 	}
 	throw new Error("update/delete requires an id or where filter object");
 }