@nkzw/fate-indexeddb 1.14.1 → 1.16.0

package/README.md

@@ -69,7 +69,9 @@ vp create fate
 
 Explore the [fate stack](https://fate.technology/#stack) to see the tools included in your new project.
 
-Choose a backend in the template selector: Void, tRPC with Drizzle or Prisma, GraphQL with Prisma, or a client for an existing GraphQL server. React is the default; choose Vue in the selector or pass `--framework vue`.
+Choose a backend in the template selector: Void, tRPC with Drizzle or Prisma, GraphQL with Prisma, or a client for an existing GraphQL server. React is the default. Choose Vue in the selector or pass `--framework vue`.
+
+Choose **Client Only** or pass `--template client-only` to start with a static Void app that saves its data in IndexedDB. See [Persisting Client State](/docs/guide/client-state.md#persisting-client-state).
 
 ### Manual Installation
 
@@ -380,6 +382,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 +604,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 +622,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 +634,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 +777,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.
 
@@ -876,8 +882,6 @@ For GraphQL servers with incremental delivery enabled, [streaming batched reads]
 
 You can wrap a list of references using `useListView` to enable connection-style lists with pagination support.
 
-Run the regular example with `vp run dev` (tRPC) or `vp run dev:graphql` (GraphQL), then open **Pagination** from its header (`http://localhost:6001/pagination/preview`). The demo uses the existing posts, client, and router to exercise independent view ranges, navigation, refreshes, and optimistic insertion and rollback. Reading and pagination work without signing in; insertions require an example account and successful insertions create real posts in its database. Browser network throttling makes pending work easier to observe.
-
 For example, you can define a `CommentView` and reuse it inside of a `CommentConnectionView`:
 
 ```tsx
@@ -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.
@@ -1545,7 +1606,7 @@ Pending mutations are never evicted to make room for cached data. If a new mutat
 
 ### Actions & Mutations
 
-With persistence configured, fate saves mutations before applying their optimistic updates or sending them to the server. The API is the same as for regular [Actions](/docs/guide/actions.md):
+With persistence and a durable mutation transport configured, fate saves server mutations before applying their optimistic updates or sending them to the server. The API is the same as for regular [Actions](/docs/guide/actions.md):
 
 ```tsx
 const [result, like] = useActionState(fate.actions.post.like, null);
@@ -1651,7 +1712,7 @@ 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.
 
-Without a durable adapter, saved reads and `persist: false` calls still work, but new durable mutations fail before being queued.
+Without a durable adapter, server mutations send immediately by default. Use `persist: true` to require durable delivery. The call fails before sending if persistence or the adapter is missing. Existing queued mutations stay saved and report a delivery error until the adapter is available again. Remote read caching and client state persistence work independently of the adapter.
 
 For GraphQL, return a standard `extensions.code` or numeric `extensions.http.status` for terminal client errors. Unrecognized execution errors remain retryable for saved mutations.
 
@@ -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:
@@ -2970,34 +3109,34 @@ For Prisma, pass Prisma query options such as `{ where: { ... } }` in `extra` in
 
 ### Data View Resolvers
 
-fate data views support computed fields. Use `computed`, `field`, and `count` to describe the hidden data needed to resolve a public field:
+fate data views support computed fields. Use `computed` to describe the hidden data needed to resolve a public field.
 
 ```tsx
-import { computed, count, field } from '@nkzw/fate/server';
+import { computed, count } from '@nkzw/fate/server';
 
 export const userDataView = dataView<UserItem>('User')({
-  email: computed<UserItem, string | null, AppContext>({
-    authorize: ({ id }, context) => context?.sessionUser?.id === id,
+  email: computed({
+    authorize: ({ id }, context?: AppContext) => context?.sessionUser?.id === id,
     select: {
-      email: field('email'),
+      email: true,
     },
-    resolve: (_item, deps) => (deps.email as string | null) ?? null,
+    resolve: (_item: UserItem, { email }) => email ?? null,
   }),
   id: true,
 });
 
 export const postDataView = dataView<PostItem>('Post')({
-  commentCount: computed<PostItem, number>({
+  commentCount: computed({
     select: {
       count: count('comments'),
     },
-    resolve: (_item, deps) => (deps.count as number) ?? 0,
+    resolve: (_item: PostItem, { count }) => count,
   }),
   id: true,
 });
 ```
 
-The adapters fetch the hidden `field(...)` and `count(...)` dependencies for you. This keeps private fields like `email` available to the resolver without exposing them to the client selection.
+Set a dependency to `true` to select a field by the same name. Use `field('path')` for aliases or nested paths and `count('relation')` for relation counts. The adapters fetch these dependencies for you. This keeps private fields like `email` available to the resolver without exposing them to the client selection.
 
 ### Connecting the Client
 
@@ -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:
@@ -3430,6 +3569,12 @@ After changing your database schema or auth configuration, run `vp run db:genera
 
 See [Void's Cloudflare deployment guide](https://void.cloud/integrations/cloudflare) for custom domains, secrets, and CI configuration.
 
+### Client-only Apps
+
+Choose `--template client-only` when creating the app. The template uses Void Pages Routing and prerenders both routes as static shells. IndexedDB stores application data in each browser.
+
+Run `vp exec void deploy --platform cloudflare` from the generated app to deploy the assets. You can also run `vp run build` and serve `dist/client/` from another static host that supports clean URLs.
+
 ### Migrating from cf-fate
 
 Fate 1.6 replaces the standalone Cloudflare adapter and template with the Void integration. Use `--template void` for new projects and `transport: 'void'` in the fate Vite plugin.

package/lib/index.mjs

@@ -1,5 +1,11 @@
 import { openDB } from "idb";
 // src/index.ts
+const prefixEnd = (prefix) => {
+	for (let index = prefix.length - 1; index >= 0; index--) {
+		const unit = prefix.charCodeAt(index);
+		if (unit < 65535) return prefix.slice(0, index) + String.fromCharCode(unit + 1);
+	}
+};
 function createIndexedDBStorage({ name = "fate" } = {}) {
 	let connectionLeases = 0;
 	let connection;
@@ -42,7 +48,8 @@ function createIndexedDBStorage({ name = "fate" } = {}) {
 	return {
 		exclusive(key, run) {
 			if (typeof navigator === "undefined" || !navigator.locks) throw new Error("fate(indexeddb): Web Locks are required for safe durable writes across tabs.");
-			return navigator.locks.request(`fate:${JSON.stringify([name, key])}`, async () => {
+			const lockName = `fate:${JSON.stringify([name, key])}`;
+			const request = (lockName) => navigator.locks.request(lockName, async () => {
 				connectionLeases++;
 				try {
 					return await run();
@@ -50,6 +57,7 @@ function createIndexedDBStorage({ name = "fate" } = {}) {
 					releaseDatabase();
 				}
 			});
+			return lockName.length <= 1024 ? request(lockName) : crypto.subtle.digest("SHA-256", new TextEncoder().encode(lockName)).then((digest) => request(`fate:sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`));
 		},
 		async read(key) {
 			const db = await acquireDatabase();
@@ -60,21 +68,24 @@ function createIndexedDBStorage({ name = "fate" } = {}) {
 			}
 		},
 		async scan(prefix, after, limit = 64) {
+			const lowerOpen = after !== void 0 && after >= prefix;
+			const lower = lowerOpen ? after : prefix;
+			if (!(limit > 0) || !lower.startsWith(prefix)) return [];
+			const upper = prefixEnd(prefix);
+			const range = upper === void 0 ? IDBKeyRange.lowerBound(lower, lowerOpen) : IDBKeyRange.bound(lower, upper, lowerOpen, true);
+			const count = Math.min(Math.ceil(limit), 4294967295);
 			const db = await acquireDatabase();
 			try {
-				const range = IDBKeyRange.lowerBound(after !== void 0 && after >= prefix ? after : prefix, after !== void 0 && after >= prefix);
 				const transaction = db.transaction("fate");
-				const entries = [];
-				let cursor = await transaction.store.openCursor(range);
-				while (cursor && String(cursor.key).startsWith(prefix) && entries.length < limit) {
-					entries.push({
-						key: String(cursor.key),
-						value: cursor.value
-					});
-					cursor = await cursor.continue();
-				}
-				await transaction.done;
-				return entries;
+				const [keys, values] = await Promise.all([
+					transaction.store.getAllKeys(range, count),
+					transaction.store.getAll(range, count),
+					transaction.done
+				]);
+				return keys.map((key, index) => ({
+					key: String(key),
+					value: values[index]
+				}));
 			} finally {
 				releaseDatabase();
 			}

package/package.json

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