@omnibase/core-js 0.6.0 → 0.7.0

package/dist/database/index.d.cts

@@ -102,4 +102,197 @@ import { PostgrestClient } from '@supabase/postgrest-js';
  */
 declare const createClient: <T = any>(url: string, anonKey: string, getCookie: (cookie: string) => string) => PostgrestClient<T>;
 
-export { createClient };
+/**
+ * Real-time database events client for WebSocket subscriptions
+ *
+ * This module provides a universal WebSocket client for subscribing to real-time
+ * database changes with Row-Level Security (RLS) authentication. Works in both
+ * browser and Node.js environments.
+ *
+ * @module Database Events
+ */
+/**
+ * Subscription options for database events
+ */
+interface SubscriptionOptions {
+    /** Specific row ID to subscribe to (optional) */
+    rowId?: number;
+    /** Specific columns to filter updates (optional) */
+    columns?: string[];
+    /** Callback function triggered on data updates */
+    onChange?: (data: any, message: UpdateMessage) => void;
+}
+/**
+ * Subscription request sent to the server
+ */
+interface Subscription {
+    table: string;
+    row_id?: number;
+    columns?: string[];
+    jwt: string;
+}
+/**
+ * Message sent from client to server
+ */
+interface SubscriptionMessage {
+    action: "subscribe" | "unsubscribe";
+    subscription: Subscription;
+}
+/**
+ * Update message received from server
+ */
+interface UpdateMessage {
+    type: "update";
+    table: string;
+    row_id: number;
+    data: any;
+}
+/**
+ * Status message received from server
+ */
+interface StatusMessage {
+    status: "subscribed" | "unsubscribed" | "error";
+    table?: string;
+    row_id?: number;
+    error?: string;
+}
+/**
+ * Universal WebSocket client for real-time database events
+ *
+ * Connects to the database events WebSocket endpoint and manages subscriptions
+ * to table changes with automatic RLS authentication and reconnection.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const client = new EventsClient(
+ *   'ws://localhost:8080/api/v1/events/ws',
+ *   'your-jwt-token'
+ * );
+ *
+ * client.subscribe('tasks', {
+ *   onChange: (data) => {
+ *     console.log('Task updated:', data);
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Subscribe to specific row:
+ * ```typescript
+ * client.subscribe('users', {
+ *   rowId: 123,
+ *   onChange: (user) => {
+ *     console.log('User 123 updated:', user);
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Subscribe to specific columns:
+ * ```typescript
+ * client.subscribe('posts', {
+ *   rowId: 456,
+ *   columns: ['title', 'content', 'status'],
+ *   onChange: (post) => {
+ *     console.log('Post columns updated:', post);
+ *   }
+ * });
+ * ```
+ */
+declare class EventsClient {
+    private url;
+    private jwt;
+    private subscriptions;
+    private ws;
+    private reconnectDelay;
+    private listeners;
+    private shouldReconnect;
+    /**
+     * Creates a new EventsClient instance
+     *
+     * @param url - WebSocket endpoint URL (e.g., 'ws://localhost:8080/api/v1/events/ws')
+     * @param jwt - JWT authentication token for RLS checks
+     */
+    constructor(url: string, jwt: string);
+    /**
+     * Establishes WebSocket connection with automatic reconnection
+     * @private
+     */
+    private connect;
+    /**
+     * Subscribe to database changes for a table
+     *
+     * @param table - Table name to subscribe to
+     * @param options - Subscription options (rowId, columns, onChange callback)
+     *
+     * @example
+     * Subscribe to entire table:
+     * ```typescript
+     * client.subscribe('tasks', {
+     *   onChange: (task) => console.log('Task changed:', task)
+     * });
+     * ```
+     *
+     * @example
+     * Subscribe to specific row:
+     * ```typescript
+     * client.subscribe('users', {
+     *   rowId: 123,
+     *   onChange: (user) => console.log('User 123 changed:', user)
+     * });
+     * ```
+     */
+    subscribe(table: string, options?: SubscriptionOptions): void;
+    /**
+     * Unsubscribe from database changes
+     *
+     * @param table - Table name to unsubscribe from
+     * @param rowId - Optional row ID (if subscribing to specific row)
+     *
+     * @example
+     * ```typescript
+     * client.unsubscribe('tasks');
+     * client.unsubscribe('users', 123);
+     * ```
+     */
+    unsubscribe(table: string, rowId?: number): void;
+    /**
+     * Send message to WebSocket server
+     * @private
+     */
+    private send;
+    /**
+     * Handle incoming WebSocket messages
+     * @private
+     */
+    private handleMessage;
+    /**
+     * Update JWT token for authentication
+     *
+     * @param jwt - New JWT token
+     *
+     * @example
+     * ```typescript
+     * client.updateJWT(newToken);
+     * ```
+     */
+    updateJWT(jwt: string): void;
+    /**
+     * Close WebSocket connection and prevent reconnection
+     *
+     * @example
+     * ```typescript
+     * client.close();
+     * ```
+     */
+    close(): void;
+    /**
+     * Check if WebSocket is currently connected
+     *
+     * @returns true if connected, false otherwise
+     */
+    isConnected(): boolean;
+}
+
+export { EventsClient, type StatusMessage, type Subscription, type SubscriptionMessage, type SubscriptionOptions, type UpdateMessage, createClient };

package/dist/database/index.d.ts

@@ -102,4 +102,197 @@ import { PostgrestClient } from '@supabase/postgrest-js';
  */
 declare const createClient: <T = any>(url: string, anonKey: string, getCookie: (cookie: string) => string) => PostgrestClient<T>;
 
-export { createClient };
+/**
+ * Real-time database events client for WebSocket subscriptions
+ *
+ * This module provides a universal WebSocket client for subscribing to real-time
+ * database changes with Row-Level Security (RLS) authentication. Works in both
+ * browser and Node.js environments.
+ *
+ * @module Database Events
+ */
+/**
+ * Subscription options for database events
+ */
+interface SubscriptionOptions {
+    /** Specific row ID to subscribe to (optional) */
+    rowId?: number;
+    /** Specific columns to filter updates (optional) */
+    columns?: string[];
+    /** Callback function triggered on data updates */
+    onChange?: (data: any, message: UpdateMessage) => void;
+}
+/**
+ * Subscription request sent to the server
+ */
+interface Subscription {
+    table: string;
+    row_id?: number;
+    columns?: string[];
+    jwt: string;
+}
+/**
+ * Message sent from client to server
+ */
+interface SubscriptionMessage {
+    action: "subscribe" | "unsubscribe";
+    subscription: Subscription;
+}
+/**
+ * Update message received from server
+ */
+interface UpdateMessage {
+    type: "update";
+    table: string;
+    row_id: number;
+    data: any;
+}
+/**
+ * Status message received from server
+ */
+interface StatusMessage {
+    status: "subscribed" | "unsubscribed" | "error";
+    table?: string;
+    row_id?: number;
+    error?: string;
+}
+/**
+ * Universal WebSocket client for real-time database events
+ *
+ * Connects to the database events WebSocket endpoint and manages subscriptions
+ * to table changes with automatic RLS authentication and reconnection.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const client = new EventsClient(
+ *   'ws://localhost:8080/api/v1/events/ws',
+ *   'your-jwt-token'
+ * );
+ *
+ * client.subscribe('tasks', {
+ *   onChange: (data) => {
+ *     console.log('Task updated:', data);
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Subscribe to specific row:
+ * ```typescript
+ * client.subscribe('users', {
+ *   rowId: 123,
+ *   onChange: (user) => {
+ *     console.log('User 123 updated:', user);
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Subscribe to specific columns:
+ * ```typescript
+ * client.subscribe('posts', {
+ *   rowId: 456,
+ *   columns: ['title', 'content', 'status'],
+ *   onChange: (post) => {
+ *     console.log('Post columns updated:', post);
+ *   }
+ * });
+ * ```
+ */
+declare class EventsClient {
+    private url;
+    private jwt;
+    private subscriptions;
+    private ws;
+    private reconnectDelay;
+    private listeners;
+    private shouldReconnect;
+    /**
+     * Creates a new EventsClient instance
+     *
+     * @param url - WebSocket endpoint URL (e.g., 'ws://localhost:8080/api/v1/events/ws')
+     * @param jwt - JWT authentication token for RLS checks
+     */
+    constructor(url: string, jwt: string);
+    /**
+     * Establishes WebSocket connection with automatic reconnection
+     * @private
+     */
+    private connect;
+    /**
+     * Subscribe to database changes for a table
+     *
+     * @param table - Table name to subscribe to
+     * @param options - Subscription options (rowId, columns, onChange callback)
+     *
+     * @example
+     * Subscribe to entire table:
+     * ```typescript
+     * client.subscribe('tasks', {
+     *   onChange: (task) => console.log('Task changed:', task)
+     * });
+     * ```
+     *
+     * @example
+     * Subscribe to specific row:
+     * ```typescript
+     * client.subscribe('users', {
+     *   rowId: 123,
+     *   onChange: (user) => console.log('User 123 changed:', user)
+     * });
+     * ```
+     */
+    subscribe(table: string, options?: SubscriptionOptions): void;
+    /**
+     * Unsubscribe from database changes
+     *
+     * @param table - Table name to unsubscribe from
+     * @param rowId - Optional row ID (if subscribing to specific row)
+     *
+     * @example
+     * ```typescript
+     * client.unsubscribe('tasks');
+     * client.unsubscribe('users', 123);
+     * ```
+     */
+    unsubscribe(table: string, rowId?: number): void;
+    /**
+     * Send message to WebSocket server
+     * @private
+     */
+    private send;
+    /**
+     * Handle incoming WebSocket messages
+     * @private
+     */
+    private handleMessage;
+    /**
+     * Update JWT token for authentication
+     *
+     * @param jwt - New JWT token
+     *
+     * @example
+     * ```typescript
+     * client.updateJWT(newToken);
+     * ```
+     */
+    updateJWT(jwt: string): void;
+    /**
+     * Close WebSocket connection and prevent reconnection
+     *
+     * @example
+     * ```typescript
+     * client.close();
+     * ```
+     */
+    close(): void;
+    /**
+     * Check if WebSocket is currently connected
+     *
+     * @returns true if connected, false otherwise
+     */
+    isConnected(): boolean;
+}
+
+export { EventsClient, type StatusMessage, type Subscription, type SubscriptionMessage, type SubscriptionOptions, type UpdateMessage, createClient };

package/dist/database/index.js

@@ -8,6 +8,219 @@ var createClient = (url, anonKey, getCookie) => {
     }
   });
 };
+
+// src/database/events.ts
+var WS = typeof globalThis !== "undefined" && globalThis.WebSocket ? globalThis.WebSocket : null;
+var EventsClient = class {
+  url;
+  jwt;
+  subscriptions = [];
+  ws = null;
+  reconnectDelay = 1e3;
+  listeners = /* @__PURE__ */ new Map();
+  shouldReconnect = true;
+  /**
+   * Creates a new EventsClient instance
+   *
+   * @param url - WebSocket endpoint URL (e.g., 'ws://localhost:8080/api/v1/events/ws')
+   * @param jwt - JWT authentication token for RLS checks
+   */
+  constructor(url, jwt) {
+    if (!WS) {
+      throw new Error(
+        'WebSocket is not available in this environment. Install "ws" package for Node.js.'
+      );
+    }
+    this.url = url;
+    this.jwt = jwt;
+    this.connect();
+  }
+  /**
+   * Establishes WebSocket connection with automatic reconnection
+   * @private
+   */
+  connect() {
+    if (!WS) return;
+    this.ws = new WS(this.url);
+    this.ws.onopen = () => {
+      console.log("\u2705 Connected to database events");
+      this.reconnectDelay = 1e3;
+      this.subscriptions.forEach((sub) => this.send(sub));
+    };
+    this.ws.onmessage = (event) => {
+      const data = typeof event.data === "string" ? event.data : event.data.toString();
+      const msg = JSON.parse(data);
+      this.handleMessage(msg);
+    };
+    this.ws.onerror = (error) => {
+      console.error("\u274C WebSocket error:", error);
+    };
+    this.ws.onclose = () => {
+      if (this.shouldReconnect) {
+        console.log(
+          `\u26A0\uFE0F Disconnected, reconnecting in ${this.reconnectDelay}ms`
+        );
+        setTimeout(() => this.connect(), this.reconnectDelay);
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, 3e4);
+      } else {
+        console.log("Disconnected from database events");
+      }
+    };
+  }
+  /**
+   * Subscribe to database changes for a table
+   *
+   * @param table - Table name to subscribe to
+   * @param options - Subscription options (rowId, columns, onChange callback)
+   *
+   * @example
+   * Subscribe to entire table:
+   * ```typescript
+   * client.subscribe('tasks', {
+   *   onChange: (task) => console.log('Task changed:', task)
+   * });
+   * ```
+   *
+   * @example
+   * Subscribe to specific row:
+   * ```typescript
+   * client.subscribe('users', {
+   *   rowId: 123,
+   *   onChange: (user) => console.log('User 123 changed:', user)
+   * });
+   * ```
+   */
+  subscribe(table, options = {}) {
+    const { rowId, columns, onChange } = options;
+    const sub = {
+      action: "subscribe",
+      subscription: {
+        table,
+        ...rowId !== void 0 && { row_id: rowId },
+        ...columns && { columns },
+        jwt: this.jwt
+      }
+    };
+    this.subscriptions.push(sub);
+    if (onChange) {
+      const key = `${table}:${rowId ?? "*"}`;
+      this.listeners.set(key, onChange);
+    }
+    this.send(sub);
+  }
+  /**
+   * Unsubscribe from database changes
+   *
+   * @param table - Table name to unsubscribe from
+   * @param rowId - Optional row ID (if subscribing to specific row)
+   *
+   * @example
+   * ```typescript
+   * client.unsubscribe('tasks');
+   * client.unsubscribe('users', 123);
+   * ```
+   */
+  unsubscribe(table, rowId) {
+    const sub = {
+      action: "unsubscribe",
+      subscription: {
+        table,
+        ...rowId !== void 0 && { row_id: rowId },
+        jwt: this.jwt
+      }
+    };
+    this.subscriptions = this.subscriptions.filter(
+      (s) => !(s.subscription.table === table && s.subscription.row_id === rowId)
+    );
+    const key = `${table}:${rowId ?? "*"}`;
+    this.listeners.delete(key);
+    this.send(sub);
+  }
+  /**
+   * Send message to WebSocket server
+   * @private
+   */
+  send(data) {
+    if (!WS) return;
+    if (this.ws?.readyState === WS.OPEN || this.ws?.readyState === 1) {
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+  /**
+   * Handle incoming WebSocket messages
+   * @private
+   */
+  handleMessage(msg) {
+    if ("type" in msg && msg.type === "update") {
+      const key = `${msg.table}:${msg.row_id}`;
+      const wildcardKey = `${msg.table}:*`;
+      const listener = this.listeners.get(key) || this.listeners.get(wildcardKey);
+      if (listener) {
+        listener(msg.data, msg);
+      }
+    } else if ("status" in msg) {
+      if (msg.status === "subscribed") {
+        console.log(
+          "\u2705 Subscribed to",
+          msg.table,
+          msg.row_id ? `(row ${msg.row_id})` : "(all rows)"
+        );
+      } else if (msg.status === "unsubscribed") {
+        console.log(
+          "Unsubscribed from",
+          msg.table,
+          msg.row_id ? `(row ${msg.row_id})` : "(all rows)"
+        );
+      } else if (msg.status === "error") {
+        console.error(
+          "\u274C Subscription error:",
+          msg.error,
+          "for table:",
+          msg.table
+        );
+      }
+    }
+  }
+  /**
+   * Update JWT token for authentication
+   *
+   * @param jwt - New JWT token
+   *
+   * @example
+   * ```typescript
+   * client.updateJWT(newToken);
+   * ```
+   */
+  updateJWT(jwt) {
+    this.jwt = jwt;
+    this.subscriptions = this.subscriptions.map((sub) => ({
+      ...sub,
+      subscription: { ...sub.subscription, jwt }
+    }));
+  }
+  /**
+   * Close WebSocket connection and prevent reconnection
+   *
+   * @example
+   * ```typescript
+   * client.close();
+   * ```
+   */
+  close() {
+    this.shouldReconnect = false;
+    this.ws?.close();
+  }
+  /**
+   * Check if WebSocket is currently connected
+   *
+   * @returns true if connected, false otherwise
+   */
+  isConnected() {
+    if (!WS) return false;
+    return this.ws?.readyState === WS.OPEN || this.ws?.readyState === 1;
+  }
+};
 export {
+  EventsClient,
   createClient
 };