@livestore/livestore 0.4.0-dev.2 → 0.4.0-dev.20

package/docs/reference/platform-adapters/web-adapter/index.md

@@ -0,0 +1,218 @@
+# Web Adapter
+
+## Installation
+
+```bash
+npm install @livestore/adapter-web @livestore/wa-sqlite
+```
+
+## Example
+
+## `reference/platform-adapters/web-adapter/main.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/main.ts"
+/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
+// ---cut---
+
+const adapter = makePersistedAdapter({
+  storage: { type: 'opfs' },
+  worker: LiveStoreWorker,
+  sharedWorker: LiveStoreSharedWorker,
+})
+```
+
+## `reference/platform-adapters/web-adapter/livestore.worker.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/livestore.worker.ts"
+
+makeWorker({ schema })
+```
+
+### `reference/platform-adapters/web-adapter/schema/index.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/schema/index.ts"
+
+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
+
+const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+  }),
+} as const
+
+const materializers = State.SQLite.materializers(events, {
+  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
+    tables.todos.insert({ id, text, completed: false }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+## Adding a sync backend
+
+## `reference/platform-adapters/web-adapter/sync-backend.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/sync-backend.ts"
+
+makeWorker({ schema, sync: { backend: makeWsSync({ url: 'ws://localhost:8787' }) } })
+```
+
+### `reference/platform-adapters/web-adapter/schema/index.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/schema/index.ts"
+
+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
+
+const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+  }),
+} as const
+
+const materializers = State.SQLite.materializers(events, {
+  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
+    tables.todos.insert({ id, text, completed: false }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+## In-memory adapter
+
+You can also use the in-memory adapter which can be useful in certain scenarios (e.g. testing).
+
+## `reference/platform-adapters/web-adapter/in-memory.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/in-memory.ts"
+/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
+// ---cut---
+
+const adapter = makeInMemoryAdapter()
+```
+
+## Web worker
+
+- Make sure your schema doesn't depend on any code which needs to run in the main thread (e.g. avoid importing from files using React)
+  - Unfortunately this constraints you from co-locating your table definitions in component files.
+  - You might be able to still work around this by using the following import in your worker:
+    ```ts
+
+    ```
+
+### Why is there a dedicated web worker and a shared worker?
+
+- Shared worker:
+  - Needed to allow tabs to communicate with each other using a binary message channel.
+  - The shared worker mostly acts as a proxy to the dedicated web worker.
+- Dedicated web worker (also called "leader worker" via leader election mechanism using web locks):
+  - Acts as the leader/single writer for the storage.
+  - Also handles connection to sync backend.
+  - Currently needed for synchronous OPFS API which isn't supported in a shared worker. (Hopefully won't be needed in the future anymore.)
+
+### Why not use a service worker?
+
+- While service workers seem similar to shared workers (i.e. only a single instance across all tabs), they serve different purposes and have different trade-offs.
+- Service workers are meant to be used to intercept network requests and tend to "shut down" when there are no requests for some period of time making them unsuitable for our use case.
+- Also note that service workers don't support some needed APIs such as OPFS.
+
+## Storage
+
+LiveStore currently only support OPFS to locally persist its data. In the future we might add support for other storage types (e.g. IndexedDB).
+
+During development (`NODE_ENV !== 'production'`), LiveStore automatically copies older state database files into `archive/` inside the OPFS directory for the store (e.g. `livestore-<storeId>@<version>/archive/`). The three most recent copies are retained so you can inspect pre-migration data; older archives are pruned. In production, we delete outdated state databases immediately.
+
+LiveStore also uses `window.sessionStorage` to retain the identity of a client session (e.g. tab/window) across reloads.
+
+### Resetting local persistence
+
+Resetting local persistence only clears data stored in the browser and does not affect any connected sync backend.
+
+In case you want to reset the local persistence of a client, you can provide the `resetPersistence` option to the adapter.
+
+## `reference/platform-adapters/web-adapter/reset-persistence.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/reset-persistence.ts"
+/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
+// ---cut---
+
+const resetPersistence = import.meta.env.DEV && new URLSearchParams(window.location.search).get('reset') !== null
+
+if (resetPersistence) {
+  const searchParams = new URLSearchParams(window.location.search)
+  searchParams.delete('reset')
+  window.history.replaceState(null, '', `${window.location.pathname}?${searchParams.toString()}`)
+}
+
+const adapter = makePersistedAdapter({
+  storage: { type: 'opfs' },
+  worker: LiveStoreWorker,
+  sharedWorker: LiveStoreSharedWorker,
+  resetPersistence,
+})
+```
+
+If you want to reset persistence manually, you can:
+
+1. **Clear site data** in Chrome DevTools (Application tab > Storage > Clear site data)
+2. **Use console command** if the above doesn't work due to a Chrome OPFS bug:
+
+```javascript
+const opfsRoot = await navigator.storage.getDirectory();
+await opfsRoot.remove();
+```
+
+Note: Only use this during development while the app is running.
+
+## Architecture diagram
+
+Assuming the web adapter in a multi-client, multi-tab browser application, a diagram looks like this:
+
+![](https://i.imgur.com/NCKbfub.png)
+
+## Other notes
+
+- The web adapter is using some browser APIs that might require a HTTPS connection (e.g. `navigator.locks`). It's recommended to even use HTTPS during local development (e.g. via [Caddy](https://caddyserver.com/docs/automatic-https)).
+
+## Browser support
+
+- Notable required browser APIs: OPFS, SharedWorker, `navigator.locks`, WASM
+- The web adapter of LiveStore currently doesn't work on Android browsers as they don't support the `SharedWorker` API (see [Chromium bug](https://issues.chromium.org/issues/40290702)).
+
+## Best Practices
+
+- It's recommended to develop in an incognito window to avoid issues with persistent storage (e.g. OPFS).
+
+## FAQ
+
+### What's the bundle size of the web adapter?
+
+LiveStore with the web adapter adds two parts to your application bundle:
+
+- The LiveStore JavaScript bundle (~180KB gzipped)
+- SQLite WASM (~300KB gzipped)

package/docs/reference/reactivity-system/index.md

@@ -0,0 +1,202 @@
+# Reactivity System
+
+LiveStore has a high-performance, fine-grained reactivity system built in which is similar to Signals (e.g. in [SolidJS](https://docs.solidjs.com/concepts/signals)).
+
+## 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
+
+## `reference/reactivity-system/query-db.ts`
+
+```ts filename="reference/reactivity-system/query-db.ts"
+/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet exposes intermediate streams */
+// ---cut---
+
+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 }),
+      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.
+
+## `reference/reactivity-system/signals.ts`
+
+```ts filename="reference/reactivity-system/signals.ts"
+
+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
+
+## `reference/reactivity-system/computed.ts`
+
+```ts filename="reference/reactivity-system/computed.ts"
+/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet highlights derived signal */
+// ---cut---
+
+const num$ = signal(0, { label: 'num$' })
+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
+
+## `reference/reactivity-system/store-access.ts`
+
+```ts filename="reference/reactivity-system/store-access.ts"
+
+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
+
+## `reference/reactivity-system/react-component.tsx`
+
+```tsx filename="reference/reactivity-system/react-component.tsx"
+
+declare const state$: LiveQueryDef<number>
+
+export const MyComponent: FC = () => {
+  const value = useQuery(state$)
+
+  return <div>{value}</div>
+}
+```
+
+#### Solid
+
+## `reference/reactivity-system/solid-component.tsx`
+
+```tsx filename="reference/reactivity-system/solid-component.tsx"
+
+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.
+
+## `reference/reactivity-system/deps-query.tsx`
+
+```tsx filename="reference/reactivity-system/deps-query.tsx"
+
+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](https://riffle.systems/essays/prelude/): Building data-centric apps with a reactive relational database
+- [Adapton](http://adapton.org/) / [miniAdapton](https://arxiv.org/pdf/1609.05337)
+
+## Related technologies
+
+- [Signia](https://signia.tldraw.dev/): Signia is a minimal, fast, and scalable signals library for TypeScript developed by TLDraw.