@nkzw/fate 0.0.1 → 0.0.3

package/README.md

@@ -10,8 +10,6 @@
 
 **_fate_** is a modern data client for React and tRPC inspired by [Relay](https://relay.dev/) and [GraphQL](https://graphql.org/). It combines view composition, normalized caching, data masking, Async React features, and tRPC's type safety.
 
-**_fate_** is designed to make data fetching and state management in React applications more composable, declarative, and predictable. The framework has a minimal API, no DSL, and no magic—_it's just JavaScript_.
-
 ### Features
 
 - **View Composition:** Components declare their data requirements using co-located "views". Views are composed into a single request per screen, minimizing network requests and eliminating waterfalls.
@@ -26,7 +24,7 @@
 
 **_fate_** is designed to make data fetching and state management in React applications more composable, declarative, and predictable. The framework has a minimal API, no DSL, and no magic—_it's just JavaScript_.
 
-GraphQL and Relay introduced several novel ideas: fragments co‑located with components, a normalized cache 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.
+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.
 
@@ -40,14 +38,66 @@ _[Learn more](/docs/guide/getting-started.md) about fate's core concepts and fea
 
 ## Getting Started
 
-### Installation
+### Template
 
-**_fate_** requires React 19.2+.
+Get started with [a ready-made template](https://github.com/nkzw-tech/fate-template) quickly:
 
-```bash
-pnpm add react-fate @nkzw/fate
+::: code-group
+
+```npm
+npx giget@latest gh:nkzw-tech/fate-template
+```
+
+```pnpm
+pnpx giget@latest gh:nkzw-tech/fate-template
+```
+
+```yarn
+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.
+
+### Manual Installation
+
+**_fate_** requires React 19.2+. For your client you need to install `react-fate`:
+
+::: code-group
+
+```npm
+npm add react-fate
 ```
 
+```pnpm
+pnpm add react-fate
+```
+
+```yarn
+yarn add react-fate
+```
+
+:::
+
+And for your server, install the core `@nkzw/fate` package:
+
+::: code-group
+
+```npm
+npm add @nkzw/fate
+```
+
+```pnpm
+pnpm add @nkzw/fate
+```
+
+```yarn
+yarn add @nkzw/fate
+```
+
+:::
+
 > [!WARNING]
 >
 > **_fate_** is currently in alpha and not production ready. If something doesn't work for you, please open a pull request.
@@ -56,11 +106,11 @@ If you'd like to try the example app in GitHub Codespaces, click the button belo
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?repo=nkzw-tech/fate)
 
-### Core Concepts
+## Core Concepts
 
 **_fate_** has a minimal API surface and is aimed at reducing data fetching complexity.
 
-#### Thinking in Views
+### Thinking in Views
 
 In fate, each component declares the data it needs using views. Views are composed upward through the component tree until they reach a root, where the actual request is made. fate fetches all required data in a single request. React Suspense manages loading states, and any data-fetching errors naturally bubble up to React error boundaries. This eliminates the need for imperative loading logic or manual error handling.
 
@@ -122,7 +172,7 @@ export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
 };
 ```
 
-A `ViewRef` is a reference to an object of a specific type, in this case a `Post`. It contains the unique ID for the object, the type name (as `__typename`) and some fate-specific metadata. fate creates and manages these references for you, and you can pass them around your components as needed.
+A `ViewRef` is a reference to a concrete object of a specific type, for example a `Post` with id `7`. It contains the unique ID of the object, the type name (as `__typename`) and some fate-specific metadata. fate creates and manages these references for you, and you can pass them around your components as needed.
 
 Components using `useView` listen to changes for all selected fields. When data changes, fate re-renders all of the fields that depend on that data. For example, if the `title` of the `Post` changes, the `PostCard` component re-renders with new data. However, if a different field such as `likes` that isn't selected in `PostView` changes, the `PostCard` component will not re-render.
 
@@ -304,7 +354,7 @@ export const PostView = view<Post>()({
 });
 ```
 
-Views are opaque objects. Even if you select the same field multiple times through different views, the composed object won't have conflicting fiels or result in TypeScript errors. fate automatically deduplicates fields during runtime and ensures that each field is only fetched once.
+Views are opaque objects. Even if you select the same field multiple times through different views, the composed object won't have conflicting fields or result in TypeScript errors. fate automatically deduplicates fields during runtime and ensures that each field is only fetched once.
 
 ### `useView` and Suspense
 
@@ -691,7 +741,7 @@ useEffect(() => {
 
 ## 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.
+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.
 
 ### Conventions & Object Identity
 

package/lib/server.mjs

@@ -265,19 +265,28 @@ function resolver(config) {
 }
 const isResolverField = (field) => Boolean(field) && typeof field === "object" && "kind" in field && field.kind === "resolver";
 const isDataViewField = (field) => Boolean(field) && typeof field === "object" && "fields" in field;
-const filterToViewFields = (item, view) => {
+const filterToViewFields = (item, view, selectedPaths, prefix = null) => {
 	if (!isRecord(item)) return item;
 	const filtered = {};
 	for (const [field, config] of Object.entries(view.fields)) {
+		const path = prefix ? `${prefix}.${field}` : field;
+		let hasSelection = selectedPaths.has(path);
+		if (!hasSelection) {
+			for (const selected of selectedPaths) if (selected.startsWith(`${path}.`)) {
+				hasSelection = true;
+				break;
+			}
+		}
+		if (!hasSelection) continue;
 		if (!(field in item)) continue;
 		const value = item[field];
 		if (isDataViewField(config)) {
 			if (Array.isArray(value)) {
-				filtered[field] = value.map((entry) => isRecord(entry) ? filterToViewFields(entry, config) : entry);
+				filtered[field] = value.map((entry) => isRecord(entry) ? filterToViewFields(entry, config, selectedPaths, path) : entry);
 				continue;
 			}
 			if (isRecord(value)) {
-				filtered[field] = filterToViewFields(value, config);
+				filtered[field] = filterToViewFields(value, config, selectedPaths, path);
 				continue;
 			}
 		}
@@ -319,14 +328,17 @@ const createSelectedNode = (view, path) => ({
 	resolvers: /* @__PURE__ */ new Map(),
 	view
 });
-const assignPath = (node, segments, path, view, allowedPaths) => {
+const assignPath = (node, segments, path, selectedPaths, view, allowedPaths) => {
 	if (segments.length === 0) return;
 	const [segment, ...rest] = segments;
 	const field = view.fields[segment];
 	if (!field) return;
 	const nextPath = path ? `${path}.${segment}` : segment;
 	if (isResolverField(field)) {
-		if (rest.length === 0) node.resolvers.set(segment, field);
+		if (rest.length === 0) {
+			node.resolvers.set(segment, field);
+			selectedPaths.add(nextPath);
+		}
 		return;
 	}
 	if (isDataViewField(field)) {
@@ -335,23 +347,20 @@ const assignPath = (node, segments, path, view, allowedPaths) => {
 			relationNode = createSelectedNode(field, nextPath);
 			node.relations.set(segment, relationNode);
 		}
+		if (field.fields.id === true) {
+			allowedPaths.add(`${nextPath}.id`);
+			selectedPaths.add(`${nextPath}.id`);
+		}
 		if (rest.length === 0) {
-			collectViewPaths(nextPath, field, allowedPaths);
+			selectedPaths.add(nextPath);
 			return;
 		}
-		assignPath(relationNode, rest, nextPath, field, allowedPaths);
+		assignPath(relationNode, rest, nextPath, selectedPaths, field, allowedPaths);
 		return;
 	}
-	if (rest.length === 0) allowedPaths.add(nextPath);
-};
-const collectViewPaths = (basePath, view, allowedPaths) => {
-	for (const [field, child] of Object.entries(view.fields)) {
-		const nextPath = `${basePath}.${field}`;
-		if (child === true) {
-			allowedPaths.add(nextPath);
-			continue;
-		}
-		if (isDataViewField(child)) collectViewPaths(nextPath, child, allowedPaths);
+	if (rest.length === 0) {
+		allowedPaths.add(nextPath);
+		selectedPaths.add(nextPath);
 	}
 };
 const collectResolvers = (node, select, args$1, context) => {
@@ -409,10 +418,12 @@ const resolveNode = async (options) => {
 */
 function createResolver({ args: args$1, ctx, select: initialSelect, view }) {
 	const allowedPaths = /* @__PURE__ */ new Set();
+	const selectedPaths = /* @__PURE__ */ new Set();
+	selectedPaths.add("id");
 	const root = createSelectedNode(view, null);
 	for (const path of initialSelect) {
 		if (!path) continue;
-		assignPath(root, path.split("."), null, view, allowedPaths);
+		assignPath(root, path.split("."), null, selectedPaths, view, allowedPaths);
 	}
 	const select = prismaSelect([...allowedPaths], args$1);
 	collectResolvers(root, select, args$1, ctx);
@@ -425,7 +436,7 @@ function createResolver({ args: args$1, ctx, select: initialSelect, view }) {
 				args: args$1,
 				context: ctx
 			}
-		}), root.view),
+		}), root.view, selectedPaths),
 		view: root.view
 	});
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/fate",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "fate is a modern data client for React.",
   "homepage": "https://github.com/nkzw-tech/fate",
   "repository": {
@@ -16,17 +16,14 @@
   "exports": {
     ".": {
       "types": "./lib/index.d.mts",
-      "development": "./src/index.ts",
       "default": "./lib/index.mjs"
     },
     "./cli": {
       "types": "./lib/cli.d.mts",
-      "development": "./src/cli.ts",
       "default": "./lib/cli.mjs"
     },
     "./server": {
       "types": "./lib/server.d.mts",
-      "development": "./src/server.ts",
       "default": "./lib/server.mjs"
     }
   },