@nkzw/fate 0.0.6 → 0.0.8

package/README.md

@@ -26,21 +26,42 @@
 
 GraphQL and Relay introduced several novel ideas: fragments co‑located with components, [a normalized cache](https://relay.dev/docs/principles-and-architecture/thinking-in-graphql/#caching-a-graph) keyed by global identifiers, and a compiler that hoists fragments into a single network request. These innovations made it possible to build large applications where data requirements are modular and self‑contained.
 
-Nakazawa Tech builds apps primarily with GraphQL and Relay. We advocate for these technologies in [talks](https://www.youtube.com/watch?v=rxPTEko8J7c&t=36s) and provide templates ([server](https://github.com/nkzw-tech/server-template), [client](https://github.com/nkzw-tech/web-app-template/tree/with-relay)) to help developers get started quickly.
+[Nakazawa Tech](https://nakazawa.tech) builds apps and [games](https://athenacrisis.com) primarily with GraphQL and Relay. We advocate for these technologies in [talks](https://www.youtube.com/watch?v=rxPTEko8J7c&t=36s) and provide templates ([server](https://github.com/nkzw-tech/server-template), [client](https://github.com/nkzw-tech/web-app-template/tree/with-relay)) to help developers get started quickly.
 
 However, GraphQL comes with its own type system and query language. If you are already using tRPC or another type‑safe RPC framework, it's a significant investment to adopt and implement GraphQL on the backend. This investment often prevents teams from adopting Relay on the frontend.
 
 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.
+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:
 
-_[Learn more](/docs/guide/getting-started.md) about fate's core concepts and features._
+```tsx
+export const PostView = view<Post>()({
+  content: true,
+  id: true,
+  title: true,
+  author: UserView,
+});
+
+export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  const post = useView(PostView, postRef);
+
+  return (
+    <Card>
+      <h2>{post.title}</h2>
+      <p>{post.content}</p>
+      <UserCard user={post.author} />
+    </Card>
+  );
+};
+```
+
+_[Learn more](/docs/guide/getting-started.md) about fate's core concepts or get started with [a ready-made template](https://github.com/nkzw-tech/fate-template#readme)._
 
 ## Getting Started
 
 ### Template
 
-Get started with [a ready-made template](https://github.com/nkzw-tech/fate-template) quickly:
+Get started with [a ready-made template](https://github.com/nkzw-tech/fate-template#readme) quickly:
 
 ::: code-group
 
@@ -58,7 +79,7 @@ yarn dlx giget@latest gh:nkzw-tech/fate-template
 
 :::
 
-The `fate-template` comes with a simple tRPC backend and a React frontend using **_fate_**. It features modern tools to deliver an incredibly fast development experience. Follow its [README.md](https://github.com/nkzw-tech/fate-template#fate-quick-start-template) to get started.
+`fate-template` comes with a simple tRPC backend and a React frontend using **_fate_**. It features modern tools to deliver an incredibly fast development experience. Follow its [README.md](https://github.com/nkzw-tech/fate-template#fate-quick-start-template) to get started.
 
 ### Manual Installation
 
@@ -126,6 +147,9 @@ Traditionally, React apps are built with components and hooks. fate introduces a
 
 With fate, you no longer worry about _when_ to fetch data, how to coordinate loading states, or how to handle errors imperatively. You avoid overfetching, stop passing unnecessary data down the tree, and eliminate boilerplate types created solely for passing server data to child components.
 
+> [!NOTE]
+> Views in _fate_ are what fragments are in GraphQL.
+
 ## Views
 
 ### Defining Views
@@ -525,7 +549,11 @@ Mutations in your tRPC backend are made available as actions and mutations by fa
 Let's assume that our `Post` entity has a tRPC mutation for liking a post called `post.like`. A `LikeButton` component using fate Actions and an async component library could then look like this:
 
 ```tsx
+import { useActionState } from 'react';
+import { useFateClient } from 'react-fate';
+
 const LikeButton = ({ post }: { post: { id: string; likes: number } }) => {
+  const fate = useFateClient();
   const [result, like] = useActionState(fate.actions.post.like, null);
 
   return (
@@ -540,6 +568,7 @@ If you are not using an async component library, you can use React's `useTransit
 
 ```tsx
 const LikeButton = ({ post }: { post: { id: string; likes: number } }) => {
+  const fate = useFateClient();
   const [, startTransition] = useTransition();
   const [result, like, isPending] = useActionState(
     fate.actions.post.like,
@@ -661,16 +690,17 @@ export const postRouter = router({
         view: postDataView,
       });
 
-      const updated = await ctx.prisma.post.update({
-        data: {
-          likes: {
-            increment: 1,
+      return resolve(
+        await ctx.prisma.post.update({
+          data: {
+            likes: {
+              increment: 1,
+            },
           },
-        },
-        select,
-        where: { id: input.id },
-      });
-      return resolve(updated as unknown as PostItem);
+          select,
+          where: { id: input.id },
+        } as PostUpdateArgs),
+      );
     }),
 });
 ```
@@ -739,6 +769,26 @@ useEffect(() => {
 }, [like, result]);
 ```
 
+### Controlling List Insertion Behavior
+
+When inserting new objects into lists, the default behavior is to append the new object to the list. You can provide an `insert` option with `before`, `after` or `none` values to customize this behavior and specify where the new object should be inserted in the list:
+
+```tsx
+addComment({
+  input: { content: 'New Comment text', postId: post.id },
+  insert: 'before', // Insert the new comment at the beginning of the list.
+});
+```
+
+Or, use the `none` option if you want to ignore inserting the new object into any lists:
+
+```tsx
+addComment({
+  input: { content: 'New Comment text', postId: post.id },
+  insert: 'none', // Do not insert the new comment into any lists.
+});
+```
+
 ## Server Integration
 
 Until now, we have focused on the client-side API of fate. You'll need a tRPC backend that follows some conventions so you can generate a typed client using fate's CLI. At the moment _fate_ is designed to work with tRPC and Prisma, but the framework is not coupled to any particular ORM or database, it's just what we are starting with.
@@ -785,35 +835,27 @@ _Note: Currently, fate provides helpers to integrate with Prisma, but the framew
 We can apply the above data view in our tRPC router and resolve the client's selection against it using `createResolver`. Here is an example implementation of the `byId` query for the `User` type which allows fetching multiple users by `id`:
 
 ```tsx
-import { connectionArgs, createResolver } from '@nkzw/fate/server';
+import { byIdInput, createResolver } from '@nkzw/fate/server';
 import { z } from 'zod';
 import type { UserFindManyArgs } from '../../prisma/prisma-client/models.ts';
 import { procedure, router } from '../init.ts';
 import { userDataView } from '../views.ts';
 
 export const userRouter = router({
-  byId: procedure
-    .input(
-      z.object({
-        args: connectionArgs,
-        ids: z.array(z.string().min(1)).nonempty(),
-        select: z.array(z.string()),
-      }),
-    )
-    .query(async ({ ctx, input }) => {
-      const { resolveMany, select } = createResolver({
-        ...input,
-        ctx,
-        view: userDataView,
-      });
-
-      const users = await ctx.prisma.user.findMany({
-        select: select,
-        where: { id: { in: input.ids } },
-      } as UserFindManyArgs);
-
-      return await resolveMany(users);
-    }),
+  byId: procedure.input(byIdInput).query(async ({ ctx, input }) => {
+    const { resolveMany, select } = createResolver({
+      ...input,
+      ctx,
+      view: userDataView,
+    });
+
+    const users = await ctx.prisma.user.findMany({
+      select: select,
+      where: { id: { in: input.ids } },
+    } as UserFindManyArgs);
+
+    return await resolveMany(users);
+  }),
 });
 ```
 
@@ -894,29 +936,19 @@ export const postDataView = dataView<PostItem>('Post')({
 });
 ```
 
-We can also define root-level lists by exporting a `Lists` object from our `views.ts` file:
+We can define extra root-level lists and queries by exporting a `Root` object from our `views.ts` file using the same view syntax as everywhere else:
 
 ```tsx
-export const Lists = {
-  posts: postDataView,
+export const Root = {
+  categories: list(categoryDataView),
+  commentSearch: { procedure: 'search', view: list(commentDataView) },
+  events: list(eventDataView),
+  posts: list(postDataView),
+  viewer: userDataView,
 };
 ```
 
-This makes it possible to fetch a list of posts from the client using `useRequest`.
-
-#### Custom Root Lists
-
-You might want to define custom root lists that don't directly map to a single data view. For example, a search endpoint that returns a list of posts based on a search query:
-
-```tsx
-export const Lists = {
-  // …
-  postSearch: { procedure: 'search', view: postDataView },
-  // …
-};
-```
-
-This maps the `postSearch` list to a `search` procedure on your post router.
+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.
 
 ### Data View Resolvers
 
@@ -925,19 +957,33 @@ fate data views support resolvers for computed fields. If we want to add a `comm
 ```tsx
 export const postDataView = dataView<PostItem>('Post')({
   author: userDataView,
-  commentCount: resolver<PostItem>({
-    resolve: ({ item }) => item._count?.comments ?? 0,
+  commentCount: resolver<PostItem, number>({
+    resolve: ({ _count }) => _count?.comments ?? 0,
     select: () => ({
       _count: { select: { comments: true } },
     }),
   }),
   comments: list(commentDataView),
   id: true,
-} as const;
+});
 ```
 
 This definition makes the `commentCount` field available to your client-side views.
 
+### Authorization in Resolvers
+
+You might want to restrict access to certain fields based on the current user or other contextual information. You can do this by adding an `authorize` function to your resolver definition:
+
+```tsx
+export const userDataView = dataView<UserItem>('User')({
+  email: resolver<UserItem, string | null, { sessionUser: string }>({
+    authorize: ({ id }, context) => context?.sessionUserId === id,
+    resolve: ({ email }) => email,
+  }),
+  id: true,
+});
+```
+
 ### Generating a typed client
 
 Now that we have defined our client views and our tRPC server, we need to connect them with some glue code. We recommend using fate's CLI for convenience.
@@ -959,10 +1005,10 @@ export type AppRouter = typeof appRouter;
 export * from './views.ts';
 ```
 
-_Note: We try to keep magic to a minimum and you can handwrite the [generated client](https://github.com/nkzw-tech/fate/blob/main/example/client/src/lib/fate.generated.ts) if you prefer._
+_Note: We try to keep magic to a minimum and you can handwrite the [generated client](https://github.com/nkzw-tech/fate/blob/main/example/client/src/fate.ts) if you prefer._
 
 ```bash
-pnpm fate generate @your-org/server/trpc/router.ts client/src/lib/fate.generated.ts
+pnpm fate generate @your-org/server/trpc/router.ts client/src/fate.ts
 ```
 
 _Note: fate uses the specified server module name to extract the server types it needs and uses the same module name to import the views into the generated client. Make sure that the module is available both at the root where you are running the CLI and in the client package._
@@ -1024,7 +1070,9 @@ Probably. One day. _Maybe._
 ### How was fate built?
 
 > [!NOTE]
-> 80% of _fate_'s code was written by OpenAI's Codex – four versions per task, carefully curated by a human. The remaining 20% was written by [@cnakazawa](https://x.com/cnakazawa). You get to decide which parts are the good ones. The docs were 100% written by a human.
+> 80% of _fate_'s code was written by OpenAI's Codex – four versions per task, carefully curated by a human. The remaining 20% was written by [@cnakazawa](https://x.com/cnakazawa). _You get to decide which parts are the good ones!_ The docs were 100% written by a human.
+>
+> If you contribute to _fate_, we [require you to disclose your use of AI tools](https://github.com/nkzw-tech/fate/blob/main/CONTRIBUTING.md#ai-assistance-notice).
 
 ## Future
 
@@ -1041,5 +1089,6 @@ Probably. One day. _Maybe._
 
 - [Relay](https://relay.dev/), [Isograph](https://isograph.dev/) & [GraphQL](https://graphql.org/) for inspiration
 - [Ricky Hanlon](https://x.com/rickyfm) for guidance on Async React
+- [Anthony Powell](https://x.com/Cephalization) for testing fate and providing feedback
 
-**_fate_** was created by [@cnakazawa](https://x.com/cnakazawa) and is maintained by [Nakazawa Tech](https://nakazawa.tech/).
+**_fate_** was created by [@cnakazawa](https://x.com/cnakazawa) and is maintained by [Nakazawa Tech](https://nakazawa.tech/).

package/lib/cli.mjs

@@ -7,11 +7,11 @@ import { styleText } from "node:util";
 const isDataViewField = (field) => Boolean(field) && typeof field === "object" && "fields" in field;
 /**
 * Builds the schema object used by the CLI generator from your data views and
-* list resolver configs.
+* root resolver configs.
 */
-const createSchema = (dataViews, lists) => {
+const createSchema = (dataViews, roots) => {
 	const canonicalViews = /* @__PURE__ */ new Map();
-	const entities = {};
+	const rootSchema = {};
 	const fateTypes = /* @__PURE__ */ new Map();
 	const processing = /* @__PURE__ */ new Set();
 	const ensureType = (view) => {
@@ -36,20 +36,25 @@ const createSchema = (dataViews, lists) => {
 		const typeName = view.typeName;
 		if (!typeName) throw new Error("Data view is missing a type name.");
 		if (!canonicalViews.has(typeName)) canonicalViews.set(typeName, view);
-		entities[typeName.toLowerCase()] = { type: typeName };
 	}
-	for (const [name, list] of Object.entries(lists)) {
-		const config = "fields" in list ? { view: list } : list;
-		const typeName = ensureType(config.view);
-		entities[typeName.toLowerCase()] = {
-			list: name,
-			listProcedure: config.procedure,
-			type: typeName
+	for (const view of dataViews) ensureType(view);
+	for (const [name, root$1] of Object.entries(roots)) {
+		const config = "fields" in root$1 ? { view: root$1 } : root$1;
+		const view = config.view;
+		const type = ensureType(view);
+		if (!view.typeName) throw new Error(`Root "${name}" is missing a data view.`);
+		const router = config.router ?? view.typeName[0]?.toLowerCase() + view.typeName.slice(1);
+		if (!router) throw new Error(`Root "${name}" is missing a router name.`);
+		rootSchema[name] = {
+			kind: view.kind === "list" ? "list" : "query",
+			procedure: config.procedure ?? (view.kind === "list" ? "list" : name),
+			router,
+			type
 		};
 	}
 	for (const view of dataViews) ensureType(view);
 	return {
-		entities,
+		roots: rootSchema,
 		types: Array.from(fateTypes.values())
 	};
 };
@@ -66,7 +71,7 @@ Generates the fate client from the server's tRPC router.
   ${styleText("dim", "<moduleName>")}  The module name to import the tRPC router from.
   ${styleText("dim", "<targetFile>")}  The file path to write the generated client to.
   
-  ${styleText("bold", "Example:")} ${styleText("blue", `pnpm fate generate @org/server/trpc/router.ts client/lib/fate.generated.ts`)}
+  ${styleText("bold", "Example:")} ${styleText("blue", `pnpm fate generate @org/server/trpc/router.ts client/lib/fate.ts`)}
 `);
 	process.exit(1);
 }
@@ -89,21 +94,29 @@ const formatTypes = (types) => {
 const indentBlock = (value, spaces) => value.split("\n").map((line) => line.length ? `${" ".repeat(spaces)}${line}` : line).join("\n");
 const generate = async () => {
 	console.log(styleText("bold", `Generating fate client…\n`));
-	const { appRouter, Lists, ...dataViews } = await import(moduleName);
-	const { entities, types } = createSchema(Object.values(dataViews), Lists);
+	const { appRouter, Root, ...dataViews } = await import(moduleName);
+	const { roots, types } = createSchema(Object.values(dataViews), Root ?? {});
 	const routerRecord = appRouter._def?.record ?? {};
 	const mutationEntries = [];
 	const byIdEntries = [];
 	const listEntries = [];
+	const queryEntries = [];
+	const rootsByRouter = /* @__PURE__ */ new Map();
+	for (const entry of Object.entries(roots)) {
+		const list = rootsByRouter.get(entry[1].router) ?? [];
+		list.push(entry);
+		rootsByRouter.set(entry[1].router, list);
+	}
 	for (const [router, procedures] of Object.entries(routerRecord)) {
-		const entity = entities[router];
-		if (!entity) continue;
+		const routerRoots = rootsByRouter.get(router);
+		if (!routerRoots?.length) continue;
+		const entityType = routerRoots[0][1].type;
 		for (const [procedureName, procedure] of Object.entries(procedures)) {
 			const type = procedure?._def?.type;
 			if (!type) continue;
 			if (type === "mutation") {
 				mutationEntries.push({
-					entityType: entity.type,
+					entityType,
 					name: `${router}.${procedureName}`,
 					procedure: procedureName,
 					router
@@ -112,21 +125,32 @@ const generate = async () => {
 			}
 			if (procedureName === "byId" && type === "query") {
 				byIdEntries.push({
-					entityType: entity.type,
+					entityType,
 					router
 				});
 				continue;
 			}
-			const listProcedure = entity.listProcedure ?? "list";
-			if (procedureName === listProcedure && type === "query" && entity.list) listEntries.push({
-				list: entity.list,
-				procedure: listProcedure,
-				router
-			});
+			for (const [queryName, root$1] of routerRoots) {
+				if (root$1.kind !== "query") continue;
+				if (procedureName === root$1.procedure && type === "query") queryEntries.push({
+					name: queryName,
+					procedure: root$1.procedure,
+					router
+				});
+			}
+			for (const [listName, root$1] of routerRoots) {
+				if (root$1.kind !== "list") continue;
+				if (procedureName === root$1.procedure && type === "query") listEntries.push({
+					list: listName,
+					procedure: root$1.procedure,
+					router
+				});
+			}
 		}
 	}
 	mutationEntries.sort((a, b) => a.name.localeCompare(b.name));
 	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 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,`);
@@ -146,12 +170,15 @@ const generate = async () => {
     select,
   }),`);
 	const listLines = listEntries.map(({ list, procedure, router }) => `${list}: (client: TRPCClientType) => client.${router}.${procedure}.query,`);
+	const queryLines = queryEntries.map(({ name, procedure, router }) => `${name}: (client: TRPCClientType) => client.${router}.${procedure}.query,`);
 	const typeImports = `import type { ${viewTypes.join(", ")} } from '${moduleName}';`;
 	const typesBlock = indentBlock(formatTypes(types), 6);
 	const mutationResolverBlock = indentBlock(mutationResolverLines.join("\n"), 4);
-	const mutationConfigBlock = indentBlock(mutationConfigLines.join("\n"), 6);
+	const mutationConfigBlock = indentBlock(mutationConfigLines.join("\n"), 2);
 	const byIdBlock = indentBlock(byIdLines.join("\n"), 8);
 	const listsBlockContent = listLines.join("\n");
+	const listsBlock = listLines.length ? `      lists: {\n${indentBlock(listsBlockContent, 8)}\n      },\n` : "";
+	const queriesBlockContent = queryLines.join("\n");
 	const source = `// @generated by \`pnpm fate generate\`
 ${typeImports}
 import { createTRPCProxyClient } from '@trpc/client';
@@ -162,27 +189,35 @@ type TRPCClientType = ReturnType<typeof createTRPCProxyClient<AppRouter>>;
 type RouterInputs = inferRouterInputs<AppRouter>;
 type RouterOutputs = inferRouterOutputs<AppRouter>;
 
+const mutations = {
+${mutationConfigBlock}
+} as const;
+
+type GeneratedClientMutations = typeof mutations;
+
+declare module 'react-fate' {
+  interface ClientMutations extends GeneratedClientMutations {}
+}
+
 export const createFateClient = (options: {
   links: Parameters<typeof createTRPCProxyClient>[0]['links'];
 }) => {
   const trpcClient = createTRPCProxyClient<AppRouter>(options);
 
-  const mutations = {
+  const trpcMutations = {
 ${mutationResolverBlock}
   } as const;
 
   return createClient({
-    mutations: {
-${mutationConfigBlock}
-    },
-    transport: createTRPCTransport<AppRouter, typeof mutations>({
+    mutations,
+    transport: createTRPCTransport<AppRouter, typeof trpcMutations>({
       byId: {
 ${byIdBlock}
       },
       client: trpcClient,
-${listLines.length ? `      lists: {\n${indentBlock(listsBlockContent, 8)}\n      },\n` : ""}      mutations,
+${queryLines.length ? `      queries: {\n${indentBlock(queriesBlockContent, 8)}\n      },\n` : ""}${listsBlock}      mutations: trpcMutations,
     }),
-    types: ${typesBlock},
+    types: ${typesBlock.trimStart()},
   });
 };
 `;