@objectstack/service-realtime 4.0.3 → 4.0.5

package/README.md

@@ -0,0 +1,438 @@
+# @objectstack/service-realtime
+
+Realtime Service for ObjectStack — implements `IRealtimeService` with WebSocket and in-memory pub/sub.
+
+## Features
+
+- **WebSocket Support**: Real-time bidirectional communication
+- **Pub/Sub Pattern**: Subscribe to channels and receive updates
+- **Room-Based Architecture**: Organize connections into rooms
+- **Presence Tracking**: Track online users and their status
+- **Message Broadcasting**: Send messages to all connections or specific rooms
+- **Event Streaming**: Stream database changes and system events
+- **Auto-Reconnection**: Client auto-reconnects on connection loss
+- **Type-Safe**: Full TypeScript support for events and messages
+
+## Installation
+
+```bash
+pnpm add @objectstack/service-realtime
+```
+
+## Basic Usage
+
+```typescript
+import { defineStack } from '@objectstack/spec';
+import { ServiceRealtime } from '@objectstack/service-realtime';
+
+const stack = defineStack({
+  services: [
+    ServiceRealtime.configure({
+      port: 3001,
+      path: '/ws',
+    }),
+  ],
+});
+```
+
+## Configuration
+
+```typescript
+interface RealtimeServiceConfig {
+  /** WebSocket server port (default: 3001) */
+  port?: number;
+
+  /** WebSocket path (default: '/ws') */
+  path?: string;
+
+  /** Enable CORS (default: true) */
+  cors?: boolean;
+
+  /** Maximum connections per user (default: 10) */
+  maxConnectionsPerUser?: number;
+
+  /** Ping interval in ms (default: 30000) */
+  pingInterval?: number;
+}
+```
+
+## Service API (Server-Side)
+
+```typescript
+// Get realtime service
+const realtime = kernel.getService<IRealtimeService>('realtime');
+```
+
+### Broadcasting
+
+```typescript
+// Broadcast to all connected clients
+await realtime.broadcast({
+  event: 'notification',
+  data: { message: 'System update in 5 minutes' },
+});
+
+// Broadcast to specific room
+await realtime.broadcastToRoom('opportunity:123', {
+  event: 'record_updated',
+  data: { recordId: '123', field: 'stage', value: 'closed_won' },
+});
+
+// Broadcast to specific user
+await realtime.broadcastToUser('user:456', {
+  event: 'mention',
+  data: { commentId: 'comment:789', mentionedBy: 'user:123' },
+});
+```
+
+### Channel Management
+
+```typescript
+// Join a channel (room)
+await realtime.join(connectionId, 'opportunity:123');
+
+// Leave a channel
+await realtime.leave(connectionId, 'opportunity:123');
+
+// Get all connections in a channel
+const connections = await realtime.getChannelConnections('opportunity:123');
+
+// Get all channels for a connection
+const channels = await realtime.getConnectionChannels(connectionId);
+```
+
+### Presence
+
+```typescript
+// Set user presence
+await realtime.setPresence('user:456', {
+  status: 'online',
+  currentPage: '/opportunity/123',
+  lastActive: new Date(),
+});
+
+// Get user presence
+const presence = await realtime.getPresence('user:456');
+
+// Get all online users
+const onlineUsers = await realtime.getOnlineUsers();
+
+// Get users in a specific channel
+const channelUsers = await realtime.getChannelPresence('opportunity:123');
+```
+
+## Client-Side Usage
+
+### React Hook
+
+```typescript
+import { useRealtime } from '@objectstack/client-react';
+
+function OpportunityDetails({ id }: { id: string }) {
+  const { subscribe, send, isConnected } = useRealtime();
+
+  useEffect(() => {
+    // Subscribe to record updates
+    const unsubscribe = subscribe(`opportunity:${id}`, (event) => {
+      if (event.type === 'record_updated') {
+        console.log('Record updated:', event.data);
+        // Update UI
+      }
+    });
+
+    return unsubscribe;
+  }, [id]);
+
+  return (
+    <div>
+      {isConnected ? '🟢 Connected' : '🔴 Disconnected'}
+    </div>
+  );
+}
+```
+
+### JavaScript Client
+
+```typescript
+import { RealtimeClient } from '@objectstack/client';
+
+const client = new RealtimeClient({
+  url: 'ws://localhost:3001/ws',
+  auth: {
+    token: 'your-auth-token',
+  },
+});
+
+// Connect
+await client.connect();
+
+// Subscribe to a channel
+client.subscribe('opportunity:123', (event) => {
+  console.log('Received event:', event);
+});
+
+// Send a message
+client.send('typing', {
+  recordId: '123',
+  userId: 'user:456',
+  isTyping: true,
+});
+
+// Disconnect
+await client.disconnect();
+```
+
+## Advanced Features
+
+### Event Streaming
+
+Stream database changes in real-time:
+
+```typescript
+// Server-side: Stream record changes
+realtime.streamRecordChanges('opportunity', {
+  onInsert: async (record) => {
+    await realtime.broadcast({
+      event: 'record_created',
+      data: { object: 'opportunity', record },
+    });
+  },
+  onUpdate: async (record, changes) => {
+    await realtime.broadcastToRoom(`opportunity:${record.id}`, {
+      event: 'record_updated',
+      data: { recordId: record.id, changes },
+    });
+  },
+  onDelete: async (recordId) => {
+    await realtime.broadcast({
+      event: 'record_deleted',
+      data: { object: 'opportunity', recordId },
+    });
+  },
+});
+```
+
+### Private Channels
+
+```typescript
+// Server-side: Authorize private channel access
+realtime.authorizeChannel = async (userId, channel) => {
+  if (channel.startsWith('user:')) {
+    // Only allow users to join their own private channel
+    return channel === `user:${userId}`;
+  }
+
+  if (channel.startsWith('opportunity:')) {
+    // Check if user has access to the opportunity
+    const opportunityId = channel.split(':')[1];
+    return await hasAccess(userId, 'opportunity', opportunityId);
+  }
+
+  return false;
+};
+```
+
+### Typing Indicators
+
+```typescript
+// Client sends typing event
+client.send('typing', {
+  recordId: '123',
+  userId: 'user:456',
+  isTyping: true,
+});
+
+// Server broadcasts to room
+realtime.on('typing', async (connectionId, data) => {
+  await realtime.broadcastToRoom(`opportunity:${data.recordId}`, {
+    event: 'user_typing',
+    data: { userId: data.userId, isTyping: data.isTyping },
+  }, { exclude: [connectionId] }); // Don't send back to sender
+});
+
+// Other clients receive typing notification
+client.subscribe('opportunity:123', (event) => {
+  if (event.type === 'user_typing') {
+    showTypingIndicator(event.data.userId, event.data.isTyping);
+  }
+});
+```
+
+### Live Cursor Tracking
+
+```typescript
+// Client sends cursor position
+client.send('cursor', {
+  recordId: '123',
+  x: 450,
+  y: 200,
+});
+
+// Server broadcasts to room
+realtime.on('cursor', async (connectionId, data) => {
+  const user = await getConnectionUser(connectionId);
+
+  await realtime.broadcastToRoom(`opportunity:${data.recordId}`, {
+    event: 'cursor_moved',
+    data: {
+      userId: user.id,
+      userName: user.name,
+      x: data.x,
+      y: data.y,
+    },
+  }, { exclude: [connectionId] });
+});
+```
+
+### Collaborative Editing
+
+```typescript
+// Operational Transform (OT) for collaborative editing
+client.send('edit', {
+  documentId: '123',
+  operation: {
+    type: 'insert',
+    position: 42,
+    text: 'Hello',
+  },
+});
+
+realtime.on('edit', async (connectionId, data) => {
+  // Apply operation transform
+  const transformedOp = await applyOT(data.operation);
+
+  // Broadcast to all editors
+  await realtime.broadcastToRoom(`document:${data.documentId}`, {
+    event: 'operation',
+    data: transformedOp,
+  }, { exclude: [connectionId] });
+});
+```
+
+## Integration with ObjectStack Features
+
+### Feed Updates
+
+```typescript
+// When a comment is added
+feed.on('comment_added', async (comment) => {
+  await realtime.broadcastToRoom(`${comment.object}:${comment.recordId}`, {
+    event: 'feed_update',
+    data: { type: 'comment', comment },
+  });
+});
+```
+
+### Workflow Status
+
+```typescript
+// When a flow step completes
+automation.on('step_completed', async (execution) => {
+  await realtime.broadcastToUser(execution.userId, {
+    event: 'flow_progress',
+    data: {
+      flowId: execution.flowId,
+      step: execution.currentStep,
+      progress: execution.progress,
+    },
+  });
+});
+```
+
+### Analytics Dashboard
+
+```typescript
+// Stream real-time metrics
+setInterval(async () => {
+  const metrics = await analytics.getCurrentMetrics();
+
+  await realtime.broadcastToRoom('dashboard:sales', {
+    event: 'metrics_update',
+    data: metrics,
+  });
+}, 5000); // Every 5 seconds
+```
+
+## Connection Events
+
+```typescript
+// Server-side event handlers
+realtime.on('connection', async (connectionId, userId) => {
+  console.log(`User ${userId} connected (${connectionId})`);
+
+  // Set initial presence
+  await realtime.setPresence(userId, { status: 'online' });
+});
+
+realtime.on('disconnection', async (connectionId, userId) => {
+  console.log(`User ${userId} disconnected`);
+
+  // Update presence
+  await realtime.setPresence(userId, {
+    status: 'offline',
+    lastSeen: new Date(),
+  });
+});
+
+realtime.on('error', async (connectionId, error) => {
+  console.error(`Connection error:`, error);
+});
+```
+
+## Best Practices
+
+1. **Channel Organization**: Use namespaced channels (e.g., `object:recordId`)
+2. **Authorization**: Always verify channel access before joining
+3. **Message Size**: Keep messages small (< 10KB)
+4. **Rate Limiting**: Limit message frequency per connection
+5. **Cleanup**: Remove disconnected users from channels
+6. **Heartbeat**: Implement ping/pong for connection health
+7. **Compression**: Enable WebSocket compression for large messages
+
+## Performance Considerations
+
+- **Scaling**: Use Redis adapter for multi-server deployments
+- **Connection Pooling**: Limit concurrent connections per user
+- **Channel Limits**: Limit channels per connection
+- **Message Batching**: Batch frequent updates to reduce traffic
+- **Binary Protocol**: Use binary for large data transfers
+
+## REST API Endpoints
+
+```
+POST   /api/v1/realtime/broadcast              # Broadcast to all
+POST   /api/v1/realtime/broadcast/room/:room   # Broadcast to room
+POST   /api/v1/realtime/broadcast/user/:userId # Broadcast to user
+GET    /api/v1/realtime/presence                # Get online users
+GET    /api/v1/realtime/presence/:userId        # Get user presence
+GET    /api/v1/realtime/channels/:channel       # Get channel connections
+```
+
+## Contract Implementation
+
+Implements `IRealtimeService` from `@objectstack/spec/contracts`:
+
+```typescript
+interface IRealtimeService {
+  broadcast(message: Message): Promise<void>;
+  broadcastToRoom(room: string, message: Message): Promise<void>;
+  broadcastToUser(userId: string, message: Message): Promise<void>;
+  join(connectionId: string, channel: string): Promise<void>;
+  leave(connectionId: string, channel: string): Promise<void>;
+  setPresence(userId: string, presence: PresenceData): Promise<void>;
+  getPresence(userId: string): Promise<PresenceData | null>;
+  getOnlineUsers(): Promise<string[]>;
+  on(event: string, handler: EventHandler): void;
+}
+```
+
+## License
+
+Apache-2.0
+
+## See Also
+
+- [WebSocket API Documentation](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
+- [@objectstack/client](../../client/)
+- [@objectstack/client-react](../../client-react/)
+- [Realtime Features Guide](/content/docs/guides/realtime/)

package/dist/index.cjs

@@ -21,11 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   InMemoryRealtimeAdapter: () => InMemoryRealtimeAdapter,
-  RealtimeServicePlugin: () => RealtimeServicePlugin,
-  SysPresence: () => SysPresence
+  RealtimeServicePlugin: () => RealtimeServicePlugin
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/realtime-service-plugin.ts
+var import_audit = require("@objectstack/platform-objects/audit");
+
 // src/in-memory-realtime-adapter.ts
 var InMemoryRealtimeAdapter = class {
   constructor(options = {}) {
@@ -101,100 +103,6 @@ var InMemoryRealtimeAdapter = class {
   }
 };
 
-// src/objects/sys-presence.object.ts
-var import_data = require("@objectstack/spec/data");
-var SysPresence = import_data.ObjectSchema.create({
-  namespace: "sys",
-  name: "presence",
-  label: "Presence",
-  pluralLabel: "Presences",
-  icon: "wifi",
-  isSystem: true,
-  description: "Real-time user presence and activity tracking",
-  titleFormat: "{user_id} ({status})",
-  compactLayout: ["user_id", "status", "last_seen"],
-  fields: {
-    id: import_data.Field.text({
-      label: "Presence ID",
-      required: true,
-      readonly: true
-    }),
-    created_at: import_data.Field.datetime({
-      label: "Created At",
-      defaultValue: "NOW()",
-      readonly: true
-    }),
-    updated_at: import_data.Field.datetime({
-      label: "Updated At",
-      defaultValue: "NOW()",
-      readonly: true
-    }),
-    user_id: import_data.Field.text({
-      label: "User ID",
-      required: true,
-      searchable: true
-    }),
-    session_id: import_data.Field.text({
-      label: "Session ID",
-      required: true
-    }),
-    status: import_data.Field.select({
-      label: "Status",
-      required: true,
-      defaultValue: "online",
-      options: [
-        { value: "online", label: "Online" },
-        { value: "away", label: "Away" },
-        { value: "busy", label: "Busy" },
-        { value: "offline", label: "Offline" }
-      ]
-    }),
-    last_seen: import_data.Field.datetime({
-      label: "Last Seen",
-      required: true,
-      defaultValue: "NOW()"
-    }),
-    current_location: import_data.Field.text({
-      label: "Current Location",
-      required: false,
-      maxLength: 500
-    }),
-    device: import_data.Field.select({
-      label: "Device",
-      required: false,
-      options: [
-        { value: "desktop", label: "Desktop" },
-        { value: "mobile", label: "Mobile" },
-        { value: "tablet", label: "Tablet" },
-        { value: "other", label: "Other" }
-      ]
-    }),
-    custom_status: import_data.Field.text({
-      label: "Custom Status",
-      required: false,
-      maxLength: 255
-    }),
-    metadata: import_data.Field.json({
-      label: "Metadata",
-      required: false,
-      description: "Arbitrary JSON metadata associated with the presence state (matches PresenceStateSchema.metadata)."
-    })
-  },
-  indexes: [
-    { fields: ["user_id"], unique: false },
-    { fields: ["session_id"], unique: true },
-    { fields: ["status"], unique: false }
-  ],
-  enable: {
-    trackHistory: false,
-    searchable: false,
-    apiEnabled: true,
-    apiMethods: ["get", "list", "create", "update", "delete"],
-    trash: false,
-    mru: false
-  }
-});
-
 // src/realtime-service-plugin.ts
 var RealtimeServicePlugin = class {
   constructor(options = {}) {
@@ -213,7 +121,7 @@ var RealtimeServicePlugin = class {
       version: "1.0.0",
       type: "plugin",
       namespace: "sys",
-      objects: [SysPresence]
+      objects: [import_audit.SysPresence]
     });
     ctx.logger.info("RealtimeServicePlugin: registered in-memory realtime adapter");
   }
@@ -221,7 +129,6 @@ var RealtimeServicePlugin = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   InMemoryRealtimeAdapter,
-  RealtimeServicePlugin,
-  SysPresence
+  RealtimeServicePlugin
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/in-memory-realtime-adapter.ts","../src/objects/sys-presence.object.ts","../src/realtime-service-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport { RealtimeServicePlugin } from './realtime-service-plugin.js';\nexport type { RealtimeServicePluginOptions } from './realtime-service-plugin.js';\nexport { InMemoryRealtimeAdapter } from './in-memory-realtime-adapter.js';\nexport type { InMemoryRealtimeAdapterOptions } from './in-memory-realtime-adapter.js';\nexport { SysPresence } from './objects/index.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n  IRealtimeService,\n  RealtimeEventPayload,\n  RealtimeEventHandler,\n  RealtimeSubscriptionOptions,\n} from '@objectstack/spec/contracts';\n\n/**\n * Internal subscription entry.\n */\ninterface Subscription {\n  id: string;\n  channel: string;\n  handler: RealtimeEventHandler;\n  options?: RealtimeSubscriptionOptions;\n}\n\n/**\n * Configuration options for InMemoryRealtimeAdapter.\n */\nexport interface InMemoryRealtimeAdapterOptions {\n  /** Maximum number of subscriptions allowed (0 = unlimited) */\n  maxSubscriptions?: number;\n}\n\n/**\n * In-memory pub/sub adapter implementing IRealtimeService.\n *\n * Uses a Map-backed subscription store with channel-based routing.\n * Supports event type and object filtering via subscription options.\n *\n * Suitable for single-process environments, development, and testing.\n * For production multi-instance deployments, use a Redis-backed adapter.\n *\n * @example\n * ```ts\n * const realtime = new InMemoryRealtimeAdapter();\n *\n * const subId = await realtime.subscribe('records', (event) => {\n *   console.log('Received:', event.type, event.payload);\n * }, { object: 'account', eventTypes: ['record.created'] });\n *\n * await realtime.publish({\n *   type: 'record.created',\n *   object: 'account',\n *   payload: { id: 'acc-1', name: 'Acme' },\n *   timestamp: new Date().toISOString(),\n * });\n *\n * await realtime.unsubscribe(subId);\n * ```\n */\nexport class InMemoryRealtimeAdapter implements IRealtimeService {\n  private readonly subscriptions = new Map<string, Subscription>();\n  private readonly channelIndex = new Map<string, Set<string>>();\n  private counter = 0;\n  private readonly maxSubscriptions: number;\n\n  constructor(options: InMemoryRealtimeAdapterOptions = {}) {\n    this.maxSubscriptions = options.maxSubscriptions ?? 0;\n  }\n\n  async publish(event: RealtimeEventPayload): Promise<void> {\n    // Deliver to all channel subscriptions that match filters\n    for (const sub of this.subscriptions.values()) {\n      if (this.matchesSubscription(event, sub)) {\n        try {\n          await sub.handler(event);\n        } catch {\n          // Swallow handler errors to avoid breaking the publish loop\n        }\n      }\n    }\n  }\n\n  async subscribe(\n    channel: string,\n    handler: RealtimeEventHandler,\n    options?: RealtimeSubscriptionOptions,\n  ): Promise<string> {\n    if (this.maxSubscriptions > 0 && this.subscriptions.size >= this.maxSubscriptions) {\n      throw new Error(\n        `Maximum subscription limit reached (${this.maxSubscriptions}). ` +\n        'Unsubscribe from existing channels before adding new subscriptions.',\n      );\n    }\n\n    const id = `sub-${++this.counter}`;\n    const sub: Subscription = { id, channel, handler, options };\n    this.subscriptions.set(id, sub);\n\n    // Maintain channel index for efficient lookups\n    if (!this.channelIndex.has(channel)) {\n      this.channelIndex.set(channel, new Set());\n    }\n    this.channelIndex.get(channel)!.add(id);\n\n    return id;\n  }\n\n  async unsubscribe(subscriptionId: string): Promise<void> {\n    const sub = this.subscriptions.get(subscriptionId);\n    if (!sub) return;\n\n    this.subscriptions.delete(subscriptionId);\n\n    // Clean up channel index\n    const channelSubs = this.channelIndex.get(sub.channel);\n    if (channelSubs) {\n      channelSubs.delete(subscriptionId);\n      if (channelSubs.size === 0) {\n        this.channelIndex.delete(sub.channel);\n      }\n    }\n  }\n\n  /**\n   * Get the number of active subscriptions.\n   */\n  getSubscriptionCount(): number {\n    return this.subscriptions.size;\n  }\n\n  /**\n   * Get all active channel names.\n   */\n  getChannels(): string[] {\n    return Array.from(this.channelIndex.keys());\n  }\n\n  /**\n   * Check if an event matches a subscription's filters.\n   */\n  private matchesSubscription(event: RealtimeEventPayload, sub: Subscription): boolean {\n    const opts = sub.options;\n    if (!opts) return true;\n\n    // Filter by object name\n    if (opts.object && event.object !== opts.object) {\n      return false;\n    }\n\n    // Filter by event types\n    if (opts.eventTypes && opts.eventTypes.length > 0) {\n      if (!opts.eventTypes.includes(event.type)) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport { ObjectSchema, Field } from '@objectstack/spec/data';\n\n/**\n * sys_presence — System Presence Object\n *\n * Tracks real-time user presence and activity across the platform.\n * Fields align with the PresenceStateSchema protocol definition\n * from `@objectstack/spec/api` (websocket.zod.ts).\n *\n * Owned by `service-realtime` as the canonical Presence domain object.\n *\n * @namespace sys\n * @see PresenceStateSchema in packages/spec/src/api/websocket.zod.ts\n */\nexport const SysPresence = ObjectSchema.create({\n  namespace: 'sys',\n  name: 'presence',\n  label: 'Presence',\n  pluralLabel: 'Presences',\n  icon: 'wifi',\n  isSystem: true,\n  description: 'Real-time user presence and activity tracking',\n  titleFormat: '{user_id} ({status})',\n  compactLayout: ['user_id', 'status', 'last_seen'],\n\n  fields: {\n    id: Field.text({\n      label: 'Presence ID',\n      required: true,\n      readonly: true,\n    }),\n\n    created_at: Field.datetime({\n      label: 'Created At',\n      defaultValue: 'NOW()',\n      readonly: true,\n    }),\n\n    updated_at: Field.datetime({\n      label: 'Updated At',\n      defaultValue: 'NOW()',\n      readonly: true,\n    }),\n\n    user_id: Field.text({\n      label: 'User ID',\n      required: true,\n      searchable: true,\n    }),\n\n    session_id: Field.text({\n      label: 'Session ID',\n      required: true,\n    }),\n\n    status: Field.select({\n      label: 'Status',\n      required: true,\n      defaultValue: 'online',\n      options: [\n        { value: 'online', label: 'Online' },\n        { value: 'away', label: 'Away' },\n        { value: 'busy', label: 'Busy' },\n        { value: 'offline', label: 'Offline' },\n      ],\n    }),\n\n    last_seen: Field.datetime({\n      label: 'Last Seen',\n      required: true,\n      defaultValue: 'NOW()',\n    }),\n\n    current_location: Field.text({\n      label: 'Current Location',\n      required: false,\n      maxLength: 500,\n    }),\n\n    device: Field.select({\n      label: 'Device',\n      required: false,\n      options: [\n        { value: 'desktop', label: 'Desktop' },\n        { value: 'mobile', label: 'Mobile' },\n        { value: 'tablet', label: 'Tablet' },\n        { value: 'other', label: 'Other' },\n      ],\n    }),\n\n    custom_status: Field.text({\n      label: 'Custom Status',\n      required: false,\n      maxLength: 255,\n    }),\n\n    metadata: Field.json({\n      label: 'Metadata',\n      required: false,\n      description: 'Arbitrary JSON metadata associated with the presence state (matches PresenceStateSchema.metadata).',\n    }),\n  },\n\n  indexes: [\n    { fields: ['user_id'], unique: false },\n    { fields: ['session_id'], unique: true },\n    { fields: ['status'], unique: false },\n  ],\n\n  enable: {\n    trackHistory: false,\n    searchable: false,\n    apiEnabled: true,\n    apiMethods: ['get', 'list', 'create', 'update', 'delete'],\n    trash: false,\n    mru: false,\n  },\n});\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { InMemoryRealtimeAdapter } from './in-memory-realtime-adapter.js';\nimport type { InMemoryRealtimeAdapterOptions } from './in-memory-realtime-adapter.js';\nimport { SysPresence } from './objects/index.js';\n\n/**\n * Configuration options for the RealtimeServicePlugin.\n */\nexport interface RealtimeServicePluginOptions {\n  /** Realtime adapter type (default: 'memory') */\n  adapter?: 'memory';\n  /** Options for the in-memory adapter */\n  memory?: InMemoryRealtimeAdapterOptions;\n}\n\n/**\n * RealtimeServicePlugin — Production IRealtimeService implementation.\n *\n * Registers a realtime pub/sub service with the kernel during the init phase.\n * Currently supports in-memory pub/sub for single-process environments.\n *\n * @example\n * ```ts\n * import { ObjectKernel } from '@objectstack/core';\n * import { RealtimeServicePlugin } from '@objectstack/service-realtime';\n *\n * const kernel = new ObjectKernel();\n * kernel.use(new RealtimeServicePlugin());\n * await kernel.bootstrap();\n *\n * const realtime = kernel.getService('realtime');\n * await realtime.subscribe('records', (event) => {\n *   console.log(event.type, event.payload);\n * });\n * ```\n */\nexport class RealtimeServicePlugin implements Plugin {\n  name = 'com.objectstack.service.realtime';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private readonly options: RealtimeServicePluginOptions;\n\n  constructor(options: RealtimeServicePluginOptions = {}) {\n    this.options = { adapter: 'memory', ...options };\n  }\n\n  async init(ctx: PluginContext): Promise<void> {\n    const realtime = new InMemoryRealtimeAdapter(this.options.memory);\n    ctx.registerService('realtime', realtime);\n\n    // Register realtime system objects via the manifest service.\n    ctx.getService<{ register(m: any): void }>('manifest').register({\n      id: 'com.objectstack.service.realtime',\n      name: 'Realtime Service',\n      version: '1.0.0',\n      type: 'plugin',\n      namespace: 'sys',\n      objects: [SysPresence],\n    });\n\n    ctx.logger.info('RealtimeServicePlugin: registered in-memory realtime adapter');\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/realtime-service-plugin.ts","../src/in-memory-realtime-adapter.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport { RealtimeServicePlugin } from './realtime-service-plugin.js';\nexport type { RealtimeServicePluginOptions } from './realtime-service-plugin.js';\nexport { InMemoryRealtimeAdapter } from './in-memory-realtime-adapter.js';\nexport type { InMemoryRealtimeAdapterOptions } from './in-memory-realtime-adapter.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { SysPresence } from '@objectstack/platform-objects/audit';\nimport { InMemoryRealtimeAdapter } from './in-memory-realtime-adapter.js';\nimport type { InMemoryRealtimeAdapterOptions } from './in-memory-realtime-adapter.js';\n\n/**\n * Configuration options for the RealtimeServicePlugin.\n */\nexport interface RealtimeServicePluginOptions {\n  /** Realtime adapter type (default: 'memory') */\n  adapter?: 'memory';\n  /** Options for the in-memory adapter */\n  memory?: InMemoryRealtimeAdapterOptions;\n}\n\n/**\n * RealtimeServicePlugin — Production IRealtimeService implementation.\n *\n * Registers a realtime pub/sub service with the kernel during the init phase.\n * Currently supports in-memory pub/sub for single-process environments.\n *\n * @example\n * ```ts\n * import { ObjectKernel } from '@objectstack/core';\n * import { RealtimeServicePlugin } from '@objectstack/service-realtime';\n *\n * const kernel = new ObjectKernel();\n * kernel.use(new RealtimeServicePlugin());\n * await kernel.bootstrap();\n *\n * const realtime = kernel.getService('realtime');\n * await realtime.subscribe('records', (event) => {\n *   console.log(event.type, event.payload);\n * });\n * ```\n */\nexport class RealtimeServicePlugin implements Plugin {\n  name = 'com.objectstack.service.realtime';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private readonly options: RealtimeServicePluginOptions;\n\n  constructor(options: RealtimeServicePluginOptions = {}) {\n    this.options = { adapter: 'memory', ...options };\n  }\n\n  async init(ctx: PluginContext): Promise<void> {\n    const realtime = new InMemoryRealtimeAdapter(this.options.memory);\n    ctx.registerService('realtime', realtime);\n\n    // Register realtime system objects via the manifest service.\n    ctx.getService<{ register(m: any): void }>('manifest').register({\n      id: 'com.objectstack.service.realtime',\n      name: 'Realtime Service',\n      version: '1.0.0',\n      type: 'plugin',\n      namespace: 'sys',\n      objects: [SysPresence],\n    });\n\n    ctx.logger.info('RealtimeServicePlugin: registered in-memory realtime adapter');\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n  IRealtimeService,\n  RealtimeEventPayload,\n  RealtimeEventHandler,\n  RealtimeSubscriptionOptions,\n} from '@objectstack/spec/contracts';\n\n/**\n * Internal subscription entry.\n */\ninterface Subscription {\n  id: string;\n  channel: string;\n  handler: RealtimeEventHandler;\n  options?: RealtimeSubscriptionOptions;\n}\n\n/**\n * Configuration options for InMemoryRealtimeAdapter.\n */\nexport interface InMemoryRealtimeAdapterOptions {\n  /** Maximum number of subscriptions allowed (0 = unlimited) */\n  maxSubscriptions?: number;\n}\n\n/**\n * In-memory pub/sub adapter implementing IRealtimeService.\n *\n * Uses a Map-backed subscription store with channel-based routing.\n * Supports event type and object filtering via subscription options.\n *\n * Suitable for single-process environments, development, and testing.\n * For production multi-instance deployments, use a Redis-backed adapter.\n *\n * @example\n * ```ts\n * const realtime = new InMemoryRealtimeAdapter();\n *\n * const subId = await realtime.subscribe('records', (event) => {\n *   console.log('Received:', event.type, event.payload);\n * }, { object: 'account', eventTypes: ['record.created'] });\n *\n * await realtime.publish({\n *   type: 'record.created',\n *   object: 'account',\n *   payload: { id: 'acc-1', name: 'Acme' },\n *   timestamp: new Date().toISOString(),\n * });\n *\n * await realtime.unsubscribe(subId);\n * ```\n */\nexport class InMemoryRealtimeAdapter implements IRealtimeService {\n  private readonly subscriptions = new Map<string, Subscription>();\n  private readonly channelIndex = new Map<string, Set<string>>();\n  private counter = 0;\n  private readonly maxSubscriptions: number;\n\n  constructor(options: InMemoryRealtimeAdapterOptions = {}) {\n    this.maxSubscriptions = options.maxSubscriptions ?? 0;\n  }\n\n  async publish(event: RealtimeEventPayload): Promise<void> {\n    // Deliver to all channel subscriptions that match filters\n    for (const sub of this.subscriptions.values()) {\n      if (this.matchesSubscription(event, sub)) {\n        try {\n          await sub.handler(event);\n        } catch {\n          // Swallow handler errors to avoid breaking the publish loop\n        }\n      }\n    }\n  }\n\n  async subscribe(\n    channel: string,\n    handler: RealtimeEventHandler,\n    options?: RealtimeSubscriptionOptions,\n  ): Promise<string> {\n    if (this.maxSubscriptions > 0 && this.subscriptions.size >= this.maxSubscriptions) {\n      throw new Error(\n        `Maximum subscription limit reached (${this.maxSubscriptions}). ` +\n        'Unsubscribe from existing channels before adding new subscriptions.',\n      );\n    }\n\n    const id = `sub-${++this.counter}`;\n    const sub: Subscription = { id, channel, handler, options };\n    this.subscriptions.set(id, sub);\n\n    // Maintain channel index for efficient lookups\n    if (!this.channelIndex.has(channel)) {\n      this.channelIndex.set(channel, new Set());\n    }\n    this.channelIndex.get(channel)!.add(id);\n\n    return id;\n  }\n\n  async unsubscribe(subscriptionId: string): Promise<void> {\n    const sub = this.subscriptions.get(subscriptionId);\n    if (!sub) return;\n\n    this.subscriptions.delete(subscriptionId);\n\n    // Clean up channel index\n    const channelSubs = this.channelIndex.get(sub.channel);\n    if (channelSubs) {\n      channelSubs.delete(subscriptionId);\n      if (channelSubs.size === 0) {\n        this.channelIndex.delete(sub.channel);\n      }\n    }\n  }\n\n  /**\n   * Get the number of active subscriptions.\n   */\n  getSubscriptionCount(): number {\n    return this.subscriptions.size;\n  }\n\n  /**\n   * Get all active channel names.\n   */\n  getChannels(): string[] {\n    return Array.from(this.channelIndex.keys());\n  }\n\n  /**\n   * Check if an event matches a subscription's filters.\n   */\n  private matchesSubscription(event: RealtimeEventPayload, sub: Subscription): boolean {\n    const opts = sub.options;\n    if (!opts) return true;\n\n    // Filter by object name\n    if (opts.object && event.object !== opts.object) {\n      return false;\n    }\n\n    // Filter by event types\n    if (opts.eventTypes && opts.eventTypes.length > 0) {\n      if (!opts.eventTypes.includes(event.type)) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n}\n"],"mappings":"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","names":[]}