Auto reconnect - typescript sdk

crates/bindings-typescript/README.md

@@ -26,22 +26,28 @@ import { DbConnection, tables } from './module_bindings';
 const connection = DbConnection.builder()
   .withUri('ws://localhost:3000')
   .withDatabaseName('MODULE_NAME')
-  .onDisconnect(() => {
-    console.log('disconnected');
+  .withAutomaticReconnect()
+  .onConnect((_connection, identity) => {
+    console.log('Connected:', identity.toHexString());
   })
-  .onConnectError(() => {
-    console.log('client_error');
-  })
-  .onConnect((connection, identity, _token) => {
+  .onDisconnect((_ctx, error, attempt, delayMs) => {
     console.log(
-      'Connected to SpacetimeDB with identity:',
-      identity.toHexString()
+      attempt === undefined
+        ? 'Disconnected'
+        : `Retry ${attempt} in ${delayMs} ms`,
+      error
+    );
+  })
+  .onConnectError((_ctx, error, attempt) => {
+    console.error(
+      attempt === undefined ? 'Connection failed' : 'Retry failed',
+      error
     );
-
-    connection.subscriptionBuilder().subscribe(tables.player);
   })
   .withToken('TOKEN')
   .build();
+
+connection.subscriptionBuilder().subscribe(tables.player);
 ```
 
 If you need to disconnect the client:
@@ -50,6 +56,10 @@ If you need to disconnect the client:
 connection.disconnect();
 ```
 
+Automatic reconnection preserves the connection, cache, handles, and callbacks. Register subscriptions and row callbacks once, outside `onConnect`, which runs again after every reconnect. Cache reads remain available during outages. Initial connection failures are not retried by the core SDK.
+
+For expiring credentials, pass the initial token with `withToken` and add `withTokenProvider(() => auth.getAccessToken())`. The SDK asks for a fresh token before reconnecting when the retained token is near expiry. The provider must return a token for the same identity.
+
 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

crates/bindings-typescript/src/lib/errors.ts

@@ -24,3 +24,37 @@ export class InternalError extends Error {
     return 'InternalError';
   }
 }
+
+/** The call was not sent because the connection was not established. */
+export class DisconnectedError extends Error {
+  constructor(message: string = 'Not connected to SpacetimeDB') {
+    super(message);
+  }
+  get name(): string {
+    return 'DisconnectedError';
+  }
+}
+
+/** The connection dropped before acknowledgement; the call may have run. */
+export class UnknownCallResultError extends Error {
+  constructor(
+    message: string = 'Connection lost before the call was acknowledged; it may or may not have run'
+  ) {
+    super(message);
+  }
+  get name(): string {
+    return 'UnknownCallResultError';
+  }
+}
+
+/** The reconnect returned a different identity, ending automatic reconnection. */
+export class IdentityChangedError extends Error {
+  constructor(
+    message: string = 'Reconnected with a different identity; the token was revoked or replaced'
+  ) {
+    super(message);
+  }
+  get name(): string {
+    return 'IdentityChangedError';
+  }
+}