create-seiro 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-seiro",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Scaffold a new Seiro project",
   "type": "module",
   "bin": {

package/template/.claude/skills/cqrs-document/references/seiro.md

@@ -47,6 +47,7 @@ export type EntityQueries = {
 export type EntityEvents = {
   entity_created: Entity;
   entity_updated: Entity;
+  entity_deleted: { id: number };  // different payload type
 };
 ```
 
@@ -74,7 +75,7 @@ const server = createServer({
 
 // Register domain handlers
 auth.register(server, sql);
-entity.register(server, sql);
+await entity.register(server, sql, listener);  // with pg_notify listener
 
 await server.start({ "/": homepage });
 ```
@@ -86,21 +87,38 @@ import type { Sql } from "postgres";
 import type { Server } from "seiro";
 import type { Entity, EntityCommands, EntityQueries, EntityEvents } from "./types";
 
-export function register<
+export async function register<
   C extends EntityCommands,
   Q extends EntityQueries,
   E extends EntityEvents,
->(server: Server<C, Q, E>, sql: Sql) {
+>(server: Server<C, Q, E>, sql: Sql, listener?: Sql) {
+  // Listen to postgres notifications (if listener provided)
+  if (listener) {
+    await listener.listen("entity_created", (payload: string) => {
+      try {
+        server.emit("entity_created", JSON.parse(payload) as Entity);
+      } catch (e) {
+        console.error("Failed to parse entity_created payload:", payload, e);
+      }
+    });
 
-  // Send profile on connect (auth example)
-  server.onOpen(async (ctx) => {
-    if (!ctx.userId) {
-      ctx.send({ profile: null });
-      return;
-    }
-    // fetch and send user profile
-    ctx.send({ profile: user });
-  });
+    await listener.listen("entity_updated", (payload: string) => {
+      try {
+        server.emit("entity_updated", JSON.parse(payload) as Entity);
+      } catch (e) {
+        console.error("Failed to parse entity_updated payload:", payload, e);
+      }
+    });
+
+    // Different payload type for delete - just the id
+    await listener.listen("entity_deleted", (payload: string) => {
+      try {
+        server.emit("entity_deleted", JSON.parse(payload) as { id: number });
+      } catch (e) {
+        console.error("Failed to parse entity_deleted payload:", payload, e);
+      }
+    });
+  }
 
   // Command with typed result
   server.command("entity.save", async (data, ctx) => {
@@ -122,9 +140,6 @@ export function register<
     }
   });
 }
-
-// Broadcast events from server
-server.emit("entity_created", entity);
 ```
 
 ## Client Setup
@@ -279,10 +294,73 @@ RETURNS SETOF jsonb AS $$
 $$ LANGUAGE sql;
 ```
 
+## Streaming Queries
+
+Queries stream rows over the WebSocket - each row is sent as soon as the server yields it, and the client can process rows as they arrive.
+
+### How It Works
+
+**Server:** Each `yield` sends a message immediately:
+
+```typescript
+server.query("logs.recent", async function* (params, ctx) {
+  const rows = await sql`SELECT * FROM logs LIMIT 1000`;
+  for (const row of rows) {
+    yield row;  // sent to client immediately
+  }
+});
+```
+
+**Wire:** Rows stream as individual messages:
+
+```
+→ { q: "logs.recent", id: 1, params: {} }
+← { id: 1, row: { id: 1, message: "..." } }   // immediate
+← { id: 1, row: { id: 2, message: "..." } }   // immediate
+← { id: 1, row: { id: 3, message: "..." } }   // immediate
+...
+← { id: 1 }                                    // end marker
+```
+
+**Client:** Process rows as they arrive:
+
+```typescript
+// Streaming - handle each row immediately
+for await (const row of client.query("logs.recent")) {
+  appendToUI(row);  // renders while more rows are coming
+}
+
+// Or collect all (waits for stream to complete)
+const all = await client.queryAll("logs.recent");
+```
+
+### Use Cases
+
+- **Large datasets:** Render first results while fetching more
+- **Progress feedback:** Show items appearing one by one
+- **Memory efficiency:** Process rows without holding all in memory
+- **Responsive UI:** User sees data immediately, not after full load
+
+### True End-to-End Streaming
+
+The example above streams WebSocket delivery, but SQL fetches all rows first. For true streaming from database to client, use cursors:
+
+```typescript
+server.query("logs.stream", async function* (params, ctx) {
+  // Cursor-based streaming from postgres
+  const cursor = sql`SELECT * FROM logs`.cursor(100);
+  for await (const rows of cursor) {
+    for (const row of rows) {
+      yield row;
+    }
+  }
+});
+```
+
 ## Conventions
 
 - Commands return `{ id }` for create/save operations
-- Queries stream rows, end with empty `{ id }`
+- Queries stream rows - each `yield` sends immediately, end with empty `{ id }`
 - Use typed SQL: `sql<[{ result: Type }]>` or `sql<{ fn_name: Type }[]>`
 - Events broadcast full data via pg_notify
 - Pattern subscriptions support wildcards: `entity_*`