appflare 0.2.47 → 0.2.48

package/Documentation.md

@@ -1,898 +1,898 @@
-# 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`.
-
-### 2.3 Relation helpers (`v.one`, `v.many`, `v.manyToMany`)
-
-- `v.one("target")` creates a single-reference relation and infers a local FK field.
-- `v.many("target")` is inverse one-to-many and infers an FK on the target table.
-- `v.manyToMany("target")` creates a many-to-many relation by synthesizing a junction table.
-
-Many-to-many example:
-
-```ts
-export const schemas = schema({
-	pets: table({
-		id: v.uuid(),
-		trips: v.manyToMany("trips"),
-	}),
-	trips: table({
-		id: v.uuid(),
-		pets: v.manyToMany("pets"),
-	}),
-});
-```
-
-Default behavior for `v.manyToMany`:
-
-- Generates one deterministic junction table per pair.
-- Junction rows are pure links (two FK columns, no payload columns).
-- Reciprocal declarations must agree on options (`junctionTable`, field names, FK actions), otherwise generation throws a conflict error.
-
----
-
-## 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,
-						},
-					}
-				: {},
-			orderBy: { column: "id", direction: "asc" },
-			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,
-		};
-	},
-});
-```
-
-#### F) Query with `orderBy`
-
-The `orderBy` field accepts an object or array of objects with `column` and optional `direction`:
-
-```ts
-import { query } from "../../_generated/handlers";
-import * as z from "zod";
-
-export const getTopUsers = query({
-	args: {
-		minScore: z.number().optional(),
-		limit: z.number().int().min(1).max(100).default(10),
-	},
-	handler: async (ctx, args) => {
-		return ctx.db.users.findMany({
-			where: args.minScore ? { score: { gte: args.minScore } } : {},
-			orderBy: { column: "score", direction: "desc" },
-			limit: args.limit,
-		});
-	},
-});
-```
-
-Multiple sort keys are supported with an array:
-
-```ts
-orderBy: [
-	{ column: "score", direction: "desc" },
-	{ column: "name", direction: "asc" },
-],
-```
-
-#### G) Array column operators (`includes`, `includesAny`, `length`)
-
-For JSON array columns, use array-specific operators:
-
-```ts
-import { query } from "../../_generated/handlers";
-import * as z from "zod";
-
-export const findProducts = query({
-	args: {
-		color: z.string().optional(),
-		tags: z.array(z.string()).optional(),
-		minTagCount: z.number().int().optional(),
-	},
-	handler: async (ctx, args) => {
-		return ctx.db.products.findMany({
-			where: {
-				...(args.tags ? { tags: { includes: args.tags } } : {}),
-				...(args.minTagCount ? { tags: { length: args.minTagCount } } : {}),
-			},
-		});
-	},
-});
-```
-
-- `includes` — row's array must contain **all** specified values
-- `includesAny` — row's array must contain **at least one** of the specified values
-- `length` — matches the array length exactly
-- `eq` / `ne` — exact match on the whole JSON array
-
-#### H) 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`).
-- Use `orderBy` with cursor-based pagination to ensure deterministic ordering across pages.
-
-### 3.2 Mutation handler examples
-
-#### Insert
-
-```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 };
-	},
-});
-```
-
-#### Upsert
-
-```ts
-import { mutation } from "../../_generated/handlers";
-import * as z from "zod";
-
-export const upsertPost = mutation({
-	args: {
-		slug: z.string().min(1),
-		title: z.string().min(1),
-	},
-	handler: async (ctx, args) => {
-		const result = await ctx.db.posts.upsert({
-			values: {
-				slug: args.slug,
-				title: args.title,
-				ownerId: "some-user-id",
-			},
-			target: "slug",
-			set: { title: args.title },
-		});
-
-		return { updated: result.length };
-	},
-});
-```
-
-- `target` — conflict column(s) to detect existing rows
-- `set` — columns to update on conflict (omit to keep existing values)
-- Supports single or array of values
-
-### 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`
-- `count` supports `where`, `field`, `distinct`, and `with` for filtered relation counts
-- `avg` supports `where`, `field`, `distinct`, and `with` for filtered relation averages
-- `where` supports shorthand operators: `eq`, `ne`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `exists`, `regex`, `$options`, `includes`, `includesAny`, `length`
-- `with` supports `_count` and `_avg` for relation-level aggregate results (returned as `XxxAggregate`)
-- `orderBy` accepts `{ column, direction }` or array thereof
-- `geoWithin` for geospatial distance queries (Haversine formula)
-- `upsert` supports `target` (conflict columns) and `set` (on-conflict update columns)
-- `ctx.error(status, message, details)` for typed failures
-
-#### Updating manyToMany relations
-
-The `update` operation supports managing manyToMany relations via the `set` payload. Each manyToMany relation field accepts an object with `items` and optional `mode`:
-
-```ts
-// Merge mode (default) — adds new links, keeps existing ones
-await ctx.db.family.update({
-  where: { primaryUserId: userId },
-  set: {
-    members: {
-      items: [
-        "existing-user-id",                    // link by ID
-        { id: "another-user-id" },             // link by ID (object form)
-        { name: "New User", email: "..." },    // create new user, then link
-      ],
-      mode: "merge",
-    },
-  },
-});
-
-// Overwrite mode — deletes all existing links, keeps only new ones
-await ctx.db.family.update({
-  where: { primaryUserId: userId },
-  set: {
-    members: {
-      items: ["user-id-1", "user-id-2"],
-      mode: "overwrite",
-    },
-  },
-});
-```
-
-- `items` — array of IDs (string/number) or partial objects. Objects without an `id` field are created in the target table before linking.
-- `mode` — `"merge"` (default) keeps existing links and adds new ones; `"overwrite"` deletes all existing links for the parent record before inserting new ones.
-- All relation updates run inside a transaction when present.
-
-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.js`
-- `_generated/client.js`
-- `_generated/auth.config.js`
-- `_generated/drizzle.config.js`
-- `_generated/handlers.js`
-- `_generated/handlers.context.js`
-- `_generated/handlers.execution.js`
-- `_generated/handlers.routes.js`
-- `_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.
+# 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`.
+
+### 2.3 Relation helpers (`v.one`, `v.many`, `v.manyToMany`)
+
+- `v.one("target")` creates a single-reference relation and infers a local FK field.
+- `v.many("target")` is inverse one-to-many and infers an FK on the target table.
+- `v.manyToMany("target")` creates a many-to-many relation by synthesizing a junction table.
+
+Many-to-many example:
+
+```ts
+export const schemas = schema({
+	pets: table({
+		id: v.uuid(),
+		trips: v.manyToMany("trips"),
+	}),
+	trips: table({
+		id: v.uuid(),
+		pets: v.manyToMany("pets"),
+	}),
+});
+```
+
+Default behavior for `v.manyToMany`:
+
+- Generates one deterministic junction table per pair.
+- Junction rows are pure links (two FK columns, no payload columns).
+- Reciprocal declarations must agree on options (`junctionTable`, field names, FK actions), otherwise generation throws a conflict error.
+
+---
+
+## 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,
+						},
+					}
+				: {},
+			orderBy: { column: "id", direction: "asc" },
+			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,
+		};
+	},
+});
+```
+
+#### F) Query with `orderBy`
+
+The `orderBy` field accepts an object or array of objects with `column` and optional `direction`:
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const getTopUsers = query({
+	args: {
+		minScore: z.number().optional(),
+		limit: z.number().int().min(1).max(100).default(10),
+	},
+	handler: async (ctx, args) => {
+		return ctx.db.users.findMany({
+			where: args.minScore ? { score: { gte: args.minScore } } : {},
+			orderBy: { column: "score", direction: "desc" },
+			limit: args.limit,
+		});
+	},
+});
+```
+
+Multiple sort keys are supported with an array:
+
+```ts
+orderBy: [
+	{ column: "score", direction: "desc" },
+	{ column: "name", direction: "asc" },
+],
+```
+
+#### G) Array column operators (`includes`, `includesAny`, `length`)
+
+For JSON array columns, use array-specific operators:
+
+```ts
+import { query } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const findProducts = query({
+	args: {
+		color: z.string().optional(),
+		tags: z.array(z.string()).optional(),
+		minTagCount: z.number().int().optional(),
+	},
+	handler: async (ctx, args) => {
+		return ctx.db.products.findMany({
+			where: {
+				...(args.tags ? { tags: { includes: args.tags } } : {}),
+				...(args.minTagCount ? { tags: { length: args.minTagCount } } : {}),
+			},
+		});
+	},
+});
+```
+
+- `includes` — row's array must contain **all** specified values
+- `includesAny` — row's array must contain **at least one** of the specified values
+- `length` — matches the array length exactly
+- `eq` / `ne` — exact match on the whole JSON array
+
+#### H) 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`).
+- Use `orderBy` with cursor-based pagination to ensure deterministic ordering across pages.
+
+### 3.2 Mutation handler examples
+
+#### Insert
+
+```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 };
+	},
+});
+```
+
+#### Upsert
+
+```ts
+import { mutation } from "../../_generated/handlers";
+import * as z from "zod";
+
+export const upsertPost = mutation({
+	args: {
+		slug: z.string().min(1),
+		title: z.string().min(1),
+	},
+	handler: async (ctx, args) => {
+		const result = await ctx.db.posts.upsert({
+			values: {
+				slug: args.slug,
+				title: args.title,
+				ownerId: "some-user-id",
+			},
+			target: "slug",
+			set: { title: args.title },
+		});
+
+		return { updated: result.length };
+	},
+});
+```
+
+- `target` — conflict column(s) to detect existing rows
+- `set` — columns to update on conflict (omit to keep existing values)
+- Supports single or array of values
+
+### 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`
+- `count` supports `where`, `field`, `distinct`, and `with` for filtered relation counts
+- `avg` supports `where`, `field`, `distinct`, and `with` for filtered relation averages
+- `where` supports shorthand operators: `eq`, `ne`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `exists`, `regex`, `$options`, `includes`, `includesAny`, `length`
+- `with` supports `_count` and `_avg` for relation-level aggregate results (returned as `XxxAggregate`)
+- `orderBy` accepts `{ column, direction }` or array thereof
+- `geoWithin` for geospatial distance queries (Haversine formula)
+- `upsert` supports `target` (conflict columns) and `set` (on-conflict update columns)
+- `ctx.error(status, message, details)` for typed failures
+
+#### Updating manyToMany relations
+
+The `update` operation supports managing manyToMany relations via the `set` payload. Each manyToMany relation field accepts an object with `items` and optional `mode`:
+
+```ts
+// Merge mode (default) — adds new links, keeps existing ones
+await ctx.db.family.update({
+  where: { primaryUserId: userId },
+  set: {
+    members: {
+      items: [
+        "existing-user-id",                    // link by ID
+        { id: "another-user-id" },             // link by ID (object form)
+        { name: "New User", email: "..." },    // create new user, then link
+      ],
+      mode: "merge",
+    },
+  },
+});
+
+// Overwrite mode — deletes all existing links, keeps only new ones
+await ctx.db.family.update({
+  where: { primaryUserId: userId },
+  set: {
+    members: {
+      items: ["user-id-1", "user-id-2"],
+      mode: "overwrite",
+    },
+  },
+});
+```
+
+- `items` — array of IDs (string/number) or partial objects. Objects without an `id` field are created in the target table before linking.
+- `mode` — `"merge"` (default) keeps existing links and adds new ones; `"overwrite"` deletes all existing links for the parent record before inserting new ones.
+- All relation updates run inside a transaction when present.
+
+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.js`
+- `_generated/client.js`
+- `_generated/auth.config.js`
+- `_generated/drizzle.config.js`
+- `_generated/handlers.js`
+- `_generated/handlers.context.js`
+- `_generated/handlers.execution.js`
+- `_generated/handlers.routes.js`
+- `_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.