@framers/sql-storage-adapter 0.7.1 → 0.7.3

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

@@ -0,0 +1,21 @@
+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 devices_exports = {};
+module.exports = __toCommonJS(devices_exports);
+__reExport(devices_exports, require("./deviceManager.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./deviceManager.js")
+});

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

@@ -0,0 +1,37 @@
+/**
+ * Cross-Platform Sync Module.
+ *
+ * Provides real-time delta synchronization across Electron, Capacitor,
+ * browser, and server platforms with conflict resolution and device management.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { createCrossPlatformSync } from '@framers/sql-storage-adapter/sync';
+ *
+ * const sync = await createCrossPlatformSync({
+ *   localAdapter: db,
+ *   endpoint: 'wss://sync.example.com',
+ *   tables: {
+ *     notes: { priority: 'high', conflictStrategy: 'merge' },
+ *     settings: { priority: 'critical', conflictStrategy: 'local-wins' },
+ *   },
+ *   hooks: {
+ *     onConflictNeedsResolution: (conflict) => showConflictDialog(conflict),
+ *   },
+ * });
+ *
+ * await sync.sync();
+ * ```
+ */
+export { CrossPlatformSync, createCrossPlatformSync, type CrossPlatformSyncOptions, type CrossPlatformSyncHooks, type TableSyncConfig, type SyncResult, type SyncStatus as CrossPlatformSyncStatus, } from './crossPlatformSync.js';
+export { VectorClock, createVectorClock, compareClocks, mergeClocks, generateDeviceId, dominates, type VectorClockData, type CausalRelation, type SerializedVectorClock, } from './protocol/vectorClock.js';
+export { type ChangeOperation, type ChangeRecord, type ChangeBatch, type SyncProgress, type SyncStatus as ProtocolSyncStatus, type BaseMessage, type HandshakeRequest, type HandshakeResponse, type DeltaPush, type DeltaPullRequest, type DeltaPullResponse, type AckMessage, type ConflictMessage, type PresenceMessage, type HeartbeatMessage, type HeartbeatAck, type ErrorMessage, type SyncMessage, type SyncMessageType, type DeviceType as ProtocolDeviceType, type DeviceInfo as ProtocolDeviceInfo, type ConflictResolution as ProtocolConflictResolution, generateMessageId, createBaseMessage, createHandshakeRequest, createAck, createHeartbeat, createError, createDeltaPushMessage, createDeltaPullRequest, createPresenceMessage, createHeartbeatMessage, createAckMessage, generateChangeId, createChangeRecord, isHandshakeRequest, isDeltaPush, isConflict, isError, isSyncMessage, } from './protocol/messages.js';
+export { BaseTransport, TransportError, TransportErrorCodes, type SyncTransport, type TransportOptions, type TransportState, type TransportStats, type TransportEventType, type TransportEvents, type TransportEventListener, } from './transport/transport.js';
+export { WebSocketTransport, createWebSocketTransport, type WebSocketTransportOptions, } from './transport/websocketTransport.js';
+export { HttpTransport, createHttpTransport, type HttpTransportOptions, } from './transport/httpTransport.js';
+export { ConflictResolver, createConflictResolver, FieldMergers, type ConflictStrategy, type ResolutionDecision, type SyncConflict, type ConflictResolution, type ConflictUIHooks, type ConflictResolverOptions, type FieldMerger, } from './conflicts/conflictResolver.js';
+export { DeviceManager, createDeviceManager, type DeviceType, type PresenceStatus, type DeviceInfo, type DeviceCapabilities, type DeviceRegistrationOptions, type PresenceEvent, type DeviceManagerEventType, type DeviceManagerEvents, type DeviceManagerOptions, } from './devices/deviceManager.js';
+export { SyncLogManager, type ChangeLogEntry as SyncLogChange, type ConflictEntry as SyncLogConflict, } from './tables/syncLogManager.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,111 @@
+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 sync_exports = {};
+__export(sync_exports, {
+  BaseTransport: () => import_transport.BaseTransport,
+  ConflictResolver: () => import_conflictResolver.ConflictResolver,
+  CrossPlatformSync: () => import_crossPlatformSync.CrossPlatformSync,
+  DeviceManager: () => import_deviceManager.DeviceManager,
+  FieldMergers: () => import_conflictResolver.FieldMergers,
+  HttpTransport: () => import_httpTransport.HttpTransport,
+  SyncLogManager: () => import_syncLogManager.SyncLogManager,
+  TransportError: () => import_transport.TransportError,
+  TransportErrorCodes: () => import_transport.TransportErrorCodes,
+  VectorClock: () => import_vectorClock.VectorClock,
+  WebSocketTransport: () => import_websocketTransport.WebSocketTransport,
+  compareClocks: () => import_vectorClock.compareClocks,
+  createAck: () => import_messages.createAck,
+  createAckMessage: () => import_messages.createAckMessage,
+  createBaseMessage: () => import_messages.createBaseMessage,
+  createChangeRecord: () => import_messages.createChangeRecord,
+  createConflictResolver: () => import_conflictResolver.createConflictResolver,
+  createCrossPlatformSync: () => import_crossPlatformSync.createCrossPlatformSync,
+  createDeltaPullRequest: () => import_messages.createDeltaPullRequest,
+  createDeltaPushMessage: () => import_messages.createDeltaPushMessage,
+  createDeviceManager: () => import_deviceManager.createDeviceManager,
+  createError: () => import_messages.createError,
+  createHandshakeRequest: () => import_messages.createHandshakeRequest,
+  createHeartbeat: () => import_messages.createHeartbeat,
+  createHeartbeatMessage: () => import_messages.createHeartbeatMessage,
+  createHttpTransport: () => import_httpTransport.createHttpTransport,
+  createPresenceMessage: () => import_messages.createPresenceMessage,
+  createVectorClock: () => import_vectorClock.createVectorClock,
+  createWebSocketTransport: () => import_websocketTransport.createWebSocketTransport,
+  dominates: () => import_vectorClock.dominates,
+  generateChangeId: () => import_messages.generateChangeId,
+  generateDeviceId: () => import_vectorClock.generateDeviceId,
+  generateMessageId: () => import_messages.generateMessageId,
+  isConflict: () => import_messages.isConflict,
+  isDeltaPush: () => import_messages.isDeltaPush,
+  isError: () => import_messages.isError,
+  isHandshakeRequest: () => import_messages.isHandshakeRequest,
+  isSyncMessage: () => import_messages.isSyncMessage,
+  mergeClocks: () => import_vectorClock.mergeClocks
+});
+module.exports = __toCommonJS(sync_exports);
+var import_crossPlatformSync = require("./crossPlatformSync.js");
+var import_vectorClock = require("./protocol/vectorClock.js");
+var import_messages = require("./protocol/messages.js");
+var import_transport = require("./transport/transport.js");
+var import_websocketTransport = require("./transport/websocketTransport.js");
+var import_httpTransport = require("./transport/httpTransport.js");
+var import_conflictResolver = require("./conflicts/conflictResolver.js");
+var import_deviceManager = require("./devices/deviceManager.js");
+var import_syncLogManager = require("./tables/syncLogManager.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseTransport,
+  ConflictResolver,
+  CrossPlatformSync,
+  DeviceManager,
+  FieldMergers,
+  HttpTransport,
+  SyncLogManager,
+  TransportError,
+  TransportErrorCodes,
+  VectorClock,
+  WebSocketTransport,
+  compareClocks,
+  createAck,
+  createAckMessage,
+  createBaseMessage,
+  createChangeRecord,
+  createConflictResolver,
+  createCrossPlatformSync,
+  createDeltaPullRequest,
+  createDeltaPushMessage,
+  createDeviceManager,
+  createError,
+  createHandshakeRequest,
+  createHeartbeat,
+  createHeartbeatMessage,
+  createHttpTransport,
+  createPresenceMessage,
+  createVectorClock,
+  createWebSocketTransport,
+  dominates,
+  generateChangeId,
+  generateDeviceId,
+  generateMessageId,
+  isConflict,
+  isDeltaPush,
+  isError,
+  isHandshakeRequest,
+  isSyncMessage,
+  mergeClocks
+});

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

@@ -0,0 +1,11 @@
+/**
+ * Sync Protocol Module.
+ *
+ * Provides message types, vector clocks, and protocol utilities
+ * for cross-platform synchronization.
+ *
+ * @packageDocumentation
+ */
+export * from './vectorClock.js';
+export * from './messages.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,23 @@
+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 protocol_exports = {};
+module.exports = __toCommonJS(protocol_exports);
+__reExport(protocol_exports, require("./vectorClock.js"), module.exports);
+__reExport(protocol_exports, require("./messages.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./vectorClock.js"),
+  ...require("./messages.js")
+});

package/dist/cjs/features/sync/protocol/messages.d.ts

@@ -0,0 +1,348 @@
+/**
+ * Cross-Platform Sync Protocol Messages.
+ *
+ * Defines the message format for device-to-device synchronization.
+ * Messages are exchanged over WebSocket or HTTP transport.
+ *
+ * @packageDocumentation
+ */
+import type { VectorClockData } from './vectorClock.js';
+/**
+ * Type of device in the sync network.
+ */
+export type DeviceType = 'electron' | 'capacitor' | 'browser' | 'server';
+/**
+ * Device information.
+ */
+export interface DeviceInfo {
+    /** Unique device identifier */
+    deviceId: string;
+    /** Device type */
+    deviceType: DeviceType;
+    /** Human-readable device name */
+    deviceName?: string;
+    /** App version running on device */
+    appVersion?: string;
+    /** Platform info (e.g., "macOS 14.0", "iOS 17.0") */
+    platform?: string;
+    /** When device was first seen */
+    firstSeen?: number;
+    /** When device was last active */
+    lastSeen?: number;
+}
+/**
+ * Type of database operation.
+ */
+export type ChangeOperation = 'INSERT' | 'UPDATE' | 'DELETE';
+/**
+ * A single database change record.
+ */
+export interface ChangeRecord {
+    /** Unique change ID (UUID) */
+    changeId: string;
+    /** Table name */
+    table: string;
+    /** Record primary key */
+    recordId: string;
+    /** Type of operation */
+    operation: ChangeOperation;
+    /** Vector clock at time of change */
+    vectorClock: VectorClockData;
+    /** Device that made the change */
+    deviceId: string;
+    /** Record data before change (for UPDATE/DELETE) */
+    oldData?: Record<string, unknown>;
+    /** Record data after change (for INSERT/UPDATE) */
+    newData?: Record<string, unknown>;
+    /** When change was made (local timestamp) */
+    timestamp: number;
+    /** Whether change has been synced */
+    synced?: boolean;
+}
+/**
+ * Batch of changes for efficient transfer.
+ */
+export interface ChangeBatch {
+    /** Changes in this batch */
+    changes: ChangeRecord[];
+    /** Batch sequence number */
+    sequence: number;
+    /** Total batches in this sync */
+    totalBatches: number;
+    /** Compressed (gzip/brotli) if true */
+    compressed?: boolean;
+}
+/**
+ * Current sync status.
+ */
+export type SyncStatus = 'idle' | 'connecting' | 'handshaking' | 'syncing' | 'resolving' | 'error' | 'disconnected';
+/**
+ * Sync progress information.
+ */
+export interface SyncProgress {
+    status: SyncStatus;
+    /** Records pushed to remote */
+    pushed: number;
+    /** Records pulled from remote */
+    pulled: number;
+    /** Conflicts detected */
+    conflicts: number;
+    /** Current table being synced */
+    currentTable?: string;
+    /** Progress percentage (0-100) */
+    percent: number;
+}
+/**
+ * Base message structure.
+ */
+export interface BaseMessage {
+    /** Message type discriminator */
+    type: string;
+    /** Unique message ID for acknowledgment */
+    messageId: string;
+    /** Sender device ID */
+    deviceId: string;
+    /** Message timestamp */
+    timestamp: number;
+}
+/**
+ * Handshake request - initiates connection.
+ */
+export interface HandshakeRequest extends BaseMessage {
+    type: 'handshake_request';
+    /** Sender device info */
+    device: DeviceInfo;
+    /** Current vector clock */
+    vectorClock: VectorClockData;
+    /** Supported protocol version */
+    protocolVersion: number;
+    /** Capabilities (e.g., compression, encryption) */
+    capabilities: string[];
+    /** Tables to sync */
+    tables: string[];
+}
+/**
+ * Handshake response - confirms connection.
+ */
+export interface HandshakeResponse extends BaseMessage {
+    type: 'handshake_response';
+    /** Whether handshake accepted */
+    accepted: boolean;
+    /** Rejection reason if not accepted */
+    rejectionReason?: string;
+    /** Server device info */
+    device: DeviceInfo;
+    /** Server's vector clock */
+    vectorClock: VectorClockData;
+    /** Negotiated protocol version */
+    protocolVersion: number;
+    /** Negotiated capabilities */
+    capabilities: string[];
+    /** Session ID for this connection */
+    sessionId: string;
+}
+/**
+ * Delta push - send local changes to remote.
+ */
+export interface DeltaPush extends BaseMessage {
+    type: 'delta_push';
+    /** Batch of changes */
+    batch: ChangeBatch;
+    /** Current vector clock after changes */
+    vectorClock: VectorClockData;
+}
+/**
+ * Delta pull request - request changes since clock.
+ */
+export interface DeltaPullRequest extends BaseMessage {
+    type: 'delta_pull_request';
+    /** Vector clock to sync from */
+    sinceVectorClock: VectorClockData;
+    /** Tables to pull */
+    tables?: string[];
+    /** Maximum records to return */
+    limit?: number;
+}
+/**
+ * Delta pull response - changes from remote.
+ */
+export interface DeltaPullResponse extends BaseMessage {
+    type: 'delta_pull_response';
+    /** Batch of changes */
+    batch: ChangeBatch;
+    /** Server's current vector clock */
+    vectorClock: VectorClockData;
+    /** Whether more changes available */
+    hasMore: boolean;
+}
+/**
+ * Acknowledgment message.
+ */
+export interface AckMessage extends BaseMessage {
+    type: 'ack';
+    /** ID of message being acknowledged */
+    ackMessageId: string;
+    /** Success status */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Conflict notification.
+ */
+export interface ConflictMessage extends BaseMessage {
+    type: 'conflict';
+    /** Table with conflict */
+    table: string;
+    /** Record ID with conflict */
+    recordId: string;
+    /** Local version */
+    localData: Record<string, unknown>;
+    /** Remote version */
+    remoteData: Record<string, unknown>;
+    /** Local vector clock */
+    localClock: VectorClockData;
+    /** Remote vector clock */
+    remoteClock: VectorClockData;
+    /** Suggested resolution */
+    suggestedResolution?: 'use_local' | 'use_remote' | 'merge';
+}
+/**
+ * Conflict resolution.
+ */
+export interface ConflictResolution extends BaseMessage {
+    type: 'conflict_resolution';
+    /** Original conflict message ID */
+    conflictMessageId: string;
+    /** Resolution strategy */
+    resolution: 'use_local' | 'use_remote' | 'use_merged' | 'keep_both' | 'defer';
+    /** Merged data if using 'use_merged' */
+    mergedData?: Record<string, unknown>;
+}
+/**
+ * Device presence update.
+ */
+export interface PresenceMessage extends BaseMessage {
+    type: 'presence';
+    /** Presence status */
+    status: 'online' | 'offline' | 'away' | 'syncing';
+    /** Device info */
+    device: DeviceInfo;
+    /** Current vector clock */
+    vectorClock?: VectorClockData;
+}
+/**
+ * Heartbeat for connection keep-alive.
+ */
+export interface HeartbeatMessage extends BaseMessage {
+    type: 'heartbeat';
+    /** Sequence number */
+    sequence: number;
+}
+/**
+ * Heartbeat acknowledgment.
+ */
+export interface HeartbeatAck extends BaseMessage {
+    type: 'heartbeat_ack';
+    /** Echo sequence number */
+    sequence: number;
+    /** Round-trip time if measurable */
+    rtt?: number;
+}
+/**
+ * Error message.
+ */
+export interface ErrorMessage extends BaseMessage {
+    type: 'error';
+    /** Error code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Whether error is recoverable */
+    recoverable: boolean;
+    /** Related message ID if applicable */
+    relatedMessageId?: string;
+}
+/**
+ * All possible sync messages.
+ */
+export type SyncMessage = HandshakeRequest | HandshakeResponse | DeltaPush | DeltaPullRequest | DeltaPullResponse | AckMessage | ConflictMessage | ConflictResolution | PresenceMessage | HeartbeatMessage | HeartbeatAck | ErrorMessage;
+/**
+ * Message type discriminator values.
+ */
+export type SyncMessageType = SyncMessage['type'];
+/**
+ * Generate a unique message ID.
+ */
+export declare function generateMessageId(): string;
+/**
+ * Create a base message with common fields.
+ */
+export declare function createBaseMessage(type: string, deviceId: string): Omit<BaseMessage, 'type'> & {
+    type: string;
+};
+/**
+ * Create a handshake request message.
+ */
+export declare function createHandshakeRequest(device: DeviceInfo, vectorClock: VectorClockData, tables: string[], capabilities?: string[]): HandshakeRequest;
+/**
+ * Create an acknowledgment message.
+ */
+export declare function createAck(deviceId: string, ackMessageId: string, success: boolean, error?: string): AckMessage;
+/**
+ * Create a heartbeat message.
+ */
+export declare function createHeartbeat(deviceId: string, sequence: number): HeartbeatMessage;
+/**
+ * Create an error message.
+ */
+export declare function createError(deviceId: string, code: string, message: string, recoverable?: boolean, relatedMessageId?: string): ErrorMessage;
+/**
+ * Check if message is a handshake request.
+ */
+export declare function isHandshakeRequest(msg: SyncMessage): msg is HandshakeRequest;
+/**
+ * Check if message is a delta push.
+ */
+export declare function isDeltaPush(msg: SyncMessage): msg is DeltaPush;
+/**
+ * Check if message is a conflict.
+ */
+export declare function isConflict(msg: SyncMessage): msg is ConflictMessage;
+/**
+ * Check if message is an error.
+ */
+export declare function isError(msg: SyncMessage): msg is ErrorMessage;
+/**
+ * Type guard to check if an unknown value is a valid SyncMessage.
+ */
+export declare function isSyncMessage(value: unknown): value is SyncMessage;
+/**
+ * Create a delta push message.
+ */
+export declare function createDeltaPushMessage(deviceId: string, changes: ChangeRecord[], vectorClock: VectorClockData, sequence?: number, totalBatches?: number): DeltaPush;
+/**
+ * Create a delta pull request message.
+ */
+export declare function createDeltaPullRequest(deviceId: string, sinceVectorClock: VectorClockData, tables?: string[], limit?: number): DeltaPullRequest;
+/**
+ * Create a presence message.
+ */
+export declare function createPresenceMessage(device: DeviceInfo, status: 'online' | 'offline' | 'away' | 'syncing', vectorClock?: VectorClockData): PresenceMessage;
+/**
+ * Create a heartbeat message.
+ */
+export declare function createHeartbeatMessage(deviceId: string, sequence?: number): HeartbeatMessage;
+/**
+ * Create an ack message.
+ */
+export declare function createAckMessage(deviceId: string, ackMessageId: string, success?: boolean, error?: string): AckMessage;
+/**
+ * Generate a unique change ID.
+ */
+export declare function generateChangeId(): string;
+/**
+ * Create a change record.
+ */
+export declare function createChangeRecord(table: string, recordId: string, operation: ChangeOperation, deviceId: string, vectorClock: VectorClockData, newData?: Record<string, unknown>, oldData?: Record<string, unknown>): ChangeRecord;
+//# sourceMappingURL=messages.d.ts.map