> ## 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.

# LarkDatabase

> API reference for the LarkDatabase class

The `LarkDatabase` class is the main entry point for interacting with a Lark database. It manages the connection lifecycle, authentication, and provides access to database references.

## Constructor

```typescript theme={null}
new LarkDatabase(projectAndDatabase: string, options?: LarkDatabaseOptions)
```

Creates a new `LarkDatabase` instance.

| Parameter            | Type                  | Description                                                   |
| -------------------- | --------------------- | ------------------------------------------------------------- |
| `projectAndDatabase` | `string`              | A combined identifier in the format `'projectId/databaseId'`. |
| `options`            | `LarkDatabaseOptions` | Optional configuration object.                                |

### LarkDatabaseOptions

| Option                | Type                                      | Default        | Description                                                                                                        |
| --------------------- | ----------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `anonymous`           | `boolean`                                 | `false`        | Connect without user credentials.                                                                                  |
| `token`               | `string`                                  | —              | A JWT for authenticated access.                                                                                    |
| `domain`              | `string`                                  | `'larkdb.net'` | The Lark server domain.                                                                                            |
| `transport`           | `'auto' \| 'websocket' \| 'webtransport'` | `'websocket'`  | Which transport protocol to use.                                                                                   |
| `webtransportTimeout` | `number`                                  | `2000`         | Milliseconds to wait for WebTransport before falling back to WebSocket. Only applies when `transport` is `'auto'`. |

You must provide either `anonymous: true` or a `token`. If you pass both, the token takes priority.

```typescript theme={null}
import { LarkDatabase } from '@lark-sh/client';

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

## Properties

| Property           | Type                                    | Description                                                                                                                               |
| ------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `connected`        | `boolean`                               | Whether the client is currently connected to the server.                                                                                  |
| `state`            | `ConnectionState`                       | The current connection state. One of `'disconnected'`, `'connecting'`, `'connected'`, `'joined'`, `'authenticated'`, or `'reconnecting'`. |
| `auth`             | `AuthInfo \| null`                      | The current authentication info, or `null` if not signed in.                                                                              |
| `reconnecting`     | `boolean`                               | Whether the client is currently attempting to reconnect.                                                                                  |
| `transportType`    | `'websocket' \| 'webtransport' \| null` | The active transport protocol, or `null` if not connected.                                                                                |
| `serverTimeOffset` | `number`                                | Estimated offset in milliseconds between the client clock and the server clock.                                                           |
| `volatilePaths`    | `string[]`                              | List of paths configured for high-frequency volatile updates.                                                                             |

### AuthInfo

| Property   | Type     | Description                                 |
| ---------- | -------- | ------------------------------------------- |
| `uid`      | `string` | The authenticated user's unique identifier. |
| `provider` | `string` | The authentication provider used.           |
| `token`    | `string` | The current authentication token.           |

## Methods

### connect

```typescript theme={null}
connect(): Promise<void>
```

Opens a connection to the Lark server using the options passed to the constructor. Resolves when the connection is fully established and authenticated.

```typescript theme={null}
const db = new LarkDatabase('my-project/my-database', { anonymous: true });
await db.connect(); // optional, operations queue automatically
```

### disconnect

```typescript theme={null}
disconnect(): Promise<void>
```

Closes the connection to the server. Resolves when the connection is fully closed.

```typescript theme={null}
await db.disconnect();
```

### ref

```typescript theme={null}
ref(path?: string): DatabaseReference
```

Returns a `DatabaseReference` pointing to the specified path in the database. If no path is provided, returns a reference to the root.

| Parameter | Type     | Description                                  |
| --------- | -------- | -------------------------------------------- |
| `path`    | `string` | Optional path relative to the database root. |

```typescript theme={null}
const usersRef = db.ref('users');
const rootRef = db.ref();
const nestedRef = db.ref('users/alice/profile');
```

### signIn

```typescript theme={null}
signIn(token: string): Promise<void>
```

Authenticates the client with the given token. Resolves when authentication succeeds.

| Parameter | Type     | Description              |
| --------- | -------- | ------------------------ |
| `token`   | `string` | An authentication token. |

```typescript theme={null}
await db.signIn('eyJhbGciOi...');
```

### signOut

```typescript theme={null}
signOut(): Promise<void>
```

Signs out the current user and reverts to unauthenticated access.

```typescript theme={null}
await db.signOut();
```

### transaction

```typescript theme={null}
transaction(ops: TransactionOperation[]): Promise<TransactionResult>
```

Executes a batch of operations atomically. All operations succeed or all fail together.

| Parameter | Type                     | Description                                   |
| --------- | ------------------------ | --------------------------------------------- |
| `ops`     | `TransactionOperation[]` | An array of operations to execute atomically. |

```typescript theme={null}
const result = await db.transaction([
  { type: 'set', path: 'counters/a', value: 1 },
  { type: 'set', path: 'counters/b', value: 2 },
]);
```

### goOffline

```typescript theme={null}
goOffline(): void
```

Manually disconnects the client and disables automatic reconnection. Pending writes are preserved.

```typescript theme={null}
db.goOffline();
```

### goOnline

```typescript theme={null}
goOnline(): void
```

Re-enables the connection after a `goOffline()` call. The client will attempt to reconnect and flush any pending writes.

```typescript theme={null}
db.goOnline();
```

### hasPendingWrites

```typescript theme={null}
hasPendingWrites(): boolean
```

Returns `true` if there are writes that have not yet been acknowledged by the server.

```typescript theme={null}
if (db.hasPendingWrites()) {
  console.log('Waiting for writes to sync...');
}
```

### getPendingWriteCount

```typescript theme={null}
getPendingWriteCount(): number
```

Returns the number of write operations that have not yet been acknowledged by the server.

```typescript theme={null}
console.log(`${db.getPendingWriteCount()} writes pending`);
```

### clearPendingWrites

```typescript theme={null}
clearPendingWrites(): void
```

Discards all pending writes that have not been sent to the server. Use with caution, because discarded writes cannot be recovered.

<Note>
  This permanently drops any unsent writes. Only use this if you intentionally want to discard local changes.
</Note>

```typescript theme={null}
db.clearPendingWrites();
```

## Event Methods

All event methods return an unsubscribe function. Call it to stop listening.

### onConnect

```typescript theme={null}
onConnect(callback: () => void): () => void
```

Registers a listener that fires when the client establishes a connection.

```typescript theme={null}
const unsubscribe = db.onConnect(() => {
  console.log('Connected to Lark');
});

// Later, stop listening
unsubscribe();
```

### onDisconnect

```typescript theme={null}
onDisconnect(callback: () => void): () => void
```

Registers a listener that fires when the client loses its connection.

```typescript theme={null}
const unsubscribe = db.onDisconnect(() => {
  console.log('Disconnected from Lark');
});
```

### onReconnecting

```typescript theme={null}
onReconnecting(callback: () => void): () => void
```

Registers a listener that fires when the client begins a reconnection attempt.

```typescript theme={null}
const unsubscribe = db.onReconnecting(() => {
  console.log('Attempting to reconnect...');
});
```

### onError

```typescript theme={null}
onError(callback: (error: LarkError) => void): () => void
```

Registers a listener that fires when a connection-level error occurs.

```typescript theme={null}
const unsubscribe = db.onError((error) => {
  console.error(`Lark error [${error.code}]: ${error.message}`);
});
```

### onAuthStateChanged

```typescript theme={null}
onAuthStateChanged(callback: (auth: AuthInfo | null) => void): () => void
```

Registers a listener that fires when the authentication state changes: on sign-in, sign-out, or token refresh.

```typescript theme={null}
const unsubscribe = db.onAuthStateChanged((auth) => {
  if (auth) {
    console.log(`Signed in as ${auth.uid}`);
  } else {
    console.log('Signed out');
  }
});
```