feat: create Svelte framework integration

crates/bindings-typescript/package.json

@@ -71,6 +71,12 @@
       "import": "./dist/server/index.mjs",
       "require": "./dist/server/index.cjs",
       "default": "./dist/server/index.mjs"
+    },
+    "./svelte": {
+      "types": "./dist/svelte/index.d.ts",
+      "import": "./dist/svelte/index.mjs",
+      "require": "./dist/svelte/index.cjs",
+      "default": "./dist/svelte/index.mjs"
     }
   },
   "size-limit": [
@@ -161,18 +167,23 @@
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0-0 || ^19.0.0",
+    "svelte": "^4.0.0 || ^5.0.0",
     "undici": "^6.19.2"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
     },
+    "svelte": {
+      "optional": true
+    },
     "undici": {
       "optional": true
     }
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
+    "svelte": "^5.0.0",
     "@size-limit/file": "^11.2.0",
     "@types/fast-text-encoding": "^1.0.3",
     "@types/react": "^19.1.13",

crates/bindings-typescript/src/svelte/SpacetimeDBProvider.ts

@@ -0,0 +1,101 @@
+import { setContext, onDestroy } from 'svelte';
+import { writable, type Writable } from 'svelte/store';
+import {
+  DbConnectionBuilder,
+  type DbConnectionImpl,
+  type ErrorContextInterface,
+  type RemoteModuleOf,
+} from '../sdk/db_connection_impl';
+import { ConnectionId } from '../lib/connection_id';
+import {
+  SPACETIMEDB_CONTEXT_KEY,
+  type ConnectionState,
+} from './connection_state';
+
+let connRef: DbConnectionImpl<any> | null = null;
+let cleanupTimeoutId: ReturnType<typeof setTimeout> | null = null;
+
+export function createSpacetimeDBProvider<
+  DbConnection extends DbConnectionImpl<any>,
+>(
+  connectionBuilder: DbConnectionBuilder<DbConnection>
+): Writable<ConnectionState> {
+  const getConnection = () => connRef as DbConnection | null;
+
+  const store = writable<ConnectionState>({
+    isActive: false,
+    identity: undefined,
+    token: undefined,
+    connectionId: ConnectionId.random(),
+    connectionError: undefined,
+    getConnection: getConnection as ConnectionState['getConnection'],
+  });
+
+  if (cleanupTimeoutId) {
+    clearTimeout(cleanupTimeoutId);
+    cleanupTimeoutId = null;
+  }
+
+  if (!connRef) {
+    connRef = connectionBuilder.build();
+  }
+
+  const onConnect = (conn: DbConnection) => {
+    store.update(s => ({
+      ...s,
+      isActive: conn.isActive,
+      identity: conn.identity,
+      token: conn.token,
+      connectionId: conn.connectionId,
+    }));
+  };
+
+  const onDisconnect = (
+    ctx: ErrorContextInterface<RemoteModuleOf<DbConnection>>
+  ) => {
+    store.update(s => ({
+      ...s,
+      isActive: ctx.isActive,
+    }));
+  };
+
+  const onConnectError = (
+    ctx: ErrorContextInterface<RemoteModuleOf<DbConnection>>,
+    err: Error
+  ) => {
+    store.update(s => ({
+      ...s,
+      isActive: ctx.isActive,
+      connectionError: err,
+    }));
+  };
+
+  connectionBuilder.onConnect(onConnect);
+  connectionBuilder.onDisconnect(onDisconnect);
+  connectionBuilder.onConnectError(onConnectError);
+
+  const conn = connRef;
+  store.update(s => ({
+    ...s,
+    isActive: conn.isActive,
+    identity: conn.identity,
+    token: conn.token,
+    connectionId: conn.connectionId,
+  }));
+
+  setContext(SPACETIMEDB_CONTEXT_KEY, store);
+
+  onDestroy(() => {
+    connRef?.removeOnConnect(onConnect as any);
+    connRef?.removeOnDisconnect(onDisconnect as any);
+    connRef?.removeOnConnectError(onConnectError as any);
+
+    cleanupTimeoutId = setTimeout(() => {
+      connRef?.disconnect();
+      connRef = null;
+      cleanupTimeoutId = null;
+    }, 0);
+  });
+
+  return store;
+}

crates/bindings-typescript/src/svelte/connection_state.ts

@@ -0,0 +1,16 @@
+import type { ConnectionId } from '../lib/connection_id';
+import type { Identity } from '../lib/identity';
+import type { DbConnectionImpl } from '../sdk/db_connection_impl';
+
+export type ConnectionState = {
+  isActive: boolean;
+  identity?: Identity;
+  token?: string;
+  connectionId: ConnectionId;
+  connectionError?: Error;
+  getConnection<
+    DbConnection extends DbConnectionImpl<any>,
+  >(): DbConnection | null;
+};
+
+export const SPACETIMEDB_CONTEXT_KEY = Symbol('spacetimedb');

crates/bindings-typescript/src/svelte/index.ts

@@ -0,0 +1,4 @@
+export * from './SpacetimeDBProvider.ts';
+export { useSpacetimeDB } from './useSpacetimeDB.ts';
+export { useTable, where, eq } from './useTable.ts';
+export { useReducer } from './useReducer.ts';

crates/bindings-typescript/src/svelte/useReducer.ts

@@ -0,0 +1,56 @@
+import { onDestroy } from 'svelte';
+import { get } from 'svelte/store';
+import type { InferTypeOfRow } from '../lib/type_builders';
+import type { UntypedReducerDef } from '../sdk/reducers';
+import { useSpacetimeDB } from './useSpacetimeDB';
+import type { Prettify } from '../lib/type_util';
+
+type IsEmptyObject<T> = [keyof T] extends [never] ? true : false;
+type MaybeParams<T> = IsEmptyObject<T> extends true ? [] : [params: T];
+
+type ParamsType<R extends UntypedReducerDef> = MaybeParams<
+  Prettify<InferTypeOfRow<R['params']>>
+>;
+
+export function useReducer<ReducerDef extends UntypedReducerDef>(
+  reducerDef: ReducerDef
+): (...params: ParamsType<ReducerDef>) => void {
+  const connectionStore = useSpacetimeDB();
+  const reducerName = reducerDef.accessorName;
+
+  // Holds calls made before the connection exists
+  const queueRef: ParamsType<ReducerDef>[] = [];
+
+  // Flush when we finally have a connection
+  const unsubscribe = connectionStore.subscribe(state => {
+    const conn = state.getConnection();
+    if (!conn) return;
+
+    const fn = (conn.reducers as any)[reducerName] as (
+      ...p: ParamsType<ReducerDef>
+    ) => void;
+    if (queueRef.length) {
+      const pending = queueRef.splice(0);
+      for (const params of pending) {
+        fn(...params);
+      }
+    }
+  });
+
+  onDestroy(() => {
+    unsubscribe();
+  });
+
+  return (...params: ParamsType<ReducerDef>) => {
+    const state = get(connectionStore);
+    const conn = state.getConnection();
+    if (!conn) {
+      queueRef.push(params);
+      return;
+    }
+    const fn = (conn.reducers as any)[reducerName] as (
+      ...p: ParamsType<ReducerDef>
+    ) => void;
+    return fn(...params);
+  };
+}

crates/bindings-typescript/src/svelte/useSpacetimeDB.ts

@@ -0,0 +1,22 @@
+import { getContext } from 'svelte';
+import type { Writable } from 'svelte/store';
+import {
+  SPACETIMEDB_CONTEXT_KEY,
+  type ConnectionState,
+} from './connection_state';
+
+// Throws an error if used outside of a SpacetimeDBProvider
+export function useSpacetimeDB(): Writable<ConnectionState> {
+  const context = getContext<Writable<ConnectionState> | undefined>(
+    SPACETIMEDB_CONTEXT_KEY
+  );
+
+  if (!context) {
+    throw new Error(
+      'useSpacetimeDB must be used within a component that called createSpacetimeDBProvider. ' +
+        'Did you forget to call `createSpacetimeDBProvider` in a parent component?'
+    );
+  }
+
+  return context;
+}