Store

Defined in: packages/@livestore/livestore/src/store/store.ts:131

Central interface to a LiveStore database providing reactive queries, event commits, and sync.

A Store instance wraps a local SQLite database that is kept in sync with other clients via an event log. Instead of mutating state directly, you commit events that get materialized into database rows. Queries automatically re-run when their underlying tables change.

Creating a Store

Use createStore (Effect-based) or createStorePromise to obtain a Store instance. In React applications, use StoreRegistry with <StoreRegistryProvider> and the useStore() hook which manages the Store lifecycle.

Querying Data

Use Store.query for one-shot reads or Store.subscribe for reactive subscriptions. Both accept query builders (e.g. tables.todo.where({ complete: true })) or custom LiveQueryDefs.

Committing Events

Use Store.commit to persist events. Events are immediately materialized locally and asynchronously synced to other clients. Multiple events can be committed atomically.

Lifecycle

The Store must be shut down when no longer needed via Store.shutdown or Store.shutdownPromise. Framework integrations (React, Effect) handle this automatically.

Example

// Query data
const todos = store.query(tables.todo.where({ complete: false }))

// Subscribe to changes
const unsubscribe = store.subscribe(tables.todo.all(), (todos) => {
  console.log('Todos updated:', todos)
})

// Commit an event
store.commit(events.todoCreated({ id: nanoid(), text: 'Buy milk' }))

Extends

• Class

Type Parameters

TSchema

TSchema extends LiveStoreSchema = Any

The LiveStore schema defining tables and events

TContext

TContext = { }

Optional user-defined context attached to the Store (e.g. for dependency injection)

Constructors

Constructor

new Store<TSchema, TContext>(__namedParameters): Store<TSchema, TContext>

Defined in: packages/@livestore/livestore/src/store/store.ts:187

Parameters

__namedParameters

StoreConstructorParams<TSchema, TContext>

Returns

Store<TSchema, TContext>

Overrides

Inspectable.Class.constructor

Properties

[StoreInternalsSymbol]

readonly [StoreInternalsSymbol]: StoreInternals

Defined in: packages/@livestore/livestore/src/store/store.ts:184

Store internals. Not part of the public API — shapes and semantics may change without notice.

---

commit()

commit: {<TCommitArg>(…list): void; (txn): void; <TCommitArg>(options, …list): void; (options, txn): void; }

Defined in: packages/@livestore/livestore/src/store/store.ts:770

Commit a list of events to the store which will immediately update the local database and sync the events across other clients (similar to a git commit).

Call Signature

<TCommitArg>(…list): void

Type Parameters

TCommitArg

TCommitArg extends readonly ForSchema<TSchema>[]

Parameters

list

…TCommitArg

Returns

void

Call Signature

(txn): void

Parameters

txn

<TCommitArg>(…list) => void

Returns

void

Call Signature

<TCommitArg>(options, …list): void

Type Parameters

TCommitArg

TCommitArg extends readonly ForSchema<TSchema>[]

Parameters

options

StoreCommitOptions

list

…TCommitArg

Returns

void

Call Signature

(options, txn): void

Parameters

options

StoreCommitOptions

txn

<TCommitArg>(…list) => void

Returns

void

Examples

store.commit(events.todoCreated({ id: nanoid(), text: 'Make coffee' }))

You can call commit with multiple events to apply them in a single database transaction.

const todoId = nanoid()
store.commit(
  events.todoCreated({ id: todoId, text: 'Make coffee' }),
  events.todoCompleted({ id: todoId }))

For more advanced transaction scenarios, you can pass a synchronous function to commit which will receive a callback to which you can pass multiple events to be committed in the same database transaction. Under the hood this will simply collect all events and apply them in a single database transaction.

store.commit((commit) => {
  const todoId = nanoid()
  if (Math.random() > 0.5) {
    commit(events.todoCreated({ id: todoId, text: 'Make coffee' }))
  } else {
    commit(events.todoCompleted({ id: todoId }))
  }
})

When committing a large batch of events, you can also skip the database refresh to improve performance and call store.manualRefresh() after all events have been committed.

const todos = [
  { id: nanoid(), text: 'Make coffee' },
  { id: nanoid(), text: 'Buy groceries' },
  // ... 1000 more todos
]
for (const todo of todos) {
  store.commit({ skipRefresh: true }, events.todoCreated({ id: todo.id, text: todo.text }))
}
store.manualRefresh()

---

context

readonly context: TContext

Defined in: packages/@livestore/livestore/src/store/store.ts:139

User-defined context attached to this Store (e.g. for dependency injection).

---

networkStatus

readonly networkStatus: Subscribable<{ devtools: { latchClosed: boolean; }; isConnected: boolean; timestampMs: number; }, never, never>

Defined in: packages/@livestore/livestore/src/store/store.ts:161

Reactive connectivity updates emitted by the backing sync backend.

Example

import { Effect, Stream } from 'effect'

const status = await store.networkStatus.pipe(Effect.runPromise)

await store.networkStatus.changes.pipe(
  Stream.tap((next) => console.log('network status update', next)),
  Stream.runDrain,
  Effect.scoped,
  Effect.runPromise,
)

---

params

readonly params: object

Defined in: packages/@livestore/livestore/src/store/store.ts:142

Options provided to the Store constructor.

eventQueryBatchSize?

optional eventQueryBatchSize: number

leaderPushBatchSize

leaderPushBatchSize: number

simulation?

optional simulation: object

simulation.clientSessionSyncProcessor

clientSessionSyncProcessor: object

simulation.clientSessionSyncProcessor.pull

readonly pull: object

simulation.clientSessionSyncProcessor.pull.1_before_leader_push_fiber_interrupt

readonly 1_before_leader_push_fiber_interrupt: number

simulation.clientSessionSyncProcessor.pull.2_before_leader_push_queue_clear

readonly 2_before_leader_push_queue_clear: number

simulation.clientSessionSyncProcessor.pull.3_before_rebase_rollback

readonly 3_before_rebase_rollback: number

simulation.clientSessionSyncProcessor.pull.4_before_leader_push_queue_offer

readonly 4_before_leader_push_queue_offer: number

simulation.clientSessionSyncProcessor.pull.5_before_leader_push_fiber_run

readonly 5_before_leader_push_fiber_run: number

---

schema

readonly schema: LiveStoreSchema

Defined in: packages/@livestore/livestore/src/store/store.ts:136

The LiveStore schema defining tables, events, and materializers.

---

storageMode

readonly storageMode: "persisted" | "in-memory"

Defined in: packages/@livestore/livestore/src/store/store.ts:179

Indicates how data is being stored.

• persisted: Data is persisted to disk (e.g., via OPFS on web, SQLite file on native)
• in-memory: Data is only stored in memory and will be lost on page refresh

The store operates in in-memory mode when persistent storage is unavailable, such as in Safari/Firefox private browsing mode where OPFS is restricted.

Example

if (store.storageMode === 'in-memory') {
  showWarning('Data will not be persisted in private browsing mode')
}

---

storeId

readonly storeId: string

Defined in: packages/@livestore/livestore/src/store/store.ts:133

Unique identifier for this Store instance, stable for its lifetime.

---

subscribe

subscribe: SubscribeFn

Defined in: packages/@livestore/livestore/src/store/store.ts:466

Subscribe to the results of a query.

• When providing an onUpdate callback it returns an Unsubscribe function.
• Without a callback it returns an AsyncIterable that yields query results.

Examples

const unsubscribe = store.subscribe(query$, (result) => console.log(result))

for await (const result of store.subscribe(query$)) {
  console.log(result)
}

Accessors

clientId

Get Signature

get clientId(): string

Defined in: packages/@livestore/livestore/src/store/store.ts:435

Stable client identifier for the process/device using this Store.

• Shared across Store instances created by the same client
• Useful for diagnostics and multi-client correlation

Returns

string

---

sessionId

Get Signature

get sessionId(): string

Defined in: packages/@livestore/livestore/src/store/store.ts:425

Current session identifier for this Store instance.

• Stable for the lifetime of the Store
• Useful for correlating events or scoping per-session data

Returns

string

Methods

events()

events(options?): AsyncIterable<ForSchema<TSchema>>

Defined in: packages/@livestore/livestore/src/store/store.ts:909

Returns an async iterable of events from the eventlog. Currently only events confirmed by the sync backend is supported.

Defaults to tracking upstreamHead as it advances. If an until event is supplied the stream finalizes upon reaching it.

To start streaming from a specific point in the eventlog you can provide a since event.

Allows filtering by:

• filter: event types
• clientIds: client identifiers
• sessionIds: session identifiers

The batchSize option controls the maximum amount of events that are fetched from the eventlog in each query. Defaults to 100 and has a max allowed value of 1000.

TODO:

• Support streaming unconfirmed events
• Leader level
• Session level
• Support streaming client-only events

Parameters

options?

StoreEventsOptions<TSchema>

Returns

AsyncIterable<ForSchema<TSchema>>

Examples

// Stream todoCompleted events from the start
for await (const event of store.events(filter: ['todoCompleted'])) {
  console.log(event)
}

// Start streaming from a specific event
for await (const event of store.events({ since: EventSequenceNumber.Client.fromString('e3') })) {
  console.log(event)
}

---

eventsStream()

eventsStream(options?): Stream<ForSchema<TSchema>, UnknownError>

Defined in: packages/@livestore/livestore/src/store/store.ts:925

Returns an Effect Stream of events from the eventlog. See store.events for details on options and behaviour.

Parameters

options?

StoreEventsOptions<TSchema>

Returns

Stream<ForSchema<TSchema>, UnknownError>

---

manualRefresh()

manualRefresh(options?): void

Defined in: packages/@livestore/livestore/src/store/store.ts:1058

This can be used in combination with skipRefresh when committing events. We might need a better solution for this. Let’s see.

Parameters

options?

label?

string

Returns

void

---

query()

query<TResult>(query, options?): TResult

Defined in: packages/@livestore/livestore/src/store/store.ts:612

Synchronously queries the database without creating a LiveQuery. This is useful for queries that don’t need to be reactive.

Example: Query builder

const completedTodos = store.query(tables.todo.where({ complete: true }))

Example: Raw SQL query

const completedTodos = store.query({ query: 'SELECT * FROM todo WHERE complete = 1', bindValues: {} })

Type Parameters

TResult

TResult

Parameters

query

Queryable<TResult> | { bindValues: Bindable; query: string; schema?: Schema<TResult, TResult, never>; }

options?

debugRefreshReason?

RefreshReason

otelContext?

Context

Returns

TResult

---

setSignal()

setSignal<T>(signalDef, value): void

Defined in: packages/@livestore/livestore/src/store/store.ts:701

Set the value of a signal

Type Parameters

T

T

Parameters

signalDef

SignalDef<T>

value

T | (prev) => T

Returns

void

Examples

const count$ = signal(0, { label: 'count$' })
store.setSignal(count$, 2)

const count$ = signal(0, { label: 'count$' })
store.setSignal(count$, (prev) => prev + 1)

---

shutdown()

shutdown(cause?): Effect<void>

Defined in: packages/@livestore/livestore/src/store/store.ts:1095

Shuts down the store and closes the client session.

This is called automatically when the store was created using the React or Effect API.

Parameters

cause?

Cause<UnknownError | MaterializeError>

Returns

Effect<void>

---

shutdownPromise()

shutdownPromise(cause?): Promise<void>

Defined in: packages/@livestore/livestore/src/store/store.ts:1079

Shuts down the store and closes the client session.

This is called automatically when the store was created using the React or Effect API.

Parameters

cause?

UnknownError

Returns

Promise<void>

---

subscribeStream()

subscribeStream<TResult>(query, options?): Stream<TResult>

Defined in: packages/@livestore/livestore/src/store/store.ts:577

Type Parameters

TResult

TResult

Parameters

query

Queryable<TResult>

options?

SubscribeOptions<TResult>

Returns

Stream<TResult>

---

subscribeSyncStatus()

subscribeSyncStatus(onUpdate): Unsubscribe

Defined in: packages/@livestore/livestore/src/store/store.ts:1025

Subscribes to sync status changes.

The callback is invoked immediately with the current status and then whenever the sync state changes (e.g., when events are pushed or confirmed).

Parameters

onUpdate

(status) => void

Callback invoked with the current sync status

Returns

Unsubscribe

Unsubscribe function to stop receiving updates

Example

const unsubscribe = store.subscribeSyncStatus((status) => {
  updateUI(status.isSynced ? 'Synced' : 'Syncing...')
})

// Later, stop listening
unsubscribe()

---

syncStatus()

syncStatus(): SyncStatus

Defined in: packages/@livestore/livestore/src/store/store.ts:969

Returns the current synchronization status of the store.

This is a synchronous operation that returns the sync state between the client session and the leader thread. Use this to display sync indicators or check if local changes have been pushed to the leader.

Returns

SyncStatus

Examples

const status = store.syncStatus()
console.log(status.isSynced ? 'Synced' : `${status.pendingCount} pending`)

// Health check for backend connectivity
const status = store.syncStatus()
if (!status.isSynced && status.pendingCount > 100) {
  console.warn('Large backlog of unsynced events')
}

---

syncStatusStream()

syncStatusStream(): Stream<SyncStatus>

Defined in: packages/@livestore/livestore/src/store/store.ts:997

Returns an Effect Stream of sync status updates.

Emits the current status immediately and then whenever the sync state changes. Use this for Effect-based workflows or when you need more control over the stream.

Returns

Stream<SyncStatus>

Example

store.syncStatusStream().pipe(
  Stream.tap((status) => Effect.log(`Sync status: ${status.isSynced}`)),
  Stream.runDrain,
)

---

toJSON()

toJSON(): object

Defined in: packages/@livestore/livestore/src/store/store.ts:1179

Returns

object

_tag

_tag: string = 'livestore.Store'

reactivityGraph

reactivityGraph: ReactiveGraphSnapshot

Overrides

Inspectable.Class.toJSON