@basictech/react 0.8.0-beta.3 → 0.9.0-beta.0

package/readme.md

@@ -1,6 +1,30 @@
 # @basictech/react
 
-React SDK for [Basic](https://basic.tech) - add authentication and real-time database to your React app in minutes.
+React SDK for [Basic](https://basic.tech) — authentication and an offline-first, synced database for your React app.
+
+Basic gives every user their own personal datastore (a PDS). Your app authenticates with OAuth, gets its own sandboxed slice of the user's datastore, and this SDK keeps a local replica of that data in the browser — reads are instant and local, writes work offline, and everything syncs live across the user's devices over the Basic **Sync/2** protocol.
+
+> **Breaking change (0.9):** this version is a ground-up rewrite for the new Basic auth system and the Sync/2 sync engine. The 0.8.x sync client speaks a protocol the server no longer supports. See [Migrating from 0.8](#migrating-from-08).
+
+---
+
+## Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Authentication](#authentication)
+- [Database](#database)
+- [Live queries](#live-queries)
+- [Sync status, offline behavior & errors](#sync-status-offline-behavior--errors)
+- [Shares (multiplayer)](#shares-multiplayer)
+- [Typed schemas](#typed-schemas)
+- [REST mode](#rest-mode)
+- [API reference](#api-reference)
+- [Advanced usage](#advanced-usage)
+- [Migrating from 0.8](#migrating-from-08)
+
+---
 
 ## Installation
 
@@ -8,13 +32,16 @@ React SDK for [Basic](https://basic.tech) - add authentication and real-time dat
 npm install @basictech/react
 ```
 
-## Quick Start
+Requires React 16.8+ (hooks). React 17, 18, and 19 are supported.
 
-### 1. Create a Schema
+## Quick start
 
-Create a `basic.config.ts` file with your project configuration:
+### 1. Define your schema
+
+Create a `basic.config.ts` with your project id (from [app.basic.tech](https://app.basic.tech)) and your tables:
 
 ```typescript
+// basic.config.ts
 export const schema = {
   project_id: "YOUR_PROJECT_ID",
   version: 1,
@@ -22,324 +49,362 @@ export const schema = {
     todos: {
       type: "collection",
       fields: {
-        title: { type: "string", indexed: true },
-        completed: { type: "boolean", indexed: true }
-      }
-    }
-  }
-}
+        title: { type: "string", indexed: true, required: true },
+        completed: { type: "boolean", indexed: true },
+      },
+    },
+  },
+};
 ```
 
-### 2. Add the Provider
+Field types: `string`, `number`, `boolean`, `json`. Publish the schema from the Basic dashboard — sync is enabled once the published version matches your local one.
 
-Wrap your app with `BasicProvider`:
+### 2. Wrap your app
 
 ```tsx
-import { BasicProvider } from '@basictech/react'
-import { schema } from './basic.config'
-
-function App() {
-  return (
-    <BasicProvider schema={schema}>
-      <YourApp />
-    </BasicProvider>
-  )
-}
+// main.tsx
+import { BasicProvider } from "@basictech/react";
+import { schema } from "./basic.config";
+
+createRoot(document.getElementById("root")!).render(
+  <BasicProvider schema={schema} devToolbar>
+    <App />
+  </BasicProvider>,
+);
 ```
 
-### 3. Use the Hook
-
-Access auth and database in any component:
+### 3. Sign in and use the database
 
 ```tsx
-import { useBasic, useQuery } from '@basictech/react'
-
-function TodoList() {
-  const { db, isSignedIn, signIn, signOut, user } = useBasic()
-  
-  // Live query - automatically updates when data changes
-  const todos = useQuery(() => db.collection('todos').getAll())
-
-  const addTodo = async () => {
-    await db.collection('todos').add({
-      title: 'New todo',
-      completed: false
-    })
-  }
+import { useBasic, useQuery } from "@basictech/react";
+
+function Todos() {
+  const { isSignedIn, signIn, signOut, user, db } = useBasic();
+  const todos = useQuery(() => db.table("todos").getAll());
 
   if (!isSignedIn) {
-    return <button onClick={signIn}>Sign In</button>
+    return <button onClick={() => signIn()}>Sign in with Basic</button>;
   }
 
   return (
     <div>
-      <p>Welcome, {user?.email}</p>
-      <button onClick={addTodo}>Add Todo</button>
-      <ul>
-        {todos?.map(todo => (
-          <li key={todo.id}>{todo.title}</li>
-        ))}
-      </ul>
-      <button onClick={signOut}>Sign Out</button>
+      <p>hi {user?.email} <button onClick={() => signOut()}>sign out</button></p>
+
+      <button onClick={() => db.table("todos").create({ title: "hello", completed: false })}>
+        add todo
+      </button>
+
+      {todos?.map((todo) => (
+        <label key={todo.id}>
+          <input
+            type="checkbox"
+            checked={!!todo.completed}
+            onChange={() => db.table("todos").patch(todo.id, { completed: !todo.completed })}
+          />
+          {String(todo.title)}
+          <button onClick={() => db.table("todos").delete(todo.id)}>×</button>
+        </label>
+      ))}
     </div>
-  )
+  );
 }
 ```
 
----
+That's the whole loop: `signIn()` runs the OAuth flow, `db.table(...)` writes apply instantly to the local replica (and queue offline), and `useQuery` re-renders whenever local data changes — whether the change came from this tab, another tab, another device, or another user via a share.
+
+## How it works
 
-## API Reference
+In the default `sync` mode, the SDK maintains a **local replica** of your app's slice of the user's datastore, in IndexedDB, and syncs it over one WebSocket:
 
-### `<BasicProvider>`
+1. **Bootstrap** — on first run the SDK fetches a snapshot of current state, then subscribes for live changes from that point.
+2. **Writes are ops** — every write is a `put` (create/replace), `patch` (shallow field merge), or `delete` operation with a client-minted unique id. Ops apply to the local view immediately (optimistic), queue in IndexedDB, and push to the server when online. Retries are always safe: the server deduplicates by op id.
+3. **Reads are local** — `get`/`getAll`/`find` read the local view: confirmed server state with your pending writes layered on top. No network round-trip.
+4. **The server is the authority** — it orders all ops (last-writer-wins per record; `patch`es merge per field), validates them against your published schema, and echoes them to every connected device. If it rejects a write, the SDK rolls it back locally and surfaces it (see [rejected ops](#rejected-ops)).
+5. **Sign-out is clean** — local data is deleted, the session is revoked server-side, and other tabs update in place. No page reloads.
 
-Root provider component. Must wrap your entire app.
+## Authentication
+
+Basic is the OAuth provider. `signIn()` redirects to the user's Basic sign-in page; after consent the user lands back on your app with a code the SDK exchanges automatically (PKCE, rotating refresh tokens — all handled for you).
 
 ```tsx
-<BasicProvider
-  schema={schema}           // Required: Your Basic schema
-  debug={false}             // Optional: Enable console logging
-  dbMode="sync"             // Optional: "sync" (default) or "remote"
-  devToolbar={false}        // Optional: Floating dev status bar (localhost / dev / debug)
-/>
+const auth = useAuth(); // or grab the same fields from useBasic()
+
+auth.status;        // 'bootstrapping' | 'authenticated' | 'recovering' | 'reauth_required' | 'signed_out'
+auth.isSignedIn;    // boolean (stays true during reauth_required so you can show user info)
+auth.user;          // { sub, email, name, picture } | null
+auth.did;           // the user's decentralized id
+auth.scope;         // scopes granted to your app
+
+await auth.signIn();                       // redirect flow (current URL is the redirect URI)
+await auth.signIn("https://app.com/done"); // custom redirect URI
+await auth.signInWithHandle("alice.basic.id"); // federated: resolve the user's own PDS first
+await auth.signOut();                      // revokes server-side + clears local data
 ```
 
-#### Props
+### Auth status lifecycle
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `schema` | `object` | required | Schema with `project_id` and `tables` |
-| `debug` | `boolean` | `false` | Enable debug logging |
-| `dbMode` | `"sync" \| "remote"` | `"sync"` | Database mode |
-| `devToolbar` | `boolean` | `false` | Show the Basic dev toolbar (only when `localhost`, `NODE_ENV === "development"`, or `debug={true}`) |
+| Status | Meaning | What to render |
+| --- | --- | --- |
+| `bootstrapping` | SDK is initializing | splash / nothing (provider hides children by default) |
+| `authenticated` | Healthy session | your app |
+| `recovering` | Session likely exists but unconfirmed (offline, mid-refresh) | your app (data still works locally) |
+| `reauth_required` | Session definitively invalid — user must sign in again | user info + a sign-in prompt |
+| `signed_out` | No session | sign-in screen |
 
-#### Database Modes
+### Calling your own API
 
-- **`sync`** - Local-first with IndexedDB + real-time sync via WebSocket
-- **`remote`** - Direct REST API calls (no local storage)
+`getToken()` returns a valid access token, refreshing it automatically (tokens are short-lived — never cache them yourself):
 
----
+```typescript
+const token = await auth.getToken();
+await fetch("https://your-api.example/thing", {
+  headers: { Authorization: `Bearer ${token}` },
+});
+// after a 401 from your API:
+await auth.getToken({ forceRefresh: true });
+```
 
-### `useBasic()`
+### Scopes
 
-Main hook for accessing auth and database.
+Default requested scopes are `profile,email,app:admin`. Check what was actually granted:
 
-```tsx
-const {
-  // Auth state
-  isReady,        // boolean - SDK initialized
-  isSignedIn,     // boolean - User authenticated
-  user,           // { id, email, ... } | null
-  
-  // Auth methods
-  signIn,         // () => void - Redirect to login
-  signOut,        // () => void - Clear session
-  signInWithCode, // (code, state?) => Promise - Manual OAuth
-  getSignInUrl,   // (redirectUri?) => string - Get OAuth URL
-  getToken,       // () => Promise<string> - Get access token
-  
-  // Database
-  db,             // Database instance
-  dbStatus,       // DBStatus - see below
-  dbMode,         // "sync" | "remote"
-
-  // Dev / schema snapshot (for custom tooling)
-  devInfo,              // BasicSchemaDevInfo | null — local vs remote schema status
-  refreshSchemaStatus,  // () => Promise<void> — re-fetch schema status from API
-} = useBasic()
+```typescript
+auth.hasScope("app:db:read"); // note: app:admin implies all app:db:* scopes
+auth.missingScopes();          // requested but not granted
 ```
 
-#### `DBStatus` (sync connection state)
+## Database
+
+`db.table(name)` returns the table API (name must exist in your schema):
 
-When `dbMode === "sync"`, `dbStatus` is one of:
+```typescript
+const todos = db.table("todos");
 
-| Value | Description |
-|-------|-------------|
-| `LOADING` | SDK initializing |
-| `OFFLINE` | Not connected |
-| `CONNECTING` | Connecting to sync server |
-| `ONLINE` | Connected and idle |
-| `SYNCING` | Syncing data |
-| `ERROR` | Sync error |
-| `ERROR_WILL_RETRY` | Sync error but client will retry (e.g. expired token). Use this to show "Reconnecting…" or trigger token refresh. |
+const created = await todos.create({ title: "buy milk" });
+// → { id: "0198…", title: "buy milk" } — id minted locally, works offline
 
-Import the enum for comparisons: `import { useBasic, DBStatus } from '@basictech/react'`.
+await todos.put(id, { title: "replace", completed: false });
+// create-or-replace the WHOLE record with these fields
 
----
+await todos.patch(id, { completed: true });
+// shallow-merge the given fields; returns null if the record doesn't exist
 
-### Development toolbar
+await todos.delete(id);   // idempotent — deleting a missing record is fine
 
-A small floating bar (similar in spirit to Next.js dev indicators) shows **auth**, **database mode**, **sync status**, and **schema vs server** health. It is **opt-in** and only appears in development: `localhost` / `127.0.0.1` / `.local`, `NODE_ENV === "development"`, or when `debug` is `true` on the provider or on the standalone component.
+await todos.get(id);      // record or null
+await todos.getAll();     // all records
+await todos.find((t) => !t.completed);
+```
+
+Semantics worth knowing:
+
+- **`put` replaces, `patch` merges.** Two devices patching *different* fields of the same record both win; patching the *same* field, the last write wins.
+- **`json` fields are atomic** — patching a `json` field replaces its whole value (no deep merge).
+- Writes are **validated locally** against your schema before queueing (same rules the server enforces), so typos fail fast with a thrown error instead of a round-trip.
+- In sync mode, `create` mints the id client-side — you get the full record back synchronously-ish, even offline.
 
-**Option A — provider flag**
+## Live queries
+
+`useQuery` re-runs your query and re-renders whenever the underlying data changes:
 
 ```tsx
-<BasicProvider schema={schema} devToolbar debug>
-  <App />
-</BasicProvider>
+const todos = useQuery(() => db.table("todos").getAll());               // undefined while loading
+const open  = useQuery(() => db.table("todos").find((t) => !t.completed));
+const one   = useQuery(() => db.table("todos").get(selectedId), [selectedId]); // deps like useEffect
 ```
 
-**Option B — place the component yourself** (must be under `BasicProvider`; respects the same visibility rules, or pass `debug` to force):
+For advanced queries, `table.ref` exposes the underlying [Dexie](https://dexie.org) table over the local view (sync mode only) — indexed fields from your schema are Dexie indexes:
 
 ```tsx
-import { BasicDevToolbar } from '@basictech/react'
+const recent = useQuery(() =>
+  db.table("todos").ref!.where("completed").equals(0).limit(10).toArray(),
+);
+```
 
-<BasicProvider schema={schema}>
-  <App />
-  <BasicDevToolbar />
-</BasicProvider>
+## Sync status, offline behavior & errors
+
+```tsx
+const sync = useSyncStatus();
+
+sync.status;        // 'idle' | 'connecting' | 'online' | 'offline' | 'auth_required' | 'revoked' | 'stopped'
+sync.enabled;       // false when the schema is invalid/unpublished
+sync.pendingCount;  // local writes not yet confirmed by the server
 ```
 
-The expanded panel includes **Refresh schema** (re-runs the remote schema check) and **Copy debug info** (JSON snapshot **without** raw access tokens). You can also read `devInfo` and call `refreshSchemaStatus()` from `useBasic()` for your own UI.
+**Offline is not an error.** Writes keep working and queue in IndexedDB; reads serve the local view; everything pushes on reconnect (safe to retry — ops are idempotent). The queue survives page reloads.
 
----
+`revoked` means the user disconnected your app from their account — data access is gone until they sign in and consent again.
 
-### `useQuery()`
+### Rejected ops
 
-Live query hook - automatically re-renders when data changes.
+If the server terminally rejects a write (schema validation, permissions, payload too large), the SDK **rolls the record back**, parks the op in a rejected store, and will never retry it:
 
 ```tsx
-import { useQuery } from '@basictech/react'
+const sync = useSyncStatus();
+const rejected = await sync.listRejected();
+// [{ op_id, op: { type, table, record_id, data }, error: 'SCHEMA_VALIDATION_FAILED', message, rejected_at }]
+await sync.clearRejected();
+```
 
-// Get all items
-const todos = useQuery(() => db.collection('todos').getAll())
+You can also listen live:
 
-// With type safety
-interface Todo {
-  id: string
-  title: string
-  completed: boolean
-}
-const todos = useQuery(() => db.collection<Todo>('todos').getAll())
+```typescript
+const { client } = useBasic();
+useEffect(() => client.engine?.on("rejected", ({ rejection }) => {
+  toast.error(`write rejected: ${rejection.error}`);
+}), [client]);
 ```
 
-> **Note:** Only works in `sync` mode. In `remote` mode, use manual fetching.
-
----
+## Shares (multiplayer)
 
-### Database Methods
+Users can grant other users access to a slice of their data — a whole table or specific records, read-only or read-write. Grants are created by the user on basic.id (apps can never share a user's data on their own); your app **lists** and **mounts** them:
 
-#### `db.collection(name)`
+```tsx
+function SharedTodos() {
+  const { received } = useShares();          // shares other users granted to me
+  const share = received[0];
+  const { db: sharedDb, status } = useShare(share?.id); // 'mounting' | 'mounted' | 'error' | 'revoked'
+  const todos = useQuery(() => sharedDb?.table("todos").getAll(), [sharedDb]);
 
-Access a collection by name.
+  if (!share) return <p>nothing shared with you yet</p>;
+  if (status !== "mounted") return <p>{status}…</p>;
 
-```tsx
-const { db } = useBasic()
-const todos = db.collection('todos')
+  return (
+    <ul>
+      {todos?.map((t) => (
+        <li key={t.id} onClick={() => sharedDb!.table("todos").patch(t.id, { completed: true })}>
+          {String(t.title)}
+        </li>
+      ))}
+    </ul>
+  );
+}
 ```
 
-#### Collection Methods
+Mounted shares live in their **own local keyspace** — separate replica, separate offline queue — and are never merged with the user's own data. Writes work when the share permission is `write` (the owner sees your changes attributed to the guest). When the owner revokes the share, the mount status flips to `revoked` and the local copy is purged.
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `getAll()` | `Promise<T[]>` | Get all records |
-| `get(id)` | `Promise<T \| null>` | Get one record by ID |
-| `add(data)` | `Promise<T>` | Create new record (returns with ID) |
-| `put(data)` | `Promise<T>` | Upsert record (requires ID) |
-| `update(id, data)` | `Promise<T \| null>` | Partial update |
-| `delete(id)` | `Promise<boolean>` | Delete record |
-| `filter(fn)` | `Promise<T[]>` | Filter with predicate |
+## Typed schemas
 
-#### Examples
+`@basictech/schema` (a dependency of this package) can infer record types from your schema:
 
-```tsx
-// Create
-const todo = await db.collection('todos').add({
-  title: 'Buy milk',
-  completed: false
-})
-console.log(todo.id) // Auto-generated ID
+```typescript
+import { defineSchema, type InferRecord } from "@basictech/schema";
 
-// Read
-const allTodos = await db.collection('todos').getAll()
-const oneTodo = await db.collection('todos').get('some-id')
+export const schema = defineSchema({
+  project_id: "…",
+  version: 1,
+  tables: {
+    todos: {
+      fields: {
+        title: { type: "string", required: true },
+        completed: { type: "boolean" },
+      },
+    },
+  },
+});
+
+type Todo = InferRecord<typeof schema, "todos">;
+// { id: string; title: string; completed?: boolean }
+
+const todos = db.table<Todo>("todos"); // fully typed CRUD
+```
 
-// Update
-await db.collection('todos').update('some-id', { completed: true })
+## REST mode
 
-// Delete
-await db.collection('todos').delete('some-id')
+Don't want a local replica? `mode="rest"` makes every table call a direct API request — no IndexedDB, no WebSocket, no offline support:
 
-// Filter
-const incomplete = await db.collection('todos').filter(t => !t.completed)
+```tsx
+<BasicProvider schema={schema} mode="rest">
 ```
 
----
+The table API is identical, with REST semantics: `create` gets its id from the server, `put`/`patch`/`delete` on missing records return null/no-op, reads hit the network. `useQuery` won't live-update in this mode (re-run queries with deps).
 
-## Advanced Usage
+## API reference
 
-### Manual OAuth Flow
+### `<BasicProvider>` props
 
-For custom OAuth handling (mobile apps, popups, etc.):
+| Prop | Default | Description |
+| --- | --- | --- |
+| `schema` | — | Your Basic schema document (`project_id` is read from it) |
+| `mode` | `"sync"` | `"sync"` (local replica) or `"rest"` (direct API) |
+| `auth.scopes` | `"profile,email,app:admin"` | OAuth scopes to request |
+| `auth.pds_url` | `https://pds.basic.id` | The Basic server (auth + data + sync) |
+| `auth.sync_url` | `wss://<pds>/sync/` | Sync WebSocket URL (rarely needed) |
+| `storage` | `localStorage` | Custom `BasicStorage` adapter for auth state |
+| `debug` | `false` | Verbose console logging |
+| `devToolbar` | `false` | Floating status toolbar (dev environments only) |
+| `renderWhileLoading` | `false` | Render children before auth bootstrap finishes |
 
-```tsx
-const { signInWithCode, getSignInUrl } = useBasic()
+### Hooks
 
-// Get OAuth URL with custom redirect
-const url = getSignInUrl('myapp://callback')
+| Hook | Returns |
+| --- | --- |
+| `useBasic()` | Everything: auth fields + actions, `db`, `sync`, `devInfo`, `client` |
+| `useAuth()` | `{ isReady, isSignedIn, status, user, did, scope, hasScope, missingScopes, signIn, signInWithHandle, signInWithCode, signOut, getToken, getSignInUrl }` |
+| `useDb()` | The table API for the user's own data |
+| `useQuery(fn, deps?)` | Live query result (`undefined` while loading) |
+| `useSyncStatus()` | `{ status, enabled, pendingCount, listRejected, clearRejected }` |
+| `useShares()` | `{ granted, received, isLoading, error, refresh }` |
+| `useShare(shareId)` | `{ db, status, error }` — a mounted share |
 
-// Exchange code for session
-const result = await signInWithCode(code, state)
-if (result.success) {
-  console.log('Signed in!')
-}
-```
+### Table API
 
-### Remote Mode
+| Method | Sync mode | REST mode |
+| --- | --- | --- |
+| `create(data)` | client-minted id, offline-capable | server-minted id |
+| `put(id, data)` | create **or replace** | replace; throws if missing |
+| `patch(id, partial)` | merge; `null` if missing locally | merge; `null` if missing |
+| `delete(id)` | idempotent | no-op if missing |
+| `get(id)` / `getAll()` / `find(fn)` | local view | network |
+| `ref` | Dexie table (live queries, indexes) | `undefined` |
 
-For server-rendered apps or when you don't need offline support:
+## Advanced usage
 
-```tsx
-<BasicProvider schema={schema} dbMode="remote">
-  <App />
-</BasicProvider>
+### Outside React
+
+Everything is available without React — `BasicClient` is the framework-agnostic core (`AuthManager` + `SyncEngine` + `RestClient`):
+
+```typescript
+import { createBasicClient } from "@basictech/react";
+
+const client = createBasicClient({ schema, debug: true });
+await client.start();
+client.subscribe(() => console.log(client.getSnapshot()));
+await client.db.table("todos").create({ title: "from anywhere" });
 ```
 
-In remote mode:
-- Data is fetched via REST API
-- No IndexedDB storage
-- `useQuery` won't auto-update (use manual refresh)
-- Requires authentication for all operations
+The Sync/2 protocol layer (`SyncEngine`, `SyncConnection`, `SyncStore`, and all wire types) is exported too, for building custom clients or other runtimes — pass a `WebSocketImpl` (e.g. the `ws` package) to run in Node.
 
-### Error Handling
+### Events
 
-```tsx
-import { NotAuthenticatedError } from '@basictech/react'
-
-try {
-  await db.collection('todos').add({ title: 'Test' })
-} catch (error) {
-  if (error instanceof NotAuthenticatedError) {
-    // User needs to sign in
-    signIn()
-  }
-}
+```typescript
+const { client } = useBasic();
+client.engine?.on("status", (s) => {});                       // sync status changes
+client.engine?.on("change", ({ sub, tables }) => {});         // records changed
+client.engine?.on("rejected", ({ sub, rejection }) => {});    // terminal write rejection
+client.engine?.on("revoked", ({ code }) => {});               // app connection revoked
 ```
 
----
+### Custom storage
 
-## TypeScript
+Auth state lives in `localStorage` by default. Provide any `{ get, set, remove }` async adapter via the `storage` prop (see `BasicStorage`). `STORAGE_KEYS` lists every key the SDK uses.
 
-Full TypeScript support with generics:
+## Migrating from 0.8
 
-```tsx
-interface Todo {
-  id: string
-  title: string
-  completed: boolean
-  createdAt: number
-}
+0.9 is a breaking rewrite — the server's legacy sync endpoint was removed, so 0.8 sync no longer functions. Changes you'll make:
 
-// Type-safe collection
-const todos = db.collection<Todo>('todos')
+| 0.8 | 0.9 |
+| --- | --- |
+| `db.collection("todos")` | `db.table("todos")` |
+| `.add(data)` | `.create(data)` |
+| `.update(id, partial)` | `.patch(id, partial)` |
+| `.put({ id, ...fields })` | `.put(id, fields)` |
+| `dbStatus` / `DBStatus` enum | `useSyncStatus().status` |
+| `dbMode="remote"` | `mode="rest"` |
+| `auth.ws_url` | `auth.sync_url` (you almost never need it) |
+| `signOut()` reloads the page | in-place teardown, no reload |
 
-// All methods are typed
-const todo = await todos.add({
-  title: 'Test',
-  completed: false,
-  createdAt: Date.now()
-})
-// todo is typed as Todo
-```
+Local data migrates by re-bootstrap: the old `basicdb` IndexedDB database is deleted automatically and 0.9 builds fresh replicas in `basic-sync:<project_id>` databases from the server (the server is the source of truth, so nothing is lost).
 
 ---