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

package/docs/framework-integrations/vue-integration/index.md

@@ -4,9 +4,9 @@ The [vue-livestore](https://github.com/slashv/vue-livestore) package provides in
 
 ## API
 
-### `LiveStoreProvider`
+### `<LiveStoreProvider>`
 
-In order to use LiveStore with Vue, you need to wrap your application in a `LiveStoreProvider`.
+In order to use LiveStore with Vue, you need to wrap your application in a `<LiveStoreProvider>`.
 
 ## `reference/framework-integrations/vue/provider.vue`
 

package/docs/getting-started/expo/index.md

@@ -242,47 +242,125 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-## Add the LiveStore Provider
+## Configure the store
 
-To make the LiveStore available throughout your app, wrap your app's root component with the `LiveStoreProvider` component from `@livestore/react`. This provider manages your app’s data store, loading, and error states.
+Create a `store.ts` file in the `src/livestore` folder. This file configures the store adapter and exports a custom hook that components will use to access the store.
 
-Here's an example:
+The `useStore()` hook accepts store configuration options (schema, adapter, store ID) and returns a store instance. It suspends while the store is loading, so make sure to use a `Suspense` boundary to handle the loading state.
 
-## `getting-started/expo/Root.tsx`
+## `getting-started/expo/livestore/store.ts`
 
-```tsx filename="getting-started/expo/Root.tsx"
+```ts filename="getting-started/expo/livestore/store.ts"
 
-const storeId = 'expo-todomvc'
 const syncUrl = 'https://example.org/sync'
 
 const adapter = makePersistedAdapter({
   sync: { backend: makeWsSync({ url: syncUrl }) },
 })
 
-export const Root: FC = () => (
-  <SafeAreaView style={{ flex: 1 }}>
-    <LiveStoreProvider
-      schema={schema}
-      adapter={adapter}
-      storeId={storeId}
-      batchUpdates={batchUpdates}
-      renderLoading={(status) => <Text>Loading LiveStore ({status.stage})...</Text>}
-      renderError={(error) => <Text>Error: {String(error)}</Text>}
-      renderShutdown={() => <Text>LiveStore shutdown</Text>}
-      boot={(store) => {
-        if (store.query(tables.todos.count()) === 0) {
-          store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
-        }
-      }}
-    >
-      <View style={{ flex: 1, gap: 24, padding: 24 }}>
-        <NewTodo />
-        <ListTodos />
-      </View>
-    </LiveStoreProvider>
-    <StatusBar style="auto" />
-  </SafeAreaView>
+export const useAppStore = () =>
+  useStore({
+    storeId: 'expo-todomvc',
+    schema,
+    adapter,
+    batchUpdates,
+    boot: (store) => {
+      if (store.query(tables.todos.count()) === 0) {
+        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
+      }
+    },
+  })
+```
+
+### `getting-started/expo/livestore/schema.ts`
+
+```ts filename="getting-started/expo/livestore/schema.ts"
+
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text({ default: '' }),
+      completed: State.SQLite.boolean({ default: false }),
+      deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromNumber }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'uiState',
+    schema: Schema.Struct({ newTodoText: Schema.String, filter: Schema.Literal('all', 'active', 'completed') }),
+    default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } },
+  }),
+}
+
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+  }),
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ id: Schema.String }),
+  }),
+  todoUncompleted: Events.synced({
+    name: 'v1.TodoUncompleted',
+    schema: Schema.Struct({ id: Schema.String }),
+  }),
+  todoDeleted: Events.synced({
+    name: 'v1.TodoDeleted',
+    schema: Schema.Struct({ id: Schema.String, deletedAt: Schema.Date }),
+  }),
+  todoClearedCompleted: Events.synced({
+    name: 'v1.TodoClearedCompleted',
+    schema: Schema.Struct({ deletedAt: Schema.Date }),
+  }),
+  uiStateSet: tables.uiState.set,
+}
+
+const materializers = State.SQLite.materializers(events, {
+  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text, completed: false }),
+  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
+  'v1.TodoUncompleted': ({ id }) => tables.todos.update({ completed: false }).where({ id }),
+  'v1.TodoDeleted': ({ id, deletedAt }) => tables.todos.update({ deletedAt }).where({ id }),
+  'v1.TodoClearedCompleted': ({ deletedAt }) => tables.todos.update({ deletedAt }).where({ completed: true }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+## Set up the store registry
+
+To enable store management throughout your app, create a `StoreRegistry` and provide it with a `<StoreRegistryProvider>`. The registry manages store instance lifecycles (loading, caching, disposal).
+
+Wrap the provider in a `Suspense` boundary to handle the loading state for when the store is loading.
+
+## `getting-started/expo/Root.tsx`
+
+```tsx filename="getting-started/expo/Root.tsx"
+
+const AppContent: FC = () => (
+  <View style={{ flex: 1, gap: 24, padding: 24 }}>
+    <NewTodo />
+    <ListTodos />
+  </View>
 )
+
+export const Root: FC = () => {
+  const [storeRegistry] = useState(() => new StoreRegistry())
+
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <Suspense fallback={<Text>Loading LiveStore...</Text>}>
+        <StoreRegistryProvider storeRegistry={storeRegistry}>
+          <AppContent />
+        </StoreRegistryProvider>
+      </Suspense>
+      <StatusBar style="auto" />
+    </SafeAreaView>
+  )
+}
 ```
 
 ### `getting-started/expo/components/ListTodos.tsx`
@@ -290,8 +368,8 @@ export const Root: FC = () => (
 ```tsx filename="getting-started/expo/components/ListTodos.tsx"
 
 export const ListTodos: FC = () => {
-  const { store } = useStore()
-  const todos = useQuery(visibleTodos$)
+  const store = useAppStore()
+  const todos = store.useQuery(visibleTodos$)
 
   const toggleTodo = useCallback(
     ({ id, completed }: typeof tables.todos.Type) => {
@@ -339,8 +417,8 @@ export const ListTodos: FC = () => {
 ```tsx filename="getting-started/expo/components/NewTodo.tsx"
 
 export const NewTodo: FC = () => {
-  const { store } = useStore()
-  const { newTodoText } = useQuery(uiState$)
+  const store = useAppStore()
+  const { newTodoText } = store.useQuery(uiState$)
 
   const updateText = (text: string) => store.commit(events.uiStateSet({ newTodoText: text }))
   const createTodo = () =>
@@ -444,19 +522,41 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-### Commit events
+### `getting-started/expo/livestore/store.ts`
+
+```ts filename="getting-started/expo/livestore/store.ts"
+
+const syncUrl = 'https://example.org/sync'
+
+const adapter = makePersistedAdapter({
+  sync: { backend: makeWsSync({ url: syncUrl }) },
+})
+
+export const useAppStore = () =>
+  useStore({
+    storeId: 'expo-todomvc',
+    schema,
+    adapter,
+    batchUpdates,
+    boot: (store) => {
+      if (store.query(tables.todos.count()) === 0) {
+        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
+      }
+    },
+  })
+```
 
-After wrapping your app with the `LiveStoreProvider`, you can use the `useStore` hook from any component to commit events.
+## Commit events
 
-Here's an example:
+After setting up the registry, use the `useAppStore()` hook from any component to access the store and commit events.
 
 ## `getting-started/expo/components/NewTodo.tsx`
 
 ```tsx filename="getting-started/expo/components/NewTodo.tsx"
 
 export const NewTodo: FC = () => {
-  const { store } = useStore()
-  const { newTodoText } = useQuery(uiState$)
+  const store = useAppStore()
+  const { newTodoText } = store.useQuery(uiState$)
 
   const updateText = (text: string) => store.commit(events.uiStateSet({ newTodoText: text }))
   const createTodo = () =>
@@ -560,21 +660,43 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
+### `getting-started/expo/livestore/store.ts`
+
+```ts filename="getting-started/expo/livestore/store.ts"
+
+const syncUrl = 'https://example.org/sync'
+
+const adapter = makePersistedAdapter({
+  sync: { backend: makeWsSync({ url: syncUrl }) },
+})
+
+export const useAppStore = () =>
+  useStore({
+    storeId: 'expo-todomvc',
+    schema,
+    adapter,
+    batchUpdates,
+    boot: (store) => {
+      if (store.query(tables.todos.count()) === 0) {
+        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
+      }
+    },
+  })
+```
+
 ## Queries
 
-To retrieve data from the database, first define a query using `queryDb` from `@livestore/livestore`. Then, execute the query with the `useQuery` hook from `@livestore/react`.
+To retrieve data from the database, define a query using `queryDb` from `@livestore/livestore`, then execute it with `store.useQuery()`.
 
 Consider abstracting queries into a separate file to keep your code organized, though you can also define them directly within components if preferred.
 
-Here's an example:
-
 ## `getting-started/expo/components/ListTodos.tsx`
 
 ```tsx filename="getting-started/expo/components/ListTodos.tsx"
 
 export const ListTodos: FC = () => {
-  const { store } = useStore()
-  const todos = useQuery(visibleTodos$)
+  const store = useAppStore()
+  const todos = store.useQuery(visibleTodos$)
 
   const toggleTodo = useCallback(
     ({ id, completed }: typeof tables.todos.Type) => {
@@ -694,6 +816,30 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
+### `getting-started/expo/livestore/store.ts`
+
+```ts filename="getting-started/expo/livestore/store.ts"
+
+const syncUrl = 'https://example.org/sync'
+
+const adapter = makePersistedAdapter({
+  sync: { backend: makeWsSync({ url: syncUrl }) },
+})
+
+export const useAppStore = () =>
+  useStore({
+    storeId: 'expo-todomvc',
+    schema,
+    adapter,
+    batchUpdates,
+    boot: (store) => {
+      if (store.query(tables.todos.count()) === 0) {
+        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' }))
+      }
+    },
+  })
+```
+
 ## Devtools
 
 To open the devtools, run the app and from your terminal press `shift + m`, then select LiveStore Devtools and press `Enter`.

package/docs/getting-started/react-web/index.md

@@ -250,15 +250,15 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-## Add the LiveStore provider
+## Configure the store
 
-To make the LiveStore available throughout your app, wrap your app's root component with the `LiveStoreProvider` component from `@livestore/react`. This provider manages your app's data store, loading, and error states.
+Create a `store.ts` file in the `src` folder. This file configures the store adapter and exports a custom hook that components will use to access the store.
 
-Here's an example:
+The `useStore()` hook accepts store configuration options (schema, adapter, store ID) and returns a store instance. It suspends while the store is loading, so make sure to use a `Suspense` boundary to handle the loading state.
 
-## `getting-started/react-web/Root.tsx`
+## `getting-started/react-web/store.ts`
 
-```tsx filename="getting-started/react-web/Root.tsx"
+```ts filename="getting-started/react-web/store.ts"
 
 const adapter = makePersistedAdapter({
   storage: { type: 'opfs' },
@@ -266,17 +266,13 @@ const adapter = makePersistedAdapter({
   sharedWorker: LiveStoreSharedWorker,
 })
 
-export const App: React.FC = () => (
-  <LiveStoreProvider
-    schema={schema}
-    adapter={adapter}
-    renderLoading={(_) => <div>Loading LiveStore ({_.stage})...</div>}
-    batchUpdates={batchUpdates}
-    storeId="my-app-store"
-  >
-    <div className="todoapp">{/* Your app components go here */}</div>
-  </LiveStoreProvider>
-)
+export const useAppStore = () =>
+  useStore({
+    storeId: 'app-root',
+    schema,
+    adapter,
+    batchUpdates,
+  })
 ```
 
 ### `getting-started/react-web/livestore/schema.ts`
@@ -341,11 +337,32 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-### Commit events
+## Set up the store registry
+
+To enable store management throughout your app, create a `StoreRegistry` and provide it with a `<StoreRegistryProvider>`. The registry manages store instance lifecycles (loading, caching, disposal).
+
+Wrap the provider in a `Suspense` boundary to handle the loading state for when the store is loading.
+
+## `getting-started/react-web/Root.tsx`
+
+```tsx filename="getting-started/react-web/Root.tsx"
+
+export const App: React.FC = () => {
+  const [storeRegistry] = useState(() => new StoreRegistry())
 
-After wrapping your app with the `LiveStoreProvider`, you can use the `useStore` hook from any component to commit events.
+  return (
+    <Suspense fallback={<div>Loading app...</div>}>
+      <StoreRegistryProvider storeRegistry={storeRegistry}>
+        <div className="todoapp">{/* Your app components go here */}</div>
+      </StoreRegistryProvider>
+    </Suspense>
+  )
+}
+```
 
-Here's an example:
+## Commit events
+
+After setting up the registry, use the `useAppStore()` hook from any component to access the store and commit events.
 
 ## `getting-started/react-web/Header.tsx`
 
@@ -354,7 +371,7 @@ Here's an example:
 const uiState$ = queryDb(tables.uiState.get(), { label: 'uiState' })
 
 export const Header: React.FC = () => {
-  const { store } = useStore()
+  const store = useAppStore()
   const { newTodoText } = store.useQuery(uiState$)
 
   const updateNewTodoText = (text: string) => store.commit(events.uiStateSet({ newTodoText: text }))
@@ -446,14 +463,31 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
+### `getting-started/react-web/store.ts`
+
+```ts filename="getting-started/react-web/store.ts"
+
+const adapter = makePersistedAdapter({
+  storage: { type: 'opfs' },
+  worker: LiveStoreWorker,
+  sharedWorker: LiveStoreSharedWorker,
+})
+
+export const useAppStore = () =>
+  useStore({
+    storeId: 'app-root',
+    schema,
+    adapter,
+    batchUpdates,
+  })
+```
+
 ## Queries
 
-To retrieve data from the database, first define a query using `queryDb` from `@livestore/livestore`. Then, execute the query with the `useQuery` hook from `@livestore/react`.
+To retrieve data from the database, define a query using `queryDb` from `@livestore/livestore`, then execute it with `store.useQuery()`.
 
 Consider abstracting queries into a separate file to keep your code organized, though you can also define them directly within components if preferred.
 
-Here's an example:
-
 ## `getting-started/react-web/MainSection.tsx`
 
 ```tsx filename="getting-started/react-web/MainSection.tsx"
@@ -472,7 +506,7 @@ const visibleTodos$ = queryDb(
 )
 
 export const MainSection: React.FC = () => {
-  const { store } = useStore()
+  const store = useAppStore()
 
   const toggleTodo = React.useCallback(
     ({ id, completed }: typeof tables.todos.Type) =>
@@ -571,3 +605,22 @@ const state = State.SQLite.makeState({ tables, materializers })
 
 export const schema = makeSchema({ events, state })
 ```
+
+### `getting-started/react-web/store.ts`
+
+```ts filename="getting-started/react-web/store.ts"
+
+const adapter = makePersistedAdapter({
+  storage: { type: 'opfs' },
+  worker: LiveStoreWorker,
+  sharedWorker: LiveStoreSharedWorker,
+})
+
+export const useAppStore = () =>
+  useStore({
+    storeId: 'app-root',
+    schema,
+    adapter,
+    batchUpdates,
+  })
+```

package/docs/getting-started/vue/index.md

@@ -198,7 +198,7 @@ export const schema = makeSchema({ events, state })
 
 ### Add the LiveStore provider
 
-To make the LiveStore available throughout your app, wrap your app's root component with the `LiveStoreProvider` component from `vue-livestore`. This provider manages your app's data store, loading, and error states.
+To make the LiveStore available throughout your app, wrap your app's root component with the `<LiveStoreProvider>` component from `vue-livestore`. This provider manages your app's data store, loading, and error states.
 
 Here's an example:
 
@@ -292,7 +292,7 @@ export const schema = makeSchema({ events, state })
 
 ### Commit events
 
-After wrapping your app with the `LiveStoreProvider`, you can use the `useStore` hook from any component to commit events.
+After wrapping your app with the `<LiveStoreProvider>`, you can use the `useStore()` hook from any component to commit events.
 
 Here's an example:
 
@@ -382,7 +382,7 @@ export const schema = makeSchema({ events, state })
 
 ### Queries
 
-To retrieve data from the database, first define a query using `queryDb` from `@livestore/livestore`. Then, execute the query with the `useQuery` hook from `vue-livestore`.
+To retrieve data from the database, first define a query using `queryDb` from `@livestore/livestore`. Then, execute the query with the `useQuery()` hook from `vue-livestore`.
 
 Consider abstracting queries into a separate file to keep your code organized, though you can also define them directly within components if preferred.
 

package/docs/index.md

@@ -35,7 +35,7 @@
 
 ## State of the documentation
 
-Please note that the documentation is still work in progress with many parts missing and often only containing notes/bullet points.
+Please note that the documentation is still work in progress. Please [leave feedback](https://github.com/livestorejs/livestore/issues) if you didn't find the information you were looking for and [consider contributing](/sustainable-open-source/contributing/docs) yourself.
 
 ### Docs for LLMs
 
@@ -102,7 +102,6 @@ Currently, we have the following root-level files:
 
 ### Examples
 
-- [Data modeling](/building-with-livestore/examples): How to model data in LiveStore.
 - [Todo app with shared workspaces](/building-with-livestore/examples/todo-workspaces): How to model a todo workspace app with shared workspaces in LiveStore.
 - [Turn-based game](/building-with-livestore/examples/turnbased-game): How to model a turn-based game in LiveStore.
 - [AI agent](/building-with-livestore/examples/ai-agent): How to model an AI agent in LiveStore.

package/docs/llms.txt

@@ -65,7 +65,6 @@
 
 ### Examples
 
-- [Data modeling](/building-with-livestore/examples): How to model data in LiveStore.
 - [Todo app with shared workspaces](/building-with-livestore/examples/todo-workspaces): How to model a todo workspace app with shared workspaces in LiveStore.
 - [Turn-based game](/building-with-livestore/examples/turnbased-game): How to model a turn-based game in LiveStore.
 - [AI agent](/building-with-livestore/examples/ai-agent): How to model an AI agent in LiveStore.

package/docs/misc/troubleshooting/index.md

@@ -53,17 +53,17 @@ Note on terminology
 
 ### Query doesn't update properly
 
-If you notice the result of a `useQuery` hook is not updating properly, you might be missing some dependencies in the query's hash.
+If you notice the result of a `useQuery()` hook is not updating properly, you might be missing some dependencies in the query's hash.
 
 For example, the following query:
 
 ```ts
 // Don't do this
-const query$ = useQuery(queryDb(tables.issues.query.where({ id: issueId }).first()))
+const query$ = store.useQuery(queryDb(tables.issues.query.where({ id: issueId }).first()))
 //                                                              ^^^^^^^ missing in deps
 
 // Do this instead
-const query$ = useQuery(queryDb(tables.issues.query.where({ id: issueId }).first(), { deps: [issueId] }))
+const query$ = store.useQuery(queryDb(tables.issues.query.where({ id: issueId }).first(), { deps: [issueId] }))
 ```
 
 ## `node_modules` related issues

package/docs/overview/how-livestore-works/index.md

@@ -14,7 +14,7 @@ On the client, LiveStore provides a reactive SQLite database for application sta
 
 Application state is materialized into a local SQLite database, offering high-performance, offline-capable data access. This SQLite database is reactive: UI components subscribe to data changes and update automatically when the state changes. LiveStore uses in-memory SQLite for sub-millisecond queries and persistent SQLite for durable storage across application sessions.
 
-#### Event Sourcing
+#### Event sourcing
 
 Underpinning the reactive state, LiveStore implements the event sourcing pattern. All data modifications are captured as an immutable, ordered sequence of events. This eventlog serves as the canonical history, enabling reliable state reconstruction and providing inherent auditability, which aids in debugging. The reactive SQLite state is a projection of this eventlog.