@electric-sql/client 0.8.0 → 0.9.1

package/src/client.ts

@@ -34,27 +34,49 @@ import {
   SHAPE_HANDLE_QUERY_PARAM,
   SHAPE_SCHEMA_HEADER,
   WHERE_QUERY_PARAM,
-  DATABASE_ID_QUERY_PARAM,
   TABLE_QUERY_PARAM,
   REPLICA_PARAM,
 } from './constants'
 
 const RESERVED_PARAMS = new Set([
-  DATABASE_ID_QUERY_PARAM,
-  COLUMNS_QUERY_PARAM,
   LIVE_CACHE_BUSTER_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
-  TABLE_QUERY_PARAM,
-  WHERE_QUERY_PARAM,
-  REPLICA_PARAM,
 ])
 
 type Replica = `full` | `default`
 
+/**
+ * PostgreSQL-specific shape parameters that can be provided externally
+ */
+type PostgresParams = {
+  /** The root table for the shape. Not required if you set the table in your proxy. */
+  table?: string
+
+  /**
+   * The columns to include in the shape.
+   * Must include primary keys, and can only include valid columns.
+   */
+  columns?: string[]
+
+  /** The where clauses for the shape */
+  where?: string
+
+  /**
+   * If `replica` is `default` (the default) then Electric will only send the
+   * changed columns in an update.
+   *
+   * If it's `full` Electric will send the entire row with both changed and
+   * unchanged values.
+   *
+   * Setting `replica` to `full` will result in higher bandwidth
+   * usage and so is not generally recommended.
+   */
+  replica?: Replica
+}
+
 type ReservedParamKeys =
-  | typeof DATABASE_ID_QUERY_PARAM
   | typeof COLUMNS_QUERY_PARAM
   | typeof LIVE_CACHE_BUSTER_QUERY_PARAM
   | typeof SHAPE_HANDLE_QUERY_PARAM
@@ -64,12 +86,38 @@ type ReservedParamKeys =
   | typeof WHERE_QUERY_PARAM
   | typeof REPLICA_PARAM
 
-type ParamsRecord = Omit<Record<string, string>, ReservedParamKeys>
+/**
+ * External params type - what users provide.
+ * Includes documented PostgreSQL params and allows string or string[] values for any additional params.
+ */
+type ExternalParamsRecord = Partial<PostgresParams> & {
+  [K in string as K extends ReservedParamKeys ? never : K]: string | string[]
+}
+
+/**
+ * Internal params type - used within the library.
+ * All values are converted to strings.
+ */
+type InternalParamsRecord = {
+  [K in string as K extends ReservedParamKeys ? never : K]: string
+}
+
+/**
+ * Helper function to convert external params to internal format
+ */
+function toInternalParams(params: ExternalParamsRecord): InternalParamsRecord {
+  const result: InternalParamsRecord = {}
+  for (const [key, value] of Object.entries(params)) {
+    result[key] = Array.isArray(value) ? value.join(`,`) : value
+  }
+  return result
+}
 
 type RetryOpts = {
-  params?: ParamsRecord
+  params?: ExternalParamsRecord
   headers?: Record<string, string>
 }
+
 type ShapeStreamErrorHandler = (
   error: Error
 ) => void | RetryOpts | Promise<void | RetryOpts>
@@ -84,40 +132,6 @@ export interface ShapeStreamOptions<T = never> {
    */
   url: string
 
-  /**
-   * Which database to use.
-   * This is optional unless Electric is used with multiple databases.
-   */
-  databaseId?: string
-
-  /**
-   * The root table for the shape. Passed as a query parameter. Not required if you set the table in your proxy.
-   */
-  table?: string
-
-  /**
-   * The where clauses for the shape.
-   */
-  where?: string
-
-  /**
-   * The columns to include in the shape.
-   * Must include primary keys, and can only inlude valid columns.
-   */
-  columns?: string[]
-
-  /**
-   * If `replica` is `default` (the default) then Electric will only send the
-   * changed columns in an update.
-   *
-   * If it's `full` Electric will send the entire row with both changed and
-   * unchanged values.
-   *
-   * Setting `replica` to `full` will obviously result in higher bandwidth
-   * usage and so is not recommended.
-   */
-  replica?: Replica
-
   /**
    * The "offset" on the shape log. This is typically not set as the ShapeStream
    * will handle this automatically. A common scenario where you might pass an offset
@@ -144,9 +158,12 @@ export interface ShapeStreamOptions<T = never> {
    * Additional request parameters to attach to the URL.
    * These will be merged with Electric's standard parameters.
    * Note: You cannot use Electric's reserved parameter names
-   * (table, where, columns, offset, handle, live, cursor, database_id, replica).
+   * (offset, handle, live, cursor).
+   *
+   * PostgreSQL-specific options like table, where, columns, and replica
+   * should be specified here.
    */
-  params?: ParamsRecord
+  params?: ExternalParamsRecord
 
   /**
    * Automatically fetch updates to the Shape. If you just want to sync the current
@@ -162,7 +179,7 @@ export interface ShapeStreamOptions<T = never> {
   /**
    * A function for handling shapestream errors.
    * This is optional, when it is not provided any shapestream errors will be thrown.
-   * If the function is provided and returns an object containing parameters and/or headers
+   * If the function returns an object containing parameters and/or headers
    * the shapestream will apply those changes and try syncing again.
    * If the function returns void the shapestream is stopped.
    */
@@ -173,7 +190,7 @@ export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
   subscribe(
     callback: (messages: Message<T>[]) => MaybePromise<void>,
     onError?: (error: FetchError | Error) => void
-  ): void
+  ): () => void
   unsubscribeAll(): void
 
   isLoading(): boolean
@@ -246,10 +263,8 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #isUpToDate: boolean = false
   #connected: boolean = false
   #shapeHandle?: string
-  #databaseId?: string
   #schema?: Schema
   #onError?: ShapeStreamErrorHandler
-  #replica?: Replica
 
   constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     this.options = { subscribe: true, ...options }
@@ -257,9 +272,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
     this.#lastOffset = this.options.offset ?? `-1`
     this.#liveCacheBuster = ``
     this.#shapeHandle = this.options.handle
-    this.#databaseId = this.options.databaseId
     this.#messageParser = new MessageParser<T>(options.parser)
-    this.#replica = this.options.replica
     this.#onError = this.options.onError
 
     const baseFetchClient =
@@ -303,7 +316,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
         (!this.options.signal?.aborted && !this.#isUpToDate) ||
         this.options.subscribe
       ) {
-        const { url, table, where, columns, signal } = this.options
+        const { url, signal } = this.options
 
         const fetchUrl = new URL(url)
 
@@ -319,16 +332,30 @@ export class ShapeStream<T extends Row<unknown> = Row>
             )
           }
 
-          for (const [key, value] of Object.entries(this.options.params)) {
-            fetchUrl.searchParams.set(key, value)
+          // Add PostgreSQL-specific parameters from params
+          const params = toInternalParams(this.options.params)
+          if (params.table)
+            fetchUrl.searchParams.set(TABLE_QUERY_PARAM, params.table)
+          if (params.where)
+            fetchUrl.searchParams.set(WHERE_QUERY_PARAM, params.where)
+          if (params.columns)
+            fetchUrl.searchParams.set(COLUMNS_QUERY_PARAM, params.columns)
+          if (params.replica)
+            fetchUrl.searchParams.set(REPLICA_PARAM, params.replica)
+
+          // Add any remaining custom parameters
+          const customParams = { ...params }
+          delete customParams.table
+          delete customParams.where
+          delete customParams.columns
+          delete customParams.replica
+
+          for (const [key, value] of Object.entries(customParams)) {
+            fetchUrl.searchParams.set(key, value as string)
           }
         }
 
         // Add Electric's internal parameters
-        if (table) fetchUrl.searchParams.set(TABLE_QUERY_PARAM, table)
-        if (where) fetchUrl.searchParams.set(WHERE_QUERY_PARAM, where)
-        if (columns && columns.length > 0)
-          fetchUrl.searchParams.set(COLUMNS_QUERY_PARAM, columns.join(`,`))
         fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, this.#lastOffset)
 
         if (this.#isUpToDate) {
@@ -347,16 +374,8 @@ export class ShapeStream<T extends Row<unknown> = Row>
           )
         }
 
-        if (this.#databaseId) {
-          fetchUrl.searchParams.set(DATABASE_ID_QUERY_PARAM, this.#databaseId!)
-        }
-
-        if (
-          (this.#replica ?? ShapeStream.Replica.DEFAULT) !=
-          ShapeStream.Replica.DEFAULT
-        ) {
-          fetchUrl.searchParams.set(REPLICA_PARAM, this.#replica as string)
-        }
+        // sort query params in-place for stable URLs and improved cache hits
+        fetchUrl.searchParams.sort()
 
         let response!: Response
         try {

package/src/constants.ts

@@ -3,7 +3,6 @@ export const SHAPE_HANDLE_HEADER = `electric-handle`
 export const CHUNK_LAST_OFFSET_HEADER = `electric-offset`
 export const SHAPE_SCHEMA_HEADER = `electric-schema`
 export const CHUNK_UP_TO_DATE_HEADER = `electric-up-to-date`
-export const DATABASE_ID_QUERY_PARAM = `database_id`
 export const COLUMNS_QUERY_PARAM = `columns`
 export const LIVE_CACHE_BUSTER_QUERY_PARAM = `cursor`
 export const SHAPE_HANDLE_QUERY_PARAM = `handle`

package/src/fetch.ts

@@ -177,13 +177,13 @@ export function createFetchWithResponseHeadersCheck(
       const input = args[0]
       const urlString = input.toString()
       const url = new URL(urlString)
-      if (url.searchParams.has(LIVE_QUERY_PARAM, `true`)) {
+      if (url.searchParams.get(LIVE_QUERY_PARAM) === `true`) {
         addMissingHeaders(requiredLiveResponseHeaders)
       }
 
       if (
         !url.searchParams.has(LIVE_QUERY_PARAM) ||
-        url.searchParams.has(LIVE_QUERY_PARAM, `false`)
+        url.searchParams.get(LIVE_QUERY_PARAM) === `false`
       ) {
         addMissingHeaders(requiredNonLiveResponseHeaders)
       }
@@ -312,6 +312,7 @@ function getNextChunkUrl(url: string, res: Response): string | void {
 
   nextUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, shapeHandle)
   nextUrl.searchParams.set(OFFSET_QUERY_PARAM, lastOffset)
+  nextUrl.searchParams.sort()
   return nextUrl.toString()
 }
 

package/src/shape.ts

@@ -21,7 +21,12 @@ export type ShapeChangedCallback<T extends Row<unknown> = Row> = (data: {
  * @param {ShapeStream<T extends Row>} - the underlying shape stream
  * @example
  * ```
- * const shapeStream = new ShapeStream<{ foo: number }>(url: `http://localhost:3000/v1/shape`, table: `foo`})
+ * const shapeStream = new ShapeStream<{ foo: number }>({
+ *   url: `http://localhost:3000/v1/shape`,
+ *   params: {
+ *     table: `foo`
+ *   }
+ * })
  * const shape = new Shape(shapeStream)
  * ```
  *
@@ -41,7 +46,7 @@ export type ShapeChangedCallback<T extends Row<unknown> = Row> = (data: {
  *     })
  */
 export class Shape<T extends Row<unknown> = Row> {
-  readonly #stream: ShapeStreamInterface<T>
+  readonly stream: ShapeStreamInterface<T>
 
   readonly #data: ShapeData<T> = new Map()
   readonly #subscribers = new Map<number, ShapeChangedCallback<T>>()
@@ -50,23 +55,23 @@ export class Shape<T extends Row<unknown> = Row> {
   #error: FetchError | false = false
 
   constructor(stream: ShapeStreamInterface<T>) {
-    this.#stream = stream
-    this.#stream.subscribe(
+    this.stream = stream
+    this.stream.subscribe(
       this.#process.bind(this),
       this.#handleError.bind(this)
     )
   }
 
   get isUpToDate(): boolean {
-    return this.#stream.isUpToDate
+    return this.stream.isUpToDate
   }
 
   get lastOffset(): Offset {
-    return this.#stream.lastOffset
+    return this.stream.lastOffset
   }
 
   get handle(): string | undefined {
-    return this.#stream.shapeHandle
+    return this.stream.shapeHandle
   }
 
   get rows(): Promise<T[]> {
@@ -79,7 +84,7 @@ export class Shape<T extends Row<unknown> = Row> {
 
   get value(): Promise<ShapeData<T>> {
     return new Promise((resolve, reject) => {
-      if (this.#stream.isUpToDate) {
+      if (this.stream.isUpToDate) {
         resolve(this.currentValue)
       } else {
         const unsubscribe = this.subscribe(({ value }) => {
@@ -101,22 +106,22 @@ export class Shape<T extends Row<unknown> = Row> {
 
   /** Unix time at which we last synced. Undefined when `isLoading` is true. */
   lastSyncedAt(): number | undefined {
-    return this.#stream.lastSyncedAt()
+    return this.stream.lastSyncedAt()
   }
 
   /** Time elapsed since last sync (in ms). Infinity if we did not yet sync. */
   lastSynced() {
-    return this.#stream.lastSynced()
+    return this.stream.lastSynced()
   }
 
   /** True during initial fetch. False afterwise.  */
   isLoading() {
-    return this.#stream.isLoading()
+    return this.stream.isLoading()
   }
 
   /** Indicates if we are connected to the Electric sync service. */
   isConnected(): boolean {
-    return this.#stream.isConnected()
+    return this.stream.isConnected()
   }
 
   subscribe(callback: ShapeChangedCallback<T>): () => void {

package/src/types.ts

@@ -23,6 +23,8 @@ interface Header {
   [key: Exclude<string, `operation` | `control`>]: Value
 }
 
+export type Operation = `insert` | `update` | `delete`
+
 export type ControlMessage = {
   headers: Header & { control: `up-to-date` | `must-refetch` }
 }
@@ -30,7 +32,7 @@ export type ControlMessage = {
 export type ChangeMessage<T extends Row<unknown> = Row> = {
   key: string
   value: T
-  headers: Header & { operation: `insert` | `update` | `delete` }
+  headers: Header & { operation: Operation }
   offset: Offset
 }