@framers/sql-storage-adapter 0.7.2 → 0.7.3

package/dist/cjs/features/sync/transport/transport.js

@@ -0,0 +1,163 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var transport_exports = {};
+__export(transport_exports, {
+  BaseTransport: () => BaseTransport,
+  TransportError: () => TransportError,
+  TransportErrorCodes: () => TransportErrorCodes
+});
+module.exports = __toCommonJS(transport_exports);
+class TransportError extends Error {
+  constructor(message, code, options) {
+    super(message);
+    this.name = "TransportError";
+    this.code = code;
+    this.recoverable = options?.recoverable ?? false;
+    this.cause = options?.cause;
+  }
+}
+const TransportErrorCodes = {
+  /** Connection failed */
+  CONNECTION_FAILED: "CONNECTION_FAILED",
+  /** Connection timeout */
+  CONNECTION_TIMEOUT: "CONNECTION_TIMEOUT",
+  /** Authentication failed */
+  AUTH_FAILED: "AUTH_FAILED",
+  /** Request timeout */
+  REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+  /** Send failed */
+  SEND_FAILED: "SEND_FAILED",
+  /** Server error */
+  SERVER_ERROR: "SERVER_ERROR",
+  /** Network error */
+  NETWORK_ERROR: "NETWORK_ERROR",
+  /** Protocol error */
+  PROTOCOL_ERROR: "PROTOCOL_ERROR",
+  /** Transport disposed */
+  DISPOSED: "DISPOSED"
+};
+class BaseTransport {
+  constructor(options) {
+    this._state = "disconnected";
+    this._disposed = false;
+    this._listeners = /* @__PURE__ */ new Map();
+    this._options = {
+      endpoint: options.endpoint,
+      authToken: options.authToken ?? "",
+      headers: options.headers ?? {},
+      connectionTimeout: options.connectionTimeout ?? 1e4,
+      requestTimeout: options.requestTimeout ?? 3e4,
+      autoReconnect: options.autoReconnect ?? true,
+      reconnectDelay: options.reconnectDelay ?? 1e3,
+      maxReconnectDelay: options.maxReconnectDelay ?? 3e4,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? 0,
+      heartbeatInterval: options.heartbeatInterval ?? 3e4,
+      compression: options.compression ?? true
+    };
+    this._stats = {
+      state: "disconnected",
+      messagesSent: 0,
+      messagesReceived: 0,
+      bytesSent: 0,
+      bytesReceived: 0,
+      reconnectAttempts: 0
+    };
+  }
+  get state() {
+    return this._state;
+  }
+  get isConnected() {
+    return this._state === "connected";
+  }
+  on(event, listener) {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    const listeners = this._listeners.get(event);
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  once(event, listener) {
+    const wrapper = (eventData) => {
+      unsubscribe();
+      listener(eventData);
+    };
+    const unsubscribe = this.on(event, wrapper);
+    return unsubscribe;
+  }
+  getStats() {
+    return { ...this._stats, state: this._state };
+  }
+  async dispose() {
+    if (this._disposed)
+      return;
+    this._disposed = true;
+    await this.disconnect("disposed");
+    this._listeners.clear();
+  }
+  /**
+   * Emit an event to all registered listeners.
+   */
+  emit(event, data) {
+    const listeners = this._listeners.get(event);
+    if (!listeners)
+      return;
+    for (const listener of listeners) {
+      try {
+        listener(data);
+      } catch (error) {
+        console.error(`[Transport] Error in ${event} listener:`, error);
+      }
+    }
+  }
+  /**
+   * Update transport state and emit event.
+   */
+  setState(newState) {
+    if (this._state === newState)
+      return;
+    const previousState = this._state;
+    this._state = newState;
+    this._stats.state = newState;
+    this.emit("stateChange", { previousState, currentState: newState });
+  }
+  /**
+   * Check if transport is disposed and throw if so.
+   */
+  checkDisposed() {
+    if (this._disposed) {
+      throw new TransportError("Transport has been disposed", TransportErrorCodes.DISPOSED, { recoverable: false });
+    }
+  }
+  /**
+   * Calculate next reconnection delay with exponential backoff.
+   */
+  calculateReconnectDelay(attempt) {
+    const delay = Math.min(this._options.reconnectDelay * Math.pow(2, attempt - 1), this._options.maxReconnectDelay);
+    const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+    return Math.floor(delay + jitter);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseTransport,
+  TransportError,
+  TransportErrorCodes
+});

package/dist/cjs/features/sync/transport/websocketTransport.d.ts

@@ -0,0 +1,126 @@
+/**
+ * WebSocket Transport Implementation.
+ *
+ * Real-time bidirectional sync transport using WebSockets.
+ * Supports automatic reconnection, heartbeats, and message compression.
+ *
+ * @packageDocumentation
+ */
+import { BaseTransport, type TransportOptions } from './transport.js';
+import type { SyncMessage } from '../protocol/messages.js';
+/**
+ * WebSocket-specific transport options.
+ */
+export interface WebSocketTransportOptions extends TransportOptions {
+    /** WebSocket protocols to use */
+    protocols?: string[];
+    /** Binary message format */
+    binaryType?: 'arraybuffer' | 'blob';
+    /** Enable ping/pong heartbeats */
+    pingPong?: boolean;
+}
+/**
+ * WebSocket transport for real-time sync.
+ *
+ * Provides low-latency bidirectional communication with:
+ * - Automatic reconnection with exponential backoff
+ * - Request/response correlation
+ * - Heartbeat keep-alive
+ * - Message compression (gzip)
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebSocketTransport({
+ *   endpoint: 'wss://sync.example.com/v1/sync',
+ *   authToken: 'bearer-token',
+ *   autoReconnect: true,
+ *   heartbeatInterval: 30000,
+ * });
+ *
+ * transport.on('message', ({ message }) => {
+ *   handleSyncMessage(message);
+ * });
+ *
+ * await transport.connect();
+ * ```
+ */
+export declare class WebSocketTransport extends BaseTransport {
+    readonly type: "websocket";
+    private _ws;
+    private _heartbeatTimer;
+    private _reconnectTimer;
+    private _pendingRequests;
+    private _wsOptions;
+    private _lastPongAt;
+    private _shouldReconnect;
+    constructor(options: WebSocketTransportOptions);
+    /**
+     * Connect to the WebSocket server.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the WebSocket server.
+     */
+    disconnect(reason?: string): Promise<void>;
+    /**
+     * Send a sync message.
+     */
+    send(message: SyncMessage): Promise<void>;
+    /**
+     * Send a message and wait for a response.
+     */
+    request(message: SyncMessage, timeout?: number): Promise<SyncMessage>;
+    /**
+     * Create WebSocket connection.
+     */
+    private _createConnection;
+    /**
+     * Build WebSocket URL with auth token.
+     */
+    private _buildUrl;
+    /**
+     * Handle incoming WebSocket message.
+     */
+    private _handleMessage;
+    /**
+     * Handle WebSocket close event.
+     */
+    private _handleClose;
+    /**
+     * Schedule reconnection attempt.
+     */
+    private _scheduleReconnect;
+    /**
+     * Start heartbeat timer.
+     */
+    private _startHeartbeat;
+    /**
+     * Stop heartbeat timer.
+     */
+    private _stopHeartbeat;
+    /**
+     * Clear all timers.
+     */
+    private _clearTimers;
+    /**
+     * Reject all pending requests.
+     */
+    private _rejectAllPending;
+    /**
+     * Serialize message for transmission.
+     */
+    private _serialize;
+    /**
+     * Deserialize received message.
+     */
+    private _deserialize;
+    /**
+     * Dispose of the transport.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Create a WebSocket transport instance.
+ */
+export declare const createWebSocketTransport: (options: WebSocketTransportOptions) => WebSocketTransport;
+//# sourceMappingURL=websocketTransport.d.ts.map

package/dist/cjs/features/sync/transport/websocketTransport.js

@@ -0,0 +1,342 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var websocketTransport_exports = {};
+__export(websocketTransport_exports, {
+  WebSocketTransport: () => WebSocketTransport,
+  createWebSocketTransport: () => createWebSocketTransport
+});
+module.exports = __toCommonJS(websocketTransport_exports);
+var import_transport = require("./transport.js");
+var import_messages = require("../protocol/messages.js");
+class WebSocketTransport extends import_transport.BaseTransport {
+  constructor(options) {
+    super(options);
+    this.type = "websocket";
+    this._ws = null;
+    this._heartbeatTimer = null;
+    this._reconnectTimer = null;
+    this._pendingRequests = /* @__PURE__ */ new Map();
+    this._lastPongAt = 0;
+    this._shouldReconnect = false;
+    this._wsOptions = {
+      ...this._options,
+      protocols: options.protocols ?? ["sync-v1"],
+      binaryType: options.binaryType ?? "arraybuffer",
+      pingPong: options.pingPong ?? true
+    };
+  }
+  /**
+   * Connect to the WebSocket server.
+   */
+  async connect() {
+    this.checkDisposed();
+    if (this._state === "connected" || this._state === "connecting") {
+      return;
+    }
+    this.setState("connecting");
+    this._shouldReconnect = this._options.autoReconnect;
+    try {
+      await this._createConnection();
+    } catch (error) {
+      this.setState("error");
+      throw error;
+    }
+  }
+  /**
+   * Disconnect from the WebSocket server.
+   */
+  async disconnect(reason = "client disconnect") {
+    this._shouldReconnect = false;
+    this._clearTimers();
+    this._rejectAllPending(new import_transport.TransportError("Disconnected", import_transport.TransportErrorCodes.DISPOSED, { recoverable: false }));
+    if (this._ws) {
+      try {
+        this._ws.close(1e3, reason);
+      } catch {
+      }
+      this._ws = null;
+    }
+    this.setState("disconnected");
+    this.emit("disconnected", { reason, wasClean: true });
+  }
+  /**
+   * Send a sync message.
+   */
+  async send(message) {
+    this.checkDisposed();
+    if (!this._ws || this._state !== "connected") {
+      throw new import_transport.TransportError("Not connected", import_transport.TransportErrorCodes.SEND_FAILED, { recoverable: true });
+    }
+    const data = this._serialize(message);
+    try {
+      this._ws.send(data);
+      this._stats.messagesSent++;
+      this._stats.bytesSent += data.length;
+    } catch (error) {
+      throw new import_transport.TransportError("Failed to send message", import_transport.TransportErrorCodes.SEND_FAILED, { recoverable: true, cause: error });
+    }
+  }
+  /**
+   * Send a message and wait for a response.
+   */
+  async request(message, timeout) {
+    this.checkDisposed();
+    const requestId = message.messageId;
+    const timeoutMs = timeout ?? this._options.requestTimeout;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pendingRequests.delete(requestId);
+        reject(new import_transport.TransportError("Request timed out", import_transport.TransportErrorCodes.REQUEST_TIMEOUT, { recoverable: true }));
+      }, timeoutMs);
+      this._pendingRequests.set(requestId, { resolve, reject, timer });
+      this.send(message).catch((error) => {
+        clearTimeout(timer);
+        this._pendingRequests.delete(requestId);
+        reject(error);
+      });
+    });
+  }
+  /**
+   * Create WebSocket connection.
+   */
+  _createConnection() {
+    return new Promise((resolve, reject) => {
+      const url = this._buildUrl();
+      const timeout = setTimeout(() => {
+        reject(new import_transport.TransportError("Connection timed out", import_transport.TransportErrorCodes.CONNECTION_TIMEOUT, { recoverable: true }));
+      }, this._options.connectionTimeout);
+      try {
+        this._ws = new WebSocket(url, this._wsOptions.protocols);
+        this._ws.binaryType = this._wsOptions.binaryType;
+      } catch (error) {
+        clearTimeout(timeout);
+        reject(new import_transport.TransportError("Failed to create WebSocket", import_transport.TransportErrorCodes.CONNECTION_FAILED, { recoverable: true, cause: error }));
+        return;
+      }
+      this._ws.onopen = () => {
+        clearTimeout(timeout);
+        this.setState("connected");
+        this._stats.connectedAt = Date.now();
+        this._stats.reconnectAttempts = 0;
+        this._startHeartbeat();
+        this.emit("connected", { timestamp: Date.now() });
+        resolve();
+      };
+      this._ws.onclose = (event) => {
+        clearTimeout(timeout);
+        this._handleClose(event);
+        if (this._state === "connecting") {
+          reject(new import_transport.TransportError(`Connection closed: ${event.reason || "unknown"}`, import_transport.TransportErrorCodes.CONNECTION_FAILED, { recoverable: true }));
+        }
+      };
+      this._ws.onerror = (event) => {
+        const error = new import_transport.TransportError("WebSocket error", import_transport.TransportErrorCodes.NETWORK_ERROR, { recoverable: true });
+        this.emit("error", { error, recoverable: true });
+        console.error("[WebSocketTransport] Connection error:", event);
+      };
+      this._ws.onmessage = (event) => {
+        this._handleMessage(event);
+      };
+    });
+  }
+  /**
+   * Build WebSocket URL with auth token.
+   */
+  _buildUrl() {
+    const url = new URL(this._options.endpoint);
+    if (this._options.authToken) {
+      url.searchParams.set("token", this._options.authToken);
+    }
+    return url.toString();
+  }
+  /**
+   * Handle incoming WebSocket message.
+   */
+  _handleMessage(event) {
+    try {
+      const message = this._deserialize(event.data);
+      if (!(0, import_messages.isSyncMessage)(message)) {
+        console.warn("[WebSocketTransport] Received invalid message:", message);
+        return;
+      }
+      this._stats.messagesReceived++;
+      this._stats.bytesReceived += typeof event.data === "string" ? event.data.length : event.data.byteLength;
+      if (message.type === "heartbeat") {
+        this._lastPongAt = Date.now();
+        this.send((0, import_messages.createAckMessage)(message.messageId, this._options.authToken || "device")).catch(() => {
+        });
+        return;
+      }
+      if (message.type === "ack") {
+        const pending = this._pendingRequests.get(message.ackMessageId);
+        if (pending) {
+          clearTimeout(pending.timer);
+          this._pendingRequests.delete(message.ackMessageId);
+          pending.resolve(message);
+        }
+        return;
+      }
+      if ("inResponseTo" in message && message.inResponseTo) {
+        const pending = this._pendingRequests.get(message.inResponseTo);
+        if (pending) {
+          clearTimeout(pending.timer);
+          this._pendingRequests.delete(message.inResponseTo);
+          pending.resolve(message);
+          return;
+        }
+      }
+      this.emit("message", { message, receivedAt: Date.now() });
+    } catch (error) {
+      console.error("[WebSocketTransport] Failed to process message:", error);
+      this.emit("error", {
+        error: new import_transport.TransportError("Failed to process message", import_transport.TransportErrorCodes.PROTOCOL_ERROR, { recoverable: true, cause: error }),
+        recoverable: true
+      });
+    }
+  }
+  /**
+   * Handle WebSocket close event.
+   */
+  _handleClose(event) {
+    this._stopHeartbeat();
+    const wasConnected = this._state === "connected";
+    const wasClean = event.wasClean;
+    const reason = event.reason || `Code: ${event.code}`;
+    this.emit("disconnected", { reason, wasClean });
+    this._rejectAllPending(new import_transport.TransportError("Connection closed", import_transport.TransportErrorCodes.NETWORK_ERROR, { recoverable: this._shouldReconnect }));
+    if (this._shouldReconnect && wasConnected) {
+      this._scheduleReconnect();
+    } else {
+      this.setState("disconnected");
+    }
+  }
+  /**
+   * Schedule reconnection attempt.
+   */
+  _scheduleReconnect() {
+    if (!this._shouldReconnect || this._disposed)
+      return;
+    const maxAttempts = this._options.maxReconnectAttempts;
+    if (maxAttempts > 0 && this._stats.reconnectAttempts >= maxAttempts) {
+      console.warn("[WebSocketTransport] Max reconnection attempts reached");
+      this.setState("error");
+      return;
+    }
+    this._stats.reconnectAttempts++;
+    const delay = this.calculateReconnectDelay(this._stats.reconnectAttempts);
+    this.setState("reconnecting");
+    this.emit("reconnecting", {
+      attempt: this._stats.reconnectAttempts,
+      delay
+    });
+    this._reconnectTimer = setTimeout(async () => {
+      if (!this._shouldReconnect || this._disposed)
+        return;
+      try {
+        await this._createConnection();
+      } catch (error) {
+        console.warn("[WebSocketTransport] Reconnection failed:", error);
+        this._scheduleReconnect();
+      }
+    }, delay);
+  }
+  /**
+   * Start heartbeat timer.
+   */
+  _startHeartbeat() {
+    if (!this._wsOptions.pingPong || this._options.heartbeatInterval <= 0) {
+      return;
+    }
+    this._lastPongAt = Date.now();
+    this._heartbeatTimer = setInterval(() => {
+      if (!this._ws || this._state !== "connected")
+        return;
+      const missedTime = Date.now() - this._lastPongAt;
+      if (missedTime > this._options.heartbeatInterval * 3) {
+        console.warn("[WebSocketTransport] Heartbeat timeout, reconnecting...");
+        this._ws.close(4e3, "Heartbeat timeout");
+        return;
+      }
+      const heartbeat = (0, import_messages.createHeartbeatMessage)(this._options.authToken || "device");
+      this.send(heartbeat).catch((error) => {
+        console.warn("[WebSocketTransport] Failed to send heartbeat:", error);
+      });
+    }, this._options.heartbeatInterval);
+  }
+  /**
+   * Stop heartbeat timer.
+   */
+  _stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+  /**
+   * Clear all timers.
+   */
+  _clearTimers() {
+    this._stopHeartbeat();
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+  }
+  /**
+   * Reject all pending requests.
+   */
+  _rejectAllPending(error) {
+    for (const [id, pending] of this._pendingRequests) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this._pendingRequests.clear();
+  }
+  /**
+   * Serialize message for transmission.
+   */
+  _serialize(message) {
+    return JSON.stringify(message);
+  }
+  /**
+   * Deserialize received message.
+   */
+  _deserialize(data) {
+    if (typeof data === "string") {
+      return JSON.parse(data);
+    }
+    const decoder = new TextDecoder();
+    const text = decoder.decode(data);
+    return JSON.parse(text);
+  }
+  /**
+   * Dispose of the transport.
+   */
+  async dispose() {
+    this._shouldReconnect = false;
+    await super.dispose();
+  }
+}
+const createWebSocketTransport = (options) => {
+  return new WebSocketTransport(options);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WebSocketTransport,
+  createWebSocketTransport
+});

package/dist/cjs/fts/PostgresFts.d.ts

@@ -0,0 +1,29 @@
+import type { IFullTextSearch } from '../core/contracts/fts.js';
+/**
+ * Postgres full-text search using tsvector columns and GIN indexes.
+ *
+ * Unlike FTS5 (separate virtual table), Postgres stores the tsvector
+ * as a column `_tsv` on the content table itself. The `createIndex()`
+ * call adds the column, creates the GIN index, and backfills existing rows.
+ */
+export declare class PostgresFts implements IFullTextSearch {
+    /** The content table is stored during createIndex for use by other methods. */
+    private _contentTable;
+    private _columns;
+    private _lang;
+    createIndex(config: {
+        table: string;
+        columns: string[];
+        contentTable?: string;
+        tokenizer?: string;
+    }): string;
+    matchClause(_indexName: string, queryPlaceholder: string): string;
+    rankExpression(_indexName: string, queryPlaceholder?: string): string;
+    rebuildCommand(_indexName: string): string;
+    syncInsert(_indexName: string, _rowIdExpr: string, columns: string[]): string;
+    sanitizeQuery(input: string): string;
+    joinClause(contentTable: string, contentAlias: string, _ftsAlias: string, _indexName: string): string;
+    /** Map FTS5-style tokenizer strings to Postgres text search configurations. */
+    private _tokenizerToLang;
+}
+//# sourceMappingURL=PostgresFts.d.ts.map