create-seiro 0.1.6 → 0.1.8

package/package.json

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

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

@@ -7,9 +7,9 @@ CQRS over WebSocket with Bun + Preact Signals + Web Components.
 ```
 ← { profile }               sent on connect (User or null)
 
-→ { cmd, cid, data }        command request
-← { cid, result }           command success
-← { cid, err }              command error
+→ { cmd, cid, data, ack? }  command request (ack=true requests response)
+← { cid, result }           command success (only if ack was true)
+← { cid, err }              command error (always sent on failure)
 
 → { q, id, params }         query request
 ← { id, row }               query row (repeated)
@@ -22,6 +22,8 @@ CQRS over WebSocket with Bun + Preact Signals + Web Components.
 → { unsub: "pattern" }      unsubscribe
 ```
 
+The `ack` flag controls whether the server sends a success response. When `ack: true`, the server sends `{ cid, result }` on completion. When `ack` is absent or false, no success response is sent (fire-and-forget). Error responses are always sent regardless of `ack`.
+
 ## Type Definitions
 
 Use `Command<D, R>` and `Query<P, R>` helpers:
@@ -93,31 +95,44 @@ export async function register<
   E extends EntityEvents,
 >(server: Server<C, Q, E>, sql: Sql, listener?: Sql) {
   // Listen to postgres notifications (if listener provided)
+  // The 3rd callback is called on connect AND reconnect - postgres.js handles reconnection internally
   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);
-      }
-    });
-
-    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);
-      }
-    });
+    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);
+        }
+      },
+      () => console.log("Listening on entity_created"),
+    );
+
+    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);
+        }
+      },
+      () => console.log("Listening on entity_updated"),
+    );
 
     // 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);
-      }
-    });
+    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);
+        }
+      },
+      () => console.log("Listening on entity_deleted"),
+    );
   }
 
   // Command with typed result
@@ -163,12 +178,15 @@ client.subscribe();
 ## Client API
 
 ```typescript
-// Command with callbacks
+// Command with callbacks (sends ack: true, server responds on success)
 client.cmd("entity.save", { id: 1, name: "Updated" }, {
   onSuccess: (result) => navigate(`#/entities/${result.id}`),
   onError: (err) => showError(err),
 });
 
+// Fire-and-forget command (no callbacks = no ack, no success response)
+client.cmd("analytics.track", { event: "page_view" });
+
 // Query (async iterator)
 for await (const row of client.query("entities.all")) {
   items.push(row);
@@ -357,6 +375,29 @@ server.query("logs.stream", async function* (params, ctx) {
 });
 ```
 
+## PostgreSQL Listener Reconnection
+
+LISTEN blocks the connection - if it drops, you need to re-establish subscriptions. The postgres.js library handles this automatically via the `onlisten` callback (third parameter to `sql.listen()`):
+
+```typescript
+await listener.listen(
+  "entity_created",
+  (payload: string) => {
+    // Handle notification
+    server.emit("entity_created", JSON.parse(payload) as Entity);
+  },
+  () => {
+    // Called on initial connect AND on reconnect
+    console.log("Listening on entity_created");
+  },
+);
+```
+
+The `onlisten` callback is useful for:
+- Logging when listeners are active (helpful for debugging)
+- Fetching any missed data after reconnection
+- Re-syncing state with the database
+
 ## Conventions
 
 - Commands return `{ id }` for create/save operations

package/template/package.json

@@ -10,7 +10,7 @@
     "test": "bun test server.test.ts"
   },
   "dependencies": {
-    "seiro": "^0.1.6",
+    "seiro": "^0.1.8",
     "@preact/signals-core": "^1.12.2",
     "postgres": "^3.4.8"
   },