@electric-sql/client 0.3.3 → 0.4.0

package/src/client.ts

@@ -1,9 +1,11 @@
-import { Message, Value, Offset, Schema } from './types'
+import { Message, Offset, Schema, Row } from './types'
 import { MessageParser, Parser } from './parser'
 import { isChangeMessage, isControlMessage } from './helpers'
 
-export type ShapeData = Map<string, { [key: string]: Value }>
-export type ShapeChangedCallback = (value: ShapeData) => void
+export type ShapeData<T extends Row = Row> = Map<string, T>
+export type ShapeChangedCallback<T extends Row = Row> = (
+  value: ShapeData<T>
+) => void
 
 export interface BackoffOptions {
   initialDelay: number
@@ -62,16 +64,16 @@ export interface ShapeStreamOptions {
  * @constructor
  * @param {(messages: Message[]) => void} callback function
  */
-class MessageProcessor {
-  private messageQueue: Message[][] = []
+class MessageProcessor<T extends Row = Row> {
+  private messageQueue: Message<T>[][] = []
   private isProcessing = false
-  private callback: (messages: Message[]) => void | Promise<void>
+  private callback: (messages: Message<T>[]) => void | Promise<void>
 
-  constructor(callback: (messages: Message[]) => void | Promise<void>) {
+  constructor(callback: (messages: Message<T>[]) => void | Promise<void>) {
     this.callback = callback
   }
 
-  process(messages: Message[]) {
+  process(messages: Message<T>[]) {
     this.messageQueue.push(messages)
 
     if (!this.isProcessing) {
@@ -144,28 +146,30 @@ export class FetchError extends Error {
  * to consume the HTTP `GET /v1/shape` api.
  *
  * @constructor
- * @param {ShapeStreamOptions} options
- *
+ * @param {ShapeStreamOptions} options - configure the shape stream
+ * @example
  * Register a callback function to subscribe to the messages.
- *
- *     const stream = new ShapeStream(options)
- *     stream.subscribe(messages => {
- *       // messages is 1 or more row updates
- *     })
+ * ```
+ * const stream = new ShapeStream(options)
+ * stream.subscribe(messages => {
+ *   // messages is 1 or more row updates
+ * })
+ * ```
  *
  * To abort the stream, abort the `signal`
  * passed in via the `ShapeStreamOptions`.
- *
- *   const aborter = new AbortController()
- *   const issueStream = new ShapeStream({
- *     url: `${BASE_URL}/${table}`
- *     subscribe: true,
- *     signal: aborter.signal,
- *   })
- *   // Later...
- *   aborter.abort()
+ * ```
+ * const aborter = new AbortController()
+ * const issueStream = new ShapeStream({
+ *   url: `${BASE_URL}/${table}`
+ *   subscribe: true,
+ *   signal: aborter.signal,
+ * })
+ * // Later...
+ * aborter.abort()
+ * ```
  */
-export class ShapeStream {
+export class ShapeStream<T extends Row = Row> {
   private options: ShapeStreamOptions
   private backoffOptions: BackoffOptions
   private fetchClient: typeof fetch
@@ -173,7 +177,7 @@ export class ShapeStream {
 
   private subscribers = new Map<
     number,
-    [MessageProcessor, ((error: Error) => void) | undefined]
+    [MessageProcessor<T>, ((error: Error) => void) | undefined]
   >()
   private upToDateSubscribers = new Map<
     number,
@@ -181,8 +185,10 @@ export class ShapeStream {
   >()
 
   private lastOffset: Offset
-  private messageParser: MessageParser
+  private messageParser: MessageParser<T>
+  private lastSyncedAt?: number // unix time
   public isUpToDate: boolean = false
+  private connected: boolean = false
 
   shapeId?: string
 
@@ -191,7 +197,7 @@ export class ShapeStream {
     this.options = { subscribe: true, ...options }
     this.lastOffset = this.options.offset ?? `-1`
     this.shapeId = this.options.shapeId
-    this.messageParser = new MessageParser(options.parser)
+    this.messageParser = new MessageParser<T>(options.parser)
 
     this.backoffOptions = options.backoffOptions ?? BackoffDefaults
     this.fetchClient =
@@ -206,85 +212,96 @@ export class ShapeStream {
 
     const { url, where, signal } = this.options
 
-    while ((!signal?.aborted && !this.isUpToDate) || this.options.subscribe) {
-      const fetchUrl = new URL(url)
-      if (where) fetchUrl.searchParams.set(`where`, where)
-      fetchUrl.searchParams.set(`offset`, this.lastOffset)
+    try {
+      while ((!signal?.aborted && !this.isUpToDate) || this.options.subscribe) {
+        const fetchUrl = new URL(url)
+        if (where) fetchUrl.searchParams.set(`where`, where)
+        fetchUrl.searchParams.set(`offset`, this.lastOffset)
 
-      if (this.isUpToDate) {
-        fetchUrl.searchParams.set(`live`, `true`)
-      }
+        if (this.isUpToDate) {
+          fetchUrl.searchParams.set(`live`, `true`)
+        }
 
-      if (this.shapeId) {
-        // This should probably be a header for better cache breaking?
-        fetchUrl.searchParams.set(`shape_id`, this.shapeId!)
-      }
+        if (this.shapeId) {
+          // This should probably be a header for better cache breaking?
+          fetchUrl.searchParams.set(`shape_id`, this.shapeId!)
+        }
 
-      let response!: Response
+        let response!: Response
+
+        try {
+          const maybeResponse = await this.fetchWithBackoff(fetchUrl)
+          if (maybeResponse) response = maybeResponse
+          else break
+        } catch (e) {
+          if (!(e instanceof FetchError)) throw e // should never happen
+          if (e.status == 409) {
+            // Upon receiving a 409, we should start from scratch
+            // with the newly provided shape ID
+            const newShapeId = e.headers[`x-electric-shape-id`]
+            this.reset(newShapeId)
+            this.publish(e.json as Message<T>[])
+            continue
+          } else if (e.status >= 400 && e.status < 500) {
+            // Notify subscribers
+            this.sendErrorToUpToDateSubscribers(e)
+            this.sendErrorToSubscribers(e)
+
+            // 400 errors are not actionable without additional user input, so we're throwing them.
+            throw e
+          }
+        }
 
-      try {
-        const maybeResponse = await this.fetchWithBackoff(fetchUrl)
-        if (maybeResponse) response = maybeResponse
-        else break
-      } catch (e) {
-        if (!(e instanceof FetchError)) throw e // should never happen
-        if (e.status == 409) {
-          // Upon receiving a 409, we should start from scratch
-          // with the newly provided shape ID
-          const newShapeId = e.headers[`x-electric-shape-id`]
-          this.reset(newShapeId)
-          this.publish(e.json as Message[])
-          continue
-        } else if (e.status >= 400 && e.status < 500) {
-          // Notify subscribers
-          this.sendErrorToUpToDateSubscribers(e)
-          this.sendErrorToSubscribers(e)
-
-          // 400 errors are not actionable without additional user input, so we're throwing them.
-          throw e
+        const { headers, status } = response
+        const shapeId = headers.get(`X-Electric-Shape-Id`)
+        if (shapeId) {
+          this.shapeId = shapeId
         }
-      }
 
-      const { headers, status } = response
-      const shapeId = headers.get(`X-Electric-Shape-Id`)
-      if (shapeId) {
-        this.shapeId = shapeId
-      }
+        const lastOffset = headers.get(`X-Electric-Chunk-Last-Offset`)
+        if (lastOffset) {
+          this.lastOffset = lastOffset as Offset
+        }
 
-      const lastOffset = headers.get(`X-Electric-Chunk-Last-Offset`)
-      if (lastOffset) {
-        this.lastOffset = lastOffset as Offset
-      }
+        const getSchema = (): Schema => {
+          const schemaHeader = headers.get(`X-Electric-Schema`)
+          return schemaHeader ? JSON.parse(schemaHeader) : {}
+        }
+        this.schema = this.schema ?? getSchema()
 
-      const getSchema = (): Schema => {
-        const schemaHeader = headers.get(`X-Electric-Schema`)
-        return schemaHeader ? JSON.parse(schemaHeader) : {}
-      }
-      this.schema = this.schema ?? getSchema()
+        const messages = status === 204 ? `[]` : await response.text()
 
-      const messages = status === 204 ? `[]` : await response.text()
+        if (status === 204) {
+          // There's no content so we are live and up to date
+          this.lastSyncedAt = Date.now()
+        }
 
-      const batch = this.messageParser.parse(messages, this.schema)
+        const batch = this.messageParser.parse(messages, this.schema)
+
+        // Update isUpToDate
+        if (batch.length > 0) {
+          const lastMessage = batch[batch.length - 1]
+          if (
+            isControlMessage(lastMessage) &&
+            lastMessage.headers.control === `up-to-date`
+          ) {
+            this.lastSyncedAt = Date.now()
+            if (!this.isUpToDate) {
+              this.isUpToDate = true
+              this.notifyUpToDateSubscribers()
+            }
+          }
 
-      // Update isUpToDate
-      if (batch.length > 0) {
-        const lastMessage = batch[batch.length - 1]
-        if (
-          isControlMessage(lastMessage) &&
-          lastMessage.headers.control === `up-to-date` &&
-          !this.isUpToDate
-        ) {
-          this.isUpToDate = true
-          this.notifyUpToDateSubscribers()
+          this.publish(batch)
         }
-
-        this.publish(batch)
       }
+    } finally {
+      this.connected = false
     }
   }
 
   subscribe(
-    callback: (messages: Message[]) => void | Promise<void>,
+    callback: (messages: Message<T>[]) => void | Promise<void>,
     onError?: (error: FetchError | Error) => void
   ) {
     const subscriptionId = Math.random()
@@ -301,7 +318,7 @@ export class ShapeStream {
     this.subscribers.clear()
   }
 
-  private publish(messages: Message[]) {
+  private publish(messages: Message<T>[]) {
     this.subscribers.forEach(([subscriber, _]) => {
       subscriber.process(messages)
     })
@@ -330,6 +347,16 @@ export class ShapeStream {
     this.upToDateSubscribers.clear()
   }
 
+  /** Time elapsed since last sync (in ms). Infinity if we did not yet sync. */
+  lastSynced(): number {
+    if (this.lastSyncedAt === undefined) return Infinity
+    return Date.now() - this.lastSyncedAt
+  }
+
+  isConnected(): boolean {
+    return this.connected
+  }
+
   private notifyUpToDateSubscribers() {
     this.upToDateSubscribers.forEach(([callback]) => {
       callback()
@@ -351,6 +378,7 @@ export class ShapeStream {
     this.lastOffset = `-1`
     this.shapeId = shapeId
     this.isUpToDate = false
+    this.connected = false
     this.schema = undefined
   }
 
@@ -386,9 +414,14 @@ export class ShapeStream {
     while (true) {
       try {
         const result = await this.fetchClient(url.toString(), { signal })
-        if (result.ok) return result
-        else throw await FetchError.fromResponse(result, url.toString())
+        if (result.ok) {
+          if (this.options.subscribe) {
+            this.connected = true
+          }
+          return result
+        } else throw await FetchError.fromResponse(result, url.toString())
       } catch (e) {
+        this.connected = false
         if (signal?.aborted) {
           return undefined
         } else if (
@@ -423,10 +456,12 @@ export class ShapeStream {
  * to simplify developing framework hooks.
  *
  * @constructor
- * @param {Shape}
- *
- *     const shapeStream = new ShapeStream(url: 'http://localhost:3000/v1/shape/foo'})
- *     const shape = new Shape(shapeStream)
+ * @param {ShapeStream<T extends Row>} - the underlying shape stream
+ * @example
+ * ```
+ * const shapeStream = new ShapeStream<{ foo: number }>(url: 'http://localhost:3000/v1/shape/foo'})
+ * const shape = new Shape(shapeStream)
+ * ```
  *
  * `value` returns a promise that resolves the Shape data once the Shape has been
  * fully loaded (and when resuming from being offline):
@@ -443,15 +478,15 @@ export class ShapeStream {
  *       console.log(shapeData)
  *     })
  */
-export class Shape {
-  private stream: ShapeStream
+export class Shape<T extends Row = Row> {
+  private stream: ShapeStream<T>
 
-  private data: ShapeData = new Map()
-  private subscribers = new Map<number, ShapeChangedCallback>()
+  private data: ShapeData<T> = new Map()
+  private subscribers = new Map<number, ShapeChangedCallback<T>>()
   public error: FetchError | false = false
   private hasNotifiedSubscribersUpToDate: boolean = false
 
-  constructor(stream: ShapeStream) {
+  constructor(stream: ShapeStream<T>) {
     this.stream = stream
     this.stream.subscribe(this.process.bind(this), this.handleError.bind(this))
     const unsubscribe = this.stream.subscribeOnceToUpToDate(
@@ -465,11 +500,15 @@ export class Shape {
     )
   }
 
-  get isUpToDate(): boolean {
-    return this.stream.isUpToDate
+  lastSynced(): number {
+    return this.stream.lastSynced()
+  }
+
+  isConnected(): boolean {
+    return this.stream.isConnected()
   }
 
-  get value(): Promise<ShapeData> {
+  get value(): Promise<ShapeData<T>> {
     return new Promise((resolve) => {
       if (this.stream.isUpToDate) {
         resolve(this.valueSync)
@@ -491,7 +530,7 @@ export class Shape {
     return this.data
   }
 
-  subscribe(callback: ShapeChangedCallback): () => void {
+  subscribe(callback: ShapeChangedCallback<T>): () => void {
     const subscriptionId = Math.random()
 
     this.subscribers.set(subscriptionId, callback)
@@ -509,7 +548,7 @@ export class Shape {
     return this.subscribers.size
   }
 
-  private process(messages: Message[]): void {
+  private process(messages: Message<T>[]): void {
     let dataMayHaveChanged = false
     let isUpToDate = false
     let newlyUpToDate = false

package/src/helpers.ts

@@ -1,4 +1,4 @@
-import { ChangeMessage, ControlMessage, Message, Value } from './types'
+import { ChangeMessage, ControlMessage, Message, Row } from './types'
 
 /**
  * Type guard for checking {@link Message} is {@link ChangeMessage}.
@@ -17,7 +17,7 @@ import { ChangeMessage, ControlMessage, Message, Value } from './types'
  * }
  * ```
  */
-export function isChangeMessage<T extends Value = { [key: string]: Value }>(
+export function isChangeMessage<T extends Row = Row>(
   message: Message<T>
 ): message is ChangeMessage<T> {
   return `key` in message
@@ -40,7 +40,7 @@ export function isChangeMessage<T extends Value = { [key: string]: Value }>(
  * }
  * ```
  */
-export function isControlMessage<T extends Value = { [key: string]: Value }>(
+export function isControlMessage<T extends Row = Row>(
   message: Message<T>
 ): message is ControlMessage {
   return !isChangeMessage(message)

package/src/parser.ts

@@ -1,4 +1,4 @@
-import { ColumnInfo, Message, Schema, Value } from './types'
+import { ColumnInfo, Message, Row, Schema, Value } from './types'
 
 type NullToken = null | `NULL`
 type Token = Exclude<string, NullToken>
@@ -79,7 +79,7 @@ export function pgArrayParser(value: Token, parser?: ParseFunction): Value {
   return loop(value)[0]
 }
 
-export class MessageParser {
+export class MessageParser<T extends Row> {
   private parser: Parser
   constructor(parser?: Parser) {
     // Merge the provided parser with the default parser
@@ -88,7 +88,7 @@ export class MessageParser {
     this.parser = { ...defaultParser, ...parser }
   }
 
-  parse(messages: string, schema: Schema): Message[] {
+  parse(messages: string, schema: Schema): Message<T>[] {
     return JSON.parse(messages, (key, value) => {
       // typeof value === `object` is needed because
       // there could be a column named `value`
@@ -101,7 +101,7 @@ export class MessageParser {
         })
       }
       return value
-    }) as Message[]
+    }) as Message<T>[]
   }
 
   // Parses the message values using the provided parser based on the schema information

package/src/types.ts

@@ -7,6 +7,8 @@ export type Value =
   | Value[]
   | { [key: string]: Value }
 
+export type Row = { [key: string]: Value }
+
 export type Offset = `-1` | `${number}_${number}`
 
 interface Header {
@@ -17,7 +19,7 @@ export type ControlMessage = {
   headers: Header & { control: `up-to-date` | `must-refetch` }
 }
 
-export type ChangeMessage<T> = {
+export type ChangeMessage<T extends Row = Row> = {
   key: string
   value: T
   headers: Header & { operation: `insert` | `update` | `delete` }
@@ -25,9 +27,7 @@ export type ChangeMessage<T> = {
 }
 
 // Define the type for a record
-export type Message<T extends Value = { [key: string]: Value }> =
-  | ControlMessage
-  | ChangeMessage<T>
+export type Message<T extends Row = Row> = ControlMessage | ChangeMessage<T>
 
 /**
  * Common properties for all columns.
@@ -104,7 +104,7 @@ export type ColumnInfo =
 
 export type Schema = { [key: string]: ColumnInfo }
 
-export type TypedMessages<T extends Value = { [key: string]: Value }> = {
+export type TypedMessages<T extends Row = Row> = {
   messages: Array<Message<T>>
   schema: ColumnInfo
 }