@nkzw/fate-indexeddb 1.16.1 → 2.0.1

package/README.md

@@ -1629,6 +1629,31 @@ Mutations are delivered in the order they were saved, one at a time per persiste
 
 The mutation promise stays pending until confirmation, which can take until the user is back online. After a reload, use [Persistence State](#persistence-state) to show pending or failed changes.
 
+We can add client fields or change computations without invalidating saved server mutations. Their recovery data contains server fields; saved client fields use [migrations](/docs/guide/client-state.md#migrations). If the server schema scope changes or a mutation is removed, fate keeps the mutation's input and marks it as failed.
+
+#### Waiting for Local Persistence
+
+Let's say we want to close our post editor once the change is saved on the device, even while offline. Each mutation promise has a `locallyPersisted` promise that we can wait for:
+
+```tsx
+const pending = fate.mutations.post.edit({
+  input: { id: post.id, title },
+  optimistic: { title },
+});
+
+void reportResult(pending);
+await pending.locallyPersisted;
+closeEditor();
+```
+
+Our editor closes after fate saves the mutation and the data needed to restore it after a reload. If the mutation is still waiting to be sent, it is also available in the [persistence state](#persistence-state) at this point. Awaiting `pending` waits for the server response instead.
+
+The server can still reject the change after it was saved locally. Replace `reportResult` with your app's handler for the eventual result, including returned errors and rejected promises. A later rejection doesn't change the resolved `locallyPersisted` promise.
+
+For [client mutations](/docs/guide/client-state.md#reading-and-updating-state), `locallyPersisted` waits for the client data to be saved. The same property is available when calling `fate.actions` directly, including actions bound with `.with()`.
+
+If validation or storage fails, `locallyPersisted` rejects, so our editor can stay open and show the error. It also rejects if the mutation isn't saved: when using `persist: false`, without persistence configured, or for a server mutation without durable delivery. Each mutation is saved separately; waiting for one save doesn't combine it with a later mutation.
+
 #### Skipping Persistence
 
 For a call that should not be saved or retried, pass `persist: false`:
@@ -1683,7 +1708,35 @@ const server = createFateServer({
 
 Your app supplies the database and receipt helpers. Lock each `(scope, id)` across server processes, and use `ctx.db` for mutation writes so they share the receipt's transaction. See the [complete SQLite example](https://github.com/nkzw-tech/fate/blob/main/example/persistence/server.ts).
 
-Keep receipts for as long as an offline client might retry. For effects outside the database, such as payments or emails, use the destination's idempotency support and a transactional outbox.
+Keep receipts for as long as an offline client might retry. For mutations with an expiry, we can clean up their receipts as described in [Receipt Retention](#receipt-retention). For effects outside the database, such as payments or emails, use the destination's idempotency support and a transactional outbox.
+
+### Receipt Retention
+
+Let's say a user likes a post, but closes the app before receiving the server response. When they return, fate retries the mutation with the same ID. The server reads its saved receipt and returns the result without adding another like.
+
+By default, a queued mutation expires after **30 days**, including time spent offline. We can change this with `mutationMaxAge` on `createPersistence`. The server's `createMutationIdempotency` also defaults to 30 days through its `maxAge` option. To allow a longer lifetime, configure both sides.
+
+The mutation ID includes its creation time and expiry. Retries and page reloads keep the same ID, so changing the configuration only affects new mutations. The server rejects mutations from a client clock more than five minutes ahead. A clock that is behind gives the mutation less time to reach the server.
+
+#### Cleaning Up Receipts
+
+Save the receipt's optional `expiresAt` timestamp with its result. We can delete expired receipts once every server handling these mutations enforces expiry. Allow some extra time for differences between server clocks. For example, a daily job could delete receipts that expired more than a day ago.
+
+This is why mutations have a fixed deadline. If we deleted a receipt while its mutation could still be retried, the server would have no way to know that it had already applied the change. Rejecting expired mutations lets us clean up receipts without applying the same mutation again.
+
+Native HTTP delivery uses protocol version 3 for expiring mutations. Older native servers reject these requests before executing them. Custom durable transports must also enforce expiry and preserve the `MUTATION_EXPIRED` error (HTTP 410).
+
+#### Handling Expired Mutations
+
+When a mutation expires, the server returns `MUTATION_EXPIRED`, even if its receipt has already been deleted. fate rolls back the optimistic update and keeps the input in persistence with `status: 'failed'` and `failureReason: 'expired'`.
+
+For our like button, the server may have applied the like before the user closed the app. We should refresh the post before deciding whether to offer another attempt. fate doesn't assign a new ID or retry the expired mutation automatically. After handling the failure, call `session.discard(id)` to remove it from the queue.
+
+When the receipt and database changes share a transaction, the server applies each mutation ID at most once within its lifetime. A mutation can still expire before reaching the server. Effects outside that transaction need their own idempotency support.
+
+#### Existing Receipts
+
+Older mutation IDs have no expiry. `createMutationIdempotency` accepts them by default, so their receipts need to stay saved. After retiring older clients, set `allowLegacyIdentities: false` to reject these mutations with the same expiry error. Once all server instances use that setting, their receipts can be deleted too.
 
 ### tRPC, GraphQL, and Custom Transports
 
@@ -1718,7 +1771,11 @@ return idempotency.execute({
 
 Forward the entire identity on every attempt. When `identity.replayOnly` is true, the endpoint must return the saved result or a 404 without running the mutation. `createMutationIdempotency` handles this for you.
 
-For a GraphQL adapter that supports only some mutations, pass `durableMutations: ['setLocale', 'updateSettings']` alongside `mutateDurably`. Other mutations send immediately. Explicit `persist: true` fails for an unsupported mutation, and previously queued calls remain saved if the adapter stops supporting them. Omitting the list means the adapter supports every mutation.
+We can also send saved mutations through an existing GraphQL route. Set `durableMutations` to the supported mutation names without passing a custom `mutateDurably` adapter. fate sends each listed mutation separately, adding `@fateDurable` to the operation and its identity to `extensions.fateMutation`.
+
+Set up the server before enabling this option. Declare `directive @fateDurable on MUTATION`, then wrap the single mutation with `createMutationIdempotency` in your execution middleware. For requests with `identity.replayOnly`, return the saved GraphQL result or a 404 without running the mutation. A server without the directive rejects the operation during GraphQL validation.
+
+For a custom GraphQL adapter that supports only some mutations, pass `durableMutations: ['setLocale', 'updateSettings']` alongside `mutateDurably`. Other mutations send immediately. Explicit `persist: true` fails for an unsupported mutation, and previously queued calls remain saved if the adapter stops supporting them. Omitting the list means the adapter supports every mutation.
 
 You can use persistence for cached reads and client state before adding a durable mutation adapter. Server mutations send immediately by default in that setup. Pass `persist: true` when a call must be saved before delivery. It fails before sending if persistence or the adapter is missing.
 
@@ -2096,6 +2153,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.
@@ -3119,13 +3292,13 @@ For Prisma, pass Prisma query options such as `{ where: { ... } }` in `extra` in
 
 ### Data View Resolvers
 
-Data views can define computed fields with their own data dependencies. Let's say we want to show a user's email only to that user, and include a comment count on each post. We can define both fields with `computed`:
+Data views can define computed fields with their own data dependencies. Let's say we want to show a user's email only to that user, and include a comment count on each post. We can define both fields with `memo`:
 
 ```tsx
-import { computed, count } from '@nkzw/fate/server';
+import { memo, count } from '@nkzw/fate/server';
 
 export const userDataView = dataView<UserItem>('User')({
-  email: computed({
+  email: memo({
     authorize: ({ id }, context?: AppContext) => context?.sessionUser?.id === id,
     select: {
       email: true,
@@ -3136,7 +3309,7 @@ export const userDataView = dataView<UserItem>('User')({
 });
 
 export const postDataView = dataView<PostItem>('Post')({
-  commentCount: computed({
+  commentCount: memo({
     select: {
       count: count('comments'),
     },
@@ -3148,7 +3321,7 @@ export const postDataView = dataView<PostItem>('Post')({
 
 The `select` object describes what each resolver needs. `email: true` selects the user's stored email, and `count('comments')` asks the adapter to count the post's comments. The resolver receives those values in its second argument. Annotating the first argument with `UserItem` or `PostItem` lets TypeScript infer the dependency types.
 
-Use `field('path')` to give a dependency a different name or read through a relationship. The adapters fetch the dependencies for you, while the client only receives the computed field's result. The same `dataView` and `computed` helpers are available for [client computed fields](/docs/guide/client-state.md#computed-fields).
+Use `field('path')` to give a dependency a different name or read through a relationship. The adapters fetch the dependencies for you, while the client only receives the computed field's result. The same `dataView` and `memo` helpers are available for [client computed fields](/docs/guide/client-state.md#computed-fields).
 
 ### Connecting the Client
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/fate-indexeddb",
-  "version": "1.16.1",
+  "version": "2.0.1",
   "description": "Optional IndexedDB persistence adapter for fate.",
   "license": "MIT",
   "files": [
@@ -19,12 +19,12 @@
     "idb": "^8.0.4"
   },
   "devDependencies": {
-    "@nkzw/fate": "1.16.1",
-    "fake-indexeddb": "^6.2.7",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.5.0",
-    "vite-plus": "1.5.0"
+    "@nkzw/fate": "2.0.1",
+    "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"
   }
 }