Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@electric-sql/client

Package Overview
Dependencies
Maintainers
3
Versions
28
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@electric-sql/client

Postgres everywhere - your data, in sync, wherever you need it.

  • 1.0.0-beta.1
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
22K
increased by3.75%
Maintainers
3
Weekly downloads
 
Created
Source

ElectricSQL logo

License - Apache 2.0 Status - Alpha Chat - Discord

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.

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.

  1. 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 folder 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

FAQs

Package last updated on 10 Dec 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc