@nkzw/fate-indexeddb 1.15.0 → 1.16.1

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`.
+
+If you want to build an app entirely with client state, choose **Client Only** or pass `--template client-only`. This template includes Void Pages Routing and a task list saved in IndexedDB. Try editing a task and reloading the page to see persistence in action. See [Client State](/docs/guide/client-state.md).
 
 ### Manual Installation
 
@@ -880,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
@@ -1239,6 +1239,8 @@ fate does not provide hooks for mutations like traditional data fetching librari
 
 fate's Vite plugin makes your server mutations available on the client. The API works the same way with native HTTP, tRPC, GraphQL, and Void.
 
+You can also define mutations for [Client State](/docs/guide/client-state.md). Components call them through the same `fate.actions` and `fate.mutations` APIs.
+
 If you have a mutation named `post.like`, a `LikeButton` component using fate Actions and an async component library could look like this:
 
 ```tsx
@@ -1353,6 +1355,8 @@ const result = await fate.mutations.comment.add({
 
 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.
 
+If a mutation doesn't take any input, you can omit the arguments entirely. For example, our [client counter](/docs/guide/client-state.md#reading-and-updating-state) increments with `fate.mutations.counter.increment()`. You can still pass options such as `{ view: CounterView }`. Actions take an options object, so dispatch the same mutation with `increment({})` inside a React Action or transition. Mutations that declare input fields still require `input`, even if every field is optional.
+
 ### Mutation Server Implementation
 
 Define mutations in your backend and return the fields requested by the client. See [Server Integration](/docs/integrations/server.md#custom-mutations) for native HTTP and tRPC, [GraphQL Integration](/docs/integrations/graphql.md#mutations) for an existing GraphQL API, or [Void Integration](/docs/integrations/void.md) for a Void app.
@@ -1518,6 +1522,8 @@ When the mutation succeeds, fate marks the post's cached fields stale. A `cache-
 
 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.
 
+The same persistence setup can save [Client State](/docs/guide/client-state.md#persisting-client-state), such as drafts or bookmarks. Client data stays saved when the remote cache expires or is cleared. You can use [migrations](/docs/guide/client-state.md#migrations) to update its shape as your app changes.
+
 ### Client Setup
 
 For a browser app, install the IndexedDB adapter:
@@ -1606,7 +1612,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):
+Let's say a user wants to like a post while offline. With persistence and a [durable mutation transport](#server-deduplication) configured, fate saves the mutation before applying its optimistic update or sending it to the server. We can use the same API as for regular [Actions](/docs/guide/actions.md):
 
 ```tsx
 const [result, like] = useActionState(fate.actions.post.like, null);
@@ -1712,7 +1718,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.
 
-Without a durable adapter, saved reads and `persist: false` calls still work, but new durable mutations fail before being queued.
+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.
+
+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.
+
+Mutations that were already queued stay saved and report a delivery error until the adapter is available again.
 
 For GraphQL, return a standard `extensions.code` or numeric `extensions.http.status` for terminal client errors. Unrecognized execution errors remain retryable for saved mutations.
 
@@ -1767,7 +1777,7 @@ To remove the saved read cache, call `clearCache()`:
 await fate.persistence!.clearCache();
 ```
 
-This leaves in-memory data and queued mutations intact.
+This leaves in-memory data, queued mutations, and saved client state intact. For example, clearing cached posts keeps the bookmarks defined in your client schema.
 
 Change `hydrationScope` when deploying incompatible data models or mutation inputs. Incompatible saved reads are discarded; incompatible queued mutations remain visible as failures so the app can handle them.
 
@@ -3109,34 +3119,36 @@ 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:
+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`:
 
 ```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.
+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).
 
 ### Connecting the Client
 
@@ -3569,6 +3581,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
+
+You can also deploy an app built entirely with [Client State](/docs/guide/client-state.md). Choose `--template client-only` when creating the app. The template includes Void Pages Routing and saves each user's data in their browser with IndexedDB.
+
+Run `vp exec void deploy --platform cloudflare` from the generated app to deploy its static pages and 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.15.0",
+  "version": "1.16.1",
   "description": "Optional IndexedDB persistence adapter for fate.",
   "license": "MIT",
   "files": [
@@ -19,7 +19,7 @@
     "idb": "^8.0.4"
   },
   "devDependencies": {
-    "@nkzw/fate": "1.15.0",
+    "@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"