Skip to content
Meshline
SDK 0.1.0-alpha.6 · GuideView source on GitHub

Storage and pagination

Use one persistent store per network, account, and local device. A second device needs a separate database. Do not copy a live database between device identities or substitute an empty database when opening the original fails.

Choose a store

Runtime Store Application considerations
Node.js NodeSqliteStore(path) Create the parent directory; synchronous SQLite calls can affect event-loop latency.
Browser IndexedDbStore(databaseName) Requires a secure origin and Web Locks; quotas, eviction, and user clearing apply.
Expo ExpoSqliteStore({ databaseName }) Requires native SQLite and a native application build.

Construction performs no I/O. Run migrate() explicitly, then initialize the client, which supplies the store's network/account binding. If using a store directly, call initialize({ context: context.toString(), accountId }). The adapters do not fall back to in-memory storage on persistence failure.

SDK secret protection covers selected key material. It does not encrypt the entire database, message bodies, or metadata. Keep the original persistent protector available when reopening.

The database format belongs to each adapter. The TypeScript SQLite format is not compatible with the .NET SDK's database; neither should be opened as the other.

Account setup persistence

One MeshlineClient component graph owns a database at a time. Retain the complete installation and its protection material together. The account establishment contract defines the ownership and concurrency requirements.

Records Owner Durable responsibility
client_account_operations Client Original setup parameters, internal operation ID and next workflow step; also explicit migration progress.
device_preparation Device manager Protected draft keys and certificate before authorization; an activation receipt after those keys become the local device.
local_device, identity_binding/device Device manager Current certificate, protected keys and device binding.
signed_requests Publishing manager Exact account, device or profile request, its revision and whether its outcome is pending. Device requests also associate the operation with its explicit replacement choice.
contacts, contact_requests, message_outbox Message manager Issued grants, target-acceptance evidence and outgoing messages used to resume authorization maintenance.

The client checkpoints a step after its manager confirms completion. On retry, each manager reconciles its own effects before repeating work. For example, the device manager determines whether a saved publication matches the intended replacement and whether authorization is effective. Internal operation IDs are stored by the SDK; applications do not supply them.

These records use the adapter's existing compare-and-commit contract. Wallet signing and network I/O stay outside transactions, and setup requires no separate schema migration. A settled signed request may have been rejected: successful setup additionally requires verified, effective authorization.

Background contact maintenance reconstructs work from grants and outgoing messages. Each pass shares one lazy outbox scan and rechecks matching delivery records before reuse. Notification progress is stored per contact, committed atomically with its outbox request, and retained across stops and restarts.

Reauthorizing a device does not restore messages or decryption keys from a lost installation.

Read local snapshots

Query methods such as getMessageHistory, getConversations, getPosts, and getMembers return QueryReader<T>. Read positive page sizes with readNext(count, signal?); an empty batch means the snapshot is exhausted. Always dispose a reader in finally.

The consumePages example in workflows.ts consumes all pages and releases the reader even if rendering or cancellation fails. unreadConversations shows reading only the first page.

A reader is fixed when opened. Concurrent arrivals do not appear in it, and a canceled read does not advance it. Open a new reader to refresh. Do not keep readers open for the lifetime of a screen that only needs materialized rows: SQLite readers retain read transactions and browser readers retain snapshot rows.

Local query Ordering
Direct history Local sequence ascending
Group history Group ID, sequence ascending
Channel posts Channel ID, sequence
Conversations Latest summary timestamp descending, conversation ID; empty last

Optional filters apply when supplied. An omitted filter and an explicitly empty array can have different meanings. Identifiers are validated even in local queries; an empty relay ID is not a request for all relays.

Read a bounded history range

Use the exported HistoryRange type to read newer messages with after or older messages with before. Resource filters, the range, and the signal are optional. Omitted, null, and empty ranges are unbounded. Managers copy and validate bounds when opening the query. readNext(count, signal?) chooses the batch size. Every batch is ascending; the boundary selects the adjacent batch.

Range overload Resource filters Sequence
messageManager.getMessageHistory(peer?, range?, signal?) Optional peer string; pass undefined for all peers. Account-wide localSequence in this database.
groupManager.getMessages(filter?, range?, signal?) groupId, sender Group event sequence, also exposed as localSequence.
channelManager.getPosts(query?, range?, signal?) channelId, author Original publication localSequence in the channel.

Both bounds are exclusive, nonnegative safe integers. When supplied together, after must be smaller than before. Group/channel bounds require one groupId/channelId, because sequences belong to that resource. Sequence gaps are valid. Only direct messages, readable group messages, and undeleted posts count toward a batch's size.

For stored sequences 1 through 100 and a batch size of 10:

Bounds First batch Next batch on the same reader
after: 80 81–90 91–100
before: 80 70–79 60–69
after: 65, before: 80 70–79 66–69
None 1–10 11–20

With before, the store selects the closest earlier items in descending order, and the reader returns each selected batch in ascending order. Prepend earlier batches to an existing list; appending backward batches does not produce globally ascending history. Without before, the reader moves forward. Unbounded group and channel queries use resource-ID/sequence order.

export async function previousMessages(client: MeshlineClient, peerAccountId: string, before: number, signal?: AbortSignal) {
    const reader = await client.messageManager.getMessageHistory(peerAccountId, { before }, signal);
    try { return await reader.readNext(50, signal); } finally { await reader.dispose(); }
}

The example is compiled in workflows.ts. It reads up to 50 messages immediately before the supplied position, in ascending order.

Resume with a new reader

To reopen and read older messages, use the first returned localSequence as before. To resume toward newer messages, use the last returned position as after. Keep the database, resource, other filters, and opposite bound. Stop at an empty batch; if updated bounds meet, the bounded range is exhausted.

Each reader retains one fixed snapshot, even across readNext calls. A newly opened reader captures current local state. Later synchronization, group decryption, channel edits and deletions can change results; refresh older ranges to discover messages that become readable there. These positions are not exact processing ACKs or proof of complete history. Local queries do not synchronize, mark read, or follow. A canceled read does not advance the reader.

Calling forms and compatibility

Existing calls such as getMessageHistory(peer, signal) and getMessages({ groupId }, signal) continue to use the original overload. Use getMessageHistory() for unbounded history, getMessageHistory(undefined, { after: 80 }) for all peers after a position, or getMessageHistory(peer, { before: 80 }) for earlier messages with one peer. getMessageHistory(peer, null, signal) explicitly requests an unbounded query.

Distinguish relay pages

Local readers do not fetch missing remote history. loadChannelHistory and group invitation/application/recovery listings instead return pages containing items and an optional nextCursor. Keep a relay cursor with the original resource and query. Stop when no next cursor is returned. These page objects are not disposable readers.

Storage adapter behavior

The supplied adapters apply key bounds and ordering in storage. Direct history and queries scoped to one group/channel use storage readers: SQLite materializes bounded batches, while IndexedDB copies the selected range to snapshot storage when opening a reader. Unscoped group/channel queries still materialize their matching local history when opened. Group/channel filtering may inspect multiple batches to skip non-message, deleted, or nonmatching rows.

Private-message history uses account-wide and per-peer sequence indexes containing message references. New messages maintain these indexes in their transaction. The first history query of an older store backfills them in atomic batches of at most 256 source rows, retaining a restartable checkpoint on failure or cancellation. That initial query can take longer than later indexed queries.

Preserve durable state

The store commits state and cursors atomically. A failed local write or secret protection operation must not be treated as successfully consumed history. Allow the SDK to retry from retained state, and report persistent failures.

Custom store contract

If implementing your own MeshlineStore, preserve atomic compare-and-commit, binding validation, fixed snapshots, cancellation, and disposal semantics. Support RecordQuery.after and before as exclusive ASCII key bounds intersected with key/prefix, reverse as key ordering, and limit as a positive maximum row count. The limit applies to the whole openQuery snapshot, not separately to each readNext call. Empty intersections return no rows. Ignoring these fields can invalidate history pagination; use updated SDK and storage adapter packages together. Adapters supplied here require no schema change for these key queries. Do computation, signing, and network I/O outside database transactions. A stale revision requires recomputing from a new read, not replaying an external business request blindly.

All guides