react-fate 1.0.3 → 1.2.0

package/lib/index.d.mts

@@ -1,10 +1,8 @@
-import { ConnectionRef, FateClient as FateClient$1, FateMutations, FateRoots, InferFateAPI, Pagination, Request, RequestOptions, RequestResult, View, ViewData, ViewEntity, ViewEntityName, ViewRef, ViewRef as ViewRef$1, ViewSelection, clientRoot, createClient, createHTTPTransport, createTRPCTransport, mutation, toEntityId, view } from "@nkzw/fate";
+import { ConnectionRef, Deferred, Deferred as Deferred$1, FateClient as FateClient$1, FateDehydratedState, FateMutations, FateRoots, GraphQLMutationDefinition, GraphQLMutationInput, GraphQLMutationMap, GraphQLMutationOutput, GraphQLTransportOptions, HydrateOptions, HydrationLimits, InferFateAPI, Pagination, Pagination as Pagination$1, Request, RequestOptions, RequestResult, View, ViewData, ViewEntity, ViewEntityName, ViewRef, ViewRef as ViewRef$1, ViewSelection, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, defer, graphqlMutation, mutation, toEntityId, view } from "@nkzw/fate";
 import { ReactNode } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
-import * as _$react_fate_client0 from "react-fate/client";
 
 //#region src/useRequest.d.ts
-type GeneratedFateClient$1 = ReturnType<typeof _$react_fate_client0.createFateClient>;
+type GeneratedFateClient$1 = ReturnType<typeof import('react-fate/client').createFateClient>;
 type Roots = [GeneratedFateClient$1] extends [never] ? FateRoots : GeneratedFateClient$1 extends FateClient$1<infer R, any> ? R : FateRoots;
 /**
  * Declares the data a screen needs and kicks off fetching, suspending while the
@@ -16,7 +14,7 @@ type Roots = [GeneratedFateClient$1] extends [never] ? FateRoots : GeneratedFate
 declare function useRequest<R extends Request, O extends FateRoots = Roots>(request: R, options?: RequestOptions): RequestResult<O, R>;
 //#endregion
 //#region src/context.d.ts
-type GeneratedFateClient = ReturnType<typeof _$react_fate_client0.createFateClient>;
+type GeneratedFateClient = ReturnType<typeof import('react-fate/client').createFateClient>;
 type Mutations = [GeneratedFateClient] extends [never] ? FateMutations : GeneratedFateClient extends FateClient$1<any, infer M> ? M : FateMutations;
 /**
  * Provider component that supplies a configured `FateClient` to React hooks.
@@ -27,7 +25,7 @@ declare function FateClient({
 }: {
   children: ReactNode;
   client: FateClient$1<any, any>;
-}): _$react_jsx_runtime0.JSX.Element;
+}): import("react").JSX.Element;
 /**
  * Returns the nearest `FateClient` from context.
  */
@@ -45,6 +43,7 @@ type ViewEntityWithTypename$1<V extends View<any, any>> = ViewEntity<V> & {
  * const post = useLiveView(PostView, postRef);
  */
 declare function useLiveView<V extends View<any, any>, R extends ViewRef$1<ViewEntityName<V>> | null>(view: V, ref: R): R extends null ? null : ViewData<ViewEntityWithTypename$1<V>, ViewSelection<V>>;
+declare function useLiveView<V extends View<any, any>, R extends Deferred$1<ViewRef$1<ViewEntityName<V>>> | null>(view: V, ref: R): R extends null ? null : ViewData<ViewEntityWithTypename$1<V>, ViewSelection<V>>;
 //#endregion
 //#region src/listView.d.ts
 type ConnectionItems<C> = C extends {
@@ -58,14 +57,16 @@ type ConnectionSelection = {
 };
 //#endregion
 //#region src/useLiveListView.d.ts
+type ConnectionValue$1 = {
+  items?: ReadonlyArray<any>;
+  pagination?: Pagination$1;
+};
+type ResolvedConnection$1<C> = C extends Deferred$1<infer Value> ? Value : NonNullable<C>;
 /**
  * Subscribes to a connection field, returning live-updating items and pagination
  * helpers to load the next or previous page.
  */
-declare function useLiveListView<C extends {
-  items?: ReadonlyArray<any>;
-  pagination?: Pagination;
-} | null | undefined>(selection: ConnectionSelection, connection: C): [ConnectionItems<NonNullable<C>>, LoadMoreFn | null, LoadMoreFn | null];
+declare function useLiveListView<C extends ConnectionValue$1 | Deferred$1<ConnectionValue$1> | null | undefined>(selection: ConnectionSelection, connection: C): [ConnectionItems<ResolvedConnection$1<C>>, LoadMoreFn | null, LoadMoreFn | null];
 //#endregion
 //#region src/useView.d.ts
 type ViewEntityWithTypename<V extends View<any, any>> = ViewEntity<V> & {
@@ -78,15 +79,19 @@ type ViewEntityWithTypename<V extends View<any, any>> = ViewEntity<V> & {
  * const post = useView(PostView, postRef);
  */
 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>>;
+declare function useView<V extends View<any, any>, R extends Deferred$1<ViewRef$1<ViewEntityName<V>>> | null>(view: V, ref: R): R extends null ? null : ViewData<ViewEntityWithTypename<V>, ViewSelection<V>>;
+declare function useView<V extends View<any, any>>(view: V, ref: Deferred$1<ViewRef$1<ViewEntityName<V>>> | ViewRef$1<ViewEntityName<V>> | null): ViewData<ViewEntityWithTypename<V>, ViewSelection<V>> | null;
 //#endregion
 //#region src/useListView.d.ts
+type ConnectionValue = {
+  items?: ReadonlyArray<any>;
+  pagination?: Pagination$1;
+};
+type ResolvedConnection<C> = C extends Deferred$1<infer Value> ? Value : NonNullable<C>;
 /**
  * Subscribes to a connection field, returning the current items and pagination
  * helpers to load the next or previous page.
  */
-declare function useListView<C extends {
-  items?: ReadonlyArray<any>;
-  pagination?: Pagination;
-} | null | undefined>(selection: ConnectionSelection, connection: C): [ConnectionItems<NonNullable<C>>, LoadMoreFn | null, LoadMoreFn | null];
+declare function useListView<C extends ConnectionValue | Deferred$1<ConnectionValue> | null | undefined>(selection: ConnectionSelection, connection: C): [ConnectionItems<ResolvedConnection<C>>, LoadMoreFn | null, LoadMoreFn | null];
 //#endregion
-export { type ConnectionRef, FateClient, type InferFateAPI, type ViewRef, clientRoot, createClient, createHTTPTransport, createTRPCTransport, mutation, toEntityId, useFateClient, useListView, useLiveListView, useLiveView, useRequest, useView, view };
+export { type ConnectionRef, type Deferred, FateClient, type FateDehydratedState, type GraphQLMutationDefinition, type GraphQLMutationInput, type GraphQLMutationMap, type GraphQLMutationOutput, type GraphQLTransportOptions, type HydrateOptions, type HydrationLimits, type InferFateAPI, type Pagination, type ViewRef, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, defer, graphqlMutation, mutation, toEntityId, useFateClient, useListView, useLiveListView, useLiveView, useRequest, useView, view };

package/lib/index.mjs

@@ -1,4 +1,4 @@
-import { ConnectionTag, clientRoot, createClient, createHTTPTransport, createTRPCTransport, isViewTag, mutation, toEntityId, view } from "@nkzw/fate";
+import { ConnectionTag, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, defer, graphqlMutation, isDeferred, isViewTag, mutation, toEntityId, view } from "@nkzw/fate";
 import { createContext, use, useCallback, useDeferredValue, useEffect, useEffectEvent, useMemo, useRef, useSyncExternalStore } from "react";
 import { jsx } from "react/jsx-runtime";
 import { getListEntries } from "@nkzw/fate/list";
@@ -22,6 +22,16 @@ function useFateClient() {
 	return context;
 }
 //#endregion
+//#region src/thenable.ts
+const isFulfilledThenable = (value) => "status" in value && value.status === "fulfilled" && "value" in value;
+const fulfilledThenable = (value) => ({
+	status: "fulfilled",
+	then(onfulfilled, onrejected) {
+		return Promise.resolve(value).then(onfulfilled, onrejected);
+	},
+	value
+});
+//#endregion
 //#region src/useView.tsx
 const nullSnapshot = {
 	status: "fulfilled",
@@ -32,19 +42,99 @@ const nullSnapshot = {
 };
 function useView(view, ref) {
 	const client = useFateClient();
+	const isDeferredRef = isDeferred(ref);
 	const snapshotRef = useRef(null);
+	const mergedSnapshotRef = useRef(null);
+	const pendingRef = useRef(null);
+	const readViewSnapshot = useCallback((viewRef, coverage = [], cacheKey) => {
+		const snapshot = client.readView(view, viewRef);
+		const mergeCoverage = (value) => ({
+			...value,
+			coverage: coverage.length ? [...coverage, ...value.coverage] : value.coverage
+		});
+		if (isFulfilledThenable(snapshot)) {
+			if (coverage.length) {
+				const cached = mergedSnapshotRef.current;
+				const resolvedKey = `${viewRef.__typename}:${String(viewRef.id)}`;
+				if (cached?.source === snapshot.value && cached.cacheKey === cacheKey && cached.resolvedKey === resolvedKey) {
+					snapshotRef.current = cached.thenable.value;
+					return cached.thenable;
+				}
+				const value = mergeCoverage(snapshot.value);
+				const thenable = fulfilledThenable(value);
+				mergedSnapshotRef.current = {
+					cacheKey,
+					resolvedKey,
+					source: snapshot.value,
+					thenable
+				};
+				snapshotRef.current = value;
+				return thenable;
+			}
+			mergedSnapshotRef.current = null;
+			snapshotRef.current = snapshot.value;
+			return snapshot;
+		}
+		mergedSnapshotRef.current = null;
+		snapshotRef.current = null;
+		return Promise.resolve(snapshot).then((value) => {
+			const resolved = mergeCoverage(value);
+			snapshotRef.current = resolved;
+			return resolved;
+		});
+	}, [client, view]);
 	const getSnapshot = useCallback(() => {
 		if (ref === null) {
 			snapshotRef.current = null;
 			return nullSnapshot;
 		}
-		const snapshot = client.readView(view, ref);
-		snapshotRef.current = snapshot.status === "fulfilled" ? snapshot.value : null;
-		return snapshot;
+		if (!isDeferredRef) {
+			pendingRef.current = null;
+			return readViewSnapshot(ref);
+		}
+		const deferred = ref;
+		const deferredSnapshot = client.readDeferred(deferred);
+		if (isFulfilledThenable(deferredSnapshot)) {
+			const resolvedRef = deferredSnapshot.value.data;
+			pendingRef.current = null;
+			if (resolvedRef === null) {
+				snapshotRef.current = {
+					coverage: deferredSnapshot.value.coverage,
+					data: null
+				};
+				return fulfilledThenable(snapshotRef.current);
+			}
+			return readViewSnapshot(client.ref(resolvedRef.__typename, resolvedRef.id, view), deferredSnapshot.value.coverage, deferred);
+		}
+		if (pendingRef.current?.deferred === ref && pendingRef.current.snapshot === deferredSnapshot) return pendingRef.current.viewSnapshot;
+		snapshotRef.current = null;
+		const viewSnapshot = Promise.resolve(deferredSnapshot).then((deferredValue) => {
+			const resolvedRef = deferredValue.data;
+			if (resolvedRef === null) {
+				const value = {
+					coverage: deferredValue.coverage,
+					data: null
+				};
+				snapshotRef.current = value;
+				return value;
+			}
+			return Promise.resolve(readViewSnapshot(client.ref(resolvedRef.__typename, resolvedRef.id, view), deferredValue.coverage, deferred)).then((value) => {
+				snapshotRef.current = value;
+				return value;
+			});
+		});
+		pendingRef.current = {
+			deferred,
+			snapshot: deferredSnapshot,
+			viewSnapshot
+		};
+		return viewSnapshot;
 	}, [
 		client,
 		view,
-		ref
+		ref,
+		isDeferredRef,
+		readViewSnapshot
 	]);
 	const snapshot = use(useDeferredValue(useSyncExternalStore(useCallback((onStoreChange) => {
 		if (ref === null) {
@@ -83,12 +173,14 @@ function useView(view, ref) {
 //#region src/useLiveView.tsx
 function useLiveView(view, ref) {
 	const client = useFateClient();
-	const liveId = ref?.id;
-	const liveType = ref?.__typename;
+	const resolvedRef = isDeferred(ref) ? use(client.readDeferred(ref)).data : ref;
+	const liveRef = resolvedRef ? client.ref(resolvedRef.__typename, resolvedRef.id, view) : null;
+	const liveId = liveRef?.id;
+	const liveType = liveRef?.__typename;
 	const subscribeLiveView = useEffectEvent(() => {
-		if (ref === null) return;
+		if (liveRef === null) return;
 		client.assertLiveViewSupport();
-		return client.subscribeLiveView(view, ref);
+		return client.subscribeLiveView(view, liveRef);
 	});
 	useEffect(() => subscribeLiveView(), [
 		client,
@@ -120,11 +212,12 @@ const useListViewInfo = (selection, connection) => ({
 */
 function useListView(selection, connection) {
 	const client = useFateClient();
-	const { metadata, nodeView } = useListViewInfo(selection, connection);
+	const resolvedConnection = isDeferred(connection) ? use(client.readDeferred(connection)).data : connection;
+	const { metadata, nodeView } = useListViewInfo(selection, resolvedConnection);
 	const subscribe = useCallback((onStoreChange) => metadata ? client.store.subscribeList(metadata.key, onStoreChange) : () => {}, [client, metadata]);
 	const getSnapshot = useCallback(() => metadata ? client.store.getListState(metadata.key) : void 0, [client, metadata]);
 	const listState = useDeferredValue(useSyncExternalStore(subscribe, getSnapshot, getSnapshot));
-	const pagination = listState?.pagination ?? connection?.pagination;
+	const pagination = listState?.pagination ?? resolvedConnection?.pagination;
 	const hasNext = Boolean(pagination?.hasNext);
 	const hasPrevious = Boolean(pagination?.hasPrevious);
 	const nextCursor = pagination?.nextCursor;
@@ -135,10 +228,10 @@ function useListView(selection, connection) {
 				cursor,
 				node: client.rootListRef(id, nodeView)
 			}));
-			return connection?.items;
+			return resolvedConnection?.items;
 		}, [
 			client,
-			connection?.items,
+			resolvedConnection?.items,
 			listState,
 			metadata,
 			nodeView
@@ -193,7 +286,8 @@ function useListView(selection, connection) {
 */
 function useLiveListView(selection, connection) {
 	const client = useFateClient();
-	const { metadata, nodeView } = useListViewInfo(selection, connection);
+	const resolvedConnection = isDeferred(connection) ? use(client.readDeferred(connection)).data : connection;
+	const { metadata, nodeView } = useListViewInfo(selection, resolvedConnection);
 	const subscribeLiveListView = useEffectEvent(() => {
 		if (!metadata) return;
 		client.assertLiveConnectionSupport();
@@ -204,7 +298,7 @@ function useLiveListView(selection, connection) {
 		metadata?.key,
 		nodeView
 	]);
-	return useListView(selection, connection);
+	return useListView(selection, resolvedConnection);
 }
 //#endregion
 //#region src/useRequest.tsx
@@ -233,4 +327,4 @@ function useRequest(request, options) {
 	return use(useDeferredValue(promise));
 }
 //#endregion
-export { FateClient, clientRoot, createClient, createHTTPTransport, createTRPCTransport, mutation, toEntityId, useFateClient, useListView, useLiveListView, useLiveView, useRequest, useView, view };
+export { FateClient, clientRoot, createClient, createGraphQLTransport, createHTTPTransport, createTRPCTransport, defer, graphqlMutation, mutation, toEntityId, useFateClient, useListView, useLiveListView, useLiveView, useRequest, useView, view };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-fate",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "fate is a modern data client for React.",
   "homepage": "https://github.com/nkzw-tech/fate",
   "license": "MIT",
@@ -40,13 +40,13 @@
     }
   },
   "dependencies": {
-    "@nkzw/fate": "^1.0.3"
+    "@nkzw/fate": "^1.2.0"
   },
   "devDependencies": {
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.16",
     "@types/react-dom": "^19.2.3",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6"
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
   },
   "peerDependencies": {
     "react": "^19.2.0",