@electric-sql/client 0.7.0 → 0.7.2

package/src/client.ts

@@ -31,6 +31,18 @@ import {
   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`
 
 /**
@@ -50,9 +62,9 @@ export interface ShapeStreamOptions<T = never> {
   databaseId?: string
 
   /**
-   * The root table for the shape.
+   * The root table for the shape. Passed as a query parameter. Not required if you set the table in your proxy.
    */
-  table: string
+  table?: string
 
   /**
    * The where clauses for the shape.
@@ -98,6 +110,12 @@ export interface ShapeStreamOptions<T = never> {
    */
   headers?: Record<string, string>
 
+  /**
+   * Additional request parameters to attach to the URL.
+   * These will be merged with Electric's standard parameters.
+   */
+  params?: Record<string, string>
+
   /**
    * Automatically fetch updates to the Shape. If you just want to sync the current
    * shape and stop, pass false.
@@ -246,7 +264,26 @@ export class ShapeStream<T extends Row<unknown> = Row>
         this.options.subscribe
       ) {
         const fetchUrl = new URL(url)
-        fetchUrl.searchParams.set(TABLE_QUERY_PARAM, table)
+
+        // Add any custom parameters first
+        if (this.options.params) {
+          // Check for reserved parameter names
+          const reservedParams = Object.keys(this.options.params).filter(
+            (key) => RESERVED_PARAMS.has(key)
+          )
+          if (reservedParams.length > 0) {
+            throw new Error(
+              `Cannot use reserved Electric parameter names in custom params: ${reservedParams.join(`, `)}`
+            )
+          }
+
+          for (const [key, value] of Object.entries(this.options.params)) {
+            fetchUrl.searchParams.set(key, value)
+          }
+        }
+
+        // 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(`,`))
@@ -465,9 +502,6 @@ function validateOptions<T>(options: Partial<ShapeStreamOptions<T>>): void {
   if (!options.url) {
     throw new Error(`Invalid shape options. It must provide the url`)
   }
-  if (!options.table) {
-    throw new Error(`Invalid shape options. It must provide the table`)
-  }
   if (options.signal && !(options.signal instanceof AbortSignal)) {
     throw new Error(
       `Invalid signal option. It must be an instance of AbortSignal.`