@electric-sql/client 1.0.0-beta.4 → 1.0.0

package/src/client.ts

@@ -34,6 +34,7 @@ import {
   SHAPE_HANDLE_QUERY_PARAM,
   SHAPE_SCHEMA_HEADER,
   WHERE_QUERY_PARAM,
+  WHERE_PARAMS_PARAM,
   TABLE_QUERY_PARAM,
   REPLICA_PARAM,
   FORCE_DISCONNECT_AND_REFRESH,
@@ -64,6 +65,17 @@ export interface PostgresParams {
   /** The where clauses for the shape */
   where?: string
 
+  /**
+   * Positional where clause paramater values. These will be passed to the server
+   * and will substitute `$i` parameters in the where clause.
+   *
+   * It can be an array (note that positional arguments start at 1, the array will be mapped
+   * accordingly), or an object with keys matching the used positional parameters in the where clause.
+   *
+   * If where clause is `id = $1 or id = $2`, params must have keys `"1"` and `"2"`, or be an array with length 2.
+   */
+  params?: Record<`${number}`, string> | string[]
+
   /**
    * If `replica` is `default` (the default) then Electric will only send the
    * changed columns in an update.
@@ -77,11 +89,10 @@ export interface PostgresParams {
    */
   replica?: Replica
 }
-
+type SerializableParamValue = string | string[] | Record<string, string>
 type ParamValue =
-  | string
-  | string[]
-  | (() => string | string[] | Promise<string | string[]>)
+  | SerializableParamValue
+  | (() => SerializableParamValue | Promise<SerializableParamValue>)
 
 /**
  * External params type - what users provide.
@@ -112,7 +123,9 @@ export type ExternalHeadersRecord = {
  * All values are converted to strings.
  */
 type InternalParamsRecord = {
-  [K in string as K extends ReservedParamKeys ? never : K]: string
+  [K in string as K extends ReservedParamKeys ? never : K]:
+    | string
+    | Record<string, string>
 }
 
 /**
@@ -391,7 +404,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
         const [requestHeaders, params] = await Promise.all([
           resolveHeaders(this.options.headers),
           this.options.params
-            ? toInternalParams(this.options.params)
+            ? toInternalParams(convertWhereParamsToObj(this.options.params))
             : undefined,
         ])
 
@@ -405,13 +418,15 @@ export class ShapeStream<T extends Row<unknown> = Row>
         // Add PostgreSQL-specific parameters
         if (params) {
           if (params.table)
-            fetchUrl.searchParams.set(TABLE_QUERY_PARAM, params.table)
+            setQueryParam(fetchUrl, TABLE_QUERY_PARAM, params.table)
           if (params.where)
-            fetchUrl.searchParams.set(WHERE_QUERY_PARAM, params.where)
+            setQueryParam(fetchUrl, WHERE_QUERY_PARAM, params.where)
           if (params.columns)
-            fetchUrl.searchParams.set(COLUMNS_QUERY_PARAM, params.columns)
+            setQueryParam(fetchUrl, COLUMNS_QUERY_PARAM, params.columns)
           if (params.replica)
-            fetchUrl.searchParams.set(REPLICA_PARAM, params.replica)
+            setQueryParam(fetchUrl, REPLICA_PARAM, params.replica)
+          if (params.params)
+            setQueryParam(fetchUrl, WHERE_PARAMS_PARAM, params.params)
 
           // Add any remaining custom parameters
           const customParams = { ...params }
@@ -419,9 +434,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
           delete customParams.where
           delete customParams.columns
           delete customParams.replica
+          delete customParams.params
 
           for (const [key, value] of Object.entries(customParams)) {
-            fetchUrl.searchParams.set(key, value as string)
+            setQueryParam(fetchUrl, key, value)
           }
         }
 
@@ -729,3 +745,34 @@ function validateOptions<T>(options: Partial<ShapeStreamOptions<T>>): void {
 
   return
 }
+
+// `unknown` being in the value is a bit of defensive programming if user doesn't use TS
+function setQueryParam(
+  url: URL,
+  key: string,
+  value: Record<string, string> | string | unknown
+): void {
+  if (value === undefined || value == null) {
+    return
+  } else if (typeof value === `string`) {
+    url.searchParams.set(key, value)
+  } else if (typeof value === `object`) {
+    for (const [k, v] of Object.entries(value)) {
+      url.searchParams.set(`${key}[${k}]`, v)
+    }
+  } else {
+    url.searchParams.set(key, value.toString())
+  }
+}
+
+function convertWhereParamsToObj(
+  allPgParams: ExternalParamsRecord
+): ExternalParamsRecord {
+  if (Array.isArray(allPgParams.params)) {
+    return {
+      ...allPgParams,
+      params: Object.fromEntries(allPgParams.params.map((v, i) => [i + 1, v])),
+    }
+  }
+  return allPgParams
+}

package/src/constants.ts

@@ -11,4 +11,5 @@ export const OFFSET_QUERY_PARAM = `offset`
 export const TABLE_QUERY_PARAM = `table`
 export const WHERE_QUERY_PARAM = `where`
 export const REPLICA_PARAM = `replica`
+export const WHERE_PARAMS_PARAM = `params`
 export const FORCE_DISCONNECT_AND_REFRESH = `force-disconnect-and-refresh`

package/src/fetch.ts

@@ -264,10 +264,8 @@ class PrefetchQueue {
     const aborter = new AbortController()
 
     try {
-      const request = this.#fetchClient(url, {
-        ...(args[1] ?? {}),
-        signal: chainAborter(aborter, args[1]?.signal),
-      })
+      const { signal, cleanup } = chainAborter(aborter, args[1]?.signal)
+      const request = this.#fetchClient(url, { ...(args[1] ?? {}), signal })
       this.#prefetchQueue.set(url, [request, aborter])
       request
         .then((response) => {
@@ -286,6 +284,7 @@ class PrefetchQueue {
           return this.#prefetch(nextUrl, args[1])
         })
         .catch(() => {})
+        .finally(cleanup)
     } catch (_) {
       // ignore prefetch errors
     }
@@ -324,12 +323,31 @@ function getNextChunkUrl(url: string, res: Response): string | void {
 function chainAborter(
   aborter: AbortController,
   sourceSignal?: AbortSignal | null
-): AbortSignal {
-  if (!sourceSignal) return aborter.signal
-  if (sourceSignal.aborted) aborter.abort()
-  else
-    sourceSignal.addEventListener(`abort`, () => aborter.abort(), {
+): {
+  signal: AbortSignal
+  cleanup: () => void
+} {
+  let cleanup = noop
+  if (!sourceSignal) {
+    // no-op, nothing to chain to
+  } else if (sourceSignal.aborted) {
+    // source signal is already aborted, abort immediately
+    aborter.abort()
+  } else {
+    // chain to source signal abort event, and add callback to unlink
+    // the aborter to avoid memory leaks
+    const abortParent = () => aborter.abort()
+    sourceSignal.addEventListener(`abort`, abortParent, {
       once: true,
+      signal: aborter.signal,
     })
-  return aborter.signal
+    cleanup = () => sourceSignal.removeEventListener(`abort`, abortParent)
+  }
+
+  return {
+    signal: aborter.signal,
+    cleanup,
+  }
 }
+
+function noop() {}

package/src/shape.ts

@@ -9,6 +9,8 @@ export type ShapeChangedCallback<T extends Row<unknown> = Row> = (data: {
   rows: T[]
 }) => void
 
+type ShapeStatus = `syncing` | `up-to-date`
+
 /**
  * A Shape is an object that subscribes to a shape log,
  * keeps a materialised shape `.rows` in memory and
@@ -50,8 +52,7 @@ export class Shape<T extends Row<unknown> = Row> {
 
   readonly #data: ShapeData<T> = new Map()
   readonly #subscribers = new Map<number, ShapeChangedCallback<T>>()
-
-  #hasNotifiedSubscribersUpToDate: boolean = false
+  #status: ShapeStatus = `syncing`
   #error: FetchError | false = false
 
   constructor(stream: ShapeStreamInterface<T>) {
@@ -63,7 +64,7 @@ export class Shape<T extends Row<unknown> = Row> {
   }
 
   get isUpToDate(): boolean {
-    return this.stream.isUpToDate
+    return this.#status === `up-to-date`
   }
 
   get lastOffset(): Offset {
@@ -143,16 +144,11 @@ export class Shape<T extends Row<unknown> = Row> {
   }
 
   #process(messages: Message<T>[]): void {
-    let dataMayHaveChanged = false
-    let isUpToDate = false
-    let newlyUpToDate = false
+    let shouldNotify = false
 
     messages.forEach((message) => {
       if (isChangeMessage(message)) {
-        dataMayHaveChanged = [`insert`, `update`, `delete`].includes(
-          message.headers.operation
-        )
-
+        shouldNotify = this.#updateShapeStatus(`syncing`)
         switch (message.headers.operation) {
           case `insert`:
             this.#data.set(message.key, message.value)
@@ -172,28 +168,24 @@ export class Shape<T extends Row<unknown> = Row> {
       if (isControlMessage(message)) {
         switch (message.headers.control) {
           case `up-to-date`:
-            isUpToDate = true
-            if (!this.#hasNotifiedSubscribersUpToDate) {
-              newlyUpToDate = true
-            }
+            shouldNotify = this.#updateShapeStatus(`up-to-date`)
             break
           case `must-refetch`:
             this.#data.clear()
             this.#error = false
-            this.#hasNotifiedSubscribersUpToDate = false
-            isUpToDate = false
-            newlyUpToDate = false
+            shouldNotify = this.#updateShapeStatus(`syncing`)
             break
         }
       }
     })
 
-    // Always notify subscribers when the Shape first is up to date.
-    // FIXME this would be cleaner with a simple state machine.
-    if (newlyUpToDate || (isUpToDate && dataMayHaveChanged)) {
-      this.#hasNotifiedSubscribersUpToDate = true
-      this.#notify()
-    }
+    if (shouldNotify) this.#notify()
+  }
+
+  #updateShapeStatus(status: ShapeStatus): boolean {
+    const stateChanged = this.#status !== status
+    this.#status = status
+    return stateChanged && status === `up-to-date`
   }
 
   #handleError(e: Error): void {