feat: support plural fragments

XiNiHa · XiNiHa · commit 29caaeee567a · 2026-05-18T17:32:09.000+09:00
diff --git a/.changeset/poor-olives-peel.md b/.changeset/poor-olives-peel.md
@@ -0,0 +1,5 @@
+---
+"solid-relay": minor
+---
+
+feat: support plural fragments
diff --git a/src/index.ts b/src/index.ts
@@ -1,5 +1,5 @@
 export { loadQuery, type LoadQueryOptions, type PreloadedQuery } from "./loadQuery";
-export { createFragment } from "./primitives/createFragment";
+export { createFragment, type MaybeArray } from "./primitives/createFragment";
 export { createLazyLoadQuery } from "./primitives/createLazyLoadQuery";
 export { createMutation } from "./primitives/createMutation";
 export { createPaginationFragment } from "./primitives/createPaginationFragment.js";
diff --git a/src/primitives/createFragment.ts b/src/primitives/createFragment.ts
@@ -1,11 +1,23 @@
-import type { GraphQLResponse, GraphQLTaggedNode, Subscribable, Subscription } from "relay-runtime";
+import type {
+	GraphQLResponse,
+	GraphQLTaggedNode,
+	Observer,
+	Subscribable,
+	Subscription,
+} from "relay-runtime";
 import { observeFragment } from "relay-runtime/experimental.js";
+import {
+	ArrayKeyType,
+	ArrayKeyTypeData,
+	FragmentState,
+	KeyType,
+	KeyTypeData,
+} from "relay-runtime/lib/store/FragmentTypes";
 import type { Accessor, Setter, Signal } from "solid-js";
 import { batch, createResource, createSignal, untrack } from "solid-js";
 import { reconcile, type SetStoreFunction, unwrap } from "solid-js/store";
 import { isServer } from "solid-js/web";
 import { useRelayEnvironment } from "../RelayEnvironment";
-import type { KeyType, KeyTypeData } from "../types/keyType";
 import { createDataStore, type DataStore } from "../utils/dataStore";
 
 type FragmentResult<T> =
@@ -50,17 +62,56 @@ export function createFragment<TKey extends KeyType>(
 		deferStream?: boolean;
 	},
 ): DataStore<KeyTypeData<TKey> | null | undefined>;
-export function createFragment<TKey extends KeyType>(
+export function createFragment<TKey extends ArrayKeyType>(
+	fragment: GraphQLTaggedNode,
+	key: Accessor<TKey>,
+	options?: {
+		deferStream?: boolean;
+	},
+): DataStore<ArrayKeyTypeData<TKey>>;
+export function createFragment<TKey extends MaybeArray<ArrayKeyType>>(
+	fragment: GraphQLTaggedNode,
+	key: Accessor<TKey>,
+	options?: {
+		deferStream?: boolean;
+	},
+): DataStore<MaybeArray<ArrayKeyTypeData<RequiredArray<TKey>>>>;
+export function createFragment<TKey extends ArrayKeyType>(
 	fragment: GraphQLTaggedNode,
 	key: Accessor<TKey | null | undefined>,
 	options?: {
 		deferStream?: boolean;
 	},
-): DataStore<KeyTypeData<TKey> | null | undefined> {
+): DataStore<ArrayKeyTypeData<TKey> | null | undefined>;
+export function createFragment<TKey extends MaybeArray<ArrayKeyType>>(
+	fragment: GraphQLTaggedNode,
+	key: Accessor<TKey | null | undefined>,
+	options?: {
+		deferStream?: boolean;
+	},
+): DataStore<MaybeArray<ArrayKeyTypeData<RequiredArray<TKey>>> | null | undefined>;
+export function createFragment<TKey extends KeyType | ArrayKeyType>(
+	fragment: GraphQLTaggedNode,
+	key: Accessor<TKey | null | undefined>,
+	options?: {
+		deferStream?: boolean;
+	},
+): DataStore<Data<TKey> | null | undefined> {
 	return createFragmentInternal(fragment, key, undefined, options);
 }
 
-export function createFragmentInternal<TKey extends KeyType>(
+export type MaybeArray<T> =
+	T extends ReadonlyArray<unknown> ? ReadonlyArray<T[number] | null | undefined> : never;
+type RequiredArray<T> =
+	T extends ReadonlyArray<(infer U) | null | undefined> ? ReadonlyArray<U> : never;
+
+type Data<TKey extends KeyType | ArrayKeyType> = TKey extends KeyType
+	? KeyTypeData<TKey>
+	: TKey extends ArrayKeyType
+		? ArrayKeyTypeData<TKey>
+		: never;
+
+export function createFragmentInternal<TKey extends KeyType | ArrayKeyType>(
 	fragment: GraphQLTaggedNode,
 	key: Accessor<TKey | null | undefined>,
 	options?: Accessor<{
@@ -69,10 +120,9 @@ export function createFragmentInternal<TKey extends KeyType>(
 	createResourceOptions?: {
 		deferStream?: boolean;
 	},
-): DataStore<KeyTypeData<TKey> | null | undefined> {
+): DataStore<Data<TKey> | null | undefined> {
 	const environment = useRelayEnvironment();
 
-	type FragmentObserver = Parameters<ReturnType<typeof observeFragment>["subscribe"]>[0];
 	const resultUpdateObserver = {
 		next(res) {
 			queueMicrotask(() => {
@@ -86,7 +136,7 @@ export function createFragmentInternal<TKey extends KeyType>(
 							setResult("pending", false);
 							setResult(
 								"data",
-								reconcile(res.value as Record<string, unknown>, {
+								reconcile(res.value, {
 									key: "__id",
 									merge: true,
 								}),
@@ -101,11 +151,11 @@ export function createFragmentInternal<TKey extends KeyType>(
 				});
 			});
 		},
-	} satisfies FragmentObserver;
+	} satisfies Observer<FragmentState<unknown>>;
 	const [subscription, setSubscription] = createSignal<Subscription>();
 
 	const setResultQueue: unknown[][] = [];
-	let setResult: SetStoreFunction<FragmentResult<TKey[" $data"]>> = (...args: unknown[]) => {
+	let setResult: SetStoreFunction<FragmentResult<unknown>> = (...args: unknown[]) => {
 		setResultQueue.push(args);
 	};
 
@@ -140,7 +190,7 @@ export function createFragmentInternal<TKey extends KeyType>(
 				});
 			}
 
-			const source = observeFragment(environment(), fragment, key);
+			const source = observeFragment(environment(), fragment, key as KeyType);
 
 			return new Promise<true>((resolve, reject) => {
 				setSubscription(
@@ -173,7 +223,9 @@ export function createFragmentInternal<TKey extends KeyType>(
 
 						if (!fetchedInSameEnv && !current && nextValue && k) {
 							setSubscription(
-								observeFragment(environment(), fragment, k).subscribe(resultUpdateObserver),
+								observeFragment(environment(), fragment, k as KeyType).subscribe(
+									resultUpdateObserver,
+								),
 							);
 						}
 
@@ -184,7 +236,7 @@ export function createFragmentInternal<TKey extends KeyType>(
 		},
 	);
 
-	const store = createDataStore<FragmentResult<TKey[" $data"]>>(
+	const store = createDataStore<FragmentResult<unknown>>(
 		{
 			data: undefined,
 			error: undefined,
@@ -197,5 +249,5 @@ export function createFragmentInternal<TKey extends KeyType>(
 	}
 	setResult = store[1];
 
-	return store[0];
+	return store[0] as DataStore<Data<TKey> | null | undefined>;
 }
diff --git a/src/primitives/createPaginationFragment.ts b/src/primitives/createPaginationFragment.ts
@@ -20,7 +20,6 @@ import {
 import { type Accessor, batch, createEffect, createMemo, createSignal, untrack } from "solid-js";
 import invariant from "tiny-invariant";
 import { useRelayEnvironment } from "../RelayEnvironment";
-import type { KeyType, KeyTypeData } from "../types/keyType";
 import { createFetchTracker } from "../utils/createFetchTracker";
 import type { DataStore } from "../utils/dataStore";
 import { getConnectionState } from "../utils/getConnectionState";
@@ -31,6 +30,7 @@ import {
 	type RefetchFnDynamic,
 	type RefetchOptions,
 } from "./createRefetchableFragment";
+import { KeyType, KeyTypeData } from "relay-runtime/lib/store/FragmentTypes";
 
 type CreatePaginationFragmentReturn<
 	TQuery extends OperationType,
diff --git a/src/primitives/createRefetchableFragment.ts b/src/primitives/createRefetchableFragment.ts
@@ -32,12 +32,12 @@ import {
 import { unwrap } from "solid-js/store";
 import { isServer } from "solid-js/web";
 import { useRelayEnvironment } from "../RelayEnvironment";
-import type { KeyType, KeyTypeData } from "../types/keyType";
 import type { DataStore } from "../utils/dataStore";
 import { getQueryRef } from "../utils/getQueryRef";
 import { useIsMounted } from "../utils/useIsMounted";
 import { createFragmentInternal } from "./createFragment";
 import { createQueryLoader } from "./createQueryLoader";
+import { KeyType, KeyTypeData } from "relay-runtime/lib/store/FragmentTypes";
 
 export type RefetchFnDynamic<
 	TQuery extends OperationType,
diff --git a/src/types/keyType.ts b/src/types/keyType.ts
diff --git a/src/types/relayRuntimeExperimental.d.ts b/src/types/relayRuntimeExperimental.d.ts
diff --git a/tests/createFragment.test.tsx b/tests/createFragment.test.tsx
@@ -6,11 +6,12 @@ import {
 	Store,
 } from "relay-runtime";
 import { createMockEnvironment, type MockEnvironment } from "relay-test-utils";
-import { createSignal, ErrorBoundary, Suspense, type JSXElement } from "solid-js";
+import { createSignal, ErrorBoundary, For, Show, Suspense, type JSXElement } from "solid-js";
 import {
 	createFragment,
 	createLazyLoadQuery,
 	type DataStore,
+	type MaybeArray,
 	RelayEnvironmentProvider,
 } from "solid-relay";
 import { page } from "vitest/browser";
@@ -19,6 +20,11 @@ import type {
 	createFragmentTest_user$key,
 } from "./__generated__/createFragmentTest_user.graphql";
 import type { createFragmentTestOwnerQuery } from "./__generated__/createFragmentTestOwnerQuery.graphql";
+import {
+	createFragmentTestPlural_users$data,
+	createFragmentTestPlural_users$key,
+} from "./__generated__/createFragmentTestPlural_users.graphql";
+import { createFragmentTestPluralQuery } from "./__generated__/createFragmentTestPluralQuery.graphql";
 import { renderToBody, wait } from "./utils";
 
 let environment: MockEnvironment;
@@ -209,4 +215,71 @@ describe("createFragment", () => {
 		expect(store?.()).toBeUndefined();
 		expect(store?.latest).toBeUndefined();
 	});
+
+	describe("plural", () => {
+		let pluralStore: DataStore<MaybeArray<createFragmentTestPlural_users$data>> | undefined;
+		const pluralQuery = graphql`
+			query createFragmentTestPluralQuery($ids: [ID!]!) {
+				nodes(ids: $ids) {
+					...createFragmentTestPlural_users
+				}
+			}
+		` as ConcreteRequest;
+		const pluralFragment = graphql`
+			fragment createFragmentTestPlural_users on User @relay(plural: true) {
+				id
+				name
+			}
+		`;
+		const pluralOperation = createOperationDescriptor(pluralQuery, { ids: ["1"] });
+
+		const PluralChild = (props: {
+			users: MaybeArray<createFragmentTestPlural_users$key>;
+			testId?: string;
+		}) => {
+			pluralStore = createFragment(pluralFragment, () => props.users);
+			return (
+				<ul>
+					<For each={pluralStore()}>
+						{(node, i) => <li data-testid={`${props.testId ?? "name"}-${i()}`}>{node?.name}</li>}
+					</For>
+				</ul>
+			);
+		};
+
+		const PluralQueryScreen = (props: {
+			users?: createFragmentTestPlural_users$key | null | undefined;
+		}) => {
+			const data = createLazyLoadQuery<createFragmentTestPluralQuery>(pluralQuery, { ids: ["1"] });
+			return (
+				<ErrorBoundary fallback={(err) => <h1 data-testid="error">{err.message}</h1>}>
+					<Suspense fallback="Fallback">
+						<Show when={data()}>
+							{(data) => <PluralChild users={props.users ?? data().nodes} />}
+						</Show>
+					</Suspense>
+				</ErrorBoundary>
+			);
+		};
+
+		beforeEach(() => {
+			pluralStore = undefined;
+		});
+
+		it("reads fragment data from a parent query key", async () => {
+			renderToBody(() => (
+				<View>
+					<PluralQueryScreen />
+				</View>
+			));
+
+			await expect.element(page.getByText("Fallback")).toBeInTheDocument();
+			environment.mock.resolve(pluralOperation, {
+				data: { nodes: [{ __typename: "User", id: "1", name: "Alice" }] },
+			});
+			await wait(2);
+			await expect.element(page.getByTestId("name-0")).toHaveTextContent("Alice");
+			await expect.element(page.getByText("Fallback")).not.toBeInTheDocument();
+		});
+	});
 });
diff --git a/tests/schema.graphql b/tests/schema.graphql
@@ -1,5 +1,6 @@
 type Query {
 	node(id: ID!): Node
+	nodes(ids: [ID!]!): [Node]!
 	users(first: Int, after: String, last: Int, before: String): UserConnection!
 }
 

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"solid-relay": minor
 +---
++
 +feat: support plural fragments
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`type Query {`
`2`	`2`	`node(id: ID!): Node`
	`3`	`+ nodes(ids: [ID!]!): [Node]!`
`3`	`4`	`users(first: Int, after: String, last: Int, before: String): UserConnection!`
`4`	`5`	`}`
`5`	`6`