mjoblin / spacetimedb-typescript-sdk Goto Github PK

This repository contains the TypeScript SDK for SpacetimeDB. The SDK allows to interact with the database server and is prepared to work with code generated from a SpacetimeDB backend code.

The SDK is an NPM package, thus you can use your package manager of choice like NPM or Yarn, for example:

npm install --save @clockworklabs/spacetimedb-sdk

You can use the package in the browser, using a bundler like webpack of vite, and in terminal applications

In order to connect to a database you have to create a new client:

import { SpacetimeDBClient } from "@clockworklabs/spacetimedb-sdk";

let client = new SpacetimeDBClient("spacetimedb.com/spacetimedb", "<db-name>");

If you would like to connect to the client you can call the below method. This also takes optional parameters to override the host or credentials:

client.connect();

If for some reason you need to disconnect the client:

client.disconnect();

This will connect to a database instance without a specified identity. If you want to persist an identity fetched on connection you can register an onConnect callback, which will receive a new assigned identity as an argument:

client.onConnect((identity: string) => {
  console.log(identity);
  console.log(client.token);
});

You may also pass credentials as an optional third argument:

let credentials = { identity: "<identity>", token: "<token>" };
let client = new SpacetimeDBClient(
  "spacetimedb.com/spacetimedb",
  "<db-name>",
  credentials
);

Typically, you will use the SDK with types generated from a backend DB service. For example, given a component named Player you can subscribe to player updates by registering the component:

client.registerComponent(Player, "Player");

Then you will be able to register callbacks on insert and delete events, for example:

Player.onInsert((newPlayer: Player) => {
  console.log(newPlayer);
});

Given a reducer called CreatePlayer you can call it using a call method:

CreatePlayer.call("Nickname");