appflare 0.1.12 → 0.2.0

package/Documentation.md

@@ -0,0 +1,735 @@
+# Appflare Documentation
+
+This guide explains how to build backend handlers, run schema and database migrations, and consume your generated Appflare client in frontend apps (both plain TypeScript/JavaScript and React).
+
+All examples are aligned with the current workspace structure and APIs.
+
+---
+
+## 1) How Appflare works (high level)
+
+Appflare follows a generate-first workflow:
+
+1. You write backend schema and handlers in your backend package.
+2. You run the Appflare CLI.
+3. Appflare generates runtime artifacts under your backend out directory (for example `_generated`).
+4. Frontend imports the generated client and calls typed query/mutation routes.
+
+In this workspace, the backend uses:
+
+- `packages/backend/appflare.config.ts`
+- `packages/backend/schema.ts`
+- `packages/backend/src/**` for handlers
+- Generated output in `packages/backend/_generated/**`
+
+---
+
+## 2) Required backend files
+
+### 2.1 Appflare config
+
+Your main config is `packages/backend/appflare.config.ts`.
+
+Important fields:
+
+- `scanDir`: where handlers are discovered (currently `./src`)
+- `outDir`: where generated artifacts are written (currently `./_generated`)
+- `schemaDsl.entry`: schema entry file (currently `./schema.ts`)
+- `schema`: schema files used by drizzle generation
+- `database`, `kv`, `r2`, `auth`, `scheduler`: runtime binding and feature configuration
+- `wranglerOverrides`: final Worker deployment settings
+
+### 2.2 Schema
+
+Schema is defined with `schema`, `table`, and `v` from Appflare.
+
+Example source: `packages/backend/schema.ts`.
+
+---
+
+## 3) How to create handlers
+
+Handlers are created with generated helpers:
+
+- `query(...)` for read endpoints
+- `mutation(...)` for write endpoints
+
+Import them from your generated handlers module:
+
+```ts
+import { query, mutation } from "../_generated/handlers";
+```
+
+### 3.1 Query handler example
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const getUserProfile = query({
+	args: {
+		userId: z.string(),
+	},
+	handler: async (ctx, args) => {
+		const user = await ctx.db.users.findFirst({
+			where: { id: args.userId },
+		});
+
+		if (!user) {
+			ctx.error(404, "User not found", { userId: args.userId });
+		}
+
+		return user;
+	},
+});
+```
+
+### 3.1.1 More query examples (basic to advanced)
+
+#### A) Search + relation include + limit
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const searchPosts = query({
+	args: {
+		search: z.string().optional(),
+		ownerId: z.string().optional(),
+		limit: z.number().int().min(1).max(100).default(25),
+	},
+	handler: async (ctx, args) => {
+		return ctx.db.posts.findMany({
+			where: {
+				title: {
+					regex: args.search ?? "",
+					$options: "i",
+				},
+				...(args.ownerId ? { ownerId: args.ownerId } : {}),
+			},
+			with: {
+				owner: true,
+				comments: true,
+			},
+			limit: args.limit,
+		});
+	},
+});
+```
+
+#### B) Cursor/pagination-style query
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const listPostsPage = query({
+	args: {
+		cursor: z.number().int().optional(),
+		pageSize: z.number().int().min(1).max(50).default(20),
+	},
+	handler: async (ctx, args) => {
+		const rows = await ctx.db.posts.findMany({
+			where: args.cursor
+				? {
+						id: {
+							gt: args.cursor,
+						},
+					}
+				: {},
+			limit: args.pageSize,
+			with: {
+				owner: true,
+			},
+		});
+
+		const nextCursor = rows.length > 0 ? rows[rows.length - 1]?.id : undefined;
+
+		return {
+			rows,
+			nextCursor,
+			hasMore: rows.length === args.pageSize,
+		};
+	},
+});
+```
+
+#### C) Aggregate-heavy query (`count`, `avg`, relation path)
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const getPostStats = query({
+	args: {
+		ownerId: z.string().optional(),
+	},
+	handler: async (ctx, args) => {
+		const totalPosts = await ctx.db.posts.count({
+			where: args.ownerId ? { ownerId: args.ownerId } : {},
+		});
+
+		const uniqueOwners = await ctx.db.posts.count({
+			field: "ownerId",
+			distinct: true,
+		});
+
+		const averagePostId = await ctx.db.posts.avg({
+			field: "id",
+		});
+
+		const averageCommentId = await ctx.db.posts.avg({
+			field: "comments.id",
+			with: {
+				comments: {
+					where: {
+						id: {
+							gte: 10000,
+						},
+					},
+				},
+			},
+		});
+
+		return {
+			totalPosts,
+			uniqueOwners,
+			averagePostId,
+			averageCommentId,
+		};
+	},
+});
+```
+
+#### D) Geo query (`geoWithin`) + filter composition
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const nearbyPlaygroundItems = query({
+	args: {
+		latitude: z.number(),
+		longitude: z.number(),
+		radiusMeters: z.number().positive().default(5000),
+	},
+	handler: async (ctx, args) => {
+		const rows = await ctx.db.queryPlayground.findMany({
+			where: {
+				geoWithin: {
+					$geometry: {
+						latitude: args.latitude,
+						longitude: args.longitude,
+					},
+					latitudeField: "latitude",
+					longitudeField: "longitude",
+					$gte: 0,
+					$lt: args.radiusMeters,
+				},
+				isActive: {
+					eq: true,
+				},
+			},
+			limit: 100,
+		});
+
+		return {
+			count: rows.length,
+			rows,
+		};
+	},
+});
+```
+
+#### E) Complex production-style query (similar to `db-features`)
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const queryDashboardData = query({
+	args: {
+		userId: z.string().optional(),
+		search: z.string().optional(),
+	},
+	handler: async (ctx, args) => {
+		const posts = await ctx.db.posts.findMany({
+			where: {
+				ownerId: args.userId,
+				title: {
+					regex: args.search ?? "test",
+					$options: "i",
+				},
+				id: { gt: 0 },
+			},
+			with: {
+				comments: true,
+				owner: true,
+			},
+			limit: 25,
+		});
+
+		const postsWithCommentStats = await ctx.db.posts.findMany({
+			with: {
+				comments: {
+					_count: true,
+					_avg: { id: true },
+				},
+			},
+			limit: 10,
+		});
+
+		const postsTotal = await ctx.db.posts.count({
+			where: { id: { $gte: 1 } },
+		});
+
+		return {
+			posts,
+			postsTotal,
+			postsWithCommentStats,
+		};
+	},
+});
+```
+
+### 3.1.2 Query design tips for complex handlers
+
+- Keep args schema strict (defaults, min/max, optional fields).
+- Return stable shapes (avoid switching response shape by condition).
+- Start with one root query and compose aggregates/relations progressively.
+- Prefer server-side filtering in `where` instead of filtering on frontend.
+- For heavy queries, add `limit`, cursor args, and response metadata (`nextCursor`, `hasMore`).
+
+### 3.2 Mutation handler example
+
+```ts
+import { mutation } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const createPost = mutation({
+	args: {
+		title: z.string().min(1),
+		slug: z.string().min(1),
+	},
+	handler: async (ctx, args) => {
+		const inserted = await ctx.db.posts.insert({
+			values: {
+				title: args.title,
+				slug: args.slug,
+				ownerId: "some-user-id",
+			},
+		});
+
+		return { created: inserted.length };
+	},
+});
+```
+
+### 3.3 Handler file placement
+
+Put handlers under `packages/backend/src` (including nested directories). Example patterns already used in this repo:
+
+- `packages/backend/src/test.ts`
+- `packages/backend/src/queries/db-features.ts`
+- `packages/backend/src/mutations/db-features.ts`
+- `packages/backend/src/bun/test.ts`
+
+Generated client route names follow directory + file + export naming. For example:
+
+- query from `src/test.ts` export `getTest` becomes `appflare.queries.test.getTest`
+- mutation from `src/mutations/db-features.ts` export `testMutationFeatures` becomes `appflare.mutations["db-features"].testMutationFeatures`
+
+### 3.4 Context utilities available in handlers
+
+Inside handlers, you commonly use:
+
+- `ctx.db.<table>.findMany/findFirst/insert/update/upsert/delete`
+- aggregate helpers like `count` and `avg`
+- `ctx.error(status, message, details)` for typed failures
+
+See real examples in:
+
+- `packages/backend/src/queries/db-features.ts`
+- `packages/backend/src/mutations/db-features.ts`
+
+---
+
+## 4) Generate artifacts
+
+From backend package:
+
+```bash
+cd packages/backend
+bun ../appflare/cli dev
+```
+
+Or via scripts in `packages/backend/package.json`:
+
+```bash
+bun run build
+```
+
+What gets generated (core set):
+
+- `_generated/server.ts`
+- `_generated/client.ts`
+- `_generated/auth.config.ts`
+- `_generated/drizzle.config.ts`
+- `_generated/handlers.ts`
+- `_generated/handlers.context.ts`
+- `_generated/handlers.execution.ts`
+- `_generated/handlers.routes.ts`
+- `_generated/client/**`
+
+### Watch mode
+
+To regenerate on file changes:
+
+```bash
+cd packages/backend
+bun ../appflare/cli dev --watch
+```
+
+---
+
+## 5) How to migrate database schema
+
+Appflare migration flow wraps two steps:
+
+1. Generate drizzle migrations
+2. Apply to D1 via Wrangler
+
+### 5.1 Standard migrate
+
+```bash
+cd packages/backend
+bun ../appflare/cli migrate
+```
+
+Or script:
+
+```bash
+bun run migrate
+```
+
+### 5.2 Choose target environment
+
+Use exactly one of these flags:
+
+- `--local`
+- `--remote`
+- `--preview`
+
+Examples:
+
+```bash
+bun ../appflare/cli migrate --local
+bun ../appflare/cli migrate --remote
+bun ../appflare/cli migrate --preview
+```
+
+### 5.3 Typical change workflow
+
+1. Update `schema.ts`.
+2. Regenerate artifacts:
+   - `bun ../appflare/cli dev`
+3. Run migration:
+   - `bun ../appflare/cli migrate --local` (or remote/preview)
+4. Verify app behavior in `wrangler dev`.
+
+---
+
+## 6) Frontend usage (plain TypeScript/JavaScript)
+
+Use the generated backend client directly.
+
+### 6.1 Create client instance
+
+```ts
+import { Appflare } from "appflare-backend/_generated/client";
+
+const appflare = new Appflare({
+	endpoint: "http://127.0.0.1:8787",
+	wsEndpoint: "ws://127.0.0.1:8787",
+	onGetAuthToken: async () => localStorage.getItem("appflare-auth-token") ?? "",
+	onSetAuthToken: async (token) => {
+		localStorage.setItem("appflare-auth-token", token);
+	},
+});
+```
+
+### 6.2 Run a query
+
+```ts
+const result = await appflare.queries.test.getTest.run({ id: "test" });
+
+if (result.error) {
+	console.error(result.error.status, result.error.message);
+} else {
+	console.log(result.data);
+}
+```
+
+### 6.2.1 More frontend query call examples
+
+#### A) Query with filters
+
+```ts
+const result = await appflare.queries["db-features"].testQueryFeatures.run({
+	search: "test",
+	userId: "as3xNgfPVzrooSuSwn1ZSEKNA92Cjp4V",
+});
+
+if (!result.error) {
+	console.log(result.data.postsCount, result.data.uniqueOwnerCount);
+}
+```
+
+#### B) Query with request options
+
+```ts
+const result = await appflare.queries.test.getTest.run(
+	{ id: "test" },
+	{
+		headers: {
+			"x-trace-id": crypto.randomUUID(),
+		},
+	},
+);
+```
+
+#### C) Query with realtime and explicit auth token
+
+```ts
+const sub = appflare.queries.test.getTest.subscribe({
+	args: { id: "test" },
+	authToken: "token-from-auth-flow",
+	onChange: (data) => {
+		console.log("fresh data", data);
+	},
+});
+
+setTimeout(() => sub.remove(), 30000);
+```
+
+### 6.3 Run a mutation
+
+```ts
+const result = await appflare.mutations.test.newTest.run({});
+
+if (result.error) {
+	console.error(result.error.message);
+} else {
+	console.log(result.data);
+}
+```
+
+### 6.4 Realtime subscribe to a query
+
+```ts
+const sub = appflare.queries.test.getTest.subscribe({
+	args: { id: "test" },
+	onChange: (data, event) => {
+		console.log("update", event.payload.queryName, data);
+	},
+	onError: (error) => {
+		console.error("subscription error", error);
+	},
+});
+
+// later
+sub.remove();
+```
+
+---
+
+## 7) How to use with React
+
+Appflare ships React hooks in `appflare/react`:
+
+- `useQuery`
+- `useInfiniteQuery`
+- `useMutation`
+
+These are thin wrappers around TanStack Query.
+
+### 7.1 Setup requirements
+
+Install peer requirements in your frontend app:
+
+```bash
+bun add @tanstack/react-query react
+```
+
+Wrap app with `QueryClientProvider`.
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function Providers({ children }: { children: React.ReactNode }) {
+	return (
+		<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+	);
+}
+```
+
+### 7.2 React query usage
+
+```tsx
+import { useQuery } from "appflare/react";
+import { appflare } from "./appflare-client";
+
+export function TestScreen() {
+	const query = useQuery(
+		appflare.queries.test.getTest,
+		{ id: "test" },
+		{
+			realtime: { enabled: true },
+		},
+	);
+
+	if (query.isLoading) return <div>Loading...</div>;
+	if (query.error) return <div>{query.error.message}</div>;
+
+	return <pre>{JSON.stringify(query.data, null, 2)}</pre>;
+}
+```
+
+### 7.3 React mutation usage
+
+```tsx
+import { useMutation } from "appflare/react";
+import { appflare } from "./appflare-client";
+
+export function CreatePostButton() {
+	const mutation = useMutation(
+		appflare.mutations.test.newTest,
+		{},
+		{
+			onSuccess: (data) => console.log("created", data),
+		},
+	);
+
+	return (
+		<button onClick={() => mutation.mutate()} disabled={mutation.isPending}>
+			Create
+		</button>
+	);
+}
+```
+
+### 7.4 React infinite query usage
+
+```tsx
+import { useInfiniteQuery } from "appflare/react";
+import { appflare } from "./appflare-client";
+
+const result = useInfiniteQuery(
+	appflare.queries.test.getTest,
+	{ id: "test" },
+	{
+		pageParamToArgs: (baseArgs, page) => ({ ...baseArgs, page }),
+		queryOptions: {
+			initialPageParam: 1,
+			getNextPageParam: (lastPage, pages) => pages.length + 1,
+		},
+	},
+);
+```
+
+### 7.5 Realtime with React hooks
+
+Both `useQuery` and `useInfiniteQuery` support:
+
+```ts
+realtime: {
+	enabled: true,
+	authToken: "optional-token",
+	requestOptions: { headers: { "x-custom": "1" } },
+	onChange: (data, update) => {},
+	onError: (error) => {},
+}
+```
+
+When enabled, hooks subscribe via generated query `.subscribe(...)` and keep query cache updated automatically.
+
+---
+
+## 8) Frontend app helper pattern
+
+A good pattern is to keep one shared client factory in a single file.
+
+Example in this workspace:
+
+- `apps/app/lib/appflare.ts`
+
+This file centralizes:
+
+- endpoint/wsEndpoint selection (web/mobile)
+- token storage and retrieval
+- exported hook wrappers
+
+---
+
+## 9) Common commands cheat sheet
+
+From `packages/backend`:
+
+```bash
+# Generate once
+bun ../appflare/cli build -c appflare.config.ts
+
+# Generate in dev mode
+bun ../appflare/cli dev -c appflare.config.ts
+
+# Generate + watch
+bun ../appflare/cli dev -c appflare.config.ts --watch
+
+# Migrate local D1
+bun ../appflare/cli migrate -c appflare.config.ts --local
+
+# Migrate remote D1
+bun ../appflare/cli migrate -c appflare.config.ts --remote
+```
+
+Or use backend scripts:
+
+```bash
+bun run build
+bun run dev
+bun run migrate
+```
+
+---
+
+## 10) Troubleshooting
+
+### Generated client has missing routes
+
+- Ensure handler file is under `scanDir`.
+- Ensure export uses `query(...)` or `mutation(...)`.
+- Run `bun ../appflare/cli dev` again.
+
+### Realtime not receiving updates
+
+- Ensure query has `.subscribe` in generated client.
+- Ensure `wsEndpoint` is set correctly.
+- Ensure valid auth token is available if your runtime requires auth.
+
+### Migration fails
+
+- Confirm database values in `appflare.config.ts`.
+- Use one environment flag only (`--local`, `--remote`, or `--preview`).
+- Re-run generation before migration if schema changed.
+
+---
+
+## 11) Recommended development loop
+
+1. Edit schema and handlers.
+2. Run generator (`dev` or `dev --watch`).
+3. Run migrations.
+4. Start backend (`wrangler dev`).
+5. Use generated client in frontend and iterate.