@nkzw/fate-indexeddb 2.0.0 → 2.1.0

package/README.md

@@ -759,6 +759,29 @@ fate.hydrate(loaderData.fate, { merge: 'replace' });
 
 Snapshots from different hydration scopes cannot be combined. Keep each user's server client and snapshot separate.
 
+#### Selective Hydration in React
+
+If your server-rendered app uses Suspense boundaries that can hydrate at different times, pass the original snapshot to the React provider as well:
+
+```tsx
+const state = loaderData.fate;
+const fate = createFateClient();
+fate.hydrate(state);
+
+hydrateRoot(
+  document,
+  <FateClient client={fate} hydrationState={state}>
+    <App />
+  </FateClient>,
+);
+```
+
+If the live cache changes before a boundary hydrates, that boundary first reads the original snapshot to match its server HTML. Once it hydrates, it reads the live cache and applies any changes. Request policies that fetch from the network resume after the component hydrates.
+
+Keep the same snapshot on the provider for the lifetime of the hydrated tree. The provider retains a separate copy of the server cache so delayed boundaries can still read it. This works with preloaded SSR data that covers the rendered content.
+
+The snapshot applies to the React request and view hooks. If you pass an explicit client to a view hook, an enclosing provider for that client supplies its snapshot. Direct reads from the client or its store still read the live cache.
+
 ### Observing Request State
 
 Outside React or Vue components, `fate.observeRequest(request, options)` provides request state through `getSnapshot()` and `subscribe(listener)`:
@@ -2153,6 +2176,122 @@ Use Vue refs or your application state library to track pending and error state.
 
 Views, requests, caching, and mutations work the same way in both adapters. Vue composables return reactive resources; await `ready()` to use Suspense, or read their pending and error state. For mutations, use `fate.mutations` and Vue refs for local state instead of React Actions.
 
+## Devtools
+
+_fate_ comes with devtools that show what your client is doing while you build your app. They run as a panel in [Vite DevTools](https://devtools.vite.dev/), next to the other tools for your app.
+
+<p align="center">
+  <img alt="The fate devtools panel in Vite DevTools" src="/public/devtools.png#gh-light-mode-only" width="100%">
+  <img alt="The fate devtools panel in Vite DevTools" src="/public/devtools-dark.png#gh-dark-mode-only" width="100%">
+</p>
+
+The panel shows:
+
+- **Cache:** every normalized record, grouped by type. For each record you can see the fields fate has loaded, which fields are stale, which lists contain it, and which records refer to it. Click a reference to jump to that record.
+- **Requests:** the requests your screens keep alive, their roots and arguments, the fields they select, and how many components are observing them.
+- **Network:** every call fate makes through its transport (`byId`, `list`, `query`, mutations, and live subscriptions), with timing, selections, arguments, and responses or errors.
+- **Lists:** connection and list state, including items, cursors, and pagination.
+- **Changes:** a log of cache writes, including invalidations and optimistic updates.
+
+From the panel you can invalidate or remove a record, log a record to the browser console (as `$fate`), and run garbage collection.
+
+### Installation
+
+Install the devtools and Vite DevTools as development dependencies of your client:
+
+::: code-group
+
+```bash [npm]
+npm add -D @nkzw/fate-devtools @vitejs/devtools
+```
+
+```bash [pnpm]
+pnpm add -D @nkzw/fate-devtools @vitejs/devtools
+```
+
+```bash [yarn]
+yarn add -D @nkzw/fate-devtools @vitejs/devtools
+```
+
+:::
+
+### Vite Plugin
+
+Enable Vite DevTools and add the devtools plugin to your Vite config:
+
+```ts
+import { fateDevtools } from '@nkzw/fate-devtools/vite';
+import { fate } from 'react-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  devtools: true,
+  plugins: [
+    fate({
+      module: '@your-org/server/trpc/router.ts',
+    }),
+    fateDevtools(),
+  ],
+});
+```
+
+The plugin only runs during development. It adds a _fate_ entry to the Vite DevTools dock and serves the panel at `/__fate-devtools/`. You can also open that URL in its own tab, which is handy when you don't use Vite DevTools or want the panel on a second screen.
+
+### Connecting a Client
+
+With React, render `<FateDevtools />` inside your `<FateClient>`. It connects the client from context and renders nothing:
+
+```tsx
+import { FateDevtools } from '@nkzw/fate-devtools/react';
+import { FateClient } from 'react-fate';
+
+export function App() {
+  return (
+    <FateClient client={fate}>
+      {import.meta.env.DEV && <FateDevtools />}
+      <Root />
+    </FateClient>
+  );
+}
+```
+
+For Vue or other setups, call `connectFateDevtools` with your client. It returns a function that disconnects the client again:
+
+```ts
+import { connectFateDevtools } from '@nkzw/fate-devtools';
+
+if (import.meta.env.DEV) {
+  connectFateDevtools(fate);
+}
+```
+
+Guard the devtools with `import.meta.env.DEV` so they are not included in production builds. If your app creates more than one client, pass a `name` to tell them apart in the panel:
+
+```tsx
+<FateDevtools name="admin" />
+```
+
+### Server-Rendered Apps
+
+Vite DevTools adds its dock to pages through Vite's HTML transform. Frameworks that render HTML on the server, such as [Void](/docs/integrations/void.md), don't run that transform, so load the dock yourself in development:
+
+```ts
+if (import.meta.env.DEV && typeof document !== 'undefined') {
+  const script = document.createElement('script');
+  script.type = 'module';
+  script.src = '/__devtools/embedded.js';
+  document.head.append(script);
+}
+```
+
+The first time you open Vite DevTools in a browser, it asks you to authorize that browser with a code printed in your terminal.
+
+### How It Works
+
+The devtools don't change how _fate_ behaves. When you connect a client, the devtools wrap its transport to record network activity and listen to cache changes. The page then sends snapshots to the panel over a [`BroadcastChannel`](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel). Snapshots are only sent while a panel is open. When you disconnect, the client's original transport is restored.
+
+Because the panel and your app talk over a `BroadcastChannel`, the panel works anywhere on the same origin: in the Vite DevTools dock, in a separate tab, or in a popup. When more than one page or client is connected, use the picker in the panel's toolbar to switch between them.
+
 ## GraphQL Integration
 
 If your backend already exposes GraphQL, you can use it with fate. Define views and call requests and mutations as usual; fate builds the GraphQL operations for you.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/fate-indexeddb",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Optional IndexedDB persistence adapter for fate.",
   "license": "MIT",
   "files": [
@@ -19,12 +19,12 @@
     "idb": "^8.0.4"
   },
   "devDependencies": {
-    "@nkzw/fate": "2.0.0",
+    "@nkzw/fate": "2.1.0",
     "fake-indexeddb": "^6.2.8",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.6.0",
     "vite-plus": "1.6.0"
   },
   "peerDependencies": {
-    "@nkzw/fate": "^1.5.1"
+    "@nkzw/fate": "^2.0.0"
   }
 }