@nkzw/fate 0.0.2 → 0.0.4

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
 
@@ -992,4 +1042,6 @@ Probably. One day. _Maybe._
 ## Acknowledgements
 
 - [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
+- [Ricky Hanlon](https://x.com/rickyfm) for guidance on Async React
+
+**_fate_** was created by [@cnakazawa](https://x.com/cnakazawa) and is maintained by [Nakazawa Tech](https://nakazawa.tech/).

package/lib/cli.mjs

@@ -9,7 +9,7 @@ const isDataViewField = (field) => Boolean(field) && typeof field === "object" &
 * Builds the schema object used by the CLI generator from your data views and
 * list resolver configs.
 */
-const createFateSchema = (dataViews, lists) => {
+const createSchema = (dataViews, lists) => {
 	const canonicalViews = /* @__PURE__ */ new Map();
 	const entities = {};
 	const fateTypes = /* @__PURE__ */ new Map();
@@ -37,6 +37,7 @@ const createFateSchema = (dataViews, lists) => {
 		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 };
+		ensureType(view);
 	}
 	for (const [name, list] of Object.entries(lists)) {
 		const config = "fields" in list ? { view: list } : list;
@@ -88,8 +89,8 @@ 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 Promise.all([import(moduleName)]);
-	const { entities, types } = createFateSchema(Object.values(dataViews), Lists);
+	const { appRouter, Lists, ...dataViews } = await import(moduleName);
+	const { entities, types } = createSchema(Object.values(dataViews), Lists);
 	const routerRecord = appRouter._def?.record ?? {};
 	const mutationEntries = [];
 	const byIdEntries = [];

package/lib/index.d.mts

@@ -26,8 +26,8 @@ declare const __FateMutationResultBrand: unique symbol;
 type __ViewEntityAnchor<T$1 extends Entity> = {
   readonly [__FateEntityBrand]?: T$1;
 };
-type __ViewSelectionAnchor<S$1> = {
-  [__FateSelectionBrand]?: S$1;
+type __ViewSelectionAnchor<S> = {
+  [__FateSelectionBrand]?: S;
 };
 type __MutationEntityAnchor<T$1 extends Entity> = {
   readonly [__FateMutationEntityBrand]?: T$1;
@@ -126,33 +126,33 @@ type SelectionViewSpread<T$1 extends Entity> = { readonly [K in ViewTag]?: Reado
 /** Declarative selection of the fields a view needs from an entity. */
 type Selection<T$1 extends Entity> = SelectionShape<T$1> & SelectionViewSpread<T$1>;
 /** View payload stored on a view tag containing the raw selection used to mask data. */
-type ViewPayload<T$1 extends Entity, S$1 extends Selection<T$1> = Selection<T$1>> = Readonly<{
-  select: S$1;
+type ViewPayload<T$1 extends Entity, S extends Selection<T$1> = Selection<T$1>> = Readonly<{
+  select: S;
   [ViewKind]: true;
 }>;
 /** Definition of a view over an entity type, including the selection of fields. */
-type View<T$1 extends Entity, S$1 extends Selection<T$1> = Selection<T$1>> = Readonly<{
-  [viewTag: ViewTag]: ViewPayload<T$1, S$1>;
-}> & __ViewEntityAnchor<T$1> & __ViewSelectionAnchor<S$1>;
-type HasViewTag<S$1> = S$1 extends { [K in ViewTag]?: infer P } ? P extends {
+type View<T$1 extends Entity, S extends Selection<T$1> = Selection<T$1>> = Readonly<{
+  [viewTag: ViewTag]: ViewPayload<T$1, S>;
+}> & __ViewEntityAnchor<T$1> & __ViewSelectionAnchor<S>;
+type HasViewTag<S> = S extends { [K in ViewTag]?: infer P } ? P extends {
   [ViewKind]: true;
 } ? true : false : false;
 /**
  * Data returned from a resolved view with masking applied and view tags
  * attached for downstream composition.
  */
-type ViewData<T$1 extends Entity, S$1 extends Selection<T$1>> = Readonly<(S$1 extends Selection<T$1> ? Mask<T$1, S$1> : T$1) & {
+type ViewData<T$1 extends Entity, S extends Selection<T$1>> = Readonly<(S extends Selection<T$1> ? Mask<T$1, S> : T$1) & {
   [ViewsTag]: Set<string>;
 }>;
 /**
  * Snapshot returned by the cache for a view, including the masked data and all
  * referenced entity IDs.
  */
-type ViewSnapshot<T$1 extends Entity, S$1 extends Selection<T$1>> = Readonly<{
+type ViewSnapshot<T$1 extends Entity, S extends Selection<T$1>> = Readonly<{
   coverage: ReadonlyArray<readonly [id: EntityId, paths: ReadonlySet<string>]>;
-  data: ViewData<T$1, S$1>;
+  data: ViewData<T$1, S>;
 }>;
-type ConnectionMask<T$1 extends Entity, S$1> = S$1 extends {
+type ConnectionMask<T$1 extends Entity, S> = S extends {
   items: infer ItemSelection;
   pagination?: infer PaginationSelection;
 } ? {
@@ -173,7 +173,7 @@ 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$1> = T$1 extends Array<infer U extends Entity> ? S$1 extends true ? Array<U> : S$1 extends ConnectionSelection<U> ? ConnectionMask<U, S$1> : HasViewTag<S$1> extends true ? Array<ViewRef<U['__typename']>> : Array<Mask<U, S$1>> : S$1 extends true ? T$1 : S$1 extends object ? HasViewTag<S$1> extends true ? ViewRef<EntityName<NonNullable<T$1>>> : { [K in keyof S$1 as K extends 'args' ? never : K]: S$1[K] extends true ? NonNullable<T$1>[Extract<K, keyof T$1>] : Mask<NonNullable<T$1>[Extract<K, keyof T$1>], Extract<S$1[K], object>> } & (T$1 extends Entity ? Pick<NonNullable<T$1>, '__typename'> : Record<never, never>) : T$1;
+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;
 /** 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. */
@@ -345,15 +345,15 @@ type SelectionPlan = {
  * Flattens a view into a `SelectionPlan`, expanding composed views and
  * partitioning nested args so the client can fetch exactly what is declared.
  */
-declare const getSelectionPlan: <T$1 extends Entity, S$1 extends Selection<T$1>, V extends View<T$1, S$1>>(viewComposition: V, ref: ViewRef<T$1["__typename"]> | null) => SelectionPlan;
+declare const getSelectionPlan: <T$1 extends Entity, S extends Selection<T$1>, V extends View<T$1, S>>(viewComposition: V, ref: ViewRef<T$1["__typename"]> | null) => SelectionPlan;
 //#endregion
 //#region src/cache.d.ts
 declare class ViewDataCache {
   private cache;
   private rootDependencies;
   private dependencyIndex;
-  get<T$1 extends Entity, S$1 extends Selection<T$1>, V extends View<T$1, S$1>>(entityId: EntityId, view: V, ref: ViewRef<T$1['__typename']>): FateThenable<ViewSnapshot<T$1, S$1>> | null;
-  set<T$1 extends Entity, S$1 extends Selection<T$1>, V extends View<T$1, S$1>>(entityId: EntityId, view: V, ref: ViewRef<T$1['__typename']>, thenable: FateThenable<ViewSnapshot<T$1, S$1>>, dependencies: ReadonlySet<EntityId>): void;
+  get<T$1 extends Entity, S extends Selection<T$1>, V extends View<T$1, S>>(entityId: EntityId, view: V, ref: ViewRef<T$1['__typename']>): FateThenable<ViewSnapshot<T$1, S>> | null;
+  set<T$1 extends Entity, S extends Selection<T$1>, V extends View<T$1, S>>(entityId: EntityId, view: V, ref: ViewRef<T$1['__typename']>, thenable: FateThenable<ViewSnapshot<T$1, S>>, dependencies: ReadonlySet<EntityId>): void;
   invalidate(entityId: EntityId): void;
   private invalidateDependents;
   private delete;
@@ -528,7 +528,7 @@ declare class FateClient<Mutations extends Record<string, MutationDefinition<any
     id: string | number;
     [ViewsTag]: Set<string>;
   }>;
-  readView<T$1 extends Entity, S$1 extends Selection<T$1>, V extends View<T$1, S$1>>(view: V, ref: ViewRef<T$1['__typename']>): FateThenable<ViewSnapshot<T$1, S$1>>;
+  readView<T$1 extends Entity, S extends Selection<T$1>, V extends View<T$1, S>>(view: V, ref: ViewRef<T$1['__typename']>): FateThenable<ViewSnapshot<T$1, S>>;
   private mergeListState;
   registerOptimisticUpdate(entityId: EntityId | null, select: ReadonlySet<string>): number | null;
   clearOptimisticUpdate(token: number | null): void;
@@ -570,7 +570,7 @@ declare function createClient<Mutations extends Record<string, MutationDefinitio
 declare const toEntityId: (type: TypeName, rawId: string | number) => EntityId;
 //#endregion
 //#region src/view.d.ts
-type SelectionValidation<T$1 extends Entity, S$1 extends Selection<T$1>> = Exclude<keyof Omit<S$1, typeof __FateEntityBrand | typeof __FateSelectionBrand>, keyof Selection<T$1>> extends never ? unknown : never;
+type SelectionValidation<T$1 extends Entity, S extends Selection<T$1>> = Exclude<keyof Omit<S, typeof __FateEntityBrand | typeof __FateSelectionBrand>, keyof Selection<T$1>> extends never ? unknown : never;
 /**
  * Creates a reusable view for an object using the declared selection.
  *
@@ -580,6 +580,6 @@ type SelectionValidation<T$1 extends Entity, S$1 extends Selection<T$1>> = Exclu
  *   title: true,
  * });
  */
-declare function view<T$1 extends Entity>(): <S$1 extends Selection<T$1>>(select: S$1 & SelectionValidation<T$1, S$1>) => View<T$1, S$1>;
+declare function view<T$1 extends Entity>(): <S extends Selection<T$1>>(select: S & SelectionValidation<T$1, S>) => View<T$1, S>;
 //#endregion
 export { type ConnectionMetadata, type ConnectionRef, ConnectionTag, type Entity, type EntityId, FateClient, 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 };

package/lib/server.d.mts

@@ -51,8 +51,8 @@ type DataViewConfig<Item$1 extends AnyRecord, Context> = Record<string, DataFiel
  *   title: true,
  * });
  */
-declare function dataView<Item$1 extends AnyRecord, Context = unknown>(typeName?: string): <Fields$1 extends DataViewConfig<Item$1, Context>>(fields: Fields$1) => DataView<Item$1, Context> & {
-  readonly [dataViewFieldsKey]: Fields$1;
+declare function dataView<Item$1 extends AnyRecord, Context = unknown>(typeName?: string): <Fields extends DataViewConfig<Item$1, Context>>(fields: Fields) => DataView<Item$1, Context> & {
+  readonly [dataViewFieldsKey]: Fields;
 };
 /**
  * Marks a data view as a list resolver so the server can respond with

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.2",
+  "version": "0.0.4",
   "description": "fate is a modern data client for React.",
   "homepage": "https://github.com/nkzw-tech/fate",
   "repository": {