Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.larksh.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Offline and reconnection

Network connections drop. Users go through tunnels, switch between Wi-Fi and cellular, or temporarily lose signal. The Lark SDK handles all of this automatically so your app stays functional.

​
Automatic reconnection

When a connection drops unexpectedly, the SDK reconnects automatically using exponential backoff with jitter:
AttemptDelay
1~1s
2~2s
3~4s
4~8s
5~16s
6+~30s (max)
Jitter adds a random factor so that thousands of clients don’t all reconnect at the same instant after a server restart. When the connection is re-established:
  • All active subscriptions are automatically re-registered.
  • Any pending writes that were queued while offline are sent to the server.
  • Your onConnect callbacks fire again.

​
Manual control

​
goOffline() and goOnline()

Pause and resume the connection manually. This preserves your local cache and subscription registrations. 
import { LarkDatabase } from "@lark-sh/client";

const db = new LarkDatabase("my-project/my-database", { anonymous: true });

// Pause the connection (e.g., app going to background)
db.goOffline();

// Resume later
db.goOnline();
While offline via goOffline():
  • Writes are queued locally and sent when you go back online.
  • Subscriptions still reflect the last known cached data.
  • No network traffic occurs.

​
disconnect()

Fully tears down the connection and clears everything: cache, subscriptions, pending writes. Use this when you’re completely done with the database. 
db.disconnect();

​
Comparison

goOffline() / goOnline()disconnect()
Local cachePreservedCleared
SubscriptionsPreserved, re-established on goOnline()Removed
Pending writesPreserved, sent on goOnline()Cleared
Reconnect methodgoOnline()New instance + connect()
Use caseTemporary pause (background/foreground)Permanent teardown

​
Pending writes

When the SDK is offline, writes queue up locally. You can inspect and manage this queue.

​
db.hasPendingWrites()

Returns true if there are writes waiting to be sent to the server: 
if (db.hasPendingWrites()) {
  showSyncIndicator();
}

​
db.getPendingWriteCount()

Returns the number of pending writes: 
const count = db.getPendingWriteCount();
console.log(`${count} writes pending`);

​
db.clearPendingWrites()

Discards all pending writes. Use this carefully, because those writes will be lost permanently. 
db.clearPendingWrites();
clearPendingWrites() cannot be undone. Any writes that haven’t been acknowledged by the server are permanently discarded. Only use this if you’re sure you want to throw away those changes.

​
Connection status

The SDK provides a special path .info/connected that reflects the current connection state. This is useful for showing online/offline indicators in your UI. 
const unsubscribe = db.ref(".info/connected").on("value", (snapshot) => {
  const connected = snapshot.val();

  if (connected) {
    console.log("Online");
  } else {
    console.log("Offline");
  }
});
Combine .info/connected with OnDisconnect operations to build robust presence systems that track which users are currently online.

​
Monitoring reconnection

Use lifecycle callbacks to track reconnection attempts: 
db.onDisconnect(() => {
  console.log("Connection lost");
  showOfflineBanner();
});

db.onReconnecting((attempt) => {
  console.log(`Reconnecting... attempt ${attempt}`);
});

db.onConnect(() => {
  console.log("Back online");
  hideOfflineBanner();
});