@framers/sql-storage-adapter 0.7.2 → 0.7.3

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

@@ -0,0 +1,346 @@
+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 httpTransport_exports = {};
+__export(httpTransport_exports, {
+  HttpTransport: () => HttpTransport,
+  createHttpTransport: () => createHttpTransport
+});
+module.exports = __toCommonJS(httpTransport_exports);
+var import_transport = require("./transport.js");
+var import_messages = require("../protocol/messages.js");
+class HttpTransport extends import_transport.BaseTransport {
+  constructor(options) {
+    super(options);
+    this.type = "http";
+    this._pollTimer = null;
+    this._abortController = null;
+    this._isPolling = false;
+    this._lastEventId = null;
+    this._messageQueue = [];
+    this._flushTimer = null;
+    this._pendingRequests = /* @__PURE__ */ new Map();
+    this._httpOptions = {
+      ...this._options,
+      pollingInterval: options.pollingInterval ?? 5e3,
+      maxMessagesPerPoll: options.maxMessagesPerPoll ?? 100,
+      longPolling: options.longPolling ?? true,
+      longPollTimeout: options.longPollTimeout ?? 3e4,
+      fetchImplementation: options.fetchImplementation ?? globalThis.fetch?.bind(globalThis)
+    };
+  }
+  /**
+   * Connect (start polling).
+   */
+  async connect() {
+    this.checkDisposed();
+    if (this._state === "connected" || this._state === "connecting") {
+      return;
+    }
+    this.setState("connecting");
+    try {
+      await this._syncCheck();
+      this.setState("connected");
+      this._stats.connectedAt = Date.now();
+      this.emit("connected", { timestamp: Date.now() });
+      this._startPolling();
+    } catch (error) {
+      this.setState("error");
+      throw error;
+    }
+  }
+  /**
+   * Disconnect (stop polling).
+   */
+  async disconnect(reason = "client disconnect") {
+    this._stopPolling();
+    this._clearPendingRequests(new import_transport.TransportError(reason, import_transport.TransportErrorCodes.DISPOSED, { recoverable: false }));
+    this.setState("disconnected");
+    this.emit("disconnected", { reason, wasClean: true });
+  }
+  /**
+   * Send a sync message.
+   */
+  async send(message) {
+    this.checkDisposed();
+    if (this._state !== "connected") {
+      throw new import_transport.TransportError("Not connected", import_transport.TransportErrorCodes.SEND_FAILED, { recoverable: true });
+    }
+    this._messageQueue.push(message);
+    this._scheduleFlush();
+  }
+  /**
+   * 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);
+      });
+    });
+  }
+  /**
+   * Perform initial sync check to verify connectivity.
+   */
+  async _syncCheck() {
+    const url = `${this._options.endpoint}/check`;
+    try {
+      const response = await this._fetch(url, {
+        method: "GET",
+        timeout: this._options.connectionTimeout
+      });
+      if (!response.ok) {
+        throw new import_transport.TransportError(`Sync check failed: ${response.status}`, response.status === 401 || response.status === 403 ? import_transport.TransportErrorCodes.AUTH_FAILED : import_transport.TransportErrorCodes.SERVER_ERROR, { recoverable: response.status >= 500 });
+      }
+    } catch (error) {
+      if (error instanceof import_transport.TransportError)
+        throw error;
+      throw new import_transport.TransportError("Connection failed", import_transport.TransportErrorCodes.CONNECTION_FAILED, { recoverable: true, cause: error });
+    }
+  }
+  /**
+   * Start the polling loop.
+   */
+  _startPolling() {
+    if (this._isPolling)
+      return;
+    this._isPolling = true;
+    this._poll();
+  }
+  /**
+   * Stop the polling loop.
+   */
+  _stopPolling() {
+    this._isPolling = false;
+    if (this._pollTimer) {
+      clearTimeout(this._pollTimer);
+      this._pollTimer = null;
+    }
+    if (this._abortController) {
+      this._abortController.abort();
+      this._abortController = null;
+    }
+    if (this._flushTimer) {
+      clearTimeout(this._flushTimer);
+      this._flushTimer = null;
+    }
+  }
+  /**
+   * Poll for new messages.
+   */
+  async _poll() {
+    if (!this._isPolling || this._disposed)
+      return;
+    this._abortController = new AbortController();
+    try {
+      const messages = await this._fetchMessages();
+      for (const message of messages) {
+        this._handleMessage(message);
+      }
+      this._pollTimer = setTimeout(() => this._poll(), this._httpOptions.pollingInterval);
+    } catch (error) {
+      if (error.name === "AbortError") {
+        return;
+      }
+      console.warn("[HttpTransport] Poll error:", error);
+      this.emit("error", {
+        error,
+        recoverable: true
+      });
+      if (this._isPolling && this._options.autoReconnect) {
+        this._stats.reconnectAttempts++;
+        const delay = this.calculateReconnectDelay(this._stats.reconnectAttempts);
+        this.emit("reconnecting", {
+          attempt: this._stats.reconnectAttempts,
+          delay
+        });
+        this._pollTimer = setTimeout(() => this._poll(), delay);
+      } else {
+        this.setState("error");
+      }
+    }
+  }
+  /**
+   * Fetch messages from server.
+   */
+  async _fetchMessages() {
+    const url = new URL(`${this._options.endpoint}/poll`);
+    if (this._lastEventId) {
+      url.searchParams.set("lastEventId", this._lastEventId);
+    }
+    url.searchParams.set("limit", String(this._httpOptions.maxMessagesPerPoll));
+    if (this._httpOptions.longPolling) {
+      url.searchParams.set("timeout", String(this._httpOptions.longPollTimeout));
+    }
+    const response = await this._fetch(url.toString(), {
+      method: "GET",
+      timeout: this._httpOptions.longPolling ? this._httpOptions.longPollTimeout + 5e3 : this._options.requestTimeout,
+      signal: this._abortController?.signal
+    });
+    if (!response.ok) {
+      throw new import_transport.TransportError(`Poll failed: ${response.status}`, import_transport.TransportErrorCodes.SERVER_ERROR, { recoverable: response.status >= 500 });
+    }
+    const data = await response.json();
+    if (data.lastEventId) {
+      this._lastEventId = data.lastEventId;
+    }
+    const messages = [];
+    for (const msg of data.messages) {
+      if ((0, import_messages.isSyncMessage)(msg)) {
+        messages.push(msg);
+        this._stats.messagesReceived++;
+      }
+    }
+    return messages;
+  }
+  /**
+   * Handle an incoming message.
+   */
+  _handleMessage(message) {
+    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;
+      }
+    }
+    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;
+    }
+    this.emit("message", { message, receivedAt: Date.now() });
+  }
+  /**
+   * Schedule message queue flush.
+   */
+  _scheduleFlush() {
+    if (this._flushTimer)
+      return;
+    this._flushTimer = setTimeout(() => {
+      this._flushTimer = null;
+      this._flushQueue().catch((error) => {
+        console.error("[HttpTransport] Flush error:", error);
+      });
+    }, 50);
+  }
+  /**
+   * Flush the message queue to server.
+   */
+  async _flushQueue() {
+    if (this._messageQueue.length === 0)
+      return;
+    const messages = this._messageQueue.splice(0, 100);
+    try {
+      const response = await this._fetch(`${this._options.endpoint}/push`, {
+        method: "POST",
+        body: JSON.stringify({ messages }),
+        timeout: this._options.requestTimeout
+      });
+      if (!response.ok) {
+        this._messageQueue.unshift(...messages);
+        throw new import_transport.TransportError(`Push failed: ${response.status}`, import_transport.TransportErrorCodes.SEND_FAILED, { recoverable: response.status >= 500 });
+      }
+      this._stats.messagesSent += messages.length;
+      const data = await response.json();
+      if (data.responses) {
+        for (const resp of data.responses) {
+          if ((0, import_messages.isSyncMessage)(resp)) {
+            this._handleMessage(resp);
+          }
+        }
+      }
+      if (this._messageQueue.length > 0) {
+        this._scheduleFlush();
+      }
+    } catch (error) {
+      if (error instanceof import_transport.TransportError)
+        throw error;
+      this._messageQueue.unshift(...messages);
+      throw new import_transport.TransportError("Failed to send messages", import_transport.TransportErrorCodes.SEND_FAILED, { recoverable: true, cause: error });
+    }
+  }
+  /**
+   * Make an HTTP request.
+   */
+  async _fetch(url, options) {
+    const fetchFn = this._httpOptions.fetchImplementation;
+    if (!fetchFn) {
+      throw new import_transport.TransportError("Fetch not available", import_transport.TransportErrorCodes.NETWORK_ERROR, { recoverable: false });
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      ...this._options.headers
+    };
+    if (this._options.authToken) {
+      headers["Authorization"] = `Bearer ${this._options.authToken}`;
+    }
+    let timeoutId;
+    let abortController;
+    if (options.timeout && !options.signal) {
+      abortController = new AbortController();
+      timeoutId = setTimeout(() => abortController.abort(), options.timeout);
+    }
+    try {
+      const response = await fetchFn(url, {
+        method: options.method,
+        headers,
+        body: options.body,
+        signal: options.signal ?? abortController?.signal
+      });
+      return response;
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+  /**
+   * Clear all pending requests.
+   */
+  _clearPendingRequests(error) {
+    for (const [id, pending] of this._pendingRequests) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this._pendingRequests.clear();
+  }
+}
+const createHttpTransport = (options) => {
+  return new HttpTransport(options);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HttpTransport,
+  createHttpTransport
+});

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

@@ -0,0 +1,12 @@
+/**
+ * Sync Transport Module.
+ *
+ * Provides transport layer abstractions for sync communication.
+ * Includes WebSocket (real-time) and HTTP (polling fallback) transports.
+ *
+ * @packageDocumentation
+ */
+export * from './transport.js';
+export * from './websocketTransport.js';
+export * from './httpTransport.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,25 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var transport_exports = {};
+module.exports = __toCommonJS(transport_exports);
+__reExport(transport_exports, require("./transport.js"), module.exports);
+__reExport(transport_exports, require("./websocketTransport.js"), module.exports);
+__reExport(transport_exports, require("./httpTransport.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./transport.js"),
+  ...require("./websocketTransport.js"),
+  ...require("./httpTransport.js")
+});

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

@@ -0,0 +1,259 @@
+/**
+ * Transport Layer Interface.
+ *
+ * Defines the contract for sync transports (WebSocket, HTTP polling, etc.).
+ * Transports handle the low-level communication between sync nodes.
+ *
+ * @packageDocumentation
+ */
+import type { SyncMessage } from '../protocol/messages.js';
+/**
+ * Transport connection state.
+ */
+export type TransportState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/**
+ * Transport configuration options.
+ */
+export interface TransportOptions {
+    /** Server endpoint URL */
+    endpoint: string;
+    /** Authentication token or API key */
+    authToken?: string;
+    /** Custom headers for HTTP requests */
+    headers?: Record<string, string>;
+    /** Connection timeout in milliseconds */
+    connectionTimeout?: number;
+    /** Request timeout in milliseconds */
+    requestTimeout?: number;
+    /** Enable automatic reconnection */
+    autoReconnect?: boolean;
+    /** Initial reconnection delay in milliseconds */
+    reconnectDelay?: number;
+    /** Maximum reconnection delay in milliseconds */
+    maxReconnectDelay?: number;
+    /** Maximum reconnection attempts (0 = unlimited) */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in milliseconds (0 = disabled) */
+    heartbeatInterval?: number;
+    /** Enable message compression */
+    compression?: boolean;
+}
+/**
+ * Transport event types.
+ */
+export type TransportEventType = 'connected' | 'disconnected' | 'message' | 'error' | 'reconnecting' | 'stateChange';
+/**
+ * Transport event payloads.
+ */
+export interface TransportEvents {
+    connected: {
+        timestamp: number;
+    };
+    disconnected: {
+        reason: string;
+        wasClean: boolean;
+    };
+    message: {
+        message: SyncMessage;
+        receivedAt: number;
+    };
+    error: {
+        error: Error;
+        recoverable: boolean;
+    };
+    reconnecting: {
+        attempt: number;
+        delay: number;
+    };
+    stateChange: {
+        previousState: TransportState;
+        currentState: TransportState;
+    };
+}
+/**
+ * Transport event listener.
+ */
+export type TransportEventListener<T extends TransportEventType> = (event: TransportEvents[T]) => void;
+/**
+ * Transport statistics.
+ */
+export interface TransportStats {
+    /** Current connection state */
+    state: TransportState;
+    /** Time when connection was established (epoch ms) */
+    connectedAt?: number;
+    /** Total messages sent */
+    messagesSent: number;
+    /** Total messages received */
+    messagesReceived: number;
+    /** Total bytes sent */
+    bytesSent: number;
+    /** Total bytes received */
+    bytesReceived: number;
+    /** Number of reconnection attempts */
+    reconnectAttempts: number;
+    /** Average round-trip latency in milliseconds */
+    averageLatency?: number;
+    /** Last error encountered */
+    lastError?: Error;
+}
+/**
+ * Transport interface for sync communication.
+ *
+ * Implementations handle the actual network communication,
+ * allowing the sync engine to be transport-agnostic.
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebSocketTransport({
+ *   endpoint: 'wss://sync.example.com',
+ *   authToken: 'bearer-token',
+ *   autoReconnect: true,
+ * });
+ *
+ * transport.on('message', ({ message }) => {
+ *   console.log('Received:', message);
+ * });
+ *
+ * await transport.connect();
+ * await transport.send(handshakeMessage);
+ * ```
+ */
+export interface SyncTransport {
+    /** Transport type identifier */
+    readonly type: 'websocket' | 'http' | 'custom';
+    /** Current connection state */
+    readonly state: TransportState;
+    /** Whether the transport is currently connected */
+    readonly isConnected: boolean;
+    /**
+     * Connect to the sync server.
+     *
+     * @throws {TransportError} If connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the sync server.
+     *
+     * @param reason - Optional disconnect reason
+     */
+    disconnect(reason?: string): Promise<void>;
+    /**
+     * Send a message to the sync server.
+     *
+     * @param message - The sync message to send
+     * @returns Promise that resolves when message is sent
+     * @throws {TransportError} If send fails
+     */
+    send(message: SyncMessage): Promise<void>;
+    /**
+     * Send a message and wait for a response.
+     *
+     * @param message - The sync message to send
+     * @param timeout - Optional response timeout in milliseconds
+     * @returns Promise that resolves with the response message
+     * @throws {TransportError} If send fails or times out
+     */
+    request(message: SyncMessage, timeout?: number): Promise<SyncMessage>;
+    /**
+     * Register an event listener.
+     *
+     * @param event - Event type to listen for
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    on<T extends TransportEventType>(event: T, listener: TransportEventListener<T>): () => void;
+    /**
+     * Register a one-time event listener.
+     *
+     * @param event - Event type to listen for
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    once<T extends TransportEventType>(event: T, listener: TransportEventListener<T>): () => void;
+    /**
+     * Get transport statistics.
+     */
+    getStats(): TransportStats;
+    /**
+     * Dispose of the transport and release resources.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Transport error with additional context.
+ */
+export declare class TransportError extends Error {
+    /** Error code for categorization */
+    readonly code: string;
+    /** Whether the error is recoverable */
+    readonly recoverable: boolean;
+    /** Original error if wrapping another error */
+    readonly cause?: Error;
+    constructor(message: string, code: string, options?: {
+        recoverable?: boolean;
+        cause?: Error;
+    });
+}
+/**
+ * Common transport error codes.
+ */
+export declare const TransportErrorCodes: {
+    /** Connection failed */
+    readonly CONNECTION_FAILED: "CONNECTION_FAILED";
+    /** Connection timeout */
+    readonly CONNECTION_TIMEOUT: "CONNECTION_TIMEOUT";
+    /** Authentication failed */
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    /** Request timeout */
+    readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
+    /** Send failed */
+    readonly SEND_FAILED: "SEND_FAILED";
+    /** Server error */
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    /** Network error */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** Protocol error */
+    readonly PROTOCOL_ERROR: "PROTOCOL_ERROR";
+    /** Transport disposed */
+    readonly DISPOSED: "DISPOSED";
+};
+/**
+ * Base transport implementation with common functionality.
+ */
+export declare abstract class BaseTransport implements SyncTransport {
+    abstract readonly type: 'websocket' | 'http' | 'custom';
+    protected _state: TransportState;
+    protected _stats: TransportStats;
+    protected _options: Required<TransportOptions>;
+    protected _disposed: boolean;
+    private _listeners;
+    constructor(options: TransportOptions);
+    get state(): TransportState;
+    get isConnected(): boolean;
+    abstract connect(): Promise<void>;
+    abstract disconnect(reason?: string): Promise<void>;
+    abstract send(message: SyncMessage): Promise<void>;
+    abstract request(message: SyncMessage, timeout?: number): Promise<SyncMessage>;
+    on<T extends TransportEventType>(event: T, listener: TransportEventListener<T>): () => void;
+    once<T extends TransportEventType>(event: T, listener: TransportEventListener<T>): () => void;
+    getStats(): TransportStats;
+    dispose(): Promise<void>;
+    /**
+     * Emit an event to all registered listeners.
+     */
+    protected emit<T extends TransportEventType>(event: T, data: TransportEvents[T]): void;
+    /**
+     * Update transport state and emit event.
+     */
+    protected setState(newState: TransportState): void;
+    /**
+     * Check if transport is disposed and throw if so.
+     */
+    protected checkDisposed(): void;
+    /**
+     * Calculate next reconnection delay with exponential backoff.
+     */
+    protected calculateReconnectDelay(attempt: number): number;
+}
+//# sourceMappingURL=transport.d.ts.map