[release/v1.4.0]: Manually apply open PR #3262: Removed @clockworklabs/typescript-sdk in favor of spacetimedb

Author: bfops

.github/workflows/ci.yml

@@ -362,7 +362,6 @@ jobs:
 
       - name: Get pnpm store directory
         shell: bash
-        working-directory: sdks/typescript
         run: |
           echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
 

.github/workflows/typescript-test.yml

@@ -26,7 +26,7 @@ jobs:
 
       - name: Get pnpm store directory
         shell: bash
-        working-directory: sdks/typescript
+        working-directory: crates/bindings-typescript
         run: |
           echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
 
@@ -38,22 +38,14 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-pnpm-store-
       
-      - name: Build module library
+      - name: Build module library and SDK
         working-directory: crates/bindings-typescript
         run: pnpm build
 
-      - name: Run module library tests
+      - name: Run module library and SDK tests
         working-directory: crates/bindings-typescript 
         run: pnpm test
 
-      - name: Build SDK
-        working-directory: sdks/typescript
-        run: pnpm build
-
-      - name: Run SDK tests
-        working-directory: sdks/typescript
-        run: pnpm test
-
       # - name: Extract SpacetimeDB branch name from file
       #   id: extract-branch
       #   run: |
@@ -104,12 +96,12 @@ jobs:
       - name: Generate client bindings
         working-directory: modules/quickstart-chat
         run: |
-          spacetime generate --lang typescript --out-dir ../../sdks/typescript/examples/quickstart-chat/src/module_bindings
-          cd ../../sdks/typescript
-          pnpm lint --write
+          spacetime generate --lang typescript --out-dir ../../crates/bindings-typescript/examples/quickstart-chat/src/module_bindings
+          cd ../../crates/bindings-typescript
+          pnpm format
 
       - name: Check for changes
-        working-directory: sdks/typescript
+        working-directory: crates/bindings-typescript
         run: |
           # This was copied from SpacetimeDB/tools/check-diff.sh.
           # It's required because `spacetime generate` creates lines with the SpacetimeDB commit
@@ -137,7 +129,7 @@ jobs:
       #     spacetime logs quickstart-chat
 
       - name: Check that quickstart-chat builds
-        working-directory: sdks/typescript/examples/quickstart-chat
+        working-directory: crates/bindings-typescript/examples/quickstart-chat
         run: pnpm build
 
       # - name: Run quickstart-chat tests

crates/bindings-typescript/.gitattributes

@@ -0,0 +1,4 @@
+src/sdk/client_api/*.ts linguist-generated=true
+src/lib/autogen/*.ts linguist-generated=true
+test-app/src/module_bindings/*.ts linguist-generated=true
+examples/quickstart/client/src/module_bindings/*.ts linguist-generated=true

sdks/typescript/.gitignore renamed to crates/bindings-typescript/.gitignore

@@ -0,0 +1,13 @@
+# Notes for maintainers
+
+The directory `src/sdk/client_api` is generated from [the SpacetimeDB client-api-messages](https://github.com/clockworklabs/SpacetimeDB/tree/master/crates/client-api-messages).
+
+The directory `src/lib/autogen` is generated from the SpacetimeDB `ModuleDef` definition using the `regen-typescript-moduledef` Rust program.
+
+In order to regenerate both of these bindings, run `pnpm generate`.
+
+Whenever the `client-api-messages` crate or the `ModuleDef` changes, you'll have to manually re-generate the definitions.
+
+## Releases and publishing
+
+In order to release and publish a new version of the package, update the version and run `npm publish`.

sdks/typescript/.npmignore renamed to crates/bindings-typescript/.npmignore

@@ -0,0 +1,118 @@
+## SpacetimeDB Module Library and SDK
+
+### Overview
+
+This repository contains both the SpacetimeDB module library and the TypeScript SDK for SpacetimeDB. The SDK allows you to interact with the database server from a client and applies type information from your SpacetimeDB server module.
+
+### Installation
+
+The SDK is an NPM package, thus you can use your package manager of choice like NPM or Yarn, for example:
+
+```
+npm add spacetimedb
+```
+
+You can use the package in the browser, using a bundler like vite/parcel/rsbuild, in server-side applications like NodeJS, Deno, Bun, NextJS, Remix, and in Cloudflare Workers.
+
+> NOTE: For usage in NodeJS 18-21, you need to install the `undici` package as a peer dependency: `npm add spacetimedb undici`. Node 22 and later are supported out of the box.
+
+### Usage
+
+In order to connect to a database you have to generate module bindings for your database.
+
+```ts
+import { DbConnection } from './module_bindings';
+
+const connection = DbConnection.builder()
+  .withUri('ws://localhost:3000')
+  .withModuleName('MODULE_NAME')
+  .onDisconnect(() => {
+    console.log('disconnected');
+  })
+  .onConnectError(() => {
+    console.log('client_error');
+  })
+  .onConnect((connection, identity, _token) => {
+    console.log(
+      'Connected to SpacetimeDB with identity:',
+      identity.toHexString()
+    );
+
+    connection.subscriptionBuilder().subscribe('SELECT * FROM player');
+  })
+  .withToken('TOKEN')
+  .build();
+```
+
+If you need to disconnect the client:
+
+```ts
+connection.disconnect();
+```
+
+Typically, you will use the SDK with types generated from SpacetimeDB module. For example, given a table named `Player` you can subscribe to player updates like this:
+
+```ts
+connection.db.player.onInsert((ctx, player) => {
+  console.log(player);
+});
+```
+
+Given a reducer called `CreatePlayer` you can call it using a call method:
+
+```ts
+connection.reducers.createPlayer();
+```
+
+#### React Usage
+
+This module also include React hooks to subscribe to tables under the `spacetimedb/react` subpath. In order to use SpacetimeDB React hooks in your project, first add a `SpacetimeDBProvider` at the top of your component hierarchy:
+
+```tsx
+const connectionBuilder = DbConnection.builder()
+  .withUri('ws://localhost:3000')
+  .withModuleName('MODULE_NAME')
+  .withLightMode(true)
+  .onDisconnect(() => {
+    console.log('disconnected');
+  })
+  .onConnectError(() => {
+    console.log('client_error');
+  })
+  .onConnect((conn, identity, _token) => {
+    console.log(
+      'Connected to SpacetimeDB with identity:',
+      identity.toHexString()
+    );
+
+    conn.subscriptionBuilder().subscribe('SELECT * FROM player');
+  })
+  .withToken('TOKEN');
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <SpacetimeDBProvider connectionBuilder={connectionBuilder}>
+      <App />
+    </SpacetimeDBProvider>
+  </React.StrictMode>
+);
+```
+
+One you add a `SpacetimeDBProvider` to your hierarchy, you can use SpacetimeDB React hooks in your render function:
+
+```tsx
+function App() {
+  const conn = useSpacetimeDB<DbConnection>();
+  const { rows: messages } = useTable<DbConnection, Message>('message');
+
+  ...
+}
+```
+
+### Developer notes
+
+To run the tests, do:
+
+```sh
+pnpm build && pnpm test
+```