Reactivity System

LiveStore has a high-performance, fine-grained reactivity system built in which is similar to Signals (e.g. in SolidJS).

Defining reactive state

LiveStore provides 3 types of reactive state:

• Reactive SQL queries on top of SQLite state (queryDb())
• Reactive state values (signal())
• Reactive computed values (computed())

Reactive state variables end on a $ by convention (e.g. todos$). The label option is optional but can be used to identify the reactive state variable in the devtools.

Reactive SQL queries

query-db.ts

import { queryDb, State, signal } from '@livestore/livestore'

  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
      createdAt: State.SQLite.datetime(),
    },
  }),
} as const

const uiState$ = signal({ showCompleted: false }, { label: 'uiState$' })

const todos$ = queryDb(tables.todos.orderBy('createdAt', 'desc'), { label: 'todos$' })

{
  const todos$ = queryDb(
    (get) => {
      const { showCompleted } = get(uiState$)
      return tables.todos.where(showCompleted ? { completed: true } : {})
    },
    { label: 'todos$' },
  )
}

Signals

Signals are reactive state values that can be set and get. This can be useful for state that is not materialized from events into SQLite tables.

signals.ts

import { type Store, signal } from '@livestore/livestore'

declare const store: Store

const now$ = signal(Date.now(), { label: 'now$' })

setInterval(() => {
  store.setSignal(now$, Date.now())
}, 1000)

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

increment()
increment()

console.log(store.query(num$))

Computed values

computed.ts

import { computed, signal } from '@livestore/livestore'

const duplicated$ = computed((get) => get(num$) * 2, { label: 'duplicated$' })

Accessing reactive state

Reactive state is always bound to a Store instance. You can access the current value of reactive state the following ways:

Using the Store instance

store-access.ts

import { queryDb, State, type Store } from '@livestore/livestore'

declare const store: Store

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      title: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
    },
  }),
} as const

const count$ = queryDb(tables.todos.count(), { label: 'count$' })
const count = store.query(count$)
console.log(count)

const unsubscribe = store.subscribe(count$, (value) => {
  console.log(value)
})

unsubscribe()

Via framework integrations

React

react-component.tsx

import type { LiveQueryDef } from '@livestore/livestore'
import { useQuery } from '@livestore/react'
import type { FC } from 'react'

declare const state$: LiveQueryDef<number>

export const MyComponent: FC = () => {
  const value = useQuery(state$)

  return <div>{value}</div>
}

Solid

solid-component.tsx

import type { LiveQueryDef } from '@livestore/livestore'
import { query } from '@livestore/solid'

declare const state$: LiveQueryDef<number>

export const MyComponent = () => {
  const value = query(state$, 0)

  return <div>{value()}</div>
}

Reacting to changing variables passed to queries

If your query depends on a variable passed in by the component, use the deps array to react to changes in this variable.

deps-query.tsx

import { queryDb, State, type Store } from '@livestore/livestore'
import type { ReactApi } from '@livestore/react'
import type { FC } from 'react'

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
    },
  }),
} as const

declare const store: Store & ReactApi

export const todos$ = ({ showCompleted }: { showCompleted: boolean }) =>
  queryDb(
    () => {
      return tables.todos.where(showCompleted ? { completed: true } : {})
    },
    {
      label: 'todos$',
      deps: [showCompleted ? 'true' : 'false'],
    },
  )

export const MyComponent: FC<{ showCompleted: boolean }> = ({ showCompleted }) => {
  const todos = store.useQuery(todos$({ showCompleted })) as ReadonlyArray<{
    id: string
    text: string
    completed: boolean
  }>

  return <div>{todos.length} Done</div>
}

Further reading

• Riffle: Building data-centric apps with a reactive relational database
• Adapton / miniAdapton

Related technologies

• Signia: Signia is a minimal, fast, and scalable signals library for TypeScript developed by TLDraw.