@electric-sql/client 1.1.5 → 1.2.1

package/src/types.ts

@@ -43,10 +43,30 @@ export type NormalizedPgSnapshot = {
 }
 
 interface Header {
-  [key: Exclude<string, `operation` | `control`>]: Value
+  [key: Exclude<string, `operation` | `control` | `event`>]: Value
 }
 
 export type Operation = `insert` | `update` | `delete`
+/**
+ * A tag is a string identifying a reason for this row to be part of the shape.
+ *
+ * Tags can be composite, but they are always sent as a single string. Compound tags
+ * are separated by `|`. It's up to the client to split the tag into its components
+ * in order to react to move-outs correctly. Tag parts are guaranteed to not contain an
+ * unescaped `|` character (escaped as `\\|`) or be a literal `*`.
+ *
+ * Composite tag width is guaranteed to be fixed for a given shape.
+ */
+export type MoveTag = string
+
+/**
+ * A move-out pattern is a position and a value. The position is the index of the column
+ * that is being moved out. The value is the value of the column that is being moved out.
+ *
+ * Tag width and value order is fixed for a given shape, so the client can determine
+ * which tags match this pattern.
+ */
+export type MoveOutPattern = { pos: number; value: string }
 
 export type ControlMessage = {
   headers:
@@ -57,16 +77,27 @@ export type ControlMessage = {
     | (Header & { control: `snapshot-end` } & PostgresSnapshot)
 }
 
+export type EventMessage = {
+  headers: Header & { event: `move-out`; patterns: MoveOutPattern[] }
+}
+
 export type ChangeMessage<T extends Row<unknown> = Row> = {
   key: string
   value: T
   old_value?: Partial<T> // Only provided for updates if `replica` is `full`
-  headers: Header & { operation: Operation; txids?: number[] }
+  headers: Header & {
+    operation: Operation
+    txids?: number[]
+    /** Tags will always be present for changes if the shape has a subquery in its where clause, and are omitted otherwise.*/
+    tags?: MoveTag[]
+    removed_tags?: MoveTag[]
+  }
 }
 
 // Define the type for a record
 export type Message<T extends Row<unknown> = Row> =
   | ControlMessage
+  | EventMessage
   | ChangeMessage<T>
 
 /**

package/src/up-to-date-tracker.ts

@@ -0,0 +1,157 @@
+interface UpToDateEntry {
+  timestamp: number
+  cursor: string
+}
+
+/**
+ * Tracks up-to-date messages to detect when we're replaying cached responses.
+ *
+ * When a shape receives an up-to-date, we record the timestamp and cursor in localStorage.
+ * On page refresh, if we find a recent timestamp (< 60s), we know we'll be replaying
+ * cached responses. We suppress their up-to-date notifications until we see a NEW cursor
+ * (different from the last recorded one), which indicates fresh data from the server.
+ *
+ * localStorage writes are throttled to once per 60 seconds to avoid performance issues
+ * with frequent updates. In-memory data is always kept current.
+ */
+export class UpToDateTracker {
+  private data: Record<string, UpToDateEntry> = {}
+  private readonly storageKey = `electric_up_to_date_tracker`
+  private readonly cacheTTL = 60_000 // 60s to match typical CDN s-maxage cache duration
+  private readonly maxEntries = 250
+  private readonly writeThrottleMs = 60_000 // Throttle localStorage writes to once per 60s
+  private lastWriteTime = 0
+  private pendingSaveTimer?: ReturnType<typeof setTimeout>
+
+  constructor() {
+    this.load()
+    this.cleanup()
+  }
+
+  /**
+   * Records that a shape received an up-to-date message with a specific cursor.
+   * This timestamp and cursor are used to detect cache replay scenarios.
+   * Updates in-memory immediately, but throttles localStorage writes.
+   */
+  recordUpToDate(shapeKey: string, cursor: string): void {
+    this.data[shapeKey] = {
+      timestamp: Date.now(),
+      cursor,
+    }
+
+    // Implement LRU eviction if we exceed max entries
+    const keys = Object.keys(this.data)
+    if (keys.length > this.maxEntries) {
+      const oldest = keys.reduce((min, k) =>
+        this.data[k].timestamp < this.data[min].timestamp ? k : min
+      )
+      delete this.data[oldest]
+    }
+
+    this.scheduleSave()
+  }
+
+  /**
+   * Schedules a throttled save to localStorage.
+   * Writes immediately if enough time has passed, otherwise schedules for later.
+   */
+  private scheduleSave(): void {
+    const now = Date.now()
+    const timeSinceLastWrite = now - this.lastWriteTime
+
+    if (timeSinceLastWrite >= this.writeThrottleMs) {
+      // Enough time has passed, write immediately
+      this.lastWriteTime = now
+      this.save()
+    } else if (!this.pendingSaveTimer) {
+      // Schedule a write for when the throttle period expires
+      const delay = this.writeThrottleMs - timeSinceLastWrite
+      this.pendingSaveTimer = setTimeout(() => {
+        this.lastWriteTime = Date.now()
+        this.pendingSaveTimer = undefined
+        this.save()
+      }, delay)
+    }
+    // else: a save is already scheduled, no need to do anything
+  }
+
+  /**
+   * Checks if we should enter replay mode for this shape.
+   * Returns the last seen cursor if there's a recent up-to-date (< 60s),
+   * which means we'll likely be replaying cached responses.
+   * Returns null if no recent up-to-date exists.
+   */
+  shouldEnterReplayMode(shapeKey: string): string | null {
+    const entry = this.data[shapeKey]
+    if (!entry) {
+      return null
+    }
+
+    const age = Date.now() - entry.timestamp
+    if (age >= this.cacheTTL) {
+      return null
+    }
+
+    return entry.cursor
+  }
+
+  /**
+   * Cleans up expired entries from the cache.
+   * Called on initialization and can be called periodically.
+   */
+  private cleanup(): void {
+    const now = Date.now()
+    const keys = Object.keys(this.data)
+    let modified = false
+
+    for (const key of keys) {
+      const age = now - this.data[key].timestamp
+      if (age > this.cacheTTL) {
+        delete this.data[key]
+        modified = true
+      }
+    }
+
+    if (modified) {
+      this.save()
+    }
+  }
+
+  private save(): void {
+    if (typeof localStorage === `undefined`) return
+    try {
+      localStorage.setItem(this.storageKey, JSON.stringify(this.data))
+    } catch {
+      // Ignore localStorage errors (quota exceeded, etc.)
+    }
+  }
+
+  private load(): void {
+    if (typeof localStorage === `undefined`) return
+    try {
+      const stored = localStorage.getItem(this.storageKey)
+      if (stored) {
+        this.data = JSON.parse(stored)
+      }
+    } catch {
+      // Ignore localStorage errors, start fresh
+      this.data = {}
+    }
+  }
+
+  /**
+   * Clears all tracked up-to-date timestamps.
+   * Useful for testing or manual cache invalidation.
+   */
+  clear(): void {
+    this.data = {}
+    if (this.pendingSaveTimer) {
+      clearTimeout(this.pendingSaveTimer)
+      this.pendingSaveTimer = undefined
+    }
+    this.save()
+  }
+}
+
+// Module-level singleton instance
+export const upToDateTracker = new UpToDateTracker()