@nkzw/fate-indexeddb 1.14.0 → 1.15.0

package/README.md

@@ -380,6 +380,8 @@ Vue provides the same API as a reactive resource. See [Resolving Arrays of Refs
 
 We learned that `useRequest` is responsible for fetching data from the server and `useView` is used for reading data from the cache. In some situations data may not be available in the cache and `useView` might need to suspend the component to fetch only the missing data. Once that data is fetched and written to the cache, the component resumes rendering.
 
+Let's say `PostCard` needs a post's `title` while a request for the same post's `title` and `content` is already in flight. fate can share a request by ID when it selects all the missing scalar fields with the same arguments. `PostCard` waits for that request, then fetches any fields it still needs.
+
 _Tip: You can test this behavior in development mode with Fast Refresh (HMR) enabled in your bundler. When you edit the selection of a view, components using that view will suspend, fetch the missing data, and then resume rendering._
 
 ### Type Safety and Data Masking
@@ -600,7 +602,7 @@ Lists with different filters or sorting arguments stay separate. Loading another
 
 `useRequest` supports different request modes to control caching and data freshness. The available modes are:
 
-- `cache-first` (_default_): Returns data from the cache if available, otherwise fetches from the network.
+- `cache-first` (_default_): Returns data from the cache when available and fresh. Fetches missing data and data marked stale by [list invalidation](/docs/guide/actions.md#invalidating-lists) or [record invalidation](/docs/guide/actions.md#invalidating-records).
 - `stale-while-revalidate`: Returns data from the cache and simultaneously fetches fresh data from the network.
 - `network-only`: Always fetches data from the network, bypassing the cache.
 - `cache-only` (React): Observes cached data without fetching or suspending. Returns `undefined` when the selection is missing.
@@ -618,6 +620,8 @@ const { posts } = useRequest(
 );
 ```
 
+When another component mounts with the same `network-only` or `stale-while-revalidate` request, it shares a request that's still in flight or starts a fresh one.
+
 For screens that also work offline, switch the same hook to `cache-only`:
 
 ```tsx
@@ -628,7 +632,7 @@ const result = useRequest(
 const viewer = useView(ViewerView, result?.viewer);
 ```
 
-Cache-only results stay subscribed to cache changes. Their references never fetch missing view fields. Switching offline bypasses a pending Suspense gate immediately, so the component can keep its local state and render its offline UI. The existing network modes keep their required result type; modes that can be `cache-only` return an optional result.
+Cache-only results stay subscribed to cache changes. Their refs read selected fields, including deferred fields, from the cache. Switching offline bypasses a pending Suspense gate immediately, so the component can keep its local state and render its offline UI. The existing network modes keep their required result type; modes that can be `cache-only` return an optional result.
 
 ### Refreshing Requests
 
@@ -771,13 +775,13 @@ The snapshot contains `data`, `error`, `isFetching`, `status`, and `refetch`. Da
 
 Reading a snapshot does not start a request. The first subscription starts an enabled request and retains its data; the last unsubscribe releases it. Use `enabled: false` to disable fetching, or `mode: 'cache-only'` to observe cached data without fetching missing fields. The possible statuses are:
 
-| Status     | Meaning                                            |
-| ---------- | -------------------------------------------------- |
-| `disabled` | The request is not enabled.                        |
-| `missing`  | A cache-only request needs data that isn't cached. |
-| `pending`  | The initial request is loading.                    |
-| `ready`    | Data is available.                                 |
-| `error`    | The initial request failed.                        |
+| Status     | Meaning                                                          |
+| ---------- | ---------------------------------------------------------------- |
+| `disabled` | The request is not enabled.                                      |
+| `missing`  | Data is missing after a cache-only read or a successful request. |
+| `pending`  | The initial request is loading.                                  |
+| `ready`    | Data is available.                                               |
+| `error`    | The initial request failed.                                      |
 
 `observer.getSnapshot().refetch()` returns a promise and requires an enabled request that isn't cache-only. Handle its rejected promise in the calling code.
 
@@ -1347,7 +1351,7 @@ const result = await fate.mutations.comment.add({
 });
 ```
 
-The options are the same as for Actions, including `optimistic`, `insert`, and `view`. The call returns a promise; handle pending state and errors in the calling code.
+The options are the same as for Actions, including `optimistic`, `insert`, `remove`, `invalidate`, and `view`. The call returns a promise. Handle pending state and errors in the calling code.
 
 ### Mutation Server Implementation
 
@@ -1453,6 +1457,63 @@ Insertions work with pagination, optimistic updates, and [offline mutations](/do
 
 Earlier versions appended mutation results automatically. Add an `insert` option to calls that relied on that behavior. The strings `'before'` and `'after'` still enable automatic list matching, but prefer an explicit target. `'none'` is now the default.
 
+### Removing Items from Lists
+
+Let's say we want to move a post from the inbox to an archive. Pass the inbox list as `remove.from` and the post's view ref as `remove.node`. Use `insert` in the same call to add the post to the archive.
+
+```tsx
+await fate.mutations.post.archive({
+  input: { id: postRef.id },
+  optimistic: { archived: true },
+  remove: { from: inbox, node: postRef },
+  insert: { into: archivedPosts, position: 'before' },
+});
+```
+
+The post disappears from the inbox immediately. If the mutation fails, fate rolls back both list changes. The post itself stays in the cache. Pass an array of removal objects to remove more than one item or update several lists.
+
+```tsx
+await fate.mutations.post.archive({
+  input: { id: postRef.id },
+  remove: [
+    { from: inbox, node: postRef },
+    { from: starredPosts, node: postRef },
+  ],
+});
+```
+
+Use the original array, connection, or deferred list returned by the same client. A deferred list still loads when a component reads it. If it loads while the mutation is pending, fate applies the removal to the loaded items. Removals also work with [offline mutations](/docs/guide/persistence.md).
+
+If archiving the post changes which items the server would return on the first page, add the list to [`invalidate`](#invalidating-lists).
+
+### Invalidating Lists
+
+Archiving a post might bring the next post into the first page of the inbox. Pass the inbox list to `invalidate` to fetch the updated page on the next request.
+
+```tsx
+await fate.mutations.post.archive({
+  input: { id: postRef.id },
+  invalidate: [inbox],
+});
+```
+
+Use the original array or connection returned by the same client. When the mutation succeeds, fate marks the list stale and keeps its current items visible. The next `cache-first` request fetches the list again. Lists with other filters keep their cached results. To refresh the list immediately, use [`useRefetch`](/docs/guide/requests.md#refreshing-requests).
+
+Refreshing the first page replaces the previously loaded pages. You can load more pages from the refreshed list.
+
+### Invalidating Records
+
+Let's add a comment to a post. If the mutation doesn't return the post's updated comment count, pass the post's view ref to `invalidate`.
+
+```tsx
+await fate.mutations.comment.add({
+  input: { content, postId: postRef.id },
+  invalidate: [postRef],
+});
+```
+
+When the mutation succeeds, fate marks the post's cached fields stale. A `cache-first` request refreshes the fields it selects. If it selects only the title, the comment count stays stale until a request selects it. You can pass both view refs and lists to `invalidate` in the same call.
+
 ## Persistence
 
 fate can keep data across page reloads and save mutations while a user is offline. When they come back, their views can show previously loaded data and their pending changes continue where they left off.
@@ -2019,7 +2080,7 @@ const like = async () => {
 
 Expected mutation errors are returned in `result.error`; unexpected failures reject the promise. See [Action & Mutation Error Handling](/docs/guide/actions.md#action--mutation-error-handling).
 
-The mutation call shape is the same as `react-fate`: `input`, `optimistic`, `insert`, and `view` work the same way. Vue does not have React Actions or `useActionState`, so Vue components should model pending and error state with Vue refs or your application state library.
+Use Vue refs or your application state library to track pending and error state. The mutation options work the same way in both frameworks, including `optimistic`, `insert`, `remove`, `invalidate`, and `view`. See [Mutations](/docs/guide/actions.md#mutations).
 
 ### API Differences from React
 
@@ -2052,7 +2113,7 @@ The GraphQL transport expects a schema with Relay-style object identity and pagi
 - Entity objects include `id` and `__typename`.
 - Object fetches use `nodes(ids:)` by default, or configured per-type query fields.
 - List fields return Relay connections with `edges`, `cursor`, `node`, and `pageInfo`.
-- Root queries and mutations return the entity type selected by the fate view.
+- Root queries and mutations that use a fate view return objects of the selected type.
 
 For example, a `Post` list can be exposed as a normal GraphQL connection:
 
@@ -2155,6 +2216,40 @@ Custom scalars default to `unknown`. Set `fateGraphQL.scalars` to describe their
 
 Use `import type` for generated types. After updating the schema, run `fate generate` to refresh them.
 
+### Views on Unions and Interfaces
+
+Let's say our `search` connection returns a `SearchResult` union of `Post` and `User`. We can compose `PostView` and `UserView` into a single view using `viewFor`.
+
+```tsx
+import { viewFor, useRequest, view } from 'react-fate';
+import type { GraphQLEntities } from '../../.fate/client.generated.ts';
+import { PostCard, PostView } from './PostCard.tsx';
+import { UserCard, UserView } from './UserCard.tsx';
+
+const SearchResultView = view<GraphQLEntities['SearchResult']>()({
+  ...viewFor('Post', PostView),
+  ...viewFor('User', UserView),
+});
+
+export function Search({ query }: { query: string }) {
+  const { search } = useRequest({ search: { args: { query }, list: SearchResultView } });
+
+  return search.map((result) => {
+    const key = `${result.__typename}:${result.id}`;
+
+    switch (result.__typename) {
+      case 'Post':
+        return <PostCard key={key} post={result} />;
+      case 'User':
+        return <UserCard key={key} user={result} />;
+    }
+    return null;
+  });
+}
+```
+
+fate fetches the fields from `PostView` for posts and from `UserView` for users. Checking `__typename` gives each card a ref of the right type to resolve with `useView`. The same composition works for interfaces. Each concrete type needs an `id` so fate can identify its objects in the cache.
+
 ### Creating a Client
 
 Create the client with your GraphQL endpoint and provide it through the `FateClient` provider:
@@ -2344,6 +2439,16 @@ const { posts } = useRequest({
 
 This produces a root `posts(first: 10)` field and a nested `comments(first: 3)` field in the generated GraphQL selection.
 
+#### Requesting Scalars
+
+Let's say the schema defines `today: Date!` with a custom `Date` scalar. Add `today: { embedded: true, type: 'Date' }` to `fateGraphQL.roots`, then use `value: true` to request it.
+
+```tsx
+const { today } = useRequest({ today: { value: true } });
+```
+
+fate returns the value as sent by the server. This also applies to custom scalars that contain objects or arrays, such as `JSON`.
+
 ### Mutations
 
 Map fate mutation names to GraphQL mutation fields:
@@ -2428,6 +2533,8 @@ const fate = createFateClient({
 
 Your server must implement these subscription fields. See the [GraphQL subscription example](https://github.com/nkzw-tech/fate/blob/main/example/server-graphql/src/graphql/live.tsx) for their event shapes and resolvers. For servers without these subscriptions, set `live: false`.
 
+For a list with several entity types, fate subscribes to membership events with an empty `select`. Return an event with `type: 'invalidate'` when membership changes. fate reruns the list query with the original arguments and view selection.
+
 ### Existing Servers
 
 Your GraphQL server continues to handle authorization, validation, pagination, and mutation side effects. You don't need fate's server or ORM adapters.
@@ -2586,7 +2693,7 @@ export const Root = {
 };
 ```
 
-Entries that wrap their view in `list(...)` are treated as list resolvers. In the native protocol, the root key is the operation name used by the client. In the tRPC adapter, `procedure` can point that root at a specific router procedure. If you omit `list(...)`, fate treats the entry as a standard query.
+Use `list(...)` for a list resolver and a plain data view for a standard query. In the native protocol, the root key is the operation name used by the client. In the tRPC adapter, `procedure` can point that root at a specific router procedure.
 
 Each `list(...)` can have its own ordering. For example, the feed can show newest posts first while comments use oldest first. Without `orderBy`, fate sorts by `id asc`. It also adds `id asc` as a tie-breaker when your ordering doesn't include `id`. Use an array when ordering by several fields.
 
@@ -2609,6 +2716,38 @@ const { posts, categories, viewer } = useRequest({
 });
 ```
 
+#### Lists with Several Types
+
+Let's add a `search` list that returns both posts and users. Pass a data view for each type to `list`, along with a query that finds the results for each page. The data view keys match the type names, and each view selects `id`. The `typeName` gives the combined type its own name in the generated client.
+
+Mixed-list membership grants access through the list query. Register an authorized standalone read for members that need direct by-ID lookups, including deferred reads.
+
+```tsx
+import { list } from '@nkzw/fate/server';
+
+export const Root = {
+  search: list(
+    { Post: postDataView, User: userDataView },
+    {
+      query: querySearch,
+      typeName: 'SearchResult',
+    },
+  ),
+};
+```
+
+Your `querySearch` function receives `args`, `ctx`, `cursor`, `direction`, and `take`. Return up to `take` entries in display order, starting after the cursor for forward pagination or ending before it for backward pagination. Each entry has a `__typename`, a string `id`, and a unique nonempty string `cursor`. Include each `(__typename, id)` pair once across the results. `take` includes one extra entry so fate can tell whether there's another page. fate fetches the selected fields in batches for each type and applies the permissions from its data view.
+
+For native HTTP, pass `Root` to `createFateServer`. For tRPC, use `fate.procedures` and register the router as `searchResult` in `appRouter`.
+
+```tsx
+const searchResultRouter = router(fate.procedures({ view: Root.search }));
+```
+
+To use a different router name, set `router` on the entry in `Root`, for example `search: { router: 'search', view: searchList }`. On the client, use [`viewFor` to compose the views](/docs/integrations/graphql.md#views-on-unions-and-interfaces) for the search results.
+
+Live membership events refresh mixed lists through the same scoped query. This applies the subscriber’s access rules and reloads the fields selected by each view.
+
 ### Native fate protocol
 
 Create a source adapter for your ORM, pass it to `createFateServer`, and add a route for the HTTP handler:
@@ -3248,13 +3387,13 @@ Your app can publish live updates through the normal fate live bus:
 
 ```tsx
 live.update('Post', postId, { changed: ['likes'] });
-live.connection('Post.comments', { id: postId }).appendNode('Comment', commentId, {
-  node: comment,
-});
+live.connection('Post.comments', { id: postId }).appendNode('Comment', commentId);
 ```
 
 Pass `changed` to refresh only those fields, or omit it to refresh the whole selected view.
 
+Void sends IDs and change metadata with live events. Each subscriber fetches the selected fields using its own credentials.
+
 ### Routes
 
 Define a live stream once in a server-only module:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/fate-indexeddb",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Optional IndexedDB persistence adapter for fate.",
   "license": "MIT",
   "files": [
@@ -19,7 +19,7 @@
     "idb": "^8.0.4"
   },
   "devDependencies": {
-    "@nkzw/fate": "1.14.0",
+    "@nkzw/fate": "1.15.0",
     "fake-indexeddb": "^6.2.7",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.5.0",
     "vite-plus": "1.5.0"