@parsrun/realtime 0.1.0

package/README.md

@@ -0,0 +1,176 @@
+# @parsrun/realtime
+
+Edge-compatible realtime features for Pars with SSE and Durable Objects support.
+
+## Features
+
+- **SSE (Server-Sent Events)**: Simple real-time streaming
+- **Durable Objects**: Cloudflare stateful WebSockets
+- **Pub/Sub**: Channel-based messaging
+- **Presence**: Online user tracking
+- **Hono Integration**: Ready-to-use middleware
+
+## Installation
+
+```bash
+pnpm add @parsrun/realtime
+```
+
+## Quick Start
+
+```typescript
+import { createSSEStream } from '@parsrun/realtime';
+
+// In Hono route
+app.get('/events', (c) => {
+  const stream = createSSEStream(c);
+
+  // Send events
+  stream.send({ type: 'connected', data: { userId: '123' } });
+
+  // Subscribe to events
+  events.on('update', (data) => {
+    stream.send({ type: 'update', data });
+  });
+
+  return stream.response();
+});
+```
+
+## API Overview
+
+### SSE (Server-Sent Events)
+
+```typescript
+import { createSSEAdapter, createSSEStream } from '@parsrun/realtime/adapters/sse';
+
+// Create SSE stream
+app.get('/events/:channel', async (c) => {
+  const channel = c.req.param('channel');
+  const stream = createSSEStream(c);
+
+  // Send initial data
+  stream.send({
+    event: 'connected',
+    data: { channel },
+  });
+
+  // Subscribe to channel
+  const unsubscribe = pubsub.subscribe(channel, (message) => {
+    stream.send({
+      event: 'message',
+      data: message,
+    });
+  });
+
+  // Cleanup on disconnect
+  c.req.raw.signal.addEventListener('abort', () => {
+    unsubscribe();
+  });
+
+  return stream.response();
+});
+```
+
+### Durable Objects (Cloudflare)
+
+```typescript
+import { createDurableObjectRoom } from '@parsrun/realtime/adapters/durable-objects';
+
+// Define room class
+export class ChatRoom extends createDurableObjectRoom({
+  onConnect: async (ws, state) => {
+    ws.send(JSON.stringify({ type: 'connected' }));
+  },
+
+  onMessage: async (ws, message, state) => {
+    // Broadcast to all connections
+    state.broadcast(message);
+  },
+
+  onDisconnect: async (ws, state) => {
+    // Cleanup
+  },
+}) {}
+
+// In worker
+app.get('/ws/:roomId', async (c) => {
+  const roomId = c.req.param('roomId');
+  const id = env.CHAT_ROOM.idFromName(roomId);
+  const room = env.CHAT_ROOM.get(id);
+
+  return room.fetch(c.req.raw);
+});
+```
+
+### Pub/Sub
+
+```typescript
+import { createPubSub } from '@parsrun/realtime';
+
+const pubsub = createPubSub();
+
+// Subscribe
+const unsubscribe = pubsub.subscribe('channel', (message) => {
+  console.log('Received:', message);
+});
+
+// Publish
+await pubsub.publish('channel', { type: 'update', data: {} });
+
+// Unsubscribe
+unsubscribe();
+```
+
+### Presence
+
+```typescript
+import { createPresence } from '@parsrun/realtime';
+
+const presence = createPresence({
+  heartbeatInterval: 30000,
+});
+
+// Join
+await presence.join('room:123', {
+  userId: 'user:1',
+  data: { name: 'John' },
+});
+
+// Get online users
+const users = await presence.getMembers('room:123');
+
+// Leave
+await presence.leave('room:123', 'user:1');
+```
+
+### Hono Integration
+
+```typescript
+import { createRealtimeMiddleware } from '@parsrun/realtime/hono';
+
+const realtime = createRealtimeMiddleware({
+  pubsub,
+  presence,
+});
+
+app.use('/realtime/*', realtime);
+
+// Routes automatically created:
+// GET /realtime/events/:channel - SSE stream
+// POST /realtime/publish/:channel - Publish message
+// GET /realtime/presence/:room - Get presence
+```
+
+## Exports
+
+```typescript
+import { ... } from '@parsrun/realtime';                      // Main exports
+import { ... } from '@parsrun/realtime/adapters/sse';          // SSE adapter
+import { ... } from '@parsrun/realtime/adapters/durable-objects'; // Durable Objects
+import { ... } from '@parsrun/realtime/hono';                  // Hono integration
+```
+
+## License
+
+MIT

package/dist/adapters/durable-objects.d.ts

@@ -0,0 +1,89 @@
+import { DurableObjectsAdapterOptions, RealtimeAdapter, MessageHandler, RealtimeMessage, PresenceUser } from '../types.js';
+
+/**
+ * @parsrun/realtime - Durable Objects Adapter
+ * Cloudflare Durable Objects adapter for WebSocket-based realtime
+ */
+
+/**
+ * RealtimeChannel Durable Object
+ * Manages a single realtime channel with WebSocket connections
+ *
+ * Usage in wrangler.toml:
+ * ```toml
+ * [durable_objects]
+ * bindings = [{ name = "REALTIME_CHANNELS", class_name = "RealtimeChannelDO" }]
+ *
+ * [[migrations]]
+ * tag = "v1"
+ * new_classes = ["RealtimeChannelDO"]
+ * ```
+ */
+declare class RealtimeChannelDO implements DurableObject {
+    private sessions;
+    private presence;
+    private channelName;
+    private state;
+    constructor(state: DurableObjectState, _env: unknown);
+    fetch(request: Request): Promise<Response>;
+    private handleWebSocketUpgrade;
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(ws: WebSocket, code: number, reason: string, _wasClean: boolean): Promise<void>;
+    webSocketError(ws: WebSocket, _error: unknown): Promise<void>;
+    private handleMessage;
+    private handlePresenceJoin;
+    private handlePresenceUpdate;
+    private handlePresenceLeave;
+    private broadcastPresenceUpdate;
+    private handleBroadcast;
+    private handleGetPresence;
+    private handleGetInfo;
+    private handleSendToUser;
+    private getSessionByWebSocket;
+    private broadcastToAll;
+}
+/**
+ * Durable Objects Adapter
+ * Uses RealtimeChannelDO for channel management
+ */
+declare class DurableObjectsAdapter implements RealtimeAdapter {
+    readonly type: "durable-objects";
+    private namespace;
+    private channelPrefix;
+    private localHandlers;
+    constructor(options: DurableObjectsAdapterOptions);
+    /**
+     * Get Durable Object stub for a channel
+     */
+    getChannelStub(channel: string): DurableObjectStub;
+    /**
+     * Get WebSocket URL for a channel
+     */
+    getWebSocketUrl(channel: string, sessionId: string, userId?: string, baseUrl?: string): string;
+    subscribe(channel: string, sessionId: string, handler: MessageHandler): Promise<void>;
+    unsubscribe(channel: string, sessionId: string): Promise<void>;
+    publish<T = unknown>(channel: string, message: RealtimeMessage<T>): Promise<void>;
+    sendToSession<T = unknown>(_sessionId: string, _message: RealtimeMessage<T>): Promise<boolean>;
+    getSubscribers(channel: string): Promise<string[]>;
+    setPresence<T = unknown>(_channel: string, _sessionId: string, _userId: string, _data: T): Promise<void>;
+    removePresence(_channel: string, _sessionId: string): Promise<void>;
+    getPresence<T = unknown>(channel: string): Promise<PresenceUser<T>[]>;
+    close(): Promise<void>;
+    /**
+     * Get channel info from Durable Object
+     */
+    getChannelInfo(channel: string): Promise<{
+        connections: number;
+        presence: number;
+    }>;
+    /**
+     * Send message to specific user in a channel
+     */
+    sendToUser<T = unknown>(channel: string, userId: string, event: string, data: T): Promise<boolean>;
+}
+/**
+ * Create Durable Objects adapter
+ */
+declare function createDurableObjectsAdapter(options: DurableObjectsAdapterOptions): DurableObjectsAdapter;
+
+export { DurableObjectsAdapter, RealtimeChannelDO, createDurableObjectsAdapter };

package/dist/adapters/durable-objects.js

@@ -0,0 +1,414 @@
+// src/types.ts
+function createMessage(options) {
+  return {
+    id: crypto.randomUUID(),
+    event: options.event,
+    channel: options.channel,
+    data: options.data,
+    senderId: options.senderId,
+    timestamp: Date.now(),
+    metadata: options.metadata
+  };
+}
+
+// src/adapters/durable-objects.ts
+var RealtimeChannelDO = class {
+  sessions = /* @__PURE__ */ new Map();
+  presence = /* @__PURE__ */ new Map();
+  channelName = "";
+  state;
+  constructor(state, _env) {
+    this.state = state;
+    this.state.getWebSockets().forEach((ws) => {
+      const meta = ws.deserializeAttachment();
+      if (meta) {
+        this.sessions.set(meta.sessionId, {
+          sessionId: meta.sessionId,
+          userId: meta.userId,
+          webSocket: ws,
+          state: "open",
+          createdAt: Date.now()
+        });
+      }
+    });
+  }
+  async fetch(request) {
+    const url = new URL(request.url);
+    const pathParts = url.pathname.split("/").filter(Boolean);
+    const lastPart = pathParts[pathParts.length - 1];
+    if (lastPart) {
+      this.channelName = lastPart;
+    }
+    if (request.headers.get("Upgrade") === "websocket") {
+      return this.handleWebSocketUpgrade(request);
+    }
+    switch (url.pathname.split("/").pop()) {
+      case "broadcast":
+        return this.handleBroadcast(request);
+      case "presence":
+        return this.handleGetPresence();
+      case "info":
+        return this.handleGetInfo();
+      case "send":
+        return this.handleSendToUser(request);
+      default:
+        return new Response("Not found", { status: 404 });
+    }
+  }
+  // ============================================================================
+  // WebSocket Handling
+  // ============================================================================
+  handleWebSocketUpgrade(request) {
+    const url = new URL(request.url);
+    const sessionId = url.searchParams.get("sessionId") || crypto.randomUUID();
+    const userId = url.searchParams.get("userId") || void 0;
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    server.serializeAttachment({ sessionId, userId });
+    this.state.acceptWebSocket(server);
+    const session = {
+      sessionId,
+      userId,
+      webSocket: server,
+      state: "open",
+      createdAt: Date.now()
+    };
+    this.sessions.set(sessionId, session);
+    server.send(
+      JSON.stringify(
+        createMessage({
+          event: "connection:open",
+          channel: this.channelName,
+          data: { sessionId, userId }
+        })
+      )
+    );
+    return new Response(null, { status: 101, webSocket: client });
+  }
+  async webSocketMessage(ws, message) {
+    const session = this.getSessionByWebSocket(ws);
+    if (!session) return;
+    try {
+      const data = typeof message === "string" ? message : new TextDecoder().decode(message);
+      const parsed = JSON.parse(data);
+      await this.handleMessage(session, parsed);
+    } catch {
+    }
+  }
+  async webSocketClose(ws, code, reason, _wasClean) {
+    const session = this.getSessionByWebSocket(ws);
+    if (!session) return;
+    this.presence.delete(session.sessionId);
+    await this.broadcastPresenceUpdate();
+    this.sessions.delete(session.sessionId);
+    await this.broadcastToAll({
+      event: "connection:close",
+      channel: this.channelName,
+      data: {
+        sessionId: session.sessionId,
+        userId: session.userId,
+        code,
+        reason
+      }
+    });
+  }
+  async webSocketError(ws, _error) {
+    const session = this.getSessionByWebSocket(ws);
+    if (session) {
+      session.state = "closed";
+      this.sessions.delete(session.sessionId);
+      this.presence.delete(session.sessionId);
+    }
+  }
+  // ============================================================================
+  // Message Handling
+  // ============================================================================
+  async handleMessage(session, message) {
+    switch (message.event) {
+      case "ping":
+        session.webSocket.send(
+          JSON.stringify(
+            createMessage({
+              event: "pong",
+              channel: this.channelName,
+              data: { timestamp: Date.now() }
+            })
+          )
+        );
+        break;
+      case "presence:join":
+        await this.handlePresenceJoin(session, message.data);
+        break;
+      case "presence:update":
+        await this.handlePresenceUpdate(session, message.data);
+        break;
+      case "presence:leave":
+        await this.handlePresenceLeave(session);
+        break;
+      case "broadcast":
+        await this.broadcastToAll(
+          {
+            event: message.event,
+            channel: this.channelName,
+            data: message.data,
+            senderId: session.sessionId
+          },
+          session.sessionId
+        );
+        break;
+      default:
+        await this.broadcastToAll(
+          {
+            event: message.event,
+            channel: this.channelName,
+            data: message.data,
+            senderId: session.sessionId
+          },
+          session.sessionId
+        );
+    }
+  }
+  // ============================================================================
+  // Presence Handling
+  // ============================================================================
+  async handlePresenceJoin(session, data) {
+    const now = Date.now();
+    const user = {
+      userId: session.userId || session.sessionId,
+      sessionId: session.sessionId,
+      data,
+      joinedAt: now,
+      lastSeenAt: now
+    };
+    this.presence.set(session.sessionId, user);
+    session.presence = data;
+    await this.broadcastPresenceUpdate();
+  }
+  async handlePresenceUpdate(session, data) {
+    const existing = this.presence.get(session.sessionId);
+    if (existing) {
+      existing.data = data;
+      existing.lastSeenAt = Date.now();
+      session.presence = data;
+      await this.broadcastPresenceUpdate();
+    }
+  }
+  async handlePresenceLeave(session) {
+    this.presence.delete(session.sessionId);
+    session.presence = void 0;
+    await this.broadcastPresenceUpdate();
+  }
+  async broadcastPresenceUpdate() {
+    const presenceList = Array.from(this.presence.values());
+    await this.broadcastToAll({
+      event: "presence:sync",
+      channel: this.channelName,
+      data: presenceList
+    });
+  }
+  // ============================================================================
+  // REST API Handlers
+  // ============================================================================
+  async handleBroadcast(request) {
+    try {
+      const body = await request.json();
+      await this.broadcastToAll({
+        event: body.event,
+        channel: this.channelName,
+        data: body.data
+      });
+      return new Response(JSON.stringify({ success: true }), {
+        headers: { "Content-Type": "application/json" }
+      });
+    } catch (err) {
+      return new Response(
+        JSON.stringify({ success: false, error: String(err) }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+  }
+  handleGetPresence() {
+    const presenceList = Array.from(this.presence.values());
+    return new Response(JSON.stringify(presenceList), {
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  handleGetInfo() {
+    return new Response(
+      JSON.stringify({
+        channel: this.channelName,
+        connections: this.sessions.size,
+        presence: this.presence.size
+      }),
+      { headers: { "Content-Type": "application/json" } }
+    );
+  }
+  async handleSendToUser(request) {
+    try {
+      const body = await request.json();
+      let sent = false;
+      for (const session of this.sessions.values()) {
+        if (session.userId === body.userId && session.state === "open") {
+          session.webSocket.send(
+            JSON.stringify(
+              createMessage({
+                event: body.event,
+                channel: this.channelName,
+                data: body.data
+              })
+            )
+          );
+          sent = true;
+        }
+      }
+      return new Response(JSON.stringify({ success: true, sent }), {
+        headers: { "Content-Type": "application/json" }
+      });
+    } catch (err) {
+      return new Response(
+        JSON.stringify({ success: false, error: String(err) }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+  }
+  // ============================================================================
+  // Helpers
+  // ============================================================================
+  getSessionByWebSocket(ws) {
+    for (const session of this.sessions.values()) {
+      if (session.webSocket === ws) {
+        return session;
+      }
+    }
+    return void 0;
+  }
+  async broadcastToAll(messageData, excludeSessionId) {
+    const message = createMessage(messageData);
+    const payload = JSON.stringify(message);
+    for (const session of this.sessions.values()) {
+      if (session.sessionId === excludeSessionId) continue;
+      if (session.state !== "open") continue;
+      try {
+        session.webSocket.send(payload);
+      } catch {
+        session.state = "closed";
+      }
+    }
+  }
+};
+var DurableObjectsAdapter = class {
+  type = "durable-objects";
+  namespace;
+  channelPrefix;
+  localHandlers = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.namespace = options.namespace;
+    this.channelPrefix = options.channelPrefix ?? "channel:";
+  }
+  /**
+   * Get Durable Object stub for a channel
+   */
+  getChannelStub(channel) {
+    const id = this.namespace.idFromName(`${this.channelPrefix}${channel}`);
+    return this.namespace.get(id);
+  }
+  /**
+   * Get WebSocket URL for a channel
+   */
+  getWebSocketUrl(channel, sessionId, userId, baseUrl) {
+    const base = baseUrl || "wss://your-worker.your-subdomain.workers.dev";
+    const params = new URLSearchParams({ sessionId });
+    if (userId) params.set("userId", userId);
+    return `${base}/realtime/${channel}?${params}`;
+  }
+  // ============================================================================
+  // RealtimeAdapter Implementation
+  // ============================================================================
+  async subscribe(channel, sessionId, handler) {
+    if (!this.localHandlers.has(channel)) {
+      this.localHandlers.set(channel, /* @__PURE__ */ new Map());
+    }
+    this.localHandlers.get(channel).set(sessionId, handler);
+  }
+  async unsubscribe(channel, sessionId) {
+    const handlers = this.localHandlers.get(channel);
+    if (handlers) {
+      handlers.delete(sessionId);
+      if (handlers.size === 0) {
+        this.localHandlers.delete(channel);
+      }
+    }
+  }
+  async publish(channel, message) {
+    const stub = this.getChannelStub(channel);
+    await stub.fetch(new Request("https://do/broadcast", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        event: message.event,
+        data: message.data
+      })
+    }));
+    const handlers = this.localHandlers.get(channel);
+    if (handlers) {
+      for (const handler of handlers.values()) {
+        try {
+          await handler(message);
+        } catch {
+        }
+      }
+    }
+  }
+  async sendToSession(_sessionId, _message) {
+    return false;
+  }
+  async getSubscribers(channel) {
+    const handlers = this.localHandlers.get(channel);
+    return handlers ? Array.from(handlers.keys()) : [];
+  }
+  async setPresence(_channel, _sessionId, _userId, _data) {
+  }
+  async removePresence(_channel, _sessionId) {
+  }
+  async getPresence(channel) {
+    const stub = this.getChannelStub(channel);
+    const response = await stub.fetch(new Request("https://do/presence"));
+    return response.json();
+  }
+  async close() {
+    this.localHandlers.clear();
+  }
+  /**
+   * Get channel info from Durable Object
+   */
+  async getChannelInfo(channel) {
+    const stub = this.getChannelStub(channel);
+    const response = await stub.fetch(new Request("https://do/info"));
+    return response.json();
+  }
+  /**
+   * Send message to specific user in a channel
+   */
+  async sendToUser(channel, userId, event, data) {
+    const stub = this.getChannelStub(channel);
+    const response = await stub.fetch(
+      new Request("https://do/send", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ userId, event, data })
+      })
+    );
+    const result = await response.json();
+    return result.sent;
+  }
+};
+function createDurableObjectsAdapter(options) {
+  return new DurableObjectsAdapter(options);
+}
+export {
+  DurableObjectsAdapter,
+  RealtimeChannelDO,
+  createDurableObjectsAdapter
+};
+//# sourceMappingURL=durable-objects.js.map