react-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/index.d.mts

@@ -1,7 +1,18 @@
-import { ConnectionRef, FateClient as FateClient$1, FateMutations, Pagination, Request, RequestOptions, RequestResult, View, ViewData, ViewEntity, ViewEntityName, ViewRef, ViewRef as ViewRef$1, ViewSelection, createClient, createTRPCTransport, mutation, view } from "@nkzw/fate";
+import { ConnectionRef, FateClient as FateClient$1, FateMutations, FateRoots, Pagination, Request, RequestOptions, RequestResult, View, ViewData, ViewEntity, ViewEntityName, ViewRef, ViewRef as ViewRef$1, ViewSelection, clientRoot, createClient, createTRPCTransport, mutation, toEntityId, view } from "@nkzw/fate";
 import { ReactNode } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
+//#region src/useRequest.d.ts
+type Roots = keyof ClientRoots extends never ? FateRoots : ClientRoots;
+/**
+ * Declares the data a screen needs and kicks off fetching, suspending while the
+ * request resolves.
+ *
+ * @example
+ * const { posts } = useRequest({ posts: { list: PostView } });
+ */
+declare function useRequest<R extends Request, O extends FateRoots = Roots>(request: R, options?: RequestOptions): RequestResult<O, R>;
+//#endregion
 //#region src/context.d.ts
 type Mutations = keyof ClientMutations extends never ? FateMutations : ClientMutations;
 /**
@@ -12,12 +23,12 @@ declare function FateClient({
   client
 }: {
   children: ReactNode;
-  client: FateClient$1<any>;
+  client: FateClient$1<any, any>;
 }): react_jsx_runtime0.JSX.Element;
 /**
  * Returns the nearest `FateClient` from context.
  */
-declare function useFateClient<M extends Mutations>(): FateClient$1<M>;
+declare function useFateClient<T extends [Roots, Mutations]>(): FateClient$1<T[0], T[1]>;
 //#endregion
 //#region src/useView.d.ts
 type ViewEntityWithTypename<V extends View<any, any>> = ViewEntity<V> & {
@@ -29,17 +40,7 @@ type ViewEntityWithTypename<V extends View<any, any>> = ViewEntity<V> & {
  * @example
  * const post = useView(PostView, postRef);
  */
-declare function useView<V extends View<any, any>>(view: V, ref: ViewRef$1<ViewEntityName<V>>): ViewData<ViewEntityWithTypename<V>, ViewSelection<V>>;
-//#endregion
-//#region src/useRequest.d.ts
-/**
- * Declares the data a screen needs and kicks off fetching, suspending while the
- * request resolves.
- *
- * @example
- * const { posts } = useRequest({ posts: { root: PostView, type: 'Post' } as const });
- */
-declare function useRequest<R extends Request>(request: R, options?: RequestOptions): RequestResult<R>;
+declare function useView<V extends View<any, any>, R extends ViewRef$1<ViewEntityName<V>> | null>(view: V, ref: R): R extends null ? null : ViewData<ViewEntityWithTypename<V>, ViewSelection<V>>;
 //#endregion
 //#region src/useListView.d.ts
 type ConnectionItems<C> = C extends {
@@ -62,5 +63,6 @@ declare function useListView<C extends {
 //#endregion
 //#region src/index.d.ts
 interface ClientMutations {}
+interface ClientRoots {}
 //#endregion
-export { ClientMutations, type ConnectionRef, FateClient, type ViewRef, createClient, createTRPCTransport, mutation, useFateClient, useListView, useRequest, useView, view };
+export { ClientMutations, ClientRoots, type ConnectionRef, FateClient, type ViewRef, clientRoot, createClient, createTRPCTransport, mutation, toEntityId, useFateClient, useListView, useRequest, useView, view };

package/lib/index.mjs

@@ -1,4 +1,4 @@
-import { ConnectionTag, createClient, createTRPCTransport, isViewTag, mutation, view } from "@nkzw/fate";
+import { ConnectionTag, clientRoot, createClient, createTRPCTransport, isViewTag, mutation, toEntityId, view } from "@nkzw/fate";
 import { createContext, use, useCallback, useDeferredValue, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 import { jsx } from "react/jsx-runtime";
 
@@ -24,25 +24,34 @@ function useFateClient() {
 
 //#endregion
 //#region src/useView.tsx
-/**
-* Resolves a reference against a view and subscribes to updates for that selection.
-*
-* @example
-* const post = useView(PostView, postRef);
-*/
+const nullSnapshot = {
+	status: "fulfilled",
+	then(onfulfilled, onrejected) {
+		return Promise.resolve(null).then(onfulfilled, onrejected);
+	},
+	value: null
+};
 function useView(view$1, ref) {
 	const client = useFateClient();
 	const snapshotRef = useRef(null);
 	const getSnapshot = useCallback(() => {
-		const snapshot = client.readView(view$1, ref);
-		snapshotRef.current = snapshot.status === "fulfilled" ? snapshot.value : null;
-		return snapshot;
+		if (ref === null) {
+			snapshotRef.current = null;
+			return nullSnapshot;
+		}
+		const snapshot$1 = client.readView(view$1, ref);
+		snapshotRef.current = snapshot$1.status === "fulfilled" ? snapshot$1.value : null;
+		return snapshot$1;
 	}, [
 		client,
 		view$1,
 		ref
 	]);
-	return use(useDeferredValue(useSyncExternalStore(useCallback((onStoreChange) => {
+	const snapshot = use(useDeferredValue(useSyncExternalStore(useCallback((onStoreChange) => {
+		if (ref === null) {
+			snapshotRef.current = null;
+			return () => {};
+		}
 		const subscriptions = /* @__PURE__ */ new Map();
 		const onChange = () => {
 			updateSubscriptions();
@@ -68,7 +77,8 @@ function useView(view$1, ref) {
 			for (const unsubscribe of subscriptions.values()) unsubscribe();
 			subscriptions.clear();
 		};
-	}, [client.store]), getSnapshot, getSnapshot))).data;
+	}, [client.store, ref]), getSnapshot, getSnapshot)));
+	return snapshot ? snapshot.data : null;
 }
 
 //#endregion
@@ -78,7 +88,7 @@ function useView(view$1, ref) {
 * request resolves.
 *
 * @example
-* const { posts } = useRequest({ posts: { root: PostView, type: 'Post' } as const });
+* const { posts } = useRequest({ posts: { list: PostView } });
 */
 function useRequest(request, options) {
 	const client = useFateClient();
@@ -173,4 +183,4 @@ function useListView(selection, connection) {
 }
 
 //#endregion
-export { FateClient, createClient, createTRPCTransport, mutation, useFateClient, useListView, useRequest, useView, view };
+export { FateClient, clientRoot, createClient, createTRPCTransport, mutation, toEntityId, useFateClient, useListView, useRequest, useView, view };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-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": {
@@ -28,7 +28,7 @@
     "lib"
   ],
   "dependencies": {
-    "@nkzw/fate": "^0.0.8"
+    "@nkzw/fate": "^0.1.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.7",