@objectstack/service-realtime 4.0.4 → 4.0.5

package/src/in-memory-realtime-adapter.ts

@@ -1,154 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type {
-  IRealtimeService,
-  RealtimeEventPayload,
-  RealtimeEventHandler,
-  RealtimeSubscriptionOptions,
-} from '@objectstack/spec/contracts';
-
-/**
- * Internal subscription entry.
- */
-interface Subscription {
-  id: string;
-  channel: string;
-  handler: RealtimeEventHandler;
-  options?: RealtimeSubscriptionOptions;
-}
-
-/**
- * Configuration options for InMemoryRealtimeAdapter.
- */
-export interface InMemoryRealtimeAdapterOptions {
-  /** Maximum number of subscriptions allowed (0 = unlimited) */
-  maxSubscriptions?: number;
-}
-
-/**
- * In-memory pub/sub adapter implementing IRealtimeService.
- *
- * Uses a Map-backed subscription store with channel-based routing.
- * Supports event type and object filtering via subscription options.
- *
- * Suitable for single-process environments, development, and testing.
- * For production multi-instance deployments, use a Redis-backed adapter.
- *
- * @example
- * ```ts
- * const realtime = new InMemoryRealtimeAdapter();
- *
- * const subId = await realtime.subscribe('records', (event) => {
- *   console.log('Received:', event.type, event.payload);
- * }, { object: 'account', eventTypes: ['record.created'] });
- *
- * await realtime.publish({
- *   type: 'record.created',
- *   object: 'account',
- *   payload: { id: 'acc-1', name: 'Acme' },
- *   timestamp: new Date().toISOString(),
- * });
- *
- * await realtime.unsubscribe(subId);
- * ```
- */
-export class InMemoryRealtimeAdapter implements IRealtimeService {
-  private readonly subscriptions = new Map<string, Subscription>();
-  private readonly channelIndex = new Map<string, Set<string>>();
-  private counter = 0;
-  private readonly maxSubscriptions: number;
-
-  constructor(options: InMemoryRealtimeAdapterOptions = {}) {
-    this.maxSubscriptions = options.maxSubscriptions ?? 0;
-  }
-
-  async publish(event: RealtimeEventPayload): Promise<void> {
-    // Deliver to all channel subscriptions that match filters
-    for (const sub of this.subscriptions.values()) {
-      if (this.matchesSubscription(event, sub)) {
-        try {
-          await sub.handler(event);
-        } catch {
-          // Swallow handler errors to avoid breaking the publish loop
-        }
-      }
-    }
-  }
-
-  async subscribe(
-    channel: string,
-    handler: RealtimeEventHandler,
-    options?: RealtimeSubscriptionOptions,
-  ): Promise<string> {
-    if (this.maxSubscriptions > 0 && this.subscriptions.size >= this.maxSubscriptions) {
-      throw new Error(
-        `Maximum subscription limit reached (${this.maxSubscriptions}). ` +
-        'Unsubscribe from existing channels before adding new subscriptions.',
-      );
-    }
-
-    const id = `sub-${++this.counter}`;
-    const sub: Subscription = { id, channel, handler, options };
-    this.subscriptions.set(id, sub);
-
-    // Maintain channel index for efficient lookups
-    if (!this.channelIndex.has(channel)) {
-      this.channelIndex.set(channel, new Set());
-    }
-    this.channelIndex.get(channel)!.add(id);
-
-    return id;
-  }
-
-  async unsubscribe(subscriptionId: string): Promise<void> {
-    const sub = this.subscriptions.get(subscriptionId);
-    if (!sub) return;
-
-    this.subscriptions.delete(subscriptionId);
-
-    // Clean up channel index
-    const channelSubs = this.channelIndex.get(sub.channel);
-    if (channelSubs) {
-      channelSubs.delete(subscriptionId);
-      if (channelSubs.size === 0) {
-        this.channelIndex.delete(sub.channel);
-      }
-    }
-  }
-
-  /**
-   * Get the number of active subscriptions.
-   */
-  getSubscriptionCount(): number {
-    return this.subscriptions.size;
-  }
-
-  /**
-   * Get all active channel names.
-   */
-  getChannels(): string[] {
-    return Array.from(this.channelIndex.keys());
-  }
-
-  /**
-   * Check if an event matches a subscription's filters.
-   */
-  private matchesSubscription(event: RealtimeEventPayload, sub: Subscription): boolean {
-    const opts = sub.options;
-    if (!opts) return true;
-
-    // Filter by object name
-    if (opts.object && event.object !== opts.object) {
-      return false;
-    }
-
-    // Filter by event types
-    if (opts.eventTypes && opts.eventTypes.length > 0) {
-      if (!opts.eventTypes.includes(event.type)) {
-        return false;
-      }
-    }
-
-    return true;
-  }
-}

package/src/index.ts

@@ -1,7 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-export { RealtimeServicePlugin } from './realtime-service-plugin.js';
-export type { RealtimeServicePluginOptions } from './realtime-service-plugin.js';
-export { InMemoryRealtimeAdapter } from './in-memory-realtime-adapter.js';
-export type { InMemoryRealtimeAdapterOptions } from './in-memory-realtime-adapter.js';
-export { SysPresence } from './objects/index.js';

package/src/objects/index.ts

@@ -1,9 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Realtime Service — System Object Definitions (sys namespace)
- *
- * Canonical ObjectSchema definitions for realtime-related system objects.
- */
-
-export { SysPresence } from './sys-presence.object.js';

package/src/objects/sys-presence.object.test.ts

@@ -1,73 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { describe, it, expect } from 'vitest';
-import { SysPresence } from './sys-presence.object';
-
-describe('SysPresence object definition', () => {
-  it('should have correct namespace and name', () => {
-    expect(SysPresence.namespace).toBe('sys');
-    expect(SysPresence.name).toBe('presence');
-  });
-
-  it('should auto-derive tableName as sys_presence', () => {
-    expect(SysPresence.tableName).toBe('sys_presence');
-  });
-
-  it('should be a system object', () => {
-    expect(SysPresence.isSystem).toBe(true);
-  });
-
-  it('should have label and pluralLabel', () => {
-    expect(SysPresence.label).toBe('Presence');
-    expect(SysPresence.pluralLabel).toBe('Presences');
-  });
-
-  it('should define all presence protocol fields', () => {
-    const fieldKeys = Object.keys(SysPresence.fields);
-    expect(fieldKeys).toContain('id');
-    expect(fieldKeys).toContain('created_at');
-    expect(fieldKeys).toContain('updated_at');
-    expect(fieldKeys).toContain('user_id');
-    expect(fieldKeys).toContain('session_id');
-    expect(fieldKeys).toContain('status');
-    expect(fieldKeys).toContain('last_seen');
-    expect(fieldKeys).toContain('current_location');
-    expect(fieldKeys).toContain('device');
-    expect(fieldKeys).toContain('custom_status');
-    expect(fieldKeys).toContain('metadata');
-  });
-
-  it('should have status field with correct options', () => {
-    const statusField = SysPresence.fields.status;
-    expect(statusField.type).toBe('select');
-    expect(statusField.options).toEqual([
-      { value: 'online', label: 'Online' },
-      { value: 'away', label: 'Away' },
-      { value: 'busy', label: 'Busy' },
-      { value: 'offline', label: 'Offline' },
-    ]);
-  });
-
-  it('should have device field with correct options', () => {
-    const deviceField = SysPresence.fields.device;
-    expect(deviceField.type).toBe('select');
-    expect(deviceField.options).toEqual([
-      { value: 'desktop', label: 'Desktop' },
-      { value: 'mobile', label: 'Mobile' },
-      { value: 'tablet', label: 'Tablet' },
-      { value: 'other', label: 'Other' },
-    ]);
-  });
-
-  it('should have indexes on user_id, session_id, and status', () => {
-    expect(SysPresence.indexes).toEqual([
-      { fields: ['user_id'], unique: false, type: 'btree' },
-      { fields: ['session_id'], unique: true, type: 'btree' },
-      { fields: ['status'], unique: false, type: 'btree' },
-    ]);
-  });
-
-  it('should have API enabled', () => {
-    expect(SysPresence.enable?.apiEnabled).toBe(true);
-  });
-});

package/src/objects/sys-presence.object.ts

@@ -1,120 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-/**
- * sys_presence — System Presence Object
- *
- * Tracks real-time user presence and activity across the platform.
- * Fields align with the PresenceStateSchema protocol definition
- * from `@objectstack/spec/api` (websocket.zod.ts).
- *
- * Owned by `service-realtime` as the canonical Presence domain object.
- *
- * @namespace sys
- * @see PresenceStateSchema in packages/spec/src/api/websocket.zod.ts
- */
-export const SysPresence = 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: Field.text({
-      label: 'Presence ID',
-      required: true,
-      readonly: true,
-    }),
-
-    created_at: Field.datetime({
-      label: 'Created At',
-      defaultValue: 'NOW()',
-      readonly: true,
-    }),
-
-    updated_at: Field.datetime({
-      label: 'Updated At',
-      defaultValue: 'NOW()',
-      readonly: true,
-    }),
-
-    user_id: Field.text({
-      label: 'User ID',
-      required: true,
-      searchable: true,
-    }),
-
-    session_id: Field.text({
-      label: 'Session ID',
-      required: true,
-    }),
-
-    status: 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: Field.datetime({
-      label: 'Last Seen',
-      required: true,
-      defaultValue: 'NOW()',
-    }),
-
-    current_location: Field.text({
-      label: 'Current Location',
-      required: false,
-      maxLength: 500,
-    }),
-
-    device: 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: Field.text({
-      label: 'Custom Status',
-      required: false,
-      maxLength: 255,
-    }),
-
-    metadata: 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,
-  },
-});

package/src/realtime-service-plugin.ts

@@ -1,67 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Plugin, PluginContext } from '@objectstack/core';
-import { InMemoryRealtimeAdapter } from './in-memory-realtime-adapter.js';
-import type { InMemoryRealtimeAdapterOptions } from './in-memory-realtime-adapter.js';
-import { SysPresence } from './objects/index.js';
-
-/**
- * Configuration options for the RealtimeServicePlugin.
- */
-export interface RealtimeServicePluginOptions {
-  /** Realtime adapter type (default: 'memory') */
-  adapter?: 'memory';
-  /** Options for the in-memory adapter */
-  memory?: InMemoryRealtimeAdapterOptions;
-}
-
-/**
- * RealtimeServicePlugin — Production IRealtimeService implementation.
- *
- * Registers a realtime pub/sub service with the kernel during the init phase.
- * Currently supports in-memory pub/sub for single-process environments.
- *
- * @example
- * ```ts
- * import { ObjectKernel } from '@objectstack/core';
- * import { RealtimeServicePlugin } from '@objectstack/service-realtime';
- *
- * const kernel = new ObjectKernel();
- * kernel.use(new RealtimeServicePlugin());
- * await kernel.bootstrap();
- *
- * const realtime = kernel.getService('realtime');
- * await realtime.subscribe('records', (event) => {
- *   console.log(event.type, event.payload);
- * });
- * ```
- */
-export class RealtimeServicePlugin implements Plugin {
-  name = 'com.objectstack.service.realtime';
-  version = '1.0.0';
-  type = 'standard';
-  dependencies = ['com.objectstack.engine.objectql'];
-
-  private readonly options: RealtimeServicePluginOptions;
-
-  constructor(options: RealtimeServicePluginOptions = {}) {
-    this.options = { adapter: 'memory', ...options };
-  }
-
-  async init(ctx: PluginContext): Promise<void> {
-    const realtime = new InMemoryRealtimeAdapter(this.options.memory);
-    ctx.registerService('realtime', realtime);
-
-    // Register realtime system objects via the manifest service.
-    ctx.getService<{ register(m: any): void }>('manifest').register({
-      id: 'com.objectstack.service.realtime',
-      name: 'Realtime Service',
-      version: '1.0.0',
-      type: 'plugin',
-      namespace: 'sys',
-      objects: [SysPresence],
-    });
-
-    ctx.logger.info('RealtimeServicePlugin: registered in-memory realtime adapter');
-  }
-}

package/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "extends": "../../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src",
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "src"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist"
-  ]
-}