@nkzw/fate 1.1.0 → 1.2.0

package/docs/{guide/graphql-integration.md → integrations/graphql.md}

@@ -1,6 +1,6 @@
 # GraphQL Integration
 
-_fate_ can use an existing GraphQL API as its transport. This keeps the React APIs, view composition, normalized cache, masking, requests, list views, live views, and actions the same while replacing the native or tRPC backend with GraphQL operations.
+_fate_ can use an existing GraphQL API as its transport. This keeps the adapter APIs, view composition, normalized cache, masking, requests, list views, live views, and mutations the same while replacing the native or tRPC backend with GraphQL operations.
 
 Use the GraphQL transport when your backend already exposes GraphQL and you want fate's client model without adding fate's native server protocol.
 
@@ -100,13 +100,15 @@ export const fateGraphQL = {
 } as const;
 ```
 
-The data views describe the fields React components are allowed to select. `Root` describes the root operations available to `useRequest`. `fateGraphQL.roots` maps those root names to actual GraphQL fields. If the GraphQL field has the same name as the fate root, the `field` entry can be omitted.
+The data views describe the fields client components are allowed to select. `Root` describes the root operations available to `useRequest`. `fateGraphQL.roots` maps those root names to actual GraphQL fields. If the GraphQL field has the same name as the fate root, the `field` entry can be omitted.
 
 ## Vite Plugin
 
 Configure the fate Vite plugin with the GraphQL transport and point it at the mapping module:
 
-```tsx
+::: code-group
+
+```tsx [React]
 import { fate } from 'react-fate/vite';
 import { defineConfig } from 'vite';
 
@@ -120,13 +122,33 @@ export default defineConfig({
 });
 ```
 
+```ts [Vue]
+import vue from '@vitejs/plugin-vue';
+import { fate } from 'vue-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    fate({
+      module: './src/fate/graphql.ts',
+      transport: 'graphql',
+    }),
+  ],
+});
+```
+
+:::
+
 The plugin generates a typed `createFateClient` helper from your views, roots, and GraphQL mapping. It also watches the mapping module and the files it imports during development.
 
 ## Creating a Client
 
 Create the client with your GraphQL endpoint and provide it through the `FateClient` provider:
 
-```tsx
+::: code-group
+
+```tsx [React]
 import { FateClient } from 'react-fate';
 import { createFateClient } from 'react-fate/client';
 
@@ -142,6 +164,29 @@ export function App() {
 }
 ```
 
+```vue [Vue]
+<script setup lang="ts">
+import { FateClient } from 'vue-fate';
+import { createFateClient } from 'vue-fate/client';
+import AppRoutes from './AppRoutes.vue';
+
+const fate = createFateClient({
+  headers: () => ({
+    authorization: `Bearer ${token}`,
+  }),
+  url: 'https://api.example.com/graphql',
+});
+</script>
+
+<template>
+  <FateClient :client="fate">
+    <AppRoutes />
+  </FateClient>
+</template>
+```
+
+:::
+
 Use `fetch` when you need to customize credentials or reuse an application fetch wrapper:
 
 ```tsx
@@ -157,6 +202,8 @@ const fate = createFateClient({
 
 GraphQL operations issued in the same microtask are batched into a single GraphQL query or mutation document with aliased fields.
 
+Deferred view fields work with the GraphQL transport through the same normalized cache flow as native HTTP: the eager query omits `defer(...)` fields, and `useView`, `useListView`, or `useLiveListView` fetches the missing selection through `nodes(ids:)` when the deferred handle is read. GraphQL `@defer` is the natural wire format for this feature, but fate's GraphQL transport currently expects one JSON result per operation and does not consume incremental multipart patches yet.
+
 ## Object IDs
 
 The transport converts between fate entity IDs and GraphQL node IDs. By default, it sends IDs as `${type}-${id}` and strips that prefix from returned IDs. Override this if your schema uses Relay global IDs, raw database IDs, or another encoding:
@@ -252,7 +299,7 @@ export const fateGraphQL = {
 } as const;
 ```
 
-Actions use the same `mutation(...)` and `useActionState` APIs described in the [Actions Guide](actions.md).
+Mutations use the same `mutation(...)` API described in the [Actions Guide](../guide/actions.md). React clients can also expose those mutations as Actions for `useActionState`.
 
 ## Live Views
 
@@ -295,4 +342,4 @@ const fate = createFateClient({
 
 The GraphQL transport is intentionally a mapping layer. It does not require `createFateServer`, the Prisma adapter, or the Drizzle adapter. Your GraphQL server remains responsible for authorization, validation, resolver behavior, cursor pagination, and mutation side effects.
 
-Use data views to expose only the fields the client should be able to select, keep GraphQL schema authorization in your server, and treat `src/fate/graphql.ts` as the contract between your GraphQL API and fate's React client.
+Use data views to expose only the fields the client should be able to select, keep GraphQL schema authorization in your server, and treat `src/fate/graphql.ts` as the contract between your GraphQL API and fate's client.

package/docs/{guide/server-integration.md → integrations/server.md}

@@ -4,7 +4,7 @@ Until now, we have focused on the client-side API of fate. You'll need a backend
 
 - The native fate protocol, which is transport-agnostic and can be hosted by any Fetch-compatible server.
 - The tRPC adapter, which keeps compatibility with existing tRPC backends.
-- The [GraphQL transport](graphql-integration.md), which maps fate views and roots to an existing GraphQL schema.
+- The [GraphQL transport](graphql.md), which maps fate views and roots to an existing GraphQL schema.
 
 _fate_ currently provides database adapters for Prisma and Drizzle, but the framework itself is not coupled to a particular ORM. The adapters plug into the same source execution runtime and can be exposed through the native protocol or through tRPC.
 
@@ -185,7 +185,9 @@ app.post('/fate/live', handler);
 
 Configure the Vite plugin with the native transport:
 
-```tsx
+::: code-group
+
+```tsx [React]
 import { fate } from 'react-fate/vite';
 import { defineConfig } from 'vite';
 
@@ -199,9 +201,29 @@ export default defineConfig({
 });
 ```
 
+```ts [Vue]
+import vue from '@vitejs/plugin-vue';
+import { fate } from 'vue-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    fate({
+      module: '@your-org/server/fate.ts',
+      transport: 'native',
+    }),
+  ],
+});
+```
+
+:::
+
 With the native transport, the Vite plugin handles the HTTP transport setup. If you need to create a client manually, use `createFateClient` with the same route:
 
-```tsx
+::: code-group
+
+```tsx [React]
 import { createFateClient } from 'react-fate/client';
 
 const client = createFateClient({
@@ -209,6 +231,16 @@ const client = createFateClient({
 });
 ```
 
+```ts [Vue]
+import { createFateClient } from 'vue-fate/client';
+
+const client = createFateClient({
+  url: '/fate',
+});
+```
+
+:::
+
 The HTTP transport batches operations issued in the same microtask into one `POST /fate` request. Live views use one `GET /fate/live` SSE stream per fate client and `POST /fate/live` control messages when views subscribe or unsubscribe.
 
 ### Custom Queries
@@ -585,7 +617,9 @@ export * from './views.ts';
 
 Configure the fate Vite plugin with your server module:
 
-```tsx
+::: code-group
+
+```tsx [React]
 import { fate } from 'react-fate/vite';
 import { defineConfig } from 'vite';
 
@@ -598,11 +632,28 @@ export default defineConfig({
 });
 ```
 
+```ts [Vue]
+import vue from '@vitejs/plugin-vue';
+import { fate } from 'vue-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    fate({
+      module: '@your-org/server/trpc/router.ts',
+    }),
+  ],
+});
+```
+
+:::
+
 _Note: fate uses the specified server module name to find the server types it needs. Make sure that the module is available to the client package's Vite config._
 
 During development, the plugin watches the server module and the files it imports. When one of those files changes, fate updates the internal client wiring and invalidates `@nkzw/fate/client` in Vite's module graph.
 
-For a barebones client without React, import the plugin from `@nkzw/fate/vite` and the client APIs from `@nkzw/fate/client`. The plugin wires the same server types for the selected import path.
+For a barebones client without a framework adapter, import the plugin from `@nkzw/fate/vite` and the client APIs from `@nkzw/fate/client`. The plugin wires the same server types for the selected import path.
 
 The plugin writes project-local types under `.fate/`. If your TypeScript config does not already include dot-directories, extend the generated config:
 
@@ -614,9 +665,11 @@ The plugin writes project-local types under `.fate/`. If your TypeScript config
 
 ## Creating a _fate_ Client
 
-Now that the Vite plugin has connected the types, create a fate client instance and provide it to your React app with the `FateClient` context provider:
+Now that the Vite plugin has connected the types, create a fate client instance and provide it to your app with the `FateClient` provider:
 
-```tsx
+::: code-group
+
+```tsx [React]
 import { httpBatchLink } from '@trpc/client';
 import { FateClient } from 'react-fate';
 import { createFateClient } from 'react-fate/client';
@@ -642,4 +695,37 @@ export function App() {
 }
 ```
 
+```vue [Vue]
+<script setup lang="ts">
+import { httpBatchLink } from '@trpc/client';
+import { computed } from 'vue';
+import { FateClient } from 'vue-fate';
+import { createFateClient } from 'vue-fate/client';
+import AppRoutes from './AppRoutes.vue';
+
+const fate = computed(() =>
+  createFateClient({
+    links: [
+      httpBatchLink({
+        fetch: (input, init) =>
+          fetch(input, {
+            ...init,
+            credentials: 'include',
+          }),
+        url: `${env('SERVER_URL')}/trpc`,
+      }),
+    ],
+  }),
+);
+</script>
+
+<template>
+  <FateClient :client="fate">
+    <AppRoutes />
+  </FateClient>
+</template>
+```
+
+:::
+
 _And you are all set. Happy building!_

package/docs/{guide/void-integration.md → integrations/void.md}

@@ -7,15 +7,25 @@ setup without copying its adapter glue.
 
 ## Install
 
-```sh
-pnpm add @nkzw/fate react-fate void-fate void
+::: code-group
+
+```sh [React]
+pnpm add @nkzw/fate react-fate void-fate void @void/react
+```
+
+```sh [Vue]
+pnpm add @nkzw/fate vue-fate void-fate void @void/vue
 ```
 
+:::
+
 ## Vite
 
-Use the regular `react-fate` Vite plugin with the Void transport:
+Use the framework adapter's Vite plugin with the Void transport:
 
-```tsx
+::: code-group
+
+```tsx [React]
 import { voidReact } from '@void/react/plugin';
 import { fate } from 'react-fate/vite';
 import { defineConfig } from 'vite-plus';
@@ -33,6 +43,26 @@ export default defineConfig({
 });
 ```
 
+```ts [Vue]
+import { voidVue } from '@void/vue/plugin';
+import { fate } from 'vue-fate/vite';
+import { defineConfig } from 'vite-plus';
+import { voidPlugin } from 'void';
+
+export default defineConfig({
+  plugins: [
+    voidPlugin(),
+    voidVue(),
+    fate({
+      module: './src/fate/server.ts',
+      transport: 'void',
+    }),
+  ],
+});
+```
+
+:::
+
 The Void transport uses `/fate` for RPC requests and `/fate-live` for live
 updates by default. In SSR, it calls the exported fate server directly. In the
 browser, it uses fetch and the SSE live endpoint.
@@ -104,12 +134,14 @@ export const { GET, POST } = defineVoidFateLiveRoute(fateServer, fateLive);
 The live route handles `GET /fate-live` SSE connections and `POST /fate-live`
 control messages. `void-fate` does not use WebSockets.
 
-## React Layout
+## Layout
 
-Wrap your app with `VoidFateClient` from `void-fate/react`. It creates and
-provides the fate client through `react-fate`:
+Wrap your app with the Void fate client for your framework. It creates and
+provides the fate client through the matching adapter.
 
-```tsx
+::: code-group
+
+```tsx [React]
 import { useShared } from '@void/react';
 import type { ReactNode } from 'react';
 import { VoidFateClient } from 'void-fate/react';
@@ -128,9 +160,36 @@ export default function Layout({ children }: { children: ReactNode }) {
 }
 ```
 
-`userId` is optional, but passing it lets `VoidFateClient` recreate the client
-when the signed-in user changes. Browser requests include credentials when a
-`userId` is present.
+```vue [Vue]
+<script setup lang="ts">
+import { useShared } from '@void/vue';
+import { computed } from 'vue';
+import { FateClient } from 'vue-fate';
+import { createFateClient } from 'vue-fate/client';
+import type { SharedData } from '../src/lib/shared.ts';
+
+const shared = useShared<SharedData>();
+
+const fate = computed(() =>
+  createFateClient({
+    origin: typeof window === 'undefined' ? shared.origin : window.location.origin,
+    userId: shared.auth.user?.id,
+  }),
+);
+</script>
+
+<template>
+  <FateClient :client="fate">
+    <slot />
+  </FateClient>
+</template>
+```
+
+:::
+
+`userId` is optional, but passing it lets the client be recreated when the
+signed-in user changes. Browser requests include credentials when a `userId` is
+present.
 
 ## Custom Paths
 
@@ -143,12 +202,35 @@ export const fateLive = createVoidFateLive({
 });
 ```
 
-```tsx
+::: code-group
+
+```tsx [React]
 <VoidFateClient livePath="/custom-fate-live" origin={origin} rpcPath="/custom-fate" userId={userId}>
   {children}
 </VoidFateClient>
 ```
 
+```vue [Vue]
+<script setup lang="ts">
+const fate = computed(() =>
+  createFateClient({
+    livePath: '/custom-fate-live',
+    origin,
+    rpcPath: '/custom-fate',
+    userId,
+  }),
+);
+</script>
+
+<template>
+  <FateClient :client="fate">
+    <slot />
+  </FateClient>
+</template>
+```
+
+:::
+
 The route helper does not own the route path. Make sure your Void route filename
 or router configuration matches the paths you pass to the client.
 

package/lib/{executor-sLcAqDMs.d.mts → executor-Dh-MLUXc.d.mts}

@@ -1,4 +1,4 @@
-import { Z as QueryProcedure, r as AnyRecord } from "./transport-BTgtSwOM.mjs";
+import { r as AnyRecord, rt as QueryProcedure } from "./transport-BjGm__3t.mjs";
 import { z } from "zod";
 
 //#region src/server/dataView.d.ts

package/lib/{graphqlTransport-DbRHbYtb.d.mts → graphqlTransport-B3cbhvJX.d.mts}

@@ -1,4 +1,4 @@
-import { E as TypeConfig, s as Entity, t as Transport, v as MutationShape } from "./transport-BTgtSwOM.mjs";
+import { C as MutationShape, f as Entity, j as TypeConfig, t as Transport } from "./transport-BjGm__3t.mjs";
 
 //#region src/graphqlTransport.d.ts
 type TransportMutations = Record<string, MutationShape>;

package/lib/graphqlTransport.d.mts

@@ -1,2 +1,2 @@
-import { a as GraphQLTransportOptions, i as GraphQLMutationOutput, n as GraphQLMutationInput, o as createGraphQLTransport, r as GraphQLMutationMap, s as graphqlMutation, t as GraphQLMutationDefinition } from "./graphqlTransport-DbRHbYtb.mjs";
+import { a as GraphQLTransportOptions, i as GraphQLMutationOutput, n as GraphQLMutationInput, o as createGraphQLTransport, r as GraphQLMutationMap, s as graphqlMutation, t as GraphQLMutationDefinition } from "./graphqlTransport-B3cbhvJX.mjs";
 export { GraphQLMutationDefinition, GraphQLMutationInput, GraphQLMutationMap, GraphQLMutationOutput, GraphQLTransportOptions, createGraphQLTransport, graphqlMutation };

package/lib/index.d.mts

@@ -1,8 +1,13 @@
-import { A as ViewEntity, B as mutation, C as RootDefinition, D as TypeName, E as TypeConfig, F as ViewTag, G as getSelectionPlan, H as RequestMode, I as __FateEntityBrand, J as HydrationLimits, K as FateDehydratedState, L as __FateSelectionBrand, M as ViewRef, N as ViewSelection, O as View, P as ViewSnapshot, R as isViewTag, S as RequestResult, T as Snapshot, U as RequestOptions, V as FateClient, W as createClient, Y as List, _ as MutationResult, a as ConnectionRef, b as Pagination, c as EntityId, d as ListItem, f as Mask, g as MutationInput, h as MutationIdentifier, i as ConnectionMetadata, j as ViewEntityName, k as ViewData, l as FateRoots, m as MutationEntity, n as createTRPCTransport, o as ConnectionTag, p as MutationDefinition, q as HydrateOptions, r as AnyRecord, s as Entity, t as Transport, u as FateThenable, v as MutationShape, w as Selection, x as Request$1, y as NodesItem, z as FateMutations } from "./transport-BTgtSwOM.mjs";
-import { a as GraphQLTransportOptions, i as GraphQLMutationOutput, n as GraphQLMutationInput, o as createGraphQLTransport, r as GraphQLMutationMap, s as graphqlMutation, t as GraphQLMutationDefinition } from "./graphqlTransport-DbRHbYtb.mjs";
-import { C as liveGlobalConnectionTopic, S as liveEntityTopic, a as FateProtocolRequest, i as FateOperation, n as FateLiveConnectionEvent, o as FateProtocolResponse, r as FateLiveEvent, t as isRecord, u as InferFateAPI, x as liveConnectionTopic } from "./record-BtdKzEGI.mjs";
-import { n as getListEntries, t as ListEntry } from "./list-CMQOQGdn.mjs";
+import { $ as HydrateOptions, A as Snapshot, B as ViewTag, C as MutationShape, D as RequestResult, E as Request$1, F as ViewEntity, G as mutation, H as __FateSelectionBrand, I as ViewEntityName, J as RequestMode, K as DeferredSnapshot, L as ViewRef, M as TypeName, N as View, O as RootDefinition, P as ViewData, Q as FateDehydratedState, R as ViewSelection, S as MutationResult, T as Pagination, U as isViewTag, V as __FateEntityBrand, W as FateMutations, X as createClient, Y as RequestOptions, Z as getSelectionPlan, _ as Mask, a as ConnectionRef, b as MutationIdentifier, c as Deferred, d as DeferredTag, et as HydrationLimits, f as Entity, g as ListItem, h as FateThenable, i as ConnectionMetadata, j as TypeConfig, k as Selection, l as DeferredMetadata, m as FateRoots, n as createTRPCTransport, o as ConnectionTag, p as EntityId, q as FateClient, r as AnyRecord, s as DeferTag, t as Transport, tt as List, u as DeferredSelection, v as MutationDefinition, w as NodesItem, x as MutationInput, y as MutationEntity, z as ViewSnapshot } from "./transport-BjGm__3t.mjs";
+import { a as GraphQLTransportOptions, i as GraphQLMutationOutput, n as GraphQLMutationInput, o as createGraphQLTransport, r as GraphQLMutationMap, s as graphqlMutation, t as GraphQLMutationDefinition } from "./graphqlTransport-B3cbhvJX.mjs";
+import { C as liveGlobalConnectionTopic, S as liveEntityTopic, a as FateProtocolRequest, i as FateOperation, n as FateLiveConnectionEvent, o as FateProtocolResponse, r as FateLiveEvent, t as isRecord, u as InferFateAPI, x as liveConnectionTopic } from "./record-BkvZwvFk.mjs";
+import { n as getListEntries, t as ListEntry } from "./list-BrL6PD_6.mjs";
 
+//#region src/defer.d.ts
+declare function defer<S>(selection: S): DeferredSelection<S>;
+declare const isDeferred: (value: unknown) => value is Deferred<unknown>;
+declare const getDeferredMetadata: <T>(deferred: Deferred<T>) => DeferredMetadata;
+//#endregion
 //#region src/httpTransport.d.ts
 type TransportMutations = Record<string, MutationShape>;
 type EmptyTransportMutations = Record<never, MutationShape>;
@@ -88,4 +93,4 @@ type SelectionValidation<T extends Entity, S extends Selection<T>> = Exclude<key
  */
 declare function view<T extends Entity>(): <S extends Selection<T>>(select: S & SelectionValidation<T, S>) => View<T, S>;
 //#endregion
-export { type ConnectionMetadata, type ConnectionRef, ConnectionTag, type Entity, type EntityId, FateClient, type FateDehydratedState, type FateLiveConnectionEvent, type FateLiveEvent, type FateMutations, type FateOperation, type FateProtocolRequest, type FateProtocolResponse, type AnyRecord as FateRecord, type FateRoots, type FateThenable, type GraphQLMutationDefinition, type GraphQLMutationInput, type GraphQLMutationMap, type GraphQLMutationOutput, type GraphQLTransportOptions, type HydrateOptions, type HydrationLimits, type InferFateAPI, type List, type ListEntry, type ListItem, type Mask, type MutationDefinition, type MutationEntity, type MutationIdentifier, type MutationInput, type MutationResult, type NodesItem, type Pagination, type Request$1 as Request, type RequestMode, type RequestOptions, type RequestResult, type Selection, type Snapshot, type Transport, type TypeConfig, type View, type ViewData, type ViewEntity, type ViewEntityName, type ViewRef, type ViewSelection, type ViewSnapshot, type ViewTag, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, getListEntries, getSelectionPlan, graphqlMutation, isRecord, isViewTag, liveConnectionTopic, liveEntityTopic, liveGlobalConnectionTopic, mutation, toEntityId, view };
+export { type ConnectionMetadata, type ConnectionRef, ConnectionTag, DeferTag, type Deferred, type DeferredMetadata, type DeferredSelection, type DeferredSnapshot, DeferredTag, type Entity, type EntityId, FateClient, type FateDehydratedState, type FateLiveConnectionEvent, type FateLiveEvent, type FateMutations, type FateOperation, type FateProtocolRequest, type FateProtocolResponse, type AnyRecord as FateRecord, type FateRoots, type FateThenable, type GraphQLMutationDefinition, type GraphQLMutationInput, type GraphQLMutationMap, type GraphQLMutationOutput, type GraphQLTransportOptions, type HydrateOptions, type HydrationLimits, type InferFateAPI, type List, type ListEntry, type ListItem, type Mask, type MutationDefinition, type MutationEntity, type MutationIdentifier, type MutationInput, type MutationResult, type NodesItem, type Pagination, type Request$1 as Request, type RequestMode, type RequestOptions, type RequestResult, type Selection, type Snapshot, type Transport, type TypeConfig, type View, type ViewData, type ViewEntity, type ViewEntityName, type ViewRef, type ViewSelection, type ViewSnapshot, type ViewTag, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, defer, getDeferredMetadata, getListEntries, getSelectionPlan, graphqlMutation, isDeferred, isRecord, isViewTag, liveConnectionTopic, liveEntityTopic, liveGlobalConnectionTopic, mutation, toEntityId, view };

package/lib/index.mjs

@@ -78,6 +78,10 @@ const ViewsTag = Symbol("__fate__views");
 const NodeRefTag = Symbol("__fate__node-ref");
 /** Symbol attached to connection results so pagination helpers can find their metadata. */
 const ConnectionTag = Symbol("__fate__connection");
+/** Symbol used to mark a selection as deferred. */
+const DeferTag = Symbol("__fate__defer");
+/** Symbol attached to deferred values returned from masked views. */
+const DeferredTag = Symbol("__fate__deferred");
 const viewTag = "__fate-view__";
 /** Generates a stable view tag for a view definition. */
 function getViewTag(id) {
@@ -104,6 +108,16 @@ const RootKind = "__fate__root";
 /** Brand used on mutation definitions to mark their identity in the d.ts output. */
 const MutationKind = "__fate__mutation";
 //#endregion
+//#region src/defer.ts
+function defer(selection) {
+	return Object.freeze({ [DeferTag]: selection });
+}
+const isDeferredSelection = (value) => typeof value === "object" && value !== null && DeferTag in value;
+const getDeferredSelection = (selection) => selection[DeferTag];
+const createDeferred = (metadata) => Object.freeze({ [DeferredTag]: metadata });
+const isDeferred = (value) => typeof value === "object" && value !== null && DeferredTag in value;
+const getDeferredMetadata = (deferred) => deferred[DeferredTag];
+//#endregion
 //#region src/node-ref.ts
 function createNodeRef(id) {
 	const ref = {};
@@ -706,6 +720,7 @@ const getSelectionPlan = (viewComposition, ref) => {
 				if (value) paths.add(path);
 				continue;
 			}
+			if (isDeferredSelection(value)) continue;
 			if (isViewTag(key)) {
 				if (!ref || ref[ViewsTag] && ref[ViewsTag].has(key)) walk(value.select, prefix);
 				continue;
@@ -743,6 +758,9 @@ const getSelectionPlan = (viewComposition, ref) => {
 		paths
 	};
 };
+const getDeferredSelectionPlan = (field, selection) => {
+	return getSelectionPlan({ [field]: selection }, null);
+};
 //#endregion
 //#region src/mutation.ts
 /**
@@ -1796,6 +1814,7 @@ var FateClient = class {
 		this.parentLists = /* @__PURE__ */ new Map();
 		this.rootLists = /* @__PURE__ */ new Map();
 		this.pending = /* @__PURE__ */ new Map();
+		this.pendingDeferred = /* @__PURE__ */ new Map();
 		this.pendingOptimisticMutations = /* @__PURE__ */ new Map();
 		this.optimisticMasks = /* @__PURE__ */ new Map();
 		this.optimisticByEntity = /* @__PURE__ */ new Map();
@@ -2095,6 +2114,63 @@ var FateClient = class {
 		}
 		return resolveSnapshot();
 	}
+	readDeferred(deferred) {
+		const metadata = getDeferredMetadata(deferred);
+		const resolvedOwner = this.optimisticEntityResolutions.get(metadata.owner) ?? metadata.owner;
+		const parsedOwner = parseEntityId(resolvedOwner);
+		const ownerRecord = this.store.read(resolvedOwner);
+		const rawOwnerId = ownerRecord && (typeof ownerRecord.id === "string" || typeof ownerRecord.id === "number") ? ownerRecord.id : parsedOwner.id;
+		const ownerType = parsedOwner.type || metadata.type;
+		const plan = getDeferredSelectionPlan(metadata.field, metadata.selection);
+		const selectedPaths = plan.paths;
+		const missing = this.store.missingForSelection(resolvedOwner, selectedPaths);
+		const hasMissingList = () => this.hasMissingDeferredList(resolvedOwner, ownerType, metadata.field, plan);
+		const listMissing = hasMissingList();
+		const fetchPaths = listMissing ? selectedPaths : missing;
+		const resolveSnapshot = () => {
+			const snapshot = this.readViewSelection({ [metadata.field]: metadata.selection }, this.stableRefWithViewNames(ownerType, rawOwnerId, /* @__PURE__ */ new Set()), resolvedOwner, plan);
+			const resolved = {
+				coverage: snapshot.coverage,
+				data: snapshot.data[metadata.field]
+			};
+			return {
+				status: "fulfilled",
+				then: (onfulfilled, onrejected) => Promise.resolve(resolved).then(onfulfilled, onrejected),
+				value: resolved
+			};
+		};
+		if (missing.size === 0 && !listMissing) {
+			this.clearStalledRequestsForEntity(resolvedOwner);
+			return resolveSnapshot();
+		}
+		const key = this.deferredPendingKey(resolvedOwner, fetchPaths, plan, this.deferredSelectionSignature(metadata.selection));
+		if (this.stalledRequests.has(key)) return resolveSnapshot();
+		const pendingOptimistic = this.getPendingOptimisticMutations(resolvedOwner);
+		if (pendingOptimistic) {
+			const pending = this.pendingDeferred.get(key);
+			if (pending) return pending;
+			const promise = Promise.all(pendingOptimistic).then(() => this.readDeferred(deferred)).finally(() => this.pendingDeferred.delete(key));
+			this.pendingDeferred.set(key, promise);
+			return promise;
+		}
+		const pendingPromise = this.pendingDeferred.get(key) || null;
+		if (pendingPromise) return pendingPromise;
+		const promise = this.trackPendingRequest(async () => {
+			try {
+				await this.fetchByIdAndNormalize(ownerType, [rawOwnerId], fetchPaths, plan);
+				if (this.store.missingForSelection(resolvedOwner, selectedPaths).size > 0 || hasMissingList()) {
+					this.stalledRequests.add(key);
+					return resolveSnapshot().value;
+				}
+				this.stalledRequests.delete(key);
+				return this.readDeferred(deferred).value;
+			} finally {
+				this.pendingDeferred.delete(key);
+			}
+		});
+		this.pendingDeferred.set(key, promise);
+		return promise;
+	}
 	assertLiveViewSupport() {
 		if (!this.transport.subscribeById) throw new Error(`fate: transport does not support live views. Please provide a 'subscribeById' implementation in your transport.`);
 	}
@@ -3138,8 +3214,20 @@ var FateClient = class {
 					target[ViewsTag].add(key);
 					continue;
 				}
-				coverageById.set(parentId, (coverageById.get(parentId) ?? /* @__PURE__ */ new Set()).add(key));
 				const fieldPath = prefix ? `${prefix}.${key}` : key;
+				if (isDeferredSelection(selectionKind)) {
+					const { id, type } = parseEntityId(parentId);
+					coverageById.set(parentId, (coverageById.get(parentId) ?? /* @__PURE__ */ new Set()).add(key));
+					target[key] = createDeferred({
+						field: key,
+						id,
+						owner: parentId,
+						selection: getDeferredSelection(selectionKind),
+						type
+					});
+					continue;
+				}
+				coverageById.set(parentId, (coverageById.get(parentId) ?? /* @__PURE__ */ new Set()).add(key));
 				const selectionType = typeof selectionKind;
 				if (selectionType === "boolean" && selectionKind) target[key] = record[key];
 				else if (selectionKind && selectionType === "object") {
@@ -3258,7 +3346,9 @@ var FateClient = class {
 			}
 		};
 		const data = { __typename: parseEntityId(entityId).type };
-		for (const viewPayload of getViewPayloads(viewComposition, ref)) walk(viewPayload.select, record, data, entityId, pathPrefix);
+		const payloads = getViewPayloads(viewComposition, ref);
+		if (payloads.length === 0 && isRecord(viewComposition)) walk(viewComposition, record, data, entityId, pathPrefix);
+		else for (const viewPayload of payloads) walk(viewPayload.select, record, data, entityId, pathPrefix);
 		return {
 			coverage: [...coverageById.entries()],
 			data
@@ -3274,6 +3364,32 @@ var FateClient = class {
 	pendingKey(entityId, missingFields) {
 		return `${this.pendingPrefix(entityId)}${[...missingFields].sort().join("|")}`;
 	}
+	deferredPendingKey(entityId, fields, plan, selectionSignature) {
+		const args = [...plan.args.entries()].map(([path, entry]) => `${path}:${entry.hash}`).sort().join("|");
+		return `${this.pendingKey(entityId, new Set(fields))}|${args}|${selectionSignature}`;
+	}
+	deferredSelectionSignature(selection) {
+		const seen = /* @__PURE__ */ new Set();
+		const serialize = (value) => {
+			if (value === null || typeof value !== "object") return `${typeof value}:${String(value)}`;
+			if (seen.has(value)) return "[Circular]";
+			seen.add(value);
+			if (Array.isArray(value)) return `[${value.map((item) => serialize(item)).join(",")}]`;
+			return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => isViewTag(key) ? `view:${key}` : `${key}:${serialize(entry)}`).join(",")}}`;
+		};
+		return serialize(selection);
+	}
+	hasMissingDeferredList(owner, type, field, plan) {
+		const descriptor = this.types.get(type)?.fields?.[field];
+		if (!descriptor || descriptor === "scalar" || !("listOf" in descriptor)) return false;
+		const fieldArgs = plan.args.get(field);
+		const listState = this.store.getListState(getListKey(owner, field, fieldArgs?.hash));
+		if (!listState) return true;
+		const args = fieldArgs?.value;
+		const paginationArgs = getPaginationArgsInfo(args);
+		if (paginationArgs.hasCursorArg) return true;
+		return !hasConnectionPageCoverage(listState, args, paginationArgs.direction);
+	}
 	liveSubscriptionKey(entityId, plan) {
 		return `${entityId}|${[...plan.paths].sort().join("|")}|${[...plan.args.entries()].map(([path, entry]) => `${path}:${entry.hash}`).sort().join("|")}`;
 	}
@@ -3808,4 +3924,4 @@ function clientRoot(type) {
 	});
 }
 //#endregion
-export { ConnectionTag, FateClient, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, getListEntries, getSelectionPlan, graphqlMutation, isRecord, isViewTag, liveConnectionTopic, liveEntityTopic, liveGlobalConnectionTopic, mutation, toEntityId, view };
+export { ConnectionTag, DeferTag, DeferredTag, FateClient, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, defer, getDeferredMetadata, getListEntries, getSelectionPlan, graphqlMutation, isDeferred, isRecord, isViewTag, liveConnectionTopic, liveEntityTopic, liveGlobalConnectionTopic, mutation, toEntityId, view };

package/lib/{list-CMQOQGdn.d.mts → list-BrL6PD_6.d.mts}

@@ -1,4 +1,4 @@
-import { Y as List, c as EntityId } from "./transport-BTgtSwOM.mjs";
+import { p as EntityId, tt as List } from "./transport-BjGm__3t.mjs";
 
 //#region src/list.d.ts
 type ListEntry = Readonly<{