@super-line/server 0.7.1 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @super-line/server
 
-The server for [**super-line**](https://mertdogar.github.io/super-line/) — end-to-end typesafe WebSockets for TypeScript. Implements a shared contract over [`ws`](https://www.npmjs.com/package/ws): role-keyed handlers, rooms, topics, middleware, lifecycle hooks, and node-to-node messaging.
+The server for [**super-line**](https://mertdogar.github.io/super-line/) — the strictly-typed realtime data bus for TypeScript. Implements a shared contract over any transport: role-keyed request handlers, rooms, topics, synced state, middleware, lifecycle hooks, and node-to-node messaging. WebSocket is the default wire; HTTP/SSE, libp2p, and loopback are alternatives.
 
 ```bash
 pnpm add @super-line/core @super-line/server @super-line/transport-websocket zod
@@ -30,7 +30,57 @@ srv.implement({
 server.listen(3000)
 ```
 
-Authenticate receives the `Handshake` (`{ transport, headers, query, peer?, raw }`) and returns `{ role, ctx }`; cross-role calls are rejected with `NOT_FOUND`. The wire is carried by a pluggable transport — [`@super-line/transport-websocket`](https://www.npmjs.com/package/@super-line/transport-websocket) provides the WS transport shown above; other transports (HTTP/SSE, libp2p) are available — see the Transports guide. Scale across processes with [`@super-line/adapter-redis`](https://www.npmjs.com/package/@super-line/adapter-redis).
+Authenticate receives the `Handshake` (`{ transport, headers, query, peer?, raw }`) and returns `{ role, ctx }`; cross-role calls are rejected with `NOT_FOUND`. The wire is carried by a pluggable transport — [`@super-line/transport-websocket`](https://www.npmjs.com/package/@super-line/transport-websocket) provides the WS transport shown above; HTTP/SSE ([`transport-http`](https://www.npmjs.com/package/@super-line/transport-http)), libp2p ([`transport-libp2p`](https://www.npmjs.com/package/@super-line/transport-libp2p)), and in-memory ([`transport-loopback`](https://www.npmjs.com/package/@super-line/transport-loopback)) are alternatives — see the Transports guide.
+
+### Cluster event bus
+
+`srv.publish(topic, data)` / `srv.subscribe(topic, handler)` is a server-side pub/sub over a shared contract topic. The callback fires for a publish from any node — including this one (local echo, in-process, no round-trip). `meta.from` is the publishing node; self-exclude with `if (meta.from === srv.nodeId) return`.
+
+```ts
+const off = srv.subscribe('orders', (order, meta) => {
+  if (meta.from === srv.nodeId) return // skip our own echo
+  // react to an order published on another node
+})
+srv.publish('orders', { id: '...', total: 42 })
+```
+
+Cross-node fan-out (rooms, topics, the bus, targeted `toConn`/`toUser`, and store changes) rides a pluggable `adapter`. Defaults to an in-memory adapter (single process); for a cluster pass one of [`adapter-redis`](https://www.npmjs.com/package/@super-line/adapter-redis), [`adapter-libp2p`](https://www.npmjs.com/package/@super-line/adapter-libp2p), [`adapter-rabbitmq`](https://www.npmjs.com/package/@super-line/adapter-rabbitmq), or [`adapter-zeromq`](https://www.npmjs.com/package/@super-line/adapter-zeromq).
+
+### Synced state (stores)
+
+Pass server-side `stores` and the server becomes authoritative over persisted, reactive Resources — clients open the matching client halves. The store decides the consistency model (LWW or CRDT), durability (in-memory / SQLite / libsql / Postgres), and clustering (`relay` fans out over the adapter; `self` owns a central backend + per-node replica, no adapter). The default pair is [`@super-line/store-memory`](https://www.npmjs.com/package/@super-line/store-memory) (LWW · in-memory · relay).
+
+```ts
+import { memoryStoreServer } from '@super-line/store-memory'
+
+const srv = createSuperLineServer(api, {
+  transports: [webSocketServerTransport({ server })],
+  authenticate,
+  stores: { docs: memoryStoreServer() },
+})
+
+const docs = srv.store('docs') // ServerStoreHandle — throws NOT_FOUND if unconfigured
+await docs.create('intro', { title: 'Hi' }, { 'user:1': { read: true, write: true } })
+await docs.grant('intro', 'user:2', { read: true })
+await docs.write('intro', { title: 'Updated' }) // LWW co-write, fanned out with a `server` origin
+await docs.delete('intro') // publishes a cluster-wide deletion (sdel) to every subscriber
+```
+
+`ServerStoreHandle`: `create` / `read` / `write` / `grant` / `revoke` / `delete` / `list`. For a reactive in-process co-writer, `open(id)` returns a `ServerReplica` — the server half's mirror of the client's `store(ns).open(id)`:
+
+```ts
+const replica = srv.store('docs').open('intro', { origin: 'agent' })
+replica.subscribe(() => console.log(replica.getSnapshot()))
+replica.update({ title: 'Live' }) // merge
+replica.delete('title')           // surgical key delete (the only way to remove a key server-side)
+replica.close()
+```
+
+`open` requires a store with reactive support (throws `UNSUPPORTED` otherwise). CRDT stores (`store-sync`, `store-sync-libsql`, `store-sync-pglite`) and the LWW stores both back it.
+
+### Control Center inspector
+
+Set `inspector: true` (or `{ redact: ['password', 'token'] }`) to emit `msg.*` telemetry and accept read-only [Control Center](https://www.npmjs.com/package/@super-line/control-center) clients. The WS transport must also be created with `inspector: true` to negotiate the subprotocol. **Default off; dev / trusted-network only.**
 
 - 📖 Docs: <https://mertdogar.github.io/super-line/>
 - 📚 Guides: [roles & auth](https://mertdogar.github.io/super-line/guide/roles-auth), [events & rooms](https://mertdogar.github.io/super-line/guide/events-rooms)

package/dist/index.cjs

@@ -17023,20 +17023,29 @@ function createSuperLineServer(contract, opts) {
     if (inspectorEnabled) emitInspectorEvent({ type: "store.unsubscribe", connId: conn.id, store: frame.n, id: frame.id });
   }
   for (const [name, store] of Object.entries(storeMap)) {
+    const isSelf = store.clustering === "self";
     store.onChange((change) => {
+      const channel = STORE + name + ":" + change.id;
+      if (isSelf) {
+        const set = members.get(channel);
+        if (!set) return;
+        const payload = serializer.encode({ t: "sch", n: name, id: change.id, u: change.update, o: change.origin });
+        for (const conn of set) conn.sendRaw(payload);
+        return;
+      }
       if (relaying) return;
       void adapter.publish(
-        STORE + name + ":" + change.id,
-        serializer.encode({
-          t: "sch",
-          n: name,
-          id: change.id,
-          u: change.update,
-          o: change.origin,
-          nd: instanceId
-        })
+        channel,
+        serializer.encode({ t: "sch", n: name, id: change.id, u: change.update, o: change.origin, nd: instanceId })
       );
     });
+    if (isSelf)
+      store.onDelete?.((id) => {
+        const set = members.get(STORE + name + ":" + id);
+        if (!set) return;
+        const payload = serializer.encode({ t: "sdel", n: name, id });
+        for (const conn of set) conn.sendRaw(payload);
+      });
   }
   function handleStoreRelay(channel, payload) {
     const set = members.get(channel);
@@ -17050,6 +17059,10 @@ function createSuperLineServer(contract, opts) {
     if (frame.nd === instanceId) return;
     const store = storeMap[frame.n];
     if (!store || store.clustering !== "relay") return;
+    if (frame.t === "sdel") {
+      void store.delete(frame.id);
+      return;
+    }
     relaying = true;
     try {
       void store.apply({ id: frame.id, update: frame.u, origin: frame.o });
@@ -17177,10 +17190,11 @@ function createSuperLineServer(contract, opts) {
       read(id) {
         return Promise.resolve(store.read(id));
       },
-      async write(id, data) {
-        await store.apply({ id, update: data, origin: SERVER_ORIGIN });
+      async write(id, data, opts2) {
+        const origin = opts2?.origin ?? SERVER_ORIGIN;
+        await store.apply({ id, update: data, origin });
         if (inspectorEnabled)
-          emitInspectorEvent({ type: "store.write", store: name, id, origin: SERVER_ORIGIN, data: safeSnapshot(data) });
+          emitInspectorEvent({ type: "store.write", store: name, id, origin, data: safeSnapshot(data) });
       },
       async grant(id, principal, perms) {
         const r = await readOrThrow(id);
@@ -17196,6 +17210,11 @@ function createSuperLineServer(contract, opts) {
       },
       async delete(id) {
         await store.delete(id);
+        if (store.clustering !== "self")
+          void adapter.publish(
+            STORE + name + ":" + id,
+            serializer.encode({ t: "sdel", n: name, id, nd: instanceId })
+          );
         if (inspectorEnabled) emitInspectorEvent({ type: "store.delete", store: name, id });
       },
       list() {

package/dist/index.d.cts

@@ -228,8 +228,13 @@ interface ServerStoreHandle {
     create(id: string, data: unknown, accessRules: AccessRules): Promise<void>;
     /** Read a Resource (data + accessRules), or undefined if absent. */
     read(id: string): Promise<Resource | undefined>;
-    /** Server co-write: replace the Resource's value (LWW), fanned out to subscribers with a `server` origin. */
-    write(id: string, data: unknown): Promise<void>;
+    /**
+     * Server co-write: replace the Resource's value (LWW), fanned out to subscribers stamped with `origin`
+     * (default `"server"`) for echo-break + inspector attribution — mirrors {@link ServerStore.open}'s origin.
+     */
+    write(id: string, data: unknown, opts?: {
+        origin?: string;
+    }): Promise<void>;
     /** Grant a principal read/write on a Resource. */
     grant(id: string, principal: string, perms: Perms): Promise<void>;
     /** Revoke a principal's access to a Resource entirely. */

package/dist/index.d.ts

@@ -228,8 +228,13 @@ interface ServerStoreHandle {
     create(id: string, data: unknown, accessRules: AccessRules): Promise<void>;
     /** Read a Resource (data + accessRules), or undefined if absent. */
     read(id: string): Promise<Resource | undefined>;
-    /** Server co-write: replace the Resource's value (LWW), fanned out to subscribers with a `server` origin. */
-    write(id: string, data: unknown): Promise<void>;
+    /**
+     * Server co-write: replace the Resource's value (LWW), fanned out to subscribers stamped with `origin`
+     * (default `"server"`) for echo-break + inspector attribution — mirrors {@link ServerStore.open}'s origin.
+     */
+    write(id: string, data: unknown, opts?: {
+        origin?: string;
+    }): Promise<void>;
     /** Grant a principal read/write on a Resource. */
     grant(id: string, principal: string, perms: Perms): Promise<void>;
     /** Revoke a principal's access to a Resource entirely. */

package/dist/index.js

@@ -755,20 +755,29 @@ function createSuperLineServer(contract, opts) {
     if (inspectorEnabled) emitInspectorEvent({ type: "store.unsubscribe", connId: conn.id, store: frame.n, id: frame.id });
   }
   for (const [name, store] of Object.entries(storeMap)) {
+    const isSelf = store.clustering === "self";
     store.onChange((change) => {
+      const channel = STORE + name + ":" + change.id;
+      if (isSelf) {
+        const set = members.get(channel);
+        if (!set) return;
+        const payload = serializer.encode({ t: "sch", n: name, id: change.id, u: change.update, o: change.origin });
+        for (const conn of set) conn.sendRaw(payload);
+        return;
+      }
       if (relaying) return;
       void adapter.publish(
-        STORE + name + ":" + change.id,
-        serializer.encode({
-          t: "sch",
-          n: name,
-          id: change.id,
-          u: change.update,
-          o: change.origin,
-          nd: instanceId
-        })
+        channel,
+        serializer.encode({ t: "sch", n: name, id: change.id, u: change.update, o: change.origin, nd: instanceId })
       );
     });
+    if (isSelf)
+      store.onDelete?.((id) => {
+        const set = members.get(STORE + name + ":" + id);
+        if (!set) return;
+        const payload = serializer.encode({ t: "sdel", n: name, id });
+        for (const conn of set) conn.sendRaw(payload);
+      });
   }
   function handleStoreRelay(channel, payload) {
     const set = members.get(channel);
@@ -782,6 +791,10 @@ function createSuperLineServer(contract, opts) {
     if (frame.nd === instanceId) return;
     const store = storeMap[frame.n];
     if (!store || store.clustering !== "relay") return;
+    if (frame.t === "sdel") {
+      void store.delete(frame.id);
+      return;
+    }
     relaying = true;
     try {
       void store.apply({ id: frame.id, update: frame.u, origin: frame.o });
@@ -909,10 +922,11 @@ function createSuperLineServer(contract, opts) {
       read(id) {
         return Promise.resolve(store.read(id));
       },
-      async write(id, data) {
-        await store.apply({ id, update: data, origin: SERVER_ORIGIN });
+      async write(id, data, opts2) {
+        const origin = opts2?.origin ?? SERVER_ORIGIN;
+        await store.apply({ id, update: data, origin });
         if (inspectorEnabled)
-          emitInspectorEvent({ type: "store.write", store: name, id, origin: SERVER_ORIGIN, data: safeSnapshot(data) });
+          emitInspectorEvent({ type: "store.write", store: name, id, origin, data: safeSnapshot(data) });
       },
       async grant(id, principal, perms) {
         const r = await readOrThrow(id);
@@ -928,6 +942,11 @@ function createSuperLineServer(contract, opts) {
       },
       async delete(id) {
         await store.delete(id);
+        if (store.clustering !== "self")
+          void adapter.publish(
+            STORE + name + ":" + id,
+            serializer.encode({ t: "sdel", n: name, id, nd: instanceId })
+          );
         if (inspectorEnabled) emitInspectorEvent({ type: "store.delete", store: name, id });
       },
       list() {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@super-line/server",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "type": "module",
-  "description": "Typesafe WebSocket server for super-line — rooms, topics, middleware, pluggable adapters.",
+  "description": "Realtime data-bus server for super-line — requests, events, rooms, topics, stores, pluggable transports & adapters.",
   "license": "MIT",
   "author": "Mert",
   "keywords": [
@@ -47,7 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@super-line/core": "^0.7.1"
+    "@super-line/core": "^0.8.0"
   },
   "devDependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
@@ -69,13 +69,13 @@
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.25.2",
     "@super-line/adapter-libp2p": "0.5.0",
-    "@super-line/adapter-redis": "0.5.0",
     "@super-line/adapter-rabbitmq": "0.5.0",
-    "@super-line/transport-websocket": "0.5.0",
-    "@super-line/transport-loopback": "0.5.0",
-    "@super-line/client": "0.6.0",
+    "@super-line/client": "0.7.0",
+    "@super-line/adapter-zeromq": "0.5.0",
+    "@super-line/adapter-redis": "0.5.0",
     "@super-line/transport-http": "0.5.0",
-    "@super-line/adapter-zeromq": "0.5.0"
+    "@super-line/transport-websocket": "0.5.0",
+    "@super-line/transport-loopback": "0.5.0"
   },
   "optionalDependencies": {
     "@standard-community/standard-json": "^0.3.5"