@nkzw/fate-indexeddb 1.16.1 → 2.0.0

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.
 
@@ -3119,13 +3176,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 +3193,7 @@ export const userDataView = dataView<UserItem>('User')({
 });
 
 export const postDataView = dataView<PostItem>('Post')({
-  commentCount: computed({
+  commentCount: memo({
     select: {
       count: count('comments'),
     },
@@ -3148,7 +3205,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.0",
   "description": "Optional IndexedDB persistence adapter for fate.",
   "license": "MIT",
   "files": [
@@ -19,10 +19,10 @@
     "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.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"