@electric-sql/client

TypeScript client for ElectricSQL

Real-time Postgres sync for modern apps.

Electric provides an HTTP interface to Postgres to enable a massive number of clients to query and get real-time updates to subsets of the database, called Shapes. In this way, Electric turns Postgres into a real-time database.

The TypeScript client helps ease reading Shapes from the HTTP API in the browser and other JavaScript environments, such as edge functions and server-side Node/Bun/Deno applications. It supports both fine-grained and coarse-grained reactivity patterns — you can subscribe to see every row that changes, or you can just subscribe to get the whole shape whenever it changes. The client also supports dynamic options through function-based params and headers, making it easy to handle auth tokens, user context, and other runtime values.

Install

The client is published on NPM as @electric-sql/client:

npm i @electric-sql/client

How to use

The client exports a ShapeStream class for getting updates to shapes on a row-by-row basis as well as a Shape class for getting updates to the entire shape.

ShapeStream

import { ShapeStream } from '@electric-sql/client'

// Passes subscribers rows as they're inserted, updated, or deleted
const stream = new ShapeStream({
  url: `${BASE_URL}/v1/shape`,
  params: {
    table: `foo`
  }
})

// You can also add custom headers and URL parameters
const streamWithParams = new ShapeStream({
  url: `${BASE_URL}/v1/shape`,
  headers: {
    'Authorization': 'Bearer token'
  },
  params: {
    table: `foo`,
    'custom-param': 'value'
  }
})

stream.subscribe(messages => {
  // messages is an array with one or more row updates
  // and the stream will wait for all subscribers to process them
  // before proceeding
})

Shape

import { ShapeStream, Shape } from '@electric-sql/client'

const stream = new ShapeStream({
  url: `${BASE_URL}/v1/shape`,
  params: {
    table: `foo`
  }
})
const shape = new Shape(stream)

// Returns promise that resolves with the latest shape data once it's fully loaded
await shape.rows

// passes subscribers shape data when the shape updates
shape.subscribe(({ rows }) => {
  // rows is an array of the latest value of each row in a shape.
}

Error Handling

The ShapeStream provides two ways to handle errors:

1. Using the onError handler:

const stream = new ShapeStream({
  url: `${BASE_URL}/v1/shape`,
  params: {
    table: `foo`
  },
  onError: (error) => {
    // Handle all stream errors here
    console.error('Stream error:', error)
  }
})

If no onError handler is provided, the ShapeStream will throw errors that occur during streaming.

2. Individual subscribers can optionally handle errors specific to their subscription:

stream.subscribe(
  (messages) => {
    // Handle messages
  },
  (error) => {
    // Handle errors for this specific subscription
    console.error('Subscription error:', error)
  }
)

Common error types include:

• MissingShapeUrlError: Missing required URL parameter
• InvalidSignalError: Invalid AbortSignal instance
• ReservedParamError: Using reserved parameter names

Runtime errors:

• FetchError: HTTP errors during shape fetching
• FetchBackoffAbortError: Fetch aborted using AbortSignal
• MissingShapeHandleError: Missing required shape handle
• ParserNullValueError: Parser encountered NULL value in a column that doesn't allow NULL values

See the typescript client docs on the website for more details on error handling.

And in general, see the docs website and examples for more information.

Develop

Install the pnpm workspace at the repo root:

pnpm install

Build the package:

cd packages/typescript-client
pnpm build

Test

In one terminal, start the backend running:

cd ../sync-service
mix deps.get
mix stop_dev && mix compile && mix start_dev && ies -S mix

Then in this folder:

pnpm test