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

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

@@ -109,7 +109,7 @@ For existing projects, see [Existing project setup](#existing-project-setup).
    <Code code={viteConfigCode} lang="js" title="vite.config.js" />
 </Steps>
 
-## Define Your Schema
+## Define your schema
 
 Create a file named `schema.ts` inside the `src/livestore` folder. This file defines your LiveStore schema consisting of your app's event definitions (describing how data changes), derived state (i.e. SQLite tables), and materializers (how state is derived from events).
 
@@ -177,7 +177,7 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-## Create the LiveStore Worker
+## Create the LiveStore worker
 
 Create a file named `livestore.worker.ts` inside the `src` folder. This file will contain the LiveStore web worker. When importing this file, make sure to add the `?worker` extension to the import path to ensure that Vite treats it as a worker file.
 
@@ -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

@@ -9,6 +9,9 @@ export const manualInstallDepsStr = [
   '@livestore/peer-deps' + versionNpmSuffix,
   '@livestore/devtools-vite' + versionNpmSuffix,
   'slashv/vue-livestore' + versionNpmSuffix,
+  'vue',
+  '@vitejs/plugin-vue',
+  'vite-plugin-vue-devtools',
 ].join(' ')
 
 ## Prerequisites
@@ -48,21 +51,19 @@ For a quick start, we recommend referencing the [playground](https://github.com/
 
    Add the following code to your `vite.config.js` file:
 
-    ```ts
+## `getting-started/vue/vite-config.ts`
 
-    export default defineConfig({
-      plugins: [
-        vue(),
-        vueDevTools(),
-        livestoreDevtoolsPlugin({ schemaPath: './src/livestore/schema.ts' }),
-      ],
-      worker: { format: 'es' },
-    })
-    ```
+```ts filename="getting-started/vue/vite-config.ts"
+
+export default defineConfig({
+  plugins: [vue(), vueDevTools(), livestoreDevtoolsPlugin({ schemaPath: './src/livestore/schema.ts' })],
+  worker: { format: 'es' },
+})
+```
 
 </Steps>
 
-### Define Your Schema
+### Define your schema
 
 Create a file named `schema.ts` inside the `src/livestore` folder. This file defines your LiveStore schema consisting of your app's event definitions (describing how data changes), derived state (i.e. SQLite tables), and materializers (how state is derived from events).
 
@@ -126,7 +127,7 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-### Create the LiveStore Worker
+### Create the LiveStore worker
 
 Create a file named `livestore.worker.ts` inside the `src/livestore` folder. This file will contain the LiveStore web worker. When importing this file, make sure to add the `?worker` extension to the import path to ensure that Vite treats it as a worker file.
 
@@ -195,13 +196,15 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-### Add the LiveStore Provider
+### 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:
 
-```vue
+## `getting-started/vue/app.vue`
+
+```vue filename="getting-started/vue/app.vue"
 <script setup lang="ts">
 
 const adapter = makePersistedAdapter({
@@ -215,6 +218,8 @@ const storeOptions = {
   adapter,
   storeId: 'test_store',
 }
+
+void storeOptions
 </script>
 
 <template>
@@ -222,29 +227,91 @@ const storeOptions = {
     <template #loading>
       <div>Loading LiveStore...</div>
     </template>
-    <ToDos />
+    <slot />
   </LiveStoreProvider>
 </template>
 ```
 
+### `getting-started/vue/livestore/schema.ts`
+
+```ts filename="getting-started/vue/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 })
+```
+
 ### 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:
 
-```vue
+## `getting-started/vue/commit-events.vue`
+
+```vue filename="getting-started/vue/commit-events.vue"
 <script setup lang="ts">
 
+// biome-ignore lint/correctness/useHookAtTopLevel: Vue composables run at script setup level
 const { store } = useStore()
 
 const newTodoText = ref('')
 
-// Events
 const createTodo = () => {
   store.commit(events.todoCreated({ id: crypto.randomUUID(), text: newTodoText.value }))
   newTodoText.value = ''
 }
+
+void createTodo
 </script>
 
 <template>
@@ -255,23 +322,83 @@ const createTodo = () => {
 </template>
 ```
 
+### `getting-started/vue/livestore/schema.ts`
+
+```ts filename="getting-started/vue/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 })
+```
+
 ### 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, 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.
 
 Here's an example:
 
-```vue
+## `getting-started/vue/queries.vue`
+
+```vue filename="getting-started/vue/queries.vue"
 <script setup lang="ts">
 
-const visibleTodos$ = queryDb(
-  () => tables.todos.where({ deletedAt: null }),
-  { label: 'visibleTodos' },
-)
+const visibleTodos$ = queryDb(() => tables.todos.where({ completed: false }), { label: 'visibleTodos' })
 
+// biome-ignore lint/correctness/useHookAtTopLevel: Vue composables run at script setup level
 const todos = useQuery(visibleTodos$)
+
+void todos
 </script>
 
 <template>
@@ -284,3 +411,61 @@ const todos = useQuery(visibleTodos$)
   </div>
 </template>
 ```
+
+### `getting-started/vue/livestore/schema.ts`
+
+```ts filename="getting-started/vue/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 })
+```