@framers/sql-storage-adapter 0.7.2 → 0.7.3

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

@@ -0,0 +1,215 @@
+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 messages_exports = {};
+__export(messages_exports, {
+  createAck: () => createAck,
+  createAckMessage: () => createAckMessage,
+  createBaseMessage: () => createBaseMessage,
+  createChangeRecord: () => createChangeRecord,
+  createDeltaPullRequest: () => createDeltaPullRequest,
+  createDeltaPushMessage: () => createDeltaPushMessage,
+  createError: () => createError,
+  createHandshakeRequest: () => createHandshakeRequest,
+  createHeartbeat: () => createHeartbeat,
+  createHeartbeatMessage: () => createHeartbeatMessage,
+  createPresenceMessage: () => createPresenceMessage,
+  generateChangeId: () => generateChangeId,
+  generateMessageId: () => generateMessageId,
+  isConflict: () => isConflict,
+  isDeltaPush: () => isDeltaPush,
+  isError: () => isError,
+  isHandshakeRequest: () => isHandshakeRequest,
+  isSyncMessage: () => isSyncMessage
+});
+module.exports = __toCommonJS(messages_exports);
+function generateMessageId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `msg_${timestamp}_${random}`;
+}
+function createBaseMessage(type, deviceId) {
+  return {
+    type,
+    messageId: generateMessageId(),
+    deviceId,
+    timestamp: Date.now()
+  };
+}
+function createHandshakeRequest(device, vectorClock, tables, capabilities = ["gzip", "delta"]) {
+  return {
+    ...createBaseMessage("handshake_request", device.deviceId),
+    type: "handshake_request",
+    device,
+    vectorClock,
+    protocolVersion: 1,
+    capabilities,
+    tables
+  };
+}
+function createAck(deviceId, ackMessageId, success, error) {
+  return {
+    ...createBaseMessage("ack", deviceId),
+    type: "ack",
+    ackMessageId,
+    success,
+    error
+  };
+}
+function createHeartbeat(deviceId, sequence) {
+  return {
+    ...createBaseMessage("heartbeat", deviceId),
+    type: "heartbeat",
+    sequence
+  };
+}
+function createError(deviceId, code, message, recoverable = true, relatedMessageId) {
+  return {
+    ...createBaseMessage("error", deviceId),
+    type: "error",
+    code,
+    message,
+    recoverable,
+    relatedMessageId
+  };
+}
+function isHandshakeRequest(msg) {
+  return msg.type === "handshake_request";
+}
+function isDeltaPush(msg) {
+  return msg.type === "delta_push";
+}
+function isConflict(msg) {
+  return msg.type === "conflict";
+}
+function isError(msg) {
+  return msg.type === "error";
+}
+function isSyncMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  if (typeof msg.type !== "string")
+    return false;
+  if (typeof msg.messageId !== "string")
+    return false;
+  if (typeof msg.deviceId !== "string")
+    return false;
+  if (typeof msg.timestamp !== "number")
+    return false;
+  const validTypes = [
+    "handshake_request",
+    "handshake_response",
+    "delta_push",
+    "delta_pull_request",
+    "delta_pull_response",
+    "ack",
+    "conflict",
+    "conflict_resolution",
+    "presence",
+    "heartbeat",
+    "heartbeat_ack",
+    "error"
+  ];
+  return validTypes.includes(msg.type);
+}
+function createDeltaPushMessage(deviceId, changes, vectorClock, sequence = 1, totalBatches = 1) {
+  return {
+    ...createBaseMessage("delta_push", deviceId),
+    type: "delta_push",
+    batch: {
+      changes,
+      sequence,
+      totalBatches
+    },
+    vectorClock
+  };
+}
+function createDeltaPullRequest(deviceId, sinceVectorClock, tables, limit) {
+  return {
+    ...createBaseMessage("delta_pull_request", deviceId),
+    type: "delta_pull_request",
+    sinceVectorClock,
+    tables,
+    limit
+  };
+}
+function createPresenceMessage(device, status, vectorClock) {
+  return {
+    ...createBaseMessage("presence", device.deviceId),
+    type: "presence",
+    status,
+    device,
+    vectorClock
+  };
+}
+function createHeartbeatMessage(deviceId, sequence = 0) {
+  return {
+    ...createBaseMessage("heartbeat", deviceId),
+    type: "heartbeat",
+    sequence
+  };
+}
+function createAckMessage(deviceId, ackMessageId, success = true, error) {
+  return {
+    ...createBaseMessage("ack", deviceId),
+    type: "ack",
+    ackMessageId,
+    success,
+    error
+  };
+}
+function generateChangeId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `chg_${timestamp}_${random}`;
+}
+function createChangeRecord(table, recordId, operation, deviceId, vectorClock, newData, oldData) {
+  return {
+    changeId: generateChangeId(),
+    table,
+    recordId,
+    operation,
+    deviceId,
+    vectorClock,
+    newData,
+    oldData,
+    timestamp: Date.now(),
+    synced: false
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAck,
+  createAckMessage,
+  createBaseMessage,
+  createChangeRecord,
+  createDeltaPullRequest,
+  createDeltaPushMessage,
+  createError,
+  createHandshakeRequest,
+  createHeartbeat,
+  createHeartbeatMessage,
+  createPresenceMessage,
+  generateChangeId,
+  generateMessageId,
+  isConflict,
+  isDeltaPush,
+  isError,
+  isHandshakeRequest,
+  isSyncMessage
+});

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

@@ -0,0 +1,164 @@
+/**
+ * Vector Clock Implementation for Causality Tracking.
+ *
+ * Vector clocks track the causal ordering of events across distributed
+ * systems. Each device maintains a counter, and comparing clocks reveals
+ * whether events happened-before, happened-after, or are concurrent.
+ *
+ * @example
+ * ```typescript
+ * const clock = new VectorClock('device-1');
+ *
+ * // Local write - increment our counter
+ * clock.tick();
+ *
+ * // Received remote update - merge clocks
+ * clock.merge(remoteClockData);
+ *
+ * // Compare causality
+ * const relation = clock.compare(otherClock);
+ * if (relation === 'concurrent') {
+ *   // Conflict detected!
+ * }
+ * ```
+ */
+/**
+ * Vector clock data structure.
+ * Maps device IDs to their logical clock values.
+ */
+export type VectorClockData = Record<string, number>;
+/**
+ * Causal relationship between two vector clocks.
+ */
+export type CausalRelation = 'before' | 'after' | 'concurrent' | 'equal';
+/**
+ * Serialized vector clock for transmission.
+ */
+export interface SerializedVectorClock {
+    /** Device ID that owns this clock */
+    deviceId: string;
+    /** Clock values for all known devices */
+    values: VectorClockData;
+    /** Timestamp when clock was last updated */
+    updatedAt: number;
+}
+/**
+ * Vector Clock for distributed causality tracking.
+ *
+ * Implements Lamport's vector clock algorithm for determining
+ * causal ordering of events across multiple devices.
+ */
+export declare class VectorClock {
+    private readonly deviceId;
+    private values;
+    private lastUpdated;
+    constructor(deviceId: string);
+    /**
+     * Increment this device's clock (local event occurred).
+     * Call this before sending a message or making a local change.
+     *
+     * @returns The new clock value for this device
+     */
+    tick(): number;
+    /**
+     * Merge another clock into this one (received remote event).
+     * Takes the maximum of each device's counter.
+     *
+     * @param other - The remote clock to merge
+     */
+    merge(other: VectorClockData | VectorClock): void;
+    /**
+     * Update from received clock without incrementing local counter.
+     * Used when just observing, not participating in the event.
+     *
+     * @param other - The remote clock to observe
+     */
+    observe(other: VectorClockData | VectorClock): void;
+    /**
+     * Compare this clock to another to determine causal relationship.
+     *
+     * @param other - The clock to compare against
+     * @returns The causal relationship
+     */
+    compare(other: VectorClockData | VectorClock): CausalRelation;
+    /**
+     * Check if this clock happened before another.
+     */
+    happenedBefore(other: VectorClockData | VectorClock): boolean;
+    /**
+     * Check if this clock happened after another.
+     */
+    happenedAfter(other: VectorClockData | VectorClock): boolean;
+    /**
+     * Check if this clock is concurrent with another (conflict).
+     */
+    isConcurrent(other: VectorClockData | VectorClock): boolean;
+    /**
+     * Get this device's ID.
+     */
+    getDeviceId(): string;
+    /**
+     * Get this device's current clock value.
+     */
+    getValue(): number;
+    /**
+     * Get clock value for a specific device.
+     */
+    getValueFor(deviceId: string): number;
+    /**
+     * Get all clock values.
+     */
+    getValues(): VectorClockData;
+    /**
+     * Get list of known device IDs.
+     */
+    getKnownDevices(): string[];
+    /**
+     * Get when the clock was last updated.
+     */
+    getLastUpdated(): number;
+    /**
+     * Serialize clock for transmission.
+     */
+    serialize(): SerializedVectorClock;
+    /**
+     * Create a clock from serialized data.
+     */
+    static deserialize(data: SerializedVectorClock): VectorClock;
+    /**
+     * Create a copy of this clock.
+     */
+    clone(): VectorClock;
+    /**
+     * Convert to JSON string.
+     */
+    toJSON(): string;
+    /**
+     * Create from JSON string.
+     */
+    static fromJSON(json: string): VectorClock;
+}
+/**
+ * Create a new vector clock for a device.
+ *
+ * @param deviceId - Unique identifier for this device
+ * @returns New VectorClock instance
+ */
+export declare function createVectorClock(deviceId: string): VectorClock;
+/**
+ * Compare two clock data objects without creating instances.
+ */
+export declare function compareClocks(a: VectorClockData, b: VectorClockData): CausalRelation;
+/**
+ * Merge multiple clocks into a new clock.
+ */
+export declare function mergeClocks(deviceId: string, ...clocks: VectorClockData[]): VectorClock;
+/**
+ * Check if a clock dominates another (happened strictly after).
+ */
+export declare function dominates(a: VectorClockData, b: VectorClockData): boolean;
+/**
+ * Generate a unique device ID.
+ */
+export declare function generateDeviceId(): string;
+//# sourceMappingURL=vectorClock.d.ts.map

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

@@ -0,0 +1,256 @@
+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 vectorClock_exports = {};
+__export(vectorClock_exports, {
+  VectorClock: () => VectorClock,
+  compareClocks: () => compareClocks,
+  createVectorClock: () => createVectorClock,
+  dominates: () => dominates,
+  generateDeviceId: () => generateDeviceId,
+  mergeClocks: () => mergeClocks
+});
+module.exports = __toCommonJS(vectorClock_exports);
+class VectorClock {
+  constructor(deviceId) {
+    this.deviceId = deviceId;
+    this.values = {};
+    this.lastUpdated = Date.now();
+    this.values[deviceId] = 0;
+  }
+  // ============================================================================
+  // Core Operations
+  // ============================================================================
+  /**
+   * Increment this device's clock (local event occurred).
+   * Call this before sending a message or making a local change.
+   *
+   * @returns The new clock value for this device
+   */
+  tick() {
+    this.values[this.deviceId] = (this.values[this.deviceId] ?? 0) + 1;
+    this.lastUpdated = Date.now();
+    return this.values[this.deviceId];
+  }
+  /**
+   * Merge another clock into this one (received remote event).
+   * Takes the maximum of each device's counter.
+   *
+   * @param other - The remote clock to merge
+   */
+  merge(other) {
+    const otherValues = other instanceof VectorClock ? other.values : other;
+    for (const [deviceId, value] of Object.entries(otherValues)) {
+      this.values[deviceId] = Math.max(this.values[deviceId] ?? 0, value);
+    }
+    this.tick();
+  }
+  /**
+   * Update from received clock without incrementing local counter.
+   * Used when just observing, not participating in the event.
+   *
+   * @param other - The remote clock to observe
+   */
+  observe(other) {
+    const otherValues = other instanceof VectorClock ? other.values : other;
+    for (const [deviceId, value] of Object.entries(otherValues)) {
+      this.values[deviceId] = Math.max(this.values[deviceId] ?? 0, value);
+    }
+    this.lastUpdated = Date.now();
+  }
+  // ============================================================================
+  // Comparison
+  // ============================================================================
+  /**
+   * Compare this clock to another to determine causal relationship.
+   *
+   * @param other - The clock to compare against
+   * @returns The causal relationship
+   */
+  compare(other) {
+    const otherValues = other instanceof VectorClock ? other.values : other;
+    let thisGreater = false;
+    let otherGreater = false;
+    const allDevices = /* @__PURE__ */ new Set([
+      ...Object.keys(this.values),
+      ...Object.keys(otherValues)
+    ]);
+    for (const deviceId of allDevices) {
+      const thisValue = this.values[deviceId] ?? 0;
+      const otherValue = otherValues[deviceId] ?? 0;
+      if (thisValue > otherValue) {
+        thisGreater = true;
+      } else if (otherValue > thisValue) {
+        otherGreater = true;
+      }
+    }
+    if (thisGreater && otherGreater) {
+      return "concurrent";
+    } else if (thisGreater) {
+      return "after";
+    } else if (otherGreater) {
+      return "before";
+    } else {
+      return "equal";
+    }
+  }
+  /**
+   * Check if this clock happened before another.
+   */
+  happenedBefore(other) {
+    return this.compare(other) === "before";
+  }
+  /**
+   * Check if this clock happened after another.
+   */
+  happenedAfter(other) {
+    return this.compare(other) === "after";
+  }
+  /**
+   * Check if this clock is concurrent with another (conflict).
+   */
+  isConcurrent(other) {
+    return this.compare(other) === "concurrent";
+  }
+  // ============================================================================
+  // Accessors
+  // ============================================================================
+  /**
+   * Get this device's ID.
+   */
+  getDeviceId() {
+    return this.deviceId;
+  }
+  /**
+   * Get this device's current clock value.
+   */
+  getValue() {
+    return this.values[this.deviceId] ?? 0;
+  }
+  /**
+   * Get clock value for a specific device.
+   */
+  getValueFor(deviceId) {
+    return this.values[deviceId] ?? 0;
+  }
+  /**
+   * Get all clock values.
+   */
+  getValues() {
+    return { ...this.values };
+  }
+  /**
+   * Get list of known device IDs.
+   */
+  getKnownDevices() {
+    return Object.keys(this.values);
+  }
+  /**
+   * Get when the clock was last updated.
+   */
+  getLastUpdated() {
+    return this.lastUpdated;
+  }
+  // ============================================================================
+  // Serialization
+  // ============================================================================
+  /**
+   * Serialize clock for transmission.
+   */
+  serialize() {
+    return {
+      deviceId: this.deviceId,
+      values: { ...this.values },
+      updatedAt: this.lastUpdated
+    };
+  }
+  /**
+   * Create a clock from serialized data.
+   */
+  static deserialize(data) {
+    const clock = new VectorClock(data.deviceId);
+    clock.values = { ...data.values };
+    clock.lastUpdated = data.updatedAt;
+    return clock;
+  }
+  /**
+   * Create a copy of this clock.
+   */
+  clone() {
+    return VectorClock.deserialize(this.serialize());
+  }
+  /**
+   * Convert to JSON string.
+   */
+  toJSON() {
+    return JSON.stringify(this.serialize());
+  }
+  /**
+   * Create from JSON string.
+   */
+  static fromJSON(json) {
+    return VectorClock.deserialize(JSON.parse(json));
+  }
+}
+function createVectorClock(deviceId) {
+  return new VectorClock(deviceId);
+}
+function compareClocks(a, b) {
+  let aGreater = false;
+  let bGreater = false;
+  const allDevices = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const deviceId of allDevices) {
+    const aValue = a[deviceId] ?? 0;
+    const bValue = b[deviceId] ?? 0;
+    if (aValue > bValue) {
+      aGreater = true;
+    } else if (bValue > aValue) {
+      bGreater = true;
+    }
+  }
+  if (aGreater && bGreater)
+    return "concurrent";
+  if (aGreater)
+    return "after";
+  if (bGreater)
+    return "before";
+  return "equal";
+}
+function mergeClocks(deviceId, ...clocks) {
+  const result = new VectorClock(deviceId);
+  for (const clock of clocks) {
+    result.observe(clock);
+  }
+  return result;
+}
+function dominates(a, b) {
+  return compareClocks(a, b) === "after";
+}
+function generateDeviceId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `device_${timestamp}_${random}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VectorClock,
+  compareClocks,
+  createVectorClock,
+  dominates,
+  generateDeviceId,
+  mergeClocks
+});