@nkzw/fate 0.0.8 → 0.1.0

package/README.md

@@ -18,7 +18,7 @@
 - **Async React:** fate uses modern Async React features like Actions, Suspense, and `use` to support concurrent rendering and enable a seamless user experience.
 - **Lists & Pagination:** fate provides built-in support for connection-style lists with cursor-based pagination, making it easy to implement infinite scrolling and "load-more" functionality.
 - **Optimistic Updates:** fate supports declarative optimistic updates for mutations, allowing the UI to update immediately while the server request is in-flight. If the request fails, the cache and its associated views are rolled back to their previous state.
-- **AI-Ready:** fate's minimal, predictable API and explicit data selection enable local reasoning, allowing AI tools to generate stable, type-safe data-fetching code.
+- **AI-Ready:** fate's minimal, predictable API and explicit data selection enable local reasoning, enabling humans and AI tools to generate stable, type-safe data-fetching code.
 
 ### A modern data client for React & tRPC
 
@@ -32,14 +32,14 @@ However, GraphQL comes with its own type system and query language. If you are a
 
 Many React data frameworks lack Relay's ergonomics, especially fragment composition, co-located data requirements, predictable caching, and deep integration with modern React features. Optimistic updates usually require manually managing keys and imperative data updates, which is error-prone and tedious.
 
-fate takes the great ideas from Relay and puts them on top of tRPC. You get the best of both worlds: type safety between the client and server, and GraphQL-like ergonomics for data fetching. Using _fate_ usually looks like this:
+_fate_ takes the great ideas from Relay and puts them on top of tRPC. You get the best of both worlds: type safety between the client and server, and GraphQL-like ergonomics for data fetching. Using _fate_ usually looks like this:
 
 ```tsx
 export const PostView = view<Post>()({
+  author: UserView,
   content: true,
   id: true,
   title: true,
-  author: UserView,
 });
 
 export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
@@ -65,15 +65,15 @@ Get started with [a ready-made template](https://github.com/nkzw-tech/fate-templ
 
 ::: code-group
 
-```npm
+```bash [npm]
 npx giget@latest gh:nkzw-tech/fate-template
 ```
 
-```pnpm
+```bash [pnpm]
 pnpx giget@latest gh:nkzw-tech/fate-template
 ```
 
-```yarn
+```bash [yarn]
 yarn dlx giget@latest gh:nkzw-tech/fate-template
 ```
 
@@ -87,15 +87,15 @@ yarn dlx giget@latest gh:nkzw-tech/fate-template
 
 ::: code-group
 
-```npm
+```bash [npm]
 npm add react-fate
 ```
 
-```pnpm
+```bash [pnpm]
 pnpm add react-fate
 ```
 
-```yarn
+```bash [yarn]
 yarn add react-fate
 ```
 
@@ -105,15 +105,15 @@ And for your server, install the core `@nkzw/fate` package:
 
 ::: code-group
 
-```npm
+```bash [npm]
 npm add @nkzw/fate
 ```
 
-```pnpm
+```bash [pnpm]
 pnpm add @nkzw/fate
 ```
 
-```yarn
+```bash [yarn]
 yarn add @nkzw/fate
 ```
 
@@ -202,34 +202,20 @@ Components using `useView` listen to changes for all selected fields. When data
 
 ### Fetching Data with `useRequest`
 
-Now that we defined our view and component, we fetch the data from the server using the `useRequest` hook from fate. This hook allows us to declare what data we need for a specific screen or component tree. At the root of our `HomePage` component, we can request a list of posts like this:
+Now that we defined our view and component, we fetch the data from the server using the `useRequest` hook from fate. This hook allows us to declare what data we need for a specific screen or component tree. At the root of our app, we can request a list of posts like this:
 
 ```tsx
 import { useRequest } from 'react-fate';
 import { PostCard, PostView } from './PostCard.tsx';
 
-export function HomePage() {
-  const { posts } = useRequest({
-    posts: { root: PostView, type: 'Post' },
-  } as const);
+export function App() {
+  const { posts } = useRequest({ posts: { list: PostView } });
 
   return posts.map((post) => <PostCard key={post.id} post={post} />);
 }
 ```
 
-This component suspends or throws errors, which bubble up to the nearest error boundary. Wrap your component tree with `ErrorBoundary` and `Suspense` components to show error and loading states:
-
-```tsx
-<ErrorBoundary FallbackComponent={ErrorComponent}>
-  <Suspense fallback={<div>Loading…</div>}>
-    <HomePage />
-  </Suspense>
-</ErrorBoundary>
-```
-
-> [!NOTE]
->
-> `useRequest` might issue multiple requests which are automatically batched together by tRPC's [HTTP Batch Link](https://trpc.io/docs/client/links/httpBatchLink).
+_Learn more about `useRequest` in the [Requests Guide](/docs/guide/requests.md)._
 
 ### Composing Views
 
@@ -237,7 +223,7 @@ In the above example we are defining a single view for a `Post`. One of fate's c
 
 ```tsx
 import { Suspense } from 'react';
-import { useRequest, useView, ViewRef } from 'react-fate';
+import { useView, ViewRef } from 'react-fate';
 
 export const PostView = view<Post>()({
   author: {
@@ -443,23 +429,62 @@ const PostDetail = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
 
 ViewRefs carry a set of view names they can resolve. `useView` throws if a ref does not include the required view.
 
-### Request Modes
+## Requests
 
-`useRequest` supports different request modes to control caching and data freshness. The available modes are:
+### Requesting Lists
 
-- `cache-first` (_default_): Returns data from the cache if available, otherwise fetches from the network.
-- `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.
+The `useRequest` hook can be used to declare our data needs for a specific screen or component tree. At the root of our app, we can request a list of posts like this:
 
-You can pass the request mode as an option to `useRequest`:
+```tsx
+import { useRequest } from 'react-fate';
+import { PostCard, PostView } from './PostCard.tsx';
+
+export function App() {
+  const { posts } = useRequest({ posts: { list: PostView } });
+  return posts.map((post) => <PostCard key={post.id} post={post} />);
+}
+```
+
+This component suspends or throws errors, which bubble up to the nearest error boundary. Wrap your component tree with `ErrorBoundary` and `Suspense` components to show error and loading states:
 
 ```tsx
-const { posts } = useRequest(
-  {
-    posts: { root: PostView, type: 'Post' },
-  },
-  { mode: 'stale-while-revalidate' },
-);
+<ErrorBoundary FallbackComponent={ErrorComponent}>
+  <Suspense fallback={<div>Loading…</div>}>
+    <App />
+  </Suspense>
+</ErrorBoundary>
+```
+
+> [!NOTE]
+>
+> `useRequest` might issue multiple requests which are automatically batched together by tRPC's [HTTP Batch Link](https://trpc.io/docs/client/links/httpBatchLink) into a single network request.
+
+### Requesting Objects by ID
+
+If you want to fetch data for a single object instead of a list, you can specify the `id` and the associated `view` like this:
+
+```tsx
+const { post } = useRequest({
+  post: { id: '12', view: PostView },
+});
+```
+
+If you want to fetch multiple objects by their IDs, you can use the `ids` field:
+
+```tsx
+const { posts } = useRequest({
+  posts: { ids: ['6', '7'], view: PostView },
+});
+```
+
+### Other Types of Requests
+
+For any other queries, pass only the `type` and `view`:
+
+```tsx
+const { viewer } = useRequest({
+  viewer: { view: UserView },
+});
 ```
 
 ### Request Arguments
@@ -470,12 +495,32 @@ You can pass arguments to `useRequest` calls. This is useful for pagination, fil
 const { posts } = useRequest({
   posts: {
     args: { first: 10 },
-    root: PostView,
-    type: 'Post',
+    list: PostView,
   },
 });
 ```
 
+### Request Modes
+
+`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.
+- `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.
+
+You can pass the request mode as an option to `useRequest`:
+
+```tsx
+const { posts } = useRequest(
+  {
+    posts: { list: PostView },
+  },
+  {
+    mode: 'stale-while-revalidate',
+  },
+);
+```
+
 ## List Views
 
 ### Pagination with `useListView`
@@ -497,7 +542,7 @@ const CommentConnectionView = {
   items: {
     node: CommentView,
   },
-} as const;
+};
 
 const PostView = view<Post>()({
   comments: CommentConnectionView,
@@ -915,7 +960,7 @@ export const postDataView = dataView<PostItem>('Post')({
   content: true,
   id: true,
   title: true,
-} as const;
+});
 ```
 
 ### Data View Lists
@@ -950,6 +995,25 @@ export const Root = {
 
 Entries that wrap their view in `list(...)` are treated as list resolvers and use the `procedure` name when calling the corresponding router procedure, defaulting to `list`. If you omit `list(...)`, fate treats the entry as a standard query and uses the view type name to infer the router name.
 
+For the above `Root` definitions, you can make the following requests using `useRequest`:
+
+```tsx
+const query = 'Apple';
+
+const { posts, categories, viewer } = useRequest({
+  // Explicit Root queries:
+  categories: { list: categoryView },
+  commentSearch: { args: { query }, list: commentView },
+  events: { list: eventView },
+  posts: { list: postView },
+  viewer: { view: userView },
+
+  // Queries by id, if those entities have a `byId` query defined:
+  post: { id: '12', view: postView },
+  comment: { ids: ['6', '7'], view: commentView },
+});
+```
+
 ### Data View Resolvers
 
 fate data views support resolvers for computed fields. If we want to add a `commentCount` field to our `Post` data view, we can use the `resolver` helper that defines a Prisma selection for the database query together with a `resolve` function:
@@ -1015,34 +1079,30 @@ _Note: fate uses the specified server module name to extract the server types it
 
 ### Creating a _fate_ Client
 
-Now that we have generated the client types, all that remains is creating the instance of the fate client, and using it in our React app using the `FateClient` context provider.
-
-Create a `fate.ts` file:
-
-```tsx
-import { createFateClient } from './lib/fate.generated';
-
-export const fate = createFateClient({
-  links: [
-    httpBatchLink({
-      fetch: (input, init) =>
-        fetch(input, {
-          ...init,
-          credentials: 'include',
-        }),
-      url: `${env('SERVER_URL')}/trpc`,
-    }),
-  ],
-});
-```
-
-Now wrap your app with the `FateClient` provider:
+Now that we have generated the client types, all that remains is creating an instance of the fate client, and using it in our React app using the `FateClient` context provider:
 
 ```tsx
+import { httpBatchLink } from '@trpc/client';
 import { FateClient } from 'react-fate';
-import { fate } from './fate.ts';
+import { createFateClient } from './fate.ts';
 
 export function App() {
+  const fate = useMemo(
+    () =>
+      createFateClient({
+        links: [
+          httpBatchLink({
+            fetch: (input, init) =>
+              fetch(input, {
+                ...init,
+                credentials: 'include',
+              }),
+            url: `${env('SERVER_URL')}/trpc`,
+          }),
+        ],
+      }),
+    [],
+  );
   return <FateClient client={fate}>{/* Components go here */}</FateClient>;
 }
 ```
@@ -1076,14 +1136,14 @@ Probably. One day. _Maybe._
 
 ## Future
 
-**_fate_** is not complete yet. It lacks core features such as garbage collection, a compiler to extract view definitions statically and ahead of time, and there is too much backend boilerplate. The current implementation of _fate_ is not tied to tRPC or Prisma, those are just the ones we are starting with. We welcome contributions and ideas to improve fate. Here are some features we'd like to add:
+**_fate_** is not complete yet. The library lacks core features such as garbage collection, a compiler to extract view definitions statically ahead of time, and there is too much backend boilerplate. The current implementation of _fate_ is not tied to tRPC or Prisma, those are just the ones we are starting with. We welcome contributions and ideas to improve fate. Here are some features we'd like to add:
 
 - Support for Drizzle
 - Support backends other than tRPC
+- Persistent storage for offline support
+- Implement garbage collection for the cache
 - Better code generation and less type repetition
 - Support for live views and real-time updates via `useLiveView` and SSE
-- Implement garbage collection for the cache
-- Add persistent storage for offline support
 
 ## Acknowledgements
 

package/lib/cli.mjs

@@ -135,7 +135,8 @@ const generate = async () => {
 				if (procedureName === root$1.procedure && type === "query") queryEntries.push({
 					name: queryName,
 					procedure: root$1.procedure,
-					router
+					router,
+					type: root$1.type
 				});
 			}
 			for (const [listName, root$1] of routerRoots) {
@@ -143,7 +144,8 @@ const generate = async () => {
 				if (procedureName === root$1.procedure && type === "query") listEntries.push({
 					list: listName,
 					procedure: root$1.procedure,
-					router
+					router,
+					type: root$1.type
 				});
 			}
 		}
@@ -152,6 +154,24 @@ const generate = async () => {
 	byIdEntries.sort((a, b) => a.entityType.localeCompare(b.entityType));
 	queryEntries.sort((a, b) => a.name.localeCompare(b.name));
 	listEntries.sort((a, b) => a.list.localeCompare(b.list));
+	const rootEntries = [
+		...byIdEntries.map(({ entityType, router }) => ({
+			name: router,
+			type: entityType,
+			value: `'${router}': clientRoot<RouterOutputs['${router}']['byId'], '${entityType}'>('${entityType}'),`
+		})),
+		...queryEntries.map(({ name, procedure, router, type }) => ({
+			name,
+			type,
+			value: `'${name}': clientRoot<RouterOutputs['${router}']['${procedure}'], '${type}'>('${type}'),`
+		})),
+		...listEntries.map(({ list, procedure, router, type }) => ({
+			name: list,
+			type,
+			value: `'${list}': clientRoot<RouterOutputs['${router}']['${procedure}'], '${type}'>('${type}'),`
+		}))
+	];
+	rootEntries.sort((a, b) => a.name.localeCompare(b.name));
 	const viewTypes = Array.from(["AppRouter", ...new Set(mutationEntries.map((entry) => entry.entityType))]).sort();
 	const mutationResolverLines = mutationEntries.map(({ name, procedure, router }) => `'${name}': (client: TRPCClientType) => client.${router}.${procedure}.mutate,`);
 	const mutationConfigLines = mutationEntries.map(({ entityType, name, procedure, router }) => `'${name}': mutation<
@@ -176,6 +196,7 @@ const generate = async () => {
 	const mutationResolverBlock = indentBlock(mutationResolverLines.join("\n"), 4);
 	const mutationConfigBlock = indentBlock(mutationConfigLines.join("\n"), 2);
 	const byIdBlock = indentBlock(byIdLines.join("\n"), 8);
+	const rootsBlock = indentBlock(rootEntries.map((entry) => entry.value).join("\n"), 2);
 	const listsBlockContent = listLines.join("\n");
 	const listsBlock = listLines.length ? `      lists: {\n${indentBlock(listsBlockContent, 8)}\n      },\n` : "";
 	const queriesBlockContent = queryLines.join("\n");
@@ -183,7 +204,7 @@ const generate = async () => {
 ${typeImports}
 import { createTRPCProxyClient } from '@trpc/client';
 import { inferRouterInputs, inferRouterOutputs } from '@trpc/server';
-import { createClient, createTRPCTransport, mutation } from 'react-fate';
+import { clientRoot, createClient, createTRPCTransport, mutation } from 'react-fate';
 
 type TRPCClientType = ReturnType<typeof createTRPCProxyClient<AppRouter>>;
 type RouterInputs = inferRouterInputs<AppRouter>;
@@ -193,10 +214,16 @@ const mutations = {
 ${mutationConfigBlock}
 } as const;
 
+const roots = {
+${rootsBlock}
+} as const;
+
 type GeneratedClientMutations = typeof mutations;
+type GeneratedClientRoots = typeof roots;
 
 declare module 'react-fate' {
   interface ClientMutations extends GeneratedClientMutations {}
+  interface ClientRoots extends GeneratedClientRoots {}
 }
 
 export const createFateClient = (options: {
@@ -208,8 +235,9 @@ export const createFateClient = (options: {
 ${mutationResolverBlock}
   } as const;
 
-  return createClient({
+  return createClient<[GeneratedClientRoots, GeneratedClientMutations]>({
     mutations,
+    roots,
     transport: createTRPCTransport<AppRouter, typeof trpcMutations>({
       byId: {
 ${byIdBlock}

package/lib/index.d.mts

@@ -1,14 +1,19 @@
-import { A as __FateEntityBrand, B as createTRPCTransport, C as ViewData, D as ViewSelection, E as ViewRef, F as FateClient, I as RequestMode, L as RequestOptions, M as isViewTag, N as FateMutations, O as ViewSnapshot, P as mutation, R as createClient, S as View, T as ViewEntityName, V as getSelectionPlan, _ as RequestResult, a as Entity, b as TypeConfig, c as Mask, d as MutationIdentifier, f as MutationInput, g as Request, h as Pagination, i as ConnectionTag, j as __FateSelectionBrand, k as ViewTag, l as MutationDefinition, m as NodesItem, n as ConnectionMetadata, o as EntityId, p as MutationResult, r as ConnectionRef, s as ListItem, t as AnyRecord, u as MutationEntity, v as Selection, w as ViewEntity, x as TypeName, y as Snapshot, z as Transport } from "./types-BPmcnouE.mjs";
+import { A as ViewSelection, B as RequestOptions, C as TypeConfig, D as ViewEntity, E as ViewData, F as isViewTag, H as Transport, I as FateMutations, L as mutation, M as ViewTag, N as __FateEntityBrand, O as ViewEntityName, P as __FateSelectionBrand, R as FateClient, S as Snapshot, T as View, U as createTRPCTransport, V as createClient, W as getSelectionPlan, _ as Pagination, a as Entity, b as RootDefinition, c as FateThenable, d as MutationDefinition, f as MutationEntity, g as NodesItem, h as MutationResult, i as ConnectionTag, j as ViewSnapshot, k as ViewRef, l as ListItem, m as MutationInput, n as ConnectionMetadata, o as EntityId, p as MutationIdentifier, r as ConnectionRef, s as FateRoots, t as AnyRecord, u as Mask, v as Request, w as TypeName, x as Selection, y as RequestResult, z as RequestMode } from "./types-CNKGKRtz.mjs";
 
-//#region src/ref.d.ts
+//#region src/root.d.ts
 
+/**
+ * Defines a root query for an entity type, capturing the response shape.
+ */
+declare function clientRoot<Result, Type extends TypeName>(type: Type): RootDefinition<Type, Result>;
+//#endregion
+//#region src/ref.d.ts
 /**
  * Builds the canonical cache ID for an entity.
  */
 declare const toEntityId: (type: TypeName, rawId: string | number) => EntityId;
 //#endregion
 //#region src/view.d.ts
-
 type SelectionValidation<T extends Entity, S extends Selection<T>> = Exclude<keyof Omit<S, typeof __FateEntityBrand | typeof __FateSelectionBrand>, keyof Selection<T>> extends never ? unknown : never;
 /**
  * Creates a reusable view for an object using the declared selection.
@@ -21,4 +26,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 FateMutations, type AnyRecord as FateRecord, type ListItem, type Mask, type MutationDefinition, type MutationEntity, type MutationIdentifier, type MutationInput, type MutationResult, type NodesItem, type Pagination, type 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, createClient, createTRPCTransport, getSelectionPlan, isViewTag, mutation, toEntityId, view };
+export { type ConnectionMetadata, type ConnectionRef, ConnectionTag, type Entity, type EntityId, FateClient, type FateMutations, type AnyRecord as FateRecord, type FateRoots, type FateThenable, type ListItem, type Mask, type MutationDefinition, type MutationEntity, type MutationIdentifier, type MutationInput, type MutationResult, type NodesItem, type Pagination, type 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, createTRPCTransport, getSelectionPlan, isViewTag, mutation, toEntityId, view };

package/lib/index.mjs

@@ -422,6 +422,8 @@ function isNodesItem(item) {
 function isQueryItem(item) {
 	return "view" in item && !("id" in item) && !("ids" in item);
 }
+/** Brand used on root definitions to mark their identity in the d.ts output. */
+const RootKind = "__fate__root";
 /** Brand used on mutation definitions to mark their identity in the d.ts output. */
 const MutationKind = "__fate__mutation";
 
@@ -1006,18 +1008,18 @@ const getRequestCacheKey = (request) => {
 		const item = request[name];
 		if (!item) continue;
 		if (isNodeItem(item)) {
-			parts.push(`node:${name}:${item.type}:${getViewSignature(item.view)}:${item.id}`);
+			parts.push(`node:${name}:${getViewSignature(item.view)}:${item.id}`);
 			continue;
 		}
 		if (isNodesItem(item)) {
-			parts.push(`node:${name}:${item.type}:${getViewSignature(item.view)}:${item.ids.map(serializeId).join(",")}`);
+			parts.push(`node:${name}:${getViewSignature(item.view)}:${item.ids.map(serializeId).join(",")}`);
 			continue;
 		}
 		if (isQueryItem(item)) {
-			parts.push(`query:${name}:${item.type}:${getViewSignature(item.view)}:${item.args ? hashArgs(item.args) : ""}`);
+			parts.push(`query:${name}:${getViewSignature(item.view)}:${item.args ? hashArgs(item.args) : ""}`);
 			continue;
 		}
-		parts.push(`list:${name}:${item.type}:${getViewSignature(item.list)}:${item.args ? hashArgs(item.args) : ""}`);
+		parts.push(`list:${name}:${getViewSignature(item.list)}:${item.args ? hashArgs(item.args) : ""}`);
 	}
 	return parts.join("$");
 };
@@ -1055,14 +1057,15 @@ var FateClient = class {
 		this.stalledRequests = /* @__PURE__ */ new Set();
 		this.store = new Store();
 		this.viewDataCache = new ViewDataCache();
+		this.actions = Object.create(null);
+		this.mutationMap = Object.create(null);
+		this.mutations = Object.create(null);
+		this.roots = options.roots;
 		this.transport = options.transport;
 		this.types = new Map(options.types.map((entity) => [entity.type, {
 			getId,
 			...entity
 		}]));
-		this.mutationMap = Object.create(null);
-		this.mutations = Object.create(null);
-		this.actions = Object.create(null);
 		if (options.mutations) for (const [key, definition] of Object.entries(options.mutations)) {
 			const mutation$1 = wrapMutation(this, {
 				...definition,
@@ -1423,30 +1426,34 @@ var FateClient = class {
 		this.executeRequest(request, { fetchAll: true }).catch(() => {});
 		return result;
 	}
+	getRootType(name) {
+		const root = this.roots[name];
+		if (!root) throw new Error(`fate: Unknown root request '${name}'.`);
+		return root.type;
+	}
 	async executeRequest(request, options = {}) {
 		const fetchAll = options.fetchAll ?? false;
 		const groups = /* @__PURE__ */ new Map();
 		const promises = [];
 		for (const [name, item] of Object.entries(request)) {
+			const type = this.getRootType(name);
 			const isNode = isNodeItem(item);
 			if (isNode || isNodesItem(item)) {
 				const plan = getSelectionPlan(item.view, null);
 				const fields = plan.paths;
-				const fieldsSignature = [...fields].slice().sort().join(",");
-				const argsSignature = [...plan.args.entries()].map(([path, entry]) => `${path}:${entry.hash}`).sort().join(",");
-				const groupKey = `${item.type}#${fieldsSignature}|${argsSignature}`;
+				const groupKey = `${type}#${[...fields].slice().sort().join(",")}|${[...plan.args.entries()].map(([path, entry]) => `${path}:${entry.hash}`).sort().join(",")}`;
 				let group = groups.get(groupKey);
 				if (!group) {
 					group = {
 						fields,
 						ids: [],
 						plan,
-						type: item.type
+						type
 					};
 					groups.set(groupKey, group);
 				}
 				for (const raw of isNode ? [item.id] : item.ids) {
-					const entityId = toEntityId(item.type, raw);
+					const entityId = toEntityId(type, raw);
 					const missing = this.store.missingForSelection(entityId, fields);
 					if (fetchAll || missing.size > 0) group.ids.push(raw);
 				}
@@ -1462,10 +1469,11 @@ var FateClient = class {
 	hasRequestData(request) {
 		for (const [name, item] of Object.entries(request)) {
 			const isNode = isNodeItem(item);
+			const type = this.getRootType(name);
 			if (isNode || isNodesItem(item)) {
 				const fields = getSelectionPlan(item.view, null).paths;
 				for (const raw of isNode ? [item.id] : item.ids) {
-					const entityId = toEntityId(item.type, raw);
+					const entityId = toEntityId(type, raw);
 					if (this.store.missingForSelection(entityId, fields).size > 0) return false;
 				}
 				continue;
@@ -1483,19 +1491,20 @@ var FateClient = class {
 	getRequestResult(request) {
 		const result = {};
 		for (const [name, item] of Object.entries(request)) {
+			const type = this.getRootType(name);
 			if (isNodeItem(item)) {
-				result[name] = this.ref(item.type, item.id, item.view);
+				result[name] = this.ref(type, item.id, item.view);
 				continue;
 			}
 			if (isNodesItem(item)) {
-				result[name] = item.ids.map((id$1) => this.ref(item.type, id$1, item.view));
+				result[name] = item.ids.map((id$1) => this.ref(type, id$1, item.view));
 				continue;
 			}
 			if (isQueryItem(item)) {
 				const entityId = this.rootRequests.get(name);
 				if (entityId) {
 					const { id: id$1 } = parseEntityId(entityId);
-					result[name] = createRef(item.type, id$1, item.view, { root: true });
+					result[name] = createRef(type, id$1, item.view, { root: true });
 				} else result[name] = null;
 				continue;
 			}
@@ -1519,7 +1528,7 @@ var FateClient = class {
 					owner: name,
 					procedure: `request.${name}`,
 					root: true,
-					type: item.type
+					type
 				};
 				Object.defineProperty(connection, ConnectionTag, {
 					configurable: false,
@@ -1543,21 +1552,22 @@ var FateClient = class {
 		if (!this.transport.fetchQuery) throw new Error(`fate: transport does not support queries. Please add support for 'fetchQuery' in your transport for '${name}'.`);
 		const record = await this.transport.fetchQuery(name, plan.paths, argsPayload);
 		if (!record || typeof record !== "object") return;
-		const entityId = this.writeEntity(item.type, record, plan.paths, void 0, plan);
+		const entityId = this.writeEntity(this.getRootType(name), record, plan.paths, void 0, plan);
 		this.rootRequests.set(name, entityId);
 	}
 	async fetchListAndNormalize(name, item) {
 		if (!this.transport.fetchList) throw new Error(`fate: 'transport.fetchList' is not configured but request includes a list for key '${name}'.`);
+		const type = this.getRootType(name);
 		const { argsPayload, plan } = this.resolveSelection(item.list, item.args);
 		const { items, pagination } = await this.transport.fetchList(name, plan.paths, argsPayload);
 		const ids = [];
 		const cursors = [];
 		for (const entry of items) {
-			const id$1 = this.writeEntity(item.type, entry.node, plan.paths, void 0, plan);
+			const id$1 = this.writeEntity(type, entry.node, plan.paths, void 0, plan);
 			ids.push(id$1);
 			cursors.push(entry.cursor);
 		}
-		this.registerRootList(item.type, name);
+		this.registerRootList(type, name);
 		this.store.setList(name, {
 			cursors,
 			ids,
@@ -1590,6 +1600,10 @@ var FateClient = class {
 			} else if (relationDescriptor && typeof relationDescriptor === "object" && "type" in relationDescriptor) {
 				if (isFieldBlocked) continue;
 				const childPaths = selectionTree.get(key) ?? emptySet;
+				if (value === null) {
+					result[key] = null;
+					continue;
+				}
 				if (value && typeof value === "object" && !isNodeRef(value)) {
 					const childType = relationDescriptor.type;
 					const childConfig = this.types.get(childType);
@@ -1600,6 +1614,10 @@ var FateClient = class {
 			} else if (relationDescriptor && typeof relationDescriptor === "object" && "listOf" in relationDescriptor) {
 				if (isFieldBlocked) continue;
 				const childPaths = selectionTree.get(key) ?? emptySet;
+				if (value === null) {
+					result[key] = null;
+					continue;
+				}
 				const childType = relationDescriptor.listOf;
 				const childConfig = this.types.get(childType);
 				if (!childConfig) throw new Error(`fate: Unknown related type '${childType}' (field '${type}.${key}').`);
@@ -1745,6 +1763,10 @@ var FateClient = class {
 					if (!(key in target)) target[key] = {};
 					const nextSelection = Object.keys(selectionWithoutArgs).length ? selectionWithoutArgs : selectionValue;
 					const value = record$1[key];
+					if (value == null) {
+						target[key] = null;
+						continue;
+					}
 					if (Array.isArray(value)) if (nextSelection.items && typeof nextSelection.items === "object") {
 						const selection = nextSelection.items;
 						const fieldArgs = plan.args.get(fieldPath);
@@ -1912,4 +1934,16 @@ function createTRPCTransport({ byId, client, lists, mutations, queries }) {
 }
 
 //#endregion
-export { ConnectionTag, FateClient, createClient, createTRPCTransport, getSelectionPlan, isViewTag, mutation, toEntityId, view };
+//#region src/root.ts
+/**
+* Defines a root query for an entity type, capturing the response shape.
+*/
+function clientRoot(type) {
+	return Object.freeze({
+		[RootKind]: true,
+		type
+	});
+}
+
+//#endregion
+export { ConnectionTag, FateClient, clientRoot, createClient, createTRPCTransport, getSelectionPlan, isViewTag, mutation, toEntityId, view };

package/lib/server.d.mts

@@ -1,4 +1,4 @@
-import { t as AnyRecord } from "./types-BPmcnouE.mjs";
+import { t as AnyRecord } from "./types-CNKGKRtz.mjs";
 import { z } from "zod";
 import { TRPCProcedureBuilder } from "@trpc/server";
 

package/lib/{types-BPmcnouE.d.mts → types-CNKGKRtz.d.mts}

@@ -164,8 +164,9 @@ type RequestMode = /** (default) Use cached data if present, otherwise fetch. */
 type RequestOptions = Readonly<{
   mode?: RequestMode;
 }>;
-type FateClientOptions<Mutations extends FateMutations = EmptyMutations> = {
+type FateClientOptions<Roots extends FateRoots, Mutations extends FateMutations> = {
   mutations?: Mutations;
+  roots: Roots;
   transport: Transport<MutationMapFromDefinitions<Mutations>>;
   types: ReadonlyArray<Omit<TypeConfig, 'getId'> & Partial<{
     getId: TypeConfig['getId'];
@@ -175,7 +176,7 @@ type FateClientOptions<Mutations extends FateMutations = EmptyMutations> = {
  * Core client that normalizes records, manages the view cache, and coordinates
  * data fetching.
  */
-declare class FateClient<Mutations extends FateMutations> {
+declare class FateClient<Roots extends FateRoots, Mutations extends FateMutations> {
   private readonly mutationMap;
   private readonly parentLists;
   private readonly rootLists;
@@ -192,7 +193,8 @@ declare class FateClient<Mutations extends FateMutations> {
   private readonly viewDataCache;
   readonly actions: MutationActionsFor<Mutations>;
   readonly mutations: MutationFunctionsFor<Mutations>;
-  constructor(options: FateClientOptions<Mutations>);
+  readonly roots: Roots;
+  constructor(options: FateClientOptions<Roots, Mutations>);
   private initializeParentLists;
   private registerRootList;
   private insertIntoRootLists;
@@ -228,12 +230,13 @@ declare class FateClient<Mutations extends FateMutations> {
     ids: ReadonlyArray<EntityId>;
     pagination?: Pagination;
   }> | undefined>;
-  request<R$1 extends Request>(request: R$1, options?: RequestOptions): Promise<RequestResult<R$1>>;
+  request<R$1 extends Request>(request: R$1, options?: RequestOptions): Promise<RequestResult<Roots, R$1>>;
   releaseRequest(request: Request, mode: RequestMode): void;
   private handleStoreAndNetworkRequest;
+  private getRootType;
   private executeRequest;
   private hasRequestData;
-  getRequestResult<R$1 extends Request>(request: R$1): RequestResult<R$1>;
+  getRequestResult<R$1 extends Request>(request: R$1): RequestResult<Roots, R$1>;
   private fetchByIdAndNormalize;
   private fetchQueryAndNormalize;
   private fetchListAndNormalize;
@@ -245,7 +248,7 @@ declare class FateClient<Mutations extends FateMutations> {
   private pendingPrefix;
   private pendingKey;
 }
-declare function createClient<Mutations extends FateMutations = EmptyMutations>(options: FateClientOptions<Mutations>): FateClient<Mutations>;
+declare function createClient<T$1 extends [FateRoots, FateMutations] = [Record<never, RootDefinition<any, any>>, Record<never, MutationDefinition<any, any, any>>]>(options: FateClientOptions<T$1[0], T$1[1]>): FateClient<T$1[0], T$1[1]>;
 //#endregion
 //#region src/mutation.d.ts
 /**
@@ -303,7 +306,6 @@ type MutationIdentifierFor<K$1 extends string, Def extends MutationDefinition<an
 }> : never;
 type UnionToIntersection<U$1> = (U$1 extends any ? (k: U$1) => void : never) extends ((k: infer I) => void) ? I : never;
 type NestedValue<Path extends string, Value> = Path extends `${infer Head}.${infer Tail}` ? { [K in Head]: NestedValue<Tail, Value> } : { [K in Path]: Value };
-type EmptyMutations = Record<never, MutationDefinition<any, any, any>>;
 /**
  * Base type for client mutations.
  */
@@ -328,6 +330,8 @@ declare const __FateSelectionBrand: unique symbol;
 declare const __FateMutationEntityBrand: unique symbol;
 declare const __FateMutationInputBrand: unique symbol;
 declare const __FateMutationResultBrand: unique symbol;
+declare const __FateRootResultBrand: unique symbol;
+declare const __FateRootTypeBrand: unique symbol;
 type __ViewEntityAnchor<T$1 extends Entity> = {
   readonly [__FateEntityBrand]?: T$1;
 };
@@ -343,12 +347,21 @@ type __MutationInputAnchor<I$1> = {
 type __MutationResultAnchor<R$1> = {
   readonly [__FateMutationResultBrand]?: R$1;
 };
+type __RootResultAnchor<R$1> = {
+  readonly [__FateRootResultBrand]?: R$1;
+};
+type __RootTypeAnchor<T$1 extends TypeName> = {
+  readonly [__FateRootTypeBrand]?: T$1;
+};
 /** Unique key that identifies a view composition entry inside a selection or reference. */
 type ViewTag = `__fate-view__${string}`;
 /** Determines whether a property key is a fate view tag. */
 declare function isViewTag(key: string): key is ViewTag;
 /** Alias for a loose record used throughout the fate's internals. */
 type AnyRecord = Record<string, unknown>;
+type Nullish<T$1> = Extract<T$1, null | undefined>;
+type NonNullish<T$1> = Exclude<T$1, null | undefined>;
+type WithNullish<T$1, R$1> = R$1 | Nullish<T$1>;
 type SelectionArgs = Readonly<{
   args: AnyRecord;
 }>;
@@ -478,7 +491,8 @@ type EntityName<T$1> = T$1 extends {
   __typename: infer N extends string;
 } ? N : never;
 /** Recursively applies a view selection to an entity to mask fields that aren't selected. */
-type Mask<T$1, S> = T$1 extends Array<infer U extends Entity> ? S extends true ? Array<U> : S extends ConnectionSelection<U> ? ConnectionMask<U, S> : HasViewTag<S> extends true ? Array<ViewRef<U['__typename']>> : Array<Mask<U, S>> : S extends true ? T$1 : S extends object ? HasViewTag<S> extends true ? ViewRef<EntityName<NonNullable<T$1>>> : { [K in keyof S as K extends 'args' ? never : K]: S[K] extends true ? NonNullable<T$1>[Extract<K, keyof T$1>] : Mask<NonNullable<T$1>[Extract<K, keyof T$1>], Extract<S[K], object>> } & (T$1 extends Entity ? Pick<NonNullable<T$1>, '__typename'> : Record<never, never>) : T$1;
+type MaskNonNullish<T$1, S> = T$1 extends Array<infer U extends Entity> ? S extends true ? Array<U> : S extends ConnectionSelection<U> ? ConnectionMask<U, S> : HasViewTag<S> extends true ? Array<ViewRef<U['__typename']>> : Array<Mask<U, S>> : S extends true ? T$1 : S extends object ? HasViewTag<S> extends true ? NonNullish<T$1> extends Entity ? ViewRef<EntityName<NonNullish<T$1>>> : ViewRef<EntityName<NonNullable<T$1>>> : { [K in keyof S as K extends 'args' ? never : K]: S[K] extends true ? NonNullish<T$1>[Extract<K, keyof T$1>] : Mask<NonNullish<T$1>[Extract<K, keyof T$1>], Extract<S[K], object>> } & (T$1 extends Entity ? Pick<NonNullish<T$1>, '__typename'> : Record<never, never>) : T$1;
+type Mask<T$1, S> = WithNullish<T$1, MaskNonNullish<NonNullish<T$1>, S>>;
 /** Entity type captured from a view definition. */
 type ViewEntity<V> = V extends View<infer T, any> ? T : never;
 /** Name of the entity type captured from a view definition. */
@@ -491,24 +505,20 @@ type ViewSelection<V> = V extends {
 type ListItem<V extends View<any, any>> = Readonly<{
   args?: Record<string, unknown>;
   list: V;
-  type: ViewEntityName<V>;
 }>;
 /** Definition of a root-level query request. */
 type QueryItem<V extends View<any, any>> = Readonly<{
   args?: Record<string, unknown>;
-  type: ViewEntityName<V>;
   view: V;
 }>;
 /** Definition of a node request with one explicit ID for fetching data from the backend. */
 type NodeItem<V extends View<any, any>> = Readonly<{
   id: string | number;
-  type: ViewEntityName<V>;
   view: V;
 }>;
 /** Definition of a node request with explicit IDs for fetching data from the backend. */
 type NodesItem<V extends View<any, any>> = Readonly<{
   ids: ReadonlyArray<string | number>;
-  type: ViewEntityName<V>;
   view: V;
 }>;
 type RequestItem = ListItem<View<any, any>> | NodeItem<View<any, any>> | NodesItem<View<any, any>> | QueryItem<View<any, any>>;
@@ -530,7 +540,7 @@ type ConnectionNodeType<Root> = Root extends {
     node?: infer Node;
   };
 } ? ViewEntityName<Node & View<any, any>> : never;
-type ListResult<Item extends AnyRequestItem> = Item extends AnyNodeItem ? ViewRef<Item['type']> : Item extends AnyNodesItem ? Array<ViewRef<Item['type']>> : Item extends AnyQueryItem ? ViewRef<Item['type']> : Item extends AnyListItem ? Item['list'] extends {
+type ListResult<Item extends AnyRequestItem, Type extends TypeName, Result> = Item extends AnyNodeItem ? ViewRef<Type> : Item extends AnyNodesItem ? Array<ViewRef<Type>> : Item extends AnyQueryItem ? Result extends null ? ViewRef<Type> | null : ViewRef<Type> : Item extends AnyListItem ? Item['list'] extends {
   items?: {
     node?: View<any, any>;
   };
@@ -540,14 +550,27 @@ type ListResult<Item extends AnyRequestItem> = Item extends AnyNodeItem ? ViewRe
     node: ViewRef<ConnectionNodeType<Item['list']>>;
   }>;
   pagination?: Pagination;
-}> : Array<ViewRef<Item['type']>> : never;
+}> : Array<ViewRef<Type>> : never;
 /**
  * The result of a `FateClient.request` and `useRequest` call, mapping each
  * request key to its corresponding result.
  */
-type RequestResult<Q extends AnyRequest> = { [K in keyof Q]: ListResult<Q[K]> };
+type RequestResult<R$1 extends FateRoots, Q extends AnyRequest> = { [K in keyof Q]: K extends keyof R$1 ? ListResult<Q[K], RootType<R$1[K]>, RootResult<R$1[K]>> : never };
+/** Brand used on root definitions to mark their identity in the d.ts output. */
+declare const RootKind = "__fate__root";
 /** Brand used on mutation definitions to mark their identity in the d.ts output. */
 declare const MutationKind = "__fate__mutation";
+/** Metadata describing a root query for a particular entity and result shape. */
+type RootDefinition<Type extends TypeName, Result> = Readonly<{
+  [RootKind]: true;
+  type: Type;
+}> & __RootResultAnchor<Result> & __RootTypeAnchor<Type>;
+/** Minimal root description used for typing root maps. */
+type FateRoots = Record<string, RootDefinition<TypeName, unknown>>;
+/** Extracts the entity type name from a root definition. */
+type RootType<R$1> = R$1 extends __RootTypeAnchor<infer T> ? T : never;
+/** Extracts the result type from a root definition. */
+type RootResult<R$1> = R$1 extends __RootResultAnchor<infer Data> ? Data : never;
 /** Metadata describing a mutation for a particular entity, input, and output. */
 type MutationDefinition<T$1 extends Entity, I$1, R$1> = Readonly<{
   entity: T$1['__typename'];
@@ -575,8 +598,6 @@ type MutationMapFromDefinitions<D extends FateMutations> = { [K in keyof D]: {
   input: MutationInput<D[K]>;
   output: MutationResult<D[K]>;
 } };
-type Nullish<T$1> = Extract<T$1, null | undefined>;
-type NonNullish<T$1> = Exclude<T$1, null | undefined>;
 type OptimisticUpdateValue<T$1> = T$1 extends ReadonlyArray<infer U> ? Array<OptimisticUpdateValue<U>> : NonNullish<T$1> extends AnyRecord ? OptimisticUpdate<NonNullish<T$1>> | Nullish<T$1> : NonNullish<T$1> | Nullish<T$1>;
 /** Shape used to describe optimistic updates for mutations. */
 type OptimisticUpdate<T$1> = { [K in keyof T$1]?: OptimisticUpdateValue<T$1[K]> };
@@ -591,4 +612,4 @@ interface FateThenable<T$1> extends PromiseLike<T$1> {
   value: T$1;
 }
 //#endregion
-export { __FateEntityBrand as A, createTRPCTransport as B, ViewData as C, ViewSelection as D, ViewRef as E, FateClient as F, RequestMode as I, RequestOptions as L, isViewTag as M, FateMutations as N, ViewSnapshot as O, mutation as P, createClient as R, View as S, ViewEntityName as T, getSelectionPlan as V, RequestResult as _, Entity as a, TypeConfig as b, Mask as c, MutationIdentifier as d, MutationInput as f, Request as g, Pagination as h, ConnectionTag as i, __FateSelectionBrand as j, ViewTag as k, MutationDefinition as l, NodesItem as m, ConnectionMetadata as n, EntityId as o, MutationResult as p, ConnectionRef as r, ListItem as s, AnyRecord as t, MutationEntity as u, Selection as v, ViewEntity as w, TypeName as x, Snapshot as y, Transport as z };
+export { ViewSelection as A, RequestOptions as B, TypeConfig as C, ViewEntity as D, ViewData as E, isViewTag as F, Transport as H, FateMutations as I, mutation as L, ViewTag as M, __FateEntityBrand as N, ViewEntityName as O, __FateSelectionBrand as P, FateClient as R, Snapshot as S, View as T, createTRPCTransport as U, createClient as V, getSelectionPlan as W, Pagination as _, Entity as a, RootDefinition as b, FateThenable as c, MutationDefinition as d, MutationEntity as f, NodesItem as g, MutationResult as h, ConnectionTag as i, ViewSnapshot as j, ViewRef as k, ListItem as l, MutationInput as m, ConnectionMetadata as n, EntityId as o, MutationIdentifier as p, ConnectionRef as r, FateRoots as s, AnyRecord as t, Mask as u, Request as v, TypeName as w, Selection as x, RequestResult as y, RequestMode as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/fate",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "description": "fate is a modern data client for React.",
   "homepage": "https://github.com/nkzw-tech/fate",
   "repository": {