appflare 0.2.25 → 0.2.26

package/cli/templates/handlers/README.md

@@ -1,353 +1,353 @@
-# Handlers Template System (with Realtime Durable Objects)
-
-This directory contains code-generation templates used by the Appflare CLI to build runtime handler files in `_generated/`.
-
-The generated runtime now supports **realtime updates** using a **single global Cloudflare Durable Object** and websocket fanout.
-
----
-
-## What this template set generates
-
-From this directory, the CLI generates:
-
-- `handlers.ts`
-- `handlers.context.ts`
-- `handlers.execution.ts`
-- `handlers.routes.ts`
-
-Key behavior added for realtime:
-
-1. Endpoint-first subscriptions (`POST /realtime/subscribe`)
-2. WebSocket connect endpoint (`GET /realtime/ws`)
-3. Per-subscription `token` + `signature`
-4. Query identity contract: `[dirName]/[fileName]/[functionName]`
-5. Args validation against discovered query schema (args-derived keys only)
-6. Mutation-to-query invalidation with **partial filter overlap** matching
-7. Push updated query result to matching subscribers only
-
----
-
-## Realtime architecture
-
-### Components
-
-- **Generated query routes** (`GET /queries/...`)
-- **Generated mutation routes** (`POST /mutations/...`)
-- **Realtime subscription endpoint** (`POST /realtime/subscribe`)
-- **Realtime websocket endpoint** (`GET /realtime/ws?token=...&authToken=...`)
-- **Global Durable Object class**: `AppflareRealtimeDurableObject`
-
-### Data flow
-
-1. Client calls `POST /realtime/subscribe` with:
-   - `queryName`: `[dir]/[file]/[function]`
-   - `args`: query arguments
-   - `authToken`: bearer token
-2. Server validates:
-   - query exists
-   - args parse against that query Zod schema
-   - auth token resolves to a user session
-3. Server stores subscription inside the global DO and returns:
-   - `token`
-   - `signature`
-   - websocket URL/protocol metadata
-4. Client opens websocket at `GET /realtime/ws?token=...&authToken=...`.
-5. On any mutation (`insert`, `update`, `delete`, `upsert`), generated `db` wrappers collect mutation events.
-6. Matching subscriptions are re-executed (same query + same validated args) and pushed over websocket as `query:update`.
-
----
-
-## Identity and signatures
-
-### Query identity
-
-Query names are generated from discovered source layout:
-
-`[dirName]/[fileName]/[functionName]`
-
-Examples:
-
-- `users/profile/getProfile`
-- `root/test/getTest`
-
-### Signature
-
-Signature is generated from:
-
-- `queryName`
-- normalized `args`
-
-The generated runtime normalizes/sorts object keys before stringifying, so logically equivalent payloads produce a stable signature.
-
----
-
-## Partial filter overlap matching
-
-When mutations run, subscribers are selected using overlap logic (not strict equality).
-
-High-level rules:
-
-- Scalars: equal values overlap
-- Arrays: overlap if any element overlaps
-- Objects: overlap if any shared key overlaps recursively
-- Matching checks both:
-  - mutation input args (`set`, `where`, `values`, etc.)
-  - returned mutation rows
-
-This means subscriptions react when filters intersect mutation impact, without requiring exact filter identity.
-
----
-
-## Authentication model
-
-### Subscribe
-
-`POST /realtime/subscribe` requires `authToken` in body.
-
-The runtime creates a request with `Authorization: Bearer <authToken>` and calls `resolveSession(...)`.
-
-If no user resolves, response is `401`.
-
-### WebSocket connect
-
-`GET /realtime/ws` requires both query params:
-
-- `token`
-- `authToken`
-
-Server validates token ownership and auth token before websocket upgrade.
-
----
-
-## Endpoint contracts
-
-### 1) Subscribe
-
-`POST /realtime/subscribe`
-
-Request:
-
-```json
-{
-	"queryName": "users/profile/getProfile",
-	"args": { "userId": "u_123" },
-	"authToken": "<token>"
-}
-```
-
-Success response:
-
-```json
-{
-	"token": "<subscription-token>",
-	"signature": "users/profile/getProfile::{\"userId\":\"u_123\"}",
-	"websocket": {
-		"url": "wss://api.example.com/realtime/ws",
-		"protocol": "appflare.realtime.v1",
-		"params": {
-			"tokenParam": "token",
-			"authTokenParam": "authToken"
-		}
-	}
-}
-```
-
-### 2) WebSocket connect
-
-`GET /realtime/ws?token=<token>&authToken=<authToken>`
-
-Server pushes messages like:
-
-```json
-{
-	"event": "query:update",
-	"payload": {
-		"queryName": "users/profile/getProfile",
-		"signature": "...",
-		"data": { "id": "u_123", "name": "Ada" }
-	}
-}
-```
-
-Heartbeat support:
-
-- client sends: `ping`
-- server replies: `{"event":"pong"}`
-
----
-
-## Mutation event capture
-
-`createQueryDb(...)` now accepts options with `onMutation`.
-
-The generated wrappers for `insert`, `update`, `upsert`, and `delete` emit:
-
-- operation kind
-- table name
-- mutation args
-- returned rows
-
-Execution contexts store these as `ctx.mutationEvents`, and mutation routes call `publishMutationEvents(...)` after successful execution.
-
----
-
-## DB aggregate helpers
-
-Generated `ctx.db.<table>` wrappers now include aggregate helpers:
-
-- `count(args?)`
-  - `where?: WhereInput<TModel>`
-  - `field?: keyof TModel | string` (supports relation paths, e.g. `comments.id`)
-  - `distinct?: boolean`
-  - `with?: QueryWithInput<...>`
-  - returns `Promise<number>`
-- `avg(args)`
-  - `where?: WhereInput<TModel>`
-  - `field: NumericFieldKey<TModel> | string` (supports relation paths, e.g. `comments.id`)
-  - `distinct?: boolean`
-  - `with?: QueryWithInput<...>`
-  - returns `Promise<number | null>`
-
-Aggregate behavior with `with`:
-
-- Relation `with.where` and nested `with` filters are treated as parent-row constraints for aggregates (EXISTS-style).
-- For `count` with `with`, `distinct` defaults to `true` when `field` is provided.
-- Nested relation paths are supported recursively for both `count` and `avg`.
-
-Relation `with` aggregates on `findMany`/`findFirst`:
-
-- You can request per-parent relation aggregates directly inside `with` using `_count` and `_avg`.
-- Result rows include a sibling `<relationName>Aggregate` object.
-- `_avg` returns `0` for parents with no related rows.
-
-Example:
-
-```ts
-const total = await ctx.db.posts.count({
-	where: { ownerId: user.id },
-});
-
-const uniqueOwners = await ctx.db.posts.count({
-	field: "ownerId",
-	distinct: true,
-});
-
-const averageId = await ctx.db.posts.avg({
-	field: "id",
-	where: { ownerId: user.id },
-});
-
-const postsWithMatchingComments = await ctx.db.posts.count({
-	with: {
-		comments: {
-			where: {
-				id: { gte: 10000 },
-			},
-		},
-	},
-});
-
-const averageCommentId = await ctx.db.posts.avg({
-	field: "comments.id",
-	with: {
-		comments: {
-			where: {
-				id: { gte: 10000 },
-			},
-		},
-	},
-});
-
-const postsWithCommentStats = await ctx.db.posts.findMany({
-	with: {
-		comments: {
-			_count: true,
-			_avg: {
-				id: true,
-			},
-		},
-	},
-});
-
-const firstPostCommentCount =
-	postsWithCommentStats[0]?.commentsAggregate.count ?? 0;
-const firstPostAverageCommentId =
-	postsWithCommentStats[0]?.commentsAggregate.avg.id ?? 0;
-```
-
-`geoWithin.latitudeField` and `geoWithin.longitudeField` are now typed to table keys (instead of free-form strings). Invalid field names still no-op the geo filter at runtime, but now emit a warning.
-
----
-
-## Durable Object responsibilities
-
-`AppflareRealtimeDurableObject` keeps in-memory maps for:
-
-- `subscriptions` (`token -> metadata`)
-- `sockets` (`token -> websocket`)
-
-Supported internal routes:
-
-- `POST /subscribe`
-- `POST /subscriptions`
-- `POST /emit`
-- `GET /ws`
-
-This design centralizes fanout in one global app DO instance.
-
----
-
-## Generated client support
-
-The client generator exposes realtime helper APIs:
-
-- `appflare.realtime.subscribe(...)`
-
-Types include:
-
-- `RealtimeSubscriptionRequest`
-- `RealtimeSubscriptionResponse`
-
-The client performs endpoint-first subscription; websocket connection is then established using returned metadata.
-
----
-
-## Configuration knobs (from app config)
-
-Realtime defaults are normalized from `realtime` config:
-
-- `enabled` (default `true`)
-- `binding` (default `APPFLARE_REALTIME`)
-- `className` (default `AppflareRealtimeDurableObject`)
-- `objectName` (default `global`)
-- `subscribePath` (default `/realtime/subscribe`)
-- `websocketPath` (default `/realtime/ws`)
-- `protocol` (default `appflare.realtime.v1`)
-
-Wrangler generation automatically emits:
-
-- `durable_objects.bindings`
-- `migrations` with DO class
-
----
-
-## Notes and limitations
-
-1. Current DO storage is in-memory; restarts drop live subscriptions.
-2. Matching is overlap-based and intentionally permissive for realtime invalidation.
-3. Query re-execution occurs on matching mutation events and can be tuned later for batching/debouncing.
-
----
-
-## Safe extension points
-
-- `registration.ts`:
-  - realtime routes, token/session policy, protocol envelopes
-- `types.ts`:
-  - mutation event payload contracts
-- `generators/context/context-creation.ts`:
-  - context-level mutation event tracking
-- `utils/handler-discovery.ts`:
-  - query identity strategy
-
-After template changes, regenerate and validate `_generated` output.
+# Handlers Template System (with Realtime Durable Objects)
+
+This directory contains code-generation templates used by the Appflare CLI to build runtime handler files in `_generated/`.
+
+The generated runtime now supports **realtime updates** using a **single global Cloudflare Durable Object** and websocket fanout.
+
+---
+
+## What this template set generates
+
+From this directory, the CLI generates:
+
+- `handlers.ts`
+- `handlers.context.ts`
+- `handlers.execution.ts`
+- `handlers.routes.ts`
+
+Key behavior added for realtime:
+
+1. Endpoint-first subscriptions (`POST /realtime/subscribe`)
+2. WebSocket connect endpoint (`GET /realtime/ws`)
+3. Per-subscription `token` + `signature`
+4. Query identity contract: `[dirName]/[fileName]/[functionName]`
+5. Args validation against discovered query schema (args-derived keys only)
+6. Mutation-to-query invalidation with **partial filter overlap** matching
+7. Push updated query result to matching subscribers only
+
+---
+
+## Realtime architecture
+
+### Components
+
+- **Generated query routes** (`GET /queries/...`)
+- **Generated mutation routes** (`POST /mutations/...`)
+- **Realtime subscription endpoint** (`POST /realtime/subscribe`)
+- **Realtime websocket endpoint** (`GET /realtime/ws?token=...&authToken=...`)
+- **Global Durable Object class**: `AppflareRealtimeDurableObject`
+
+### Data flow
+
+1. Client calls `POST /realtime/subscribe` with:
+   - `queryName`: `[dir]/[file]/[function]`
+   - `args`: query arguments
+   - `authToken`: bearer token
+2. Server validates:
+   - query exists
+   - args parse against that query Zod schema
+   - auth token resolves to a user session
+3. Server stores subscription inside the global DO and returns:
+   - `token`
+   - `signature`
+   - websocket URL/protocol metadata
+4. Client opens websocket at `GET /realtime/ws?token=...&authToken=...`.
+5. On any mutation (`insert`, `update`, `delete`, `upsert`), generated `db` wrappers collect mutation events.
+6. Matching subscriptions are re-executed (same query + same validated args) and pushed over websocket as `query:update`.
+
+---
+
+## Identity and signatures
+
+### Query identity
+
+Query names are generated from discovered source layout:
+
+`[dirName]/[fileName]/[functionName]`
+
+Examples:
+
+- `users/profile/getProfile`
+- `root/test/getTest`
+
+### Signature
+
+Signature is generated from:
+
+- `queryName`
+- normalized `args`
+
+The generated runtime normalizes/sorts object keys before stringifying, so logically equivalent payloads produce a stable signature.
+
+---
+
+## Partial filter overlap matching
+
+When mutations run, subscribers are selected using overlap logic (not strict equality).
+
+High-level rules:
+
+- Scalars: equal values overlap
+- Arrays: overlap if any element overlaps
+- Objects: overlap if any shared key overlaps recursively
+- Matching checks both:
+  - mutation input args (`set`, `where`, `values`, etc.)
+  - returned mutation rows
+
+This means subscriptions react when filters intersect mutation impact, without requiring exact filter identity.
+
+---
+
+## Authentication model
+
+### Subscribe
+
+`POST /realtime/subscribe` requires `authToken` in body.
+
+The runtime creates a request with `Authorization: Bearer <authToken>` and calls `resolveSession(...)`.
+
+If no user resolves, response is `401`.
+
+### WebSocket connect
+
+`GET /realtime/ws` requires both query params:
+
+- `token`
+- `authToken`
+
+Server validates token ownership and auth token before websocket upgrade.
+
+---
+
+## Endpoint contracts
+
+### 1) Subscribe
+
+`POST /realtime/subscribe`
+
+Request:
+
+```json
+{
+	"queryName": "users/profile/getProfile",
+	"args": { "userId": "u_123" },
+	"authToken": "<token>"
+}
+```
+
+Success response:
+
+```json
+{
+	"token": "<subscription-token>",
+	"signature": "users/profile/getProfile::{\"userId\":\"u_123\"}",
+	"websocket": {
+		"url": "wss://api.example.com/realtime/ws",
+		"protocol": "appflare.realtime.v1",
+		"params": {
+			"tokenParam": "token",
+			"authTokenParam": "authToken"
+		}
+	}
+}
+```
+
+### 2) WebSocket connect
+
+`GET /realtime/ws?token=<token>&authToken=<authToken>`
+
+Server pushes messages like:
+
+```json
+{
+	"event": "query:update",
+	"payload": {
+		"queryName": "users/profile/getProfile",
+		"signature": "...",
+		"data": { "id": "u_123", "name": "Ada" }
+	}
+}
+```
+
+Heartbeat support:
+
+- client sends: `ping`
+- server replies: `{"event":"pong"}`
+
+---
+
+## Mutation event capture
+
+`createQueryDb(...)` now accepts options with `onMutation`.
+
+The generated wrappers for `insert`, `update`, `upsert`, and `delete` emit:
+
+- operation kind
+- table name
+- mutation args
+- returned rows
+
+Execution contexts store these as `ctx.mutationEvents`, and mutation routes call `publishMutationEvents(...)` after successful execution.
+
+---
+
+## DB aggregate helpers
+
+Generated `ctx.db.<table>` wrappers now include aggregate helpers:
+
+- `count(args?)`
+  - `where?: WhereInput<TModel>`
+  - `field?: keyof TModel | string` (supports relation paths, e.g. `comments.id`)
+  - `distinct?: boolean`
+  - `with?: QueryWithInput<...>`
+  - returns `Promise<number>`
+- `avg(args)`
+  - `where?: WhereInput<TModel>`
+  - `field: NumericFieldKey<TModel> | string` (supports relation paths, e.g. `comments.id`)
+  - `distinct?: boolean`
+  - `with?: QueryWithInput<...>`
+  - returns `Promise<number | null>`
+
+Aggregate behavior with `with`:
+
+- Relation `with.where` and nested `with` filters are treated as parent-row constraints for aggregates (EXISTS-style).
+- For `count` with `with`, `distinct` defaults to `true` when `field` is provided.
+- Nested relation paths are supported recursively for both `count` and `avg`.
+
+Relation `with` aggregates on `findMany`/`findFirst`:
+
+- You can request per-parent relation aggregates directly inside `with` using `_count` and `_avg`.
+- Result rows include a sibling `<relationName>Aggregate` object.
+- `_avg` returns `0` for parents with no related rows.
+
+Example:
+
+```ts
+const total = await ctx.db.posts.count({
+	where: { ownerId: user.id },
+});
+
+const uniqueOwners = await ctx.db.posts.count({
+	field: "ownerId",
+	distinct: true,
+});
+
+const averageId = await ctx.db.posts.avg({
+	field: "id",
+	where: { ownerId: user.id },
+});
+
+const postsWithMatchingComments = await ctx.db.posts.count({
+	with: {
+		comments: {
+			where: {
+				id: { gte: 10000 },
+			},
+		},
+	},
+});
+
+const averageCommentId = await ctx.db.posts.avg({
+	field: "comments.id",
+	with: {
+		comments: {
+			where: {
+				id: { gte: 10000 },
+			},
+		},
+	},
+});
+
+const postsWithCommentStats = await ctx.db.posts.findMany({
+	with: {
+		comments: {
+			_count: true,
+			_avg: {
+				id: true,
+			},
+		},
+	},
+});
+
+const firstPostCommentCount =
+	postsWithCommentStats[0]?.commentsAggregate.count ?? 0;
+const firstPostAverageCommentId =
+	postsWithCommentStats[0]?.commentsAggregate.avg.id ?? 0;
+```
+
+`geoWithin.latitudeField` and `geoWithin.longitudeField` are now typed to table keys (instead of free-form strings). Invalid field names still no-op the geo filter at runtime, but now emit a warning.
+
+---
+
+## Durable Object responsibilities
+
+`AppflareRealtimeDurableObject` keeps in-memory maps for:
+
+- `subscriptions` (`token -> metadata`)
+- `sockets` (`token -> websocket`)
+
+Supported internal routes:
+
+- `POST /subscribe`
+- `POST /subscriptions`
+- `POST /emit`
+- `GET /ws`
+
+This design centralizes fanout in one global app DO instance.
+
+---
+
+## Generated client support
+
+The client generator exposes realtime helper APIs:
+
+- `appflare.realtime.subscribe(...)`
+
+Types include:
+
+- `RealtimeSubscriptionRequest`
+- `RealtimeSubscriptionResponse`
+
+The client performs endpoint-first subscription; websocket connection is then established using returned metadata.
+
+---
+
+## Configuration knobs (from app config)
+
+Realtime defaults are normalized from `realtime` config:
+
+- `enabled` (default `true`)
+- `binding` (default `APPFLARE_REALTIME`)
+- `className` (default `AppflareRealtimeDurableObject`)
+- `objectName` (default `global`)
+- `subscribePath` (default `/realtime/subscribe`)
+- `websocketPath` (default `/realtime/ws`)
+- `protocol` (default `appflare.realtime.v1`)
+
+Wrangler generation automatically emits:
+
+- `durable_objects.bindings`
+- `migrations` with DO class
+
+---
+
+## Notes and limitations
+
+1. Current DO storage is in-memory; restarts drop live subscriptions.
+2. Matching is overlap-based and intentionally permissive for realtime invalidation.
+3. Query re-execution occurs on matching mutation events and can be tuned later for batching/debouncing.
+
+---
+
+## Safe extension points
+
+- `registration.ts`:
+  - realtime routes, token/session policy, protocol envelopes
+- `types.ts`:
+  - mutation event payload contracts
+- `generators/context/context-creation.ts`:
+  - context-level mutation event tracking
+- `utils/handler-discovery.ts`:
+  - query identity strategy
+
+After template changes, regenerate and validate `_generated` output.