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

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

@@ -0,0 +1,294 @@
+# Vue integration for LiveStore
+
+The [vue-livestore](https://github.com/slashv/vue-livestore) package provides integration with Vue. It's currently in beta but aims to match feature parity with the React integration.
+
+## API
+
+### `<LiveStoreProvider>`
+
+In order to use LiveStore with Vue, you need to wrap your application in a `<LiveStoreProvider>`.
+
+## `reference/framework-integrations/vue/provider.vue`
+
+```vue filename="reference/framework-integrations/vue/provider.vue"
+<script setup lang="ts">
+
+const adapter = makeInMemoryAdapter()
+const storeId = 'demo-store'
+const _options = { schema, adapter, storeId }
+</script>
+
+<template>
+  <LiveStoreProvider :options="options">
+    <template #loading>
+      <div>Loading LiveStore...</div>
+    </template>
+    <slot />
+  </LiveStoreProvider>
+</template>
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export 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 }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export 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 })
+```
+
+### `reference/framework-integrations/vue/schema.ts`
+
+```ts filename="reference/framework-integrations/vue/schema.ts"
+export { events, schema, tables } from '../react/schema.ts'
+```
+
+### useStore
+
+## `reference/framework-integrations/vue/use-store.ts`
+
+```ts filename="reference/framework-integrations/vue/use-store.ts"
+
+export const createTodo = () => {
+  const { store } = useStore()
+
+  store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Eat broccoli' }))
+}
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export 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 }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export 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 })
+```
+
+### `reference/framework-integrations/vue/schema.ts`
+
+```ts filename="reference/framework-integrations/vue/schema.ts"
+export { events, schema, tables } from '../react/schema.ts'
+```
+
+### useQuery
+
+## `reference/framework-integrations/vue/use-query.vue`
+
+```vue filename="reference/framework-integrations/vue/use-query.vue"
+<script setup lang="ts">
+
+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>
+  <div>
+    <ul>
+      <li v-for="todo in todos" :key="todo.id">
+        {{ todo.text }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export 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 }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export 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 })
+```
+
+### `reference/framework-integrations/vue/schema.ts`
+
+```ts filename="reference/framework-integrations/vue/schema.ts"
+export { events, schema, tables } from '../react/schema.ts'
+```
+
+### useClientDocument
+
+**[!] The interface for useClientDocument is experimental and might change**
+
+Since it's more common in Vue to work with a single writable ref (as compared to state, setState in React) the useClientDocument composable for Vue tries to make that easier by directly returning a collection of refs.
+
+The current implementation destructures all client state variables into the return object which allows directly binding to v-model or editing the .value reactivly.
+
+## `reference/framework-integrations/vue/use-client-document.vue`
+
+```vue filename="reference/framework-integrations/vue/use-client-document.vue"
+<script setup lang="ts">
+
+// biome-ignore lint/correctness/useHookAtTopLevel: Vue composables run at script setup level
+const { text: newTodoText, filters } = useClientDocument(tables.uiState)
+
+void newTodoText
+void filters
+
+void newTodoText
+void filters
+</script>
+
+<template>
+  <div>
+    <input type="text" v-model="newTodoText" />
+
+    <select v-model="filters">
+      <option value="all">All</option>
+      <option value="active">Active</option>
+      <option value="completed">Completed</option>
+    </select>
+  </div>
+</template>
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export 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 }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export 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 })
+```
+
+### `reference/framework-integrations/vue/schema.ts`
+
+```ts filename="reference/framework-integrations/vue/schema.ts"
+export { events, schema, tables } from '../react/schema.ts'
+```
+
+## Usage with ...
+
+### Vite
+
+LiveStore and vue-livestore works with Vite out of the box.
+
+### Nuxt.js
+
+Works out of the box with Nuxt if SSR is disabled by just wrapping the main content in a LiveStoreProvider. Example repo upcoming.
+
+## Technical notes
+
+- Vue-livestore uses the provider component pattern similar to the React integration. In Vue the plugin pattern is more common but it isn't clear that that's the most suitable structure for LiveStore in Vue. We might switch to the plugin pattern if we later find that more suitable especially with regards to Nuxt support and supporting multiple stores.

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

@@ -178,7 +178,7 @@ For existing projects see [Existing project setup](#existing-project-setup).
 
 </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).
 
@@ -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`.