@livestore/livestore 0.4.0-dev.22 → 0.4.0-dev.23

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

@@ -1,287 +0,0 @@
-# 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.
-
-### Private browsing mode
-
-In Safari and Firefox private browsing mode, OPFS is not available due to browser restrictions. When this happens, LiveStore automatically falls back to in-memory storage. This means:
-
-- The app will continue to work normally during the session
-- Data will not persist across page reloads or tab closures
-- Sync functionality (if configured) will still work
-
-You can detect when the store is running in-memory mode using `store.storageMode`:
-
-```tsx
-if (store.storageMode === 'in-memory') {
-  // Show a warning to the user
-  showToast('Data will not be saved in private browsing mode')
-}
-```
-
-The `storageMode` property returns:
-- `'persisted'`: Data is being persisted to disk (e.g., via OPFS)
-- `'in-memory'`: Data is only stored in memory and will be lost on page refresh
-
-You can also listen for boot status events including warnings using the `onBootStatus` callback in your store options:
-
-```ts
-const useAppStore = () => useStore({
-  storeId: 'app',
-  schema,
-  adapter,
-  batchUpdates: ReactDOM.unstable_batchedUpdates,
-  onBootStatus: (status) => {
-    if (status.stage === 'warning') {
-      console.warn(`Storage warning (${status.reason}): ${status.message}`)
-    }
-  },
-})
-```
-
-### 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, `navigator.locks`, WASM
-- SharedWorker is used for multi-tab synchronization but is not strictly required
-
-### Android Chrome (Single-tab mode)
-
-Android Chrome does not support the `SharedWorker` API ([Chromium bug #40290702](https://issues.chromium.org/issues/40290702)). When running on Android Chrome, LiveStore automatically falls back to **single-tab mode**:
-
-- Each browser tab runs independently with its own leader worker
-- Data is still persisted to OPFS (same as full mode)
-- Multi-tab synchronization is not available
-- Devtools are not supported in single-tab mode
-- A warning is logged to the console when this fallback occurs
-
-You can also explicitly use single-tab mode if you don't need multi-tab support:
-
-## `reference/platform-adapters/web-adapter/single-tab.ts`
-
-```ts filename="reference/platform-adapters/web-adapter/single-tab.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
-// ---cut---
-
-// Use this only if you specifically need single-tab mode.
-// Prefer makePersistedAdapter which auto-detects SharedWorker support.
-const adapter = makeSingleTabAdapter({
-  worker: LiveStoreWorker,
-  storage: { type: 'opfs' },
-})
-```
-
-:::note
-The single-tab adapter is intended as a fallback for browsers without SharedWorker support.
-We plan to remove it once SharedWorker is supported in Android Chrome.
-Track progress: [LiveStore #321](https://github.com/livestorejs/livestore/issues/321)
-:::
-
-## 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/sustainable-open-source/contributing/docs/index.md

@@ -1,94 +0,0 @@
-# Docs
-
-Please follow LiveStore's [guiding principles](/sustainable-open-source/contributing/info#guiding-principles) when writing docs.
-
-## Writing style
-
-This project broadly tries to follow the [Prisma docs style guide](https://www.prisma.io/docs/about/style-guide/writing-style).
-
-## Use regular sentence casing for titles of navigation item, pages and sections
-
-All titles for navigation items, pages and sections are using regular sentence casing. This means that only the first word and proper nouns (e.g. "Cloudflare Workers" or "Cloudflare Durable Objects") are capitalized.
-
-### Example 1
-
-Good:
-
-```md
-## This is the title of this section
-```
-
-Bad:
-
-```md
-## This is the Title of this Section
-```
-
-### Example 2
-
-Good:
-
-```md
-## This pages is about Cloudflare Workers
-```
-
-Bad:
-
-```md
-##  This pages is about cloudflare workers
-```
-
-## Create proper frontmatter for every page
-
-Frontmatter is YAML metadata at the start of MD/MDX files (between `---` markers) that controls page rendering, navigation, and SEO.
-
-### Required fields
-
-- **`title`**: Page title used for the browser tab, search results, and page heading. Always required.
-- **`description`**: Brief summary (150-160 characters) used for search snippets and social previews. Highly recommended for SEO.
-
-### Optional fields
-
-- **`sidebar`**: Controls sidebar navigation
-  - `label`: Custom sidebar label (defaults to `title`)
-  - `order`: Numeric sort order (lower numbers appear first)
-
-### SEO impact
-
-The `title` and `description` fields directly impact SEO:
-- `title` becomes the `<title>` tag and search result headline
-- `description` becomes the `<meta name="description">` tag and search snippet
-- Both are used for Open Graph and Twitter Card previews
-- OG images are auto-generated at `/og/{slug}.png` using these fields
-
-### Examples
-
-Minimal (title only):
-```yaml
----
-title: Getting started with LiveStore + React
----
-```
-
-With description and sidebar:
-```yaml
----
-title: Getting started with LiveStore + React
-description: How to use LiveStore with React on the web.
-sidebar:
-  label: React web
-  order: 1
----
-```
-
-## Snippets
-
-For snippet guidelines, see: `/contributor-docs/docs/snippets.md`
-
-## Deploying the docs
-
-- Run `direnv exec . mono docs deploy` to build and deploy the documentation to the dev domain (`https://dev.docs.livestore.dev`).
-- Passing `--prod` targets the production domain (`https://docs.livestore.dev`) when you are on `main` (otherwise the command deploys using a branch alias).
-- Use `--site=<slug>` if you need to override the default Netlify site name.
-- Add `--purge-cdn` when you need to invalidate Netlify's CDN cache after deploying; this ensures new edge handlers or content-negotiation changes take effect immediately.
-- CI automatically builds and deploys the docs: `main` updates `https://docs.livestore.dev`, `dev` updates `https://dev.docs.livestore.dev`, and feature branches publish to the dev domain behind a branch alias.

package/docs/sustainable-open-source/contributing/info/index.md

@@ -1,63 +0,0 @@
-# Info
-
-## Before contributing
-
-First of all, thank you for your interest in contributing to LiveStore! Building LiveStore has been an incredible amount of work, so everyone interested in contributing is very much appreciated. 🧡
-
-Please note that LiveStore is still in active development with many things yet subject to change (e.g. APIs, examples, docs, etc).
-
-Before you start contributing, please check with the maintainers if the changes you'd like to make are likely to be accepted. Please get in touch via the `#contrib` channel on [Discord](https://discord.gg/RbMcjUAPd7).
-
-## Areas for contribution
-
-There are many ways to contribute to LiveStore.
-
-### Help wanted for ...
-
-- You can look at ["help wanted" issues](https://github.com/livestorejs/livestore/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) on GitHub for ideas.
-- [SQLite WASM build](https://github.com/livestorejs/wa-sqlite) maintainer (e.g. keeping it up to date with upstream SQLite and wa-sqlite versions)
-- Examples maintainer (e.g. keeping dependencies & best practices up to date)
-- Solid integration maintainer (e.g. keeping it up to date with upstream Solid versions)
-
-### In scope and encouraged
-
-- Documentation improvements
-- Improving examples
-- Test cases
-- Bug fixes
-- Benchmarking
-
-### Potentially in scope
-
-- New features
-- Larger architectural changes in the core library
-- Adding new examples
-- Adding new integrations (e.g. for technologies such as Svelte, Vue, ...)
-- Monorepo setup changes
-- Changes to the docs site/setup
-
-**Note:** For significant changes to public APIs or core architecture, consider writing an [RFC (Request for Comments)](https://github.com/livestorejs/livestore/tree/dev/contributor-docs/rfcs) first to gather feedback before implementation.
-
-### Out of scope (for now)
-
-- Changes to the landing page
-- Changes to the devtools
-- Rewriting the core library in a different language
-
-### Open research questions
-
-- Safer event schema evolution
-- Incremental view maintenance for complex SQLite database views
-
-Please get in touch if you'd like to discuss any of these topics!
-
-## Bug reports
-
-- Please include a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) for how to reproduce the bug.
-
-## Guiding principles {#guiding-principles}
-
-- Keep it as simple as possible
-- Reduce surface area
-- Make the right thing easy
-- Document the "why"

package/docs/sustainable-open-source/contributing/monorepo/index.md

@@ -1,195 +0,0 @@
-# Monorepo
-
-## Prerequisites
-
-### Personal experience
-
-Depending on the kind of contribution you're interested in, the following
-experience is recommended:
-
-- Deep experience with TypeScript (incl. type-level programming)
-- Experience with TypeScript monorepo setups
-- Experience with distributed systems
-- Experience with [Effect](https://effect.website) (or willingness to learn)
-
-### Recommended tooling: Use devenv + direnv for a consistent setup
-
-To make development easy and consistent across systems and platforms, this
-project uses [Nix](https://zero-to-nix.com/) with [devenv](https://devenv.sh)
-to manage "system dependencies" such as Node.js, Bun, etc.
-Use [direnv](https://direnv.net) (recommended) to automatically load the
-environment, or run commands explicitly with devenv, for example:
-`devenv shell pnpm install`.
-
-### Manual setup
-
-You'll need to have a recent version the following tools installed:
-
-- Node.js
-- Bun
-- pnpm
-
-## Initial setup
-
-```bash
-git clone git@github.com:livestorejs/livestore.git
-cd livestore
-# Loads env vars, installs deps and builds the project
-./bootstrap.sh
-```
-
-## General notes
-
-- TypeScript
-  - LiveStore tries to follow the strictest TypeScript rules possible to ensure
-    type safety and avoid subtle bugs.
-    - LiveStore also makes heavy use of
-      [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html).
-- Package management
-  - This project uses [pnpm](https://pnpm.io/) to manage the workspace.
-- LiveStore is primarily developed in VSCode/Cursor.
-- Testing
-  - LiveStore uses Vitest for most tests and Playwright for browser tests.
-
-### Notable used tools / technologies
-
-- [TypeScript](https://www.typescriptlang.org/)
-- [Effect](https://effect.website)
-- [pnpm](https://pnpm.io/)
-- [Bun](https://bun.sh/)
-- [Vitest](https://vitest.dev/)
-- [Playwright](https://playwright.dev/)
-- [OpenTelemetry](https://opentelemetry.io/)
-- [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) (included as git subtree) - see [wa-sqlite management](../../../../../../contributor-docs/wa-sqlite-management.md)
-- [Nix](https://zero-to-nix.com/)
-- [Direnv](https://direnv.net/)
-- [devenv](https://devenv.sh)
-
-### Environment variables
-
-The `.envrc` file contains all necessary environment variables for the project.
-You can create a `.envrc.local` file to override or add variables for your local
-setup. You'll need to run `direnv allow` to load the environment variables.
-
-### VSCode tasks
-
-- This project is primarily developed in VSCode and makes use of
-  [tasks](https://code.visualstudio.com/docs/editor/tasks) to run commands.
-- Common tasks are:
-  - `dev:ts:watch` to run the TypeScript compiler in watch mode for the entire
-    monorepo
-  - `pnpm:install` to install all dependencies (e.g. when changing a
-    `package.json`)
-
-## Tasks to run before committing
-
-Please run the following tasks before committing & pushing:
-
-- `mono ts` to build the TypeScript code
-- `mono lint` to run the linting checks
-- `mono test` to run the tests
-
-## Examples
-
-- Once you've set up the monorepo locally, you'll find all examples in the
-  `/examples` directory.
-- All examples are self-contained and can be run independently.
-- Examples use explicit version dependencies (e.g., `0.3.2-dev.0`) for LiveStore packages.
-- Examples are not part of the monorepo TypeScript build system to maintain independence.
-- Each example has its own TypeScript configuration that's independent of the
-  monorepo build system.
-
-#### Making changes to examples
-
-1. Make your desired changes directly in `/examples/<example-name>`.
-2. Test your changes by running the example (e.g., `pnpm dev` in the example
-   directory).
-3. Commit your changes.
-
-### OpenTelemetry setup
-
-As a local OpenTelemetry setup, we recommend the
-[docker-otel-lgtm](https://github.com/grafana/docker-otel-lgtm) setup.
-
-Add the following to your `.envrc.local` file:
-
-```bash
-export VITE_GRAFANA_ENDPOINT="http://localhost:30003"
-export GRAFANA_ENDPOINT="http://localhost:30003"
-export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
-export VITE_OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
-```
-
-### TypeScript
-
-- Each package has its own `tsconfig.json` file which extends the root
-  `tsconfig.base.json`.
-- This project makes heavy use of TypeScript project references.
-
-### Package management
-
-- This project uses [pnpm](https://pnpm.io/) to manage the workspace.
-- We're using the `workspace:*` protocol to link packages together.
-- We should try to keep dependencies to an absolute minimum and only add them if
-  we absolutely need them.
-- We also need to manually add peer dependencies for each package.
-- We should try to avoid duplicate dependencies across the monorepo as much as
-  possible as duplicate dependencies can lead to a lot of issues and pain.
-  - We're also using the `resolutions` field in the root `package.json` to force
-    some packages to be the same across the monorepo (ideally not needed but for
-    some packages it's necessary currently).
-- We're using [syncpack](https://github.com/JamieMason/syncpack) to help
-  maintain consistent dependency versions across the monorepo.
-  - See `syncpack.config.mjs` for the configuration.
-  - Common commands:
-    - `bunx syncpack format` to format the `package.json` files
-    - `bunx syncpack lint` to check all version ranges
-    - `bunx syncpack fix-mismatches` to adjust versions across `package.json`
-      files (check before with `lint`)
-    - `bunx syncpack update` to update packages across the monorepo to the
-      latest versions
-
-### Notes on external dependencies
-
-LiveStore tries to use as few external dependencies as possible. Given LiveStore
-is built on top of Effect, which can be considered a standard library for
-TypeScript, it should handle most use cases.
-
-#### Notes on some packages
-
-The following packages need to be updated with extra care:
-
-- `react`/`react-dom` as we need to move in lockstep with Expo / React Native
-  (currently pinned to {REACT_VERSION})
-- `effect` (currently pinned to {EFFECT_VERSION})
-
-#### Effect
-
-- LiveStore makes heavy use of the [Effect](https://effect.website) library and
-  ecosystem throughout the implementation of the various packages.
-- Effect is not imposed on the app developers using LiveStore but where it makes
-  sense, LiveStore is also exposing a Effect-based API (e.g. `createStore`).
-
-#### Updating dependencies
-
-- Either update the versions manually in each `package.json` file or use
-  `bunx syncpack update`.
-
-### Notes on monorepo structure
-
-- The `@livestore/utils` package re-exports many common modules/functions (e.g.
-  from `effect`) in order to
-  - Reduce the number of direct dependencies for other packages
-  - Allows for convenient extension of modules (e.g. adding methods to
-    `Effect.___`, `Schema.___`, ...)
-
-## Docs
-
-The LiveStore docs are built with
-[Astro Starlight](https://starlight.astro.build/).
-
-## Related external repos
-
-- [Fork of wa-sqlite](https://github.com/livestorejs/wa-sqlite) with Nix build setup included as git subtree.
-- The source code of the devtools is currently not part of this monorepo but in
-  a separate private repo.