Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat: custom urql-solid lib (#5345)

dev-rbb80d9c1490f5
diff --git a/apps/web/src/lib/signals/access.ts b/apps/web/src/lib/signals/access.ts
new file mode 100644
index 0000000000..53b3cad7bc
--- /dev/null
+++ b/apps/web/src/lib/signals/access.ts
@@ -0,0 +1,9 @@
+import type { Accessor } from 'solid-js';
+
+/** A fixed value or a reactive accessor that returns it. */
+export type MaybeAccessor<T> = T | Accessor<T>;
+
+/** Reads a fixed value or invokes its reactive accessor. */
+export function access<T>(value: MaybeAccessor<T>): T {
+ return typeof value === 'function' ? (value as Accessor<T>)() : value;
+}
diff --git a/apps/web/src/lib/urql-solid/context.tsx b/apps/web/src/lib/urql-solid/context.tsx
new file mode 100644
index 0000000000..8972db30bd
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/context.tsx
@@ -0,0 +1,42 @@
+import { access } from '@app/lib/signals/access';
+import type { Client } from '@urql/core';
+import {
+ type Accessor,
+ createContext,
+ type ParentProps,
+ useContext,
+} from 'solid-js';
+import type { UrqlClientSource } from './types';
+
+const UrqlClientContext = createContext<Accessor<Client>>();
+
+/** Props for the application-local urql client provider. */
+export type UrqlProviderProps = ParentProps<{
+ /** A fixed client or reactive client accessor. */
+ client: UrqlClientSource;
+}>;
+
+/** Provides the default urql client used by descendant queries. */
+export function UrqlProvider(props: UrqlProviderProps) {
+ const client = (): Client => access(props.client);
+
+ return (
+ <UrqlClientContext.Provider value={client}>
+ {props.children}
+ </UrqlClientContext.Provider>
+ );
+}
+
+/** Returns the nearest reactive urql client, when a provider is present. */
+export function useOptionalUrqlClient(): Accessor<Client> | undefined {
+ return useContext(UrqlClientContext);
+}
+
+/** Returns the nearest reactive urql client or throws when none is provided. */
+export function useUrqlClient(): Accessor<Client> {
+ const client = useOptionalUrqlClient();
+ if (!client) {
+ throw new Error('useUrqlClient must be used within an UrqlProvider');
+ }
+ return client;
+}
diff --git a/apps/web/src/lib/urql-solid/create-base-query.ts b/apps/web/src/lib/urql-solid/create-base-query.ts
new file mode 100644
index 0000000000..728b00bca7
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/create-base-query.ts
@@ -0,0 +1,98 @@
+import {
+ type Accessor,
+ createComputed,
+ createMemo,
+ createSignal,
+ onCleanup,
+ untrack,
+} from 'solid-js';
+import { createStore, reconcile } from 'solid-js/store';
+import { useOptionalUrqlClient } from './context';
+import type { ObserverClientOptions, UrqlObserverFactory } from './observer';
+
+/** Bridges a framework-neutral urql observer into one reactive Solid store. */
+export function createBaseQuery<
+ Options extends ObserverClientOptions,
+ Result extends object,
+>(
+ getOptions: Accessor<Options>,
+ createObserver: UrqlObserverFactory<Options, Result>,
+ name: string
+): Result {
+ const providerClient = useOptionalUrqlClient();
+ const options = createMemo(getOptions);
+
+ const client = createMemo(() => {
+ const override = options().client;
+ if (override) return override;
+ if (providerClient) return providerClient();
+ throw new Error(
+ `${name} requires an UrqlProvider or a client option override`
+ );
+ });
+
+ const initialOptions = untrack(options);
+ const initialClient = untrack(client);
+
+ const initialObserver = untrack(() =>
+ createObserver(initialClient, initialOptions)
+ );
+
+ const [observer, setObserver] = createSignal(initialObserver, {
+ equals: false,
+ });
+
+ const [state, setState] = createStore<Result>(
+ untrack(() => initialObserver.getCurrentResult())
+ );
+
+ const result = new Proxy(state, {
+ get(target, property) {
+ return Reflect.get(target, property);
+ },
+ }) as Result;
+
+ initialObserver.setReference?.(result);
+
+ const update = (next: Result): void => {
+ setState(reconcile(next));
+ };
+
+ createComputed(() => {
+ const current = observer();
+ update(untrack(() => current.getCurrentResult()));
+ const unsubscribe = current.subscribe(update);
+ onCleanup(unsubscribe);
+ });
+
+ let firstOptionsRun = true;
+ let currentClient = initialClient;
+
+ createComputed(() => {
+ const nextOptions = options();
+ const nextClient = client();
+ if (firstOptionsRun) {
+ firstOptionsRun = false;
+ return;
+ }
+
+ const current = untrack(observer);
+ if (nextClient !== currentClient) {
+ const replacement = untrack(() =>
+ createObserver(nextClient, nextOptions)
+ );
+ replacement.setReference?.(result);
+ currentClient = nextClient;
+ setObserver(replacement);
+ current.destroy();
+ } else {
+ untrack(() => current.setOptions(nextOptions, nextClient));
+ }
+ });
+
+ onCleanup(() => {
+ untrack(observer).destroy();
+ });
+
+ return result;
+}
diff --git a/apps/web/src/lib/urql-solid/create-urql-infinite-query.test.tsx b/apps/web/src/lib/urql-solid/create-urql-infinite-query.test.tsx
new file mode 100644
index 0000000000..3ebb5ba706
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/create-urql-infinite-query.test.tsx
@@ -0,0 +1,284 @@
+import {
+ type Client,
+ type GraphQLRequest,
+ gql,
+ type Operation,
+ type OperationContext,
+ type OperationResult,
+} from '@urql/core';
+import { createRoot, createSignal } from 'solid-js';
+import { afterEach, describe, expect, it } from 'vitest';
+import { makeSubject, onEnd, pipe } from 'wonka';
+import { createUrqlInfiniteQuery } from './create-urql-infinite-query';
+import { InfiniteQueryObserver } from './infinite-query-observer';
+
+type Page = {
+ values: string[];
+ nextCursor: string | null;
+};
+type Variables = { cursor: string | null };
+
+type FakeExecution = {
+ variables: Variables;
+ next(data: Page): void;
+ readonly unsubscribed: boolean;
+};
+
+function makeFakeClient(): {
+ client: Client;
+ executions: FakeExecution[];
+} {
+ const executions: FakeExecution[] = [];
+ const execute = (
+ request: GraphQLRequest<Page, Variables>,
+ context: Partial<OperationContext>
+ ) => {
+ const subject = makeSubject<OperationResult<Page, Variables>>();
+ let unsubscribed = false;
+ const operation = {
+ kind: 'query',
+ context,
+ } as Operation<Page, Variables>;
+ executions.push({
+ variables: request.variables,
+ next: (data) =>
+ subject.next({ operation, data } as OperationResult<Page, Variables>),
+ get unsubscribed() {
+ return unsubscribed;
+ },
+ });
+ return pipe(
+ subject.source,
+ onEnd(() => {
+ unsubscribed = true;
+ })
+ );
+ };
+
+ return {
+ executions,
+ client: {
+ executeQuery: execute,
+ } as unknown as Client,
+ };
+}
+
+const DOCUMENT = gql`
+ query Page($cursor: String) {
+ page(cursor: $cursor)
+ }
+`;
+
+const disposals: Array<() => void> = [];
+afterEach(() => {
+ for (const dispose of disposals.splice(0)) dispose();
+});
+
+describe('createUrqlInfiniteQuery', () => {
+ it('caches immutable observer results between emissions', () => {
+ const fake = makeFakeClient();
+ let selectCalls = 0;
+ const observer = new InfiniteQueryObserver<
+ Page,
+ Variables,
+ string | null,
+ string[]
+ >(fake.client, {
+ query: DOCUMENT,
+ initialPageParam: null,
+ variables: (cursor) => ({ cursor }),
+ getNextPageParam: (lastPage) => lastPage.nextCursor,
+ select: ({ pages }) => {
+ selectCalls += 1;
+ return pages.flatMap((page) => page.values);
+ },
+ });
+
+ const initial = observer.getCurrentResult();
+ expect(observer.getCurrentResult()).toBe(initial);
+
+ fake.executions[0]?.next({ values: ['first'], nextCursor: null });
+
+ const updated = observer.getCurrentResult();
+ expect(updated).not.toBe(initial);
+ expect(observer.getCurrentResult()).toBe(updated);
+ expect(selectCalls).toBe(1);
+
+ observer.destroy();
+ });
+
+ it('appends continuation pages while keeping loaded pages live', async () => {
+ const fake = makeFakeClient();
+ let query!: ReturnType<
+ typeof createUrqlInfiniteQuery<Page, Variables, string | null, string[]>
+ >;
+ const dispose = createRoot((rootDispose) => {
+ query = createUrqlInfiniteQuery<Page, Variables, string | null, string[]>(
+ () => ({
+ query: DOCUMENT,
+ client: fake.client,
+ initialPageParam: null,
+ variables: (cursor) => ({ cursor }),
+ getNextPageParam: (lastPage) => lastPage.nextCursor,
+ select: ({ pages }) => pages.flatMap((page) => page.values),
+ })
+ );
+ return rootDispose;
+ });
+ disposals.push(dispose);
+
+ expect(fake.executions).toHaveLength(1);
+ fake.executions[0]?.next({ values: ['first'], nextCursor: 'cursor-1' });
+ expect(query.data).toEqual(['first']);
+ expect(query.hasNextPage).toBe(true);
+
+ const nextPage = query.fetchNextPage();
+ expect(fake.executions).toHaveLength(2);
+ expect(fake.executions[1]?.variables).toEqual({ cursor: 'cursor-1' });
+ fake.executions[1]?.next({ values: ['second'], nextCursor: null });
+ await nextPage;
+
+ expect(query.data).toEqual(['first', 'second']);
+ expect(query.hasNextPage).toBe(false);
+
+ fake.executions[0]?.next({
+ values: ['first-updated'],
+ nextCursor: 'cursor-1',
+ });
+ expect(query.data).toEqual(['first-updated', 'second']);
+ expect(fake.executions[0]?.unsubscribed).toBe(false);
+ });
+
+ it('disables page subscriptions and re-enables them', () => {
+ const fake = makeFakeClient();
+ const [enabled, setEnabled] = createSignal(true);
+ let query!: ReturnType<
+ typeof createUrqlInfiniteQuery<Page, Variables, string | null, string[]>
+ >;
+ const dispose = createRoot((rootDispose) => {
+ query = createUrqlInfiniteQuery<Page, Variables, string | null, string[]>(
+ () => ({
+ query: DOCUMENT,
+ client: fake.client,
+ enabled: enabled(),
+ initialPageParam: null,
+ variables: (cursor) => ({ cursor }),
+ getNextPageParam: (lastPage) => lastPage.nextCursor,
+ select: ({ pages }) => pages.flatMap((page) => page.values),
+ })
+ );
+ return rootDispose;
+ });
+ disposals.push(dispose);
+
+ fake.executions[0]?.next({ values: ['first'], nextCursor: null });
+ setEnabled(false);
+
+ expect(query.isEnabled).toBe(false);
+ expect(query.data).toEqual(['first']);
+ expect(fake.executions[0]?.unsubscribed).toBe(true);
+
+ setEnabled(true);
+
+ expect(query.isEnabled).toBe(true);
+ expect(query.data).toEqual(['first']);
+ expect(fake.executions).toHaveLength(2);
+ });
+
+ it('retains selected data while a changed query loads', () => {
+ const fake = makeFakeClient();
+ const [initialPageParam, setInitialPageParam] = createSignal<string | null>(
+ null
+ );
+ let query!: ReturnType<
+ typeof createUrqlInfiniteQuery<Page, Variables, string | null, string[]>
+ >;
+ const dispose = createRoot((rootDispose) => {
+ query = createUrqlInfiniteQuery<Page, Variables, string | null, string[]>(
+ () => ({
+ query: DOCUMENT,
+ client: fake.client,
+ initialPageParam: initialPageParam(),
+ variables: (cursor) => ({ cursor }),
+ getNextPageParam: (lastPage) => lastPage.nextCursor,
+ select: ({ pages }) => pages.flatMap((page) => page.values),
+ })
+ );
+ return rootDispose;
+ });
+ disposals.push(dispose);
+
+ fake.executions[0]?.next({ values: ['first'], nextCursor: null });
+ expect(query.data).toEqual(['first']);
+
+ setInitialPageParam('replacement');
+
+ expect(fake.executions).toHaveLength(2);
+ expect(fake.executions[0]?.unsubscribed).toBe(true);
+ expect(query.data).toEqual(['first']);
+
+ fake.executions[1]?.next({ values: ['replacement'], nextCursor: null });
+ expect(query.data).toEqual(['replacement']);
+ });
+
+ it('exposes selector failures without interrupting page delivery', () => {
+ const fake = makeFakeClient();
+ let query!: ReturnType<
+ typeof createUrqlInfiniteQuery<Page, Variables, string | null, string[]>
+ >;
+ const dispose = createRoot((rootDispose) => {
+ query = createUrqlInfiniteQuery<Page, Variables, string | null, string[]>(
+ () => ({
+ query: DOCUMENT,
+ client: fake.client,
+ initialPageParam: null,
+ variables: (cursor) => ({ cursor }),
+ getNextPageParam: (lastPage) => lastPage.nextCursor,
+ select: () => {
+ throw new Error('selector failed');
+ },
+ })
+ );
+ return rootDispose;
+ });
+ disposals.push(dispose);
+
+ expect(() =>
+ fake.executions[0]?.next({ values: ['first'], nextCursor: 'cursor-1' })
+ ).not.toThrow();
+ expect(query.error?.networkError?.message).toBe('selector failed');
+ expect(query.isError).toBe(true);
+ expect(query.hasNextPage).toBe(false);
+ });
+
+ it('exposes pagination callback failures without interrupting delivery', () => {
+ const fake = makeFakeClient();
+ let query!: ReturnType<
+ typeof createUrqlInfiniteQuery<Page, Variables, string | null, string[]>
+ >;
+ const dispose = createRoot((rootDispose) => {
+ query = createUrqlInfiniteQuery<Page, Variables, string | null, string[]>(
+ () => ({
+ query: DOCUMENT,
+ client: fake.client,
+ initialPageParam: null,
+ variables: (cursor) => ({ cursor }),
+ getNextPageParam: () => {
+ throw new Error('pagination failed');
+ },
+ select: ({ pages }) => pages.flatMap((page) => page.values),
+ })
+ );
+ return rootDispose;
+ });
+ disposals.push(dispose);
+
+ expect(() =>
+ fake.executions[0]?.next({ values: ['first'], nextCursor: 'cursor-1' })
+ ).not.toThrow();
+ expect(query.data).toEqual(['first']);
+ expect(query.error?.networkError?.message).toBe('pagination failed');
+ expect(query.isError).toBe(true);
+ expect(query.hasNextPage).toBe(false);
+ });
+});
diff --git a/apps/web/src/lib/urql-solid/create-urql-infinite-query.ts b/apps/web/src/lib/urql-solid/create-urql-infinite-query.ts
new file mode 100644
index 0000000000..67910d6113
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/create-urql-infinite-query.ts
@@ -0,0 +1,27 @@
+import type { AnyVariables } from '@urql/core';
+import type { Accessor } from 'solid-js';
+import { createBaseQuery } from './create-base-query';
+import { createInfiniteQueryObserver } from './infinite-query-observer';
+import type {
+ UrqlInfiniteData,
+ UrqlInfiniteQueryOptions,
+ UrqlInfiniteQueryResult,
+} from './types';
+
+/** Creates a live, paginated Solid binding over an urql infinite observer. */
+export function createUrqlInfiniteQuery<
+ PageData,
+ Variables extends AnyVariables,
+ PageParam,
+ SelectedData = UrqlInfiniteData<PageData, PageParam>,
+>(
+ getOptions: Accessor<
+ UrqlInfiniteQueryOptions<PageData, Variables, PageParam, SelectedData>
+ >
+): UrqlInfiniteQueryResult<PageData, Variables, PageParam, SelectedData> {
+ return createBaseQuery(
+ getOptions,
+ createInfiniteQueryObserver<PageData, Variables, PageParam, SelectedData>,
+ 'createUrqlInfiniteQuery'
+ );
+}
diff --git a/apps/web/src/lib/urql-solid/create-urql-mutation.test.tsx b/apps/web/src/lib/urql-solid/create-urql-mutation.test.tsx
new file mode 100644
index 0000000000..c6f4f6c043
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/create-urql-mutation.test.tsx
@@ -0,0 +1,430 @@
+import {
+ type Client,
+ CombinedError,
+ gql,
+ type Operation,
+ type OperationContext,
+ type OperationResult,
+ type OperationResultSource,
+} from '@urql/core';
+import { createRoot } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createUrqlMutation } from './create-urql-mutation';
+import type {
+ UrqlMutationExecutor,
+ UrqlMutationOptions,
+ UrqlMutationResult,
+} from './types';
+
+type Data = { updateValue: string };
+type Variables = { input: string };
+
+type Deferred<T> = {
+ promise: Promise<T>;
+ resolve(value: T): void;
+ reject(error: unknown): void;
+};
+
+type FakeExecution = {
+ variables: Variables;
+ context: Partial<OperationContext>;
+ deferred: Deferred<OperationResult<Data, Variables>>;
+};
+
+const DOCUMENT = gql`
+ mutation UpdateValue($input: String!) {
+ updateValue(input: $input)
+ }
+`;
+
+function deferred<T>(): Deferred<T> {
+ let resolve!: (value: T) => void;
+ let reject!: (error: unknown) => void;
+ const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+ resolve = resolvePromise;
+ reject = rejectPromise;
+ });
+ return { promise, resolve, reject };
+}
+
+function resultSource<TData, TVariables extends Record<string, unknown>>(
+ promise: Promise<OperationResult<TData, TVariables>>
+): OperationResultSource<OperationResult<TData, TVariables>> {
+ return {
+ toPromise: () => promise,
+ } as OperationResultSource<OperationResult<TData, TVariables>>;
+}
+
+function operation(
+ context: Partial<OperationContext> = {}
+): Operation<Data, Variables> {
+ return { kind: 'mutation', context } as Operation<Data, Variables>;
+}
+
+function makeFakeClient(): { client: Client; executions: FakeExecution[] } {
+ const executions: FakeExecution[] = [];
+ const client = {
+ mutation: vi.fn(
+ (
+ _document: unknown,
+ variables: Variables,
+ context: Partial<OperationContext> = {}
+ ) => {
+ const pending = deferred<OperationResult<Data, Variables>>();
+ executions.push({ variables, context, deferred: pending });
+ return resultSource(pending.promise);
+ }
+ ),
+ } as unknown as Client;
+ return { client, executions };
+}
+
+const disposals: Array<() => void> = [];
+afterEach(() => {
+ for (const dispose of disposals.splice(0)) dispose();
+ vi.restoreAllMocks();
+});
+
+function setup<OnMutateResult = void>(
+ options: UrqlMutationOptions<Data, Variables, Variables, OnMutateResult>
+): UrqlMutationResult<Data, Variables, Variables, OnMutateResult> {
+ let mutation!: UrqlMutationResult<Data, Variables, Variables, OnMutateResult>;
+ const dispose = createRoot((rootDispose) => {
+ mutation = createUrqlMutation(() => options);
+ return rootDispose;
+ });
+ disposals.push(dispose);
+ return mutation;
+}
+
+describe('createUrqlMutation', () => {
+ it('requires a provider or client override', () => {
+ expect(() =>
+ createRoot((dispose) => {
+ try {
+ createUrqlMutation<Data, Variables>(() => ({ mutation: DOCUMENT }));
+ } finally {
+ dispose();
+ }
+ })
+ ).toThrow(
+ 'createUrqlMutation requires an UrqlProvider or a client option override'
+ );
+ });
+
+ it('executes lazily and exposes the latest raw mutation state', async () => {
+ const { client, executions } = makeFakeClient();
+ const mutation = setup({ mutation: DOCUMENT, client });
+
+ expect(executions).toHaveLength(0);
+ expect(mutation.isPending).toBe(false);
+
+ const promise = mutation.mutateAsync({ input: 'first' });
+ expect(executions).toHaveLength(1);
+ expect(mutation.isPending).toBe(true);
+
+ const result: OperationResult<Data, Variables> = {
+ operation: operation(),
+ data: { updateValue: 'saved' },
+ stale: false,
+ hasNext: false,
+ };
+ executions[0].deferred.resolve(result);
+
+ await expect(promise).resolves.toBe(result);
+ expect(mutation.isPending).toBe(false);
+ expect(mutation.data).toEqual({ updateValue: 'saved' });
+ expect(mutation.error).toBeNull();
+ expect(mutation.operation).toEqual(result.operation);
+ });
+
+ it('submits fire-and-forget mutations', async () => {
+ const { client, executions } = makeFakeClient();
+ const mutation = setup({ mutation: DOCUMENT, client });
+
+ expect(mutation.mutate({ input: 'fire-and-forget' })).toBeUndefined();
+ expect(executions).toHaveLength(1);
+
+ executions[0].deferred.resolve({
+ operation: operation(),
+ data: { updateValue: 'saved' },
+ stale: false,
+ hasNext: false,
+ });
+
+ await vi.waitFor(() => {
+ expect(mutation.isPending).toBe(false);
+ expect(mutation.data).toEqual({ updateValue: 'saved' });
+ });
+ });
+
+ it('supports custom execution with merged operation context', async () => {
+ const { client } = makeFakeClient();
+ const pending = deferred<OperationResult<Data, Variables>>();
+ const execute: UrqlMutationExecutor<Data, Variables> = vi.fn(() =>
+ resultSource(pending.promise)
+ );
+ const mutation = setup({
+ mutation: DOCUMENT,
+ client,
+ context: { requestPolicy: 'network-only', base: true },
+ execute,
+ });
+
+ const promise = mutation.mutateAsync(
+ { input: 'durable' },
+ { context: { base: false, execution: true } }
+ );
+
+ expect(execute).toHaveBeenCalledWith({
+ client,
+ mutation: DOCUMENT,
+ input: { input: 'durable' },
+ context: {
+ requestPolicy: 'network-only',
+ base: false,
+ execution: true,
+ },
+ });
+
+ const result: OperationResult<Data, Variables> = {
+ operation: operation(),
+ data: { updateValue: 'queued' },
+ extensions: {
+ normalizedCacheMutationDisposition: {
+ kind: 'queued',
+ transactionId: 'txn-1',
+ },
+ },
+ stale: false,
+ hasNext: false,
+ };
+ pending.resolve(result);
+
+ await expect(promise).resolves.toBe(result);
+ });
+
+ it('lets async executors transform consumer input into GraphQL variables', async () => {
+ type Input = { entityId: string; nextValue: string };
+
+ const { client, executions } = makeFakeClient();
+ const onSuccess = vi.fn();
+ const execute: UrqlMutationExecutor<Data, Variables, Input> = vi.fn(
+ async ({ client, mutation, input, context }) => {
+ await Promise.resolve();
+ return client
+ .mutation(
+ mutation,
+ { input: `${input.entityId}:${input.nextValue}` },
+ context
+ )
+ .toPromise();
+ }
+ );
+ let mutation!: UrqlMutationResult<Data, Variables, Input>;
+ const dispose = createRoot((rootDispose) => {
+ mutation = createUrqlMutation<Data, Variables, Input>(() => ({
+ mutation: DOCUMENT,
+ client,
+ execute,
+ onSuccess,
+ }));
+ return rootDispose;
+ });
+ disposals.push(dispose);
+
+ const input: Input = { entityId: 'entity-1', nextValue: 'updated' };
+ const promise = mutation.mutateAsync(input);
+
+ await vi.waitFor(() => expect(executions).toHaveLength(1));
+ expect(execute).toHaveBeenCalledWith({
+ client,
+ mutation: DOCUMENT,
+ input,
+ context: {},
+ });
+ expect(executions[0].variables).toEqual({
+ input: 'entity-1:updated',
+ });
+
+ const result: OperationResult<Data, Variables> = {
+ operation: operation(),
+ data: { updateValue: 'updated' },
+ stale: false,
+ hasNext: false,
+ };
+ executions[0].deferred.resolve(result);
+
+ await expect(promise).resolves.toBe(result);
+ expect(onSuccess).toHaveBeenCalledWith(
+ result.data,
+ input,
+ undefined,
+ result
+ );
+ });
+
+ it('runs configured and per-execution lifecycle callbacks', async () => {
+ const { client, executions } = makeFakeClient();
+ const events: string[] = [];
+ const mutation = setup({
+ mutation: DOCUMENT,
+ client,
+ onMutate: async (variables) => {
+ events.push(`mutate:${variables.input}`);
+ return { previous: 'before' };
+ },
+ onSuccess: async (data, variables, context, result) => {
+ expect(data).toEqual({ updateValue: 'saved' });
+ expect(variables).toEqual({ input: 'callbacks' });
+ expect(context).toEqual({ previous: 'before' });
+ expect(result.data).toBe(data);
+ events.push('configured-success');
+ },
+ onSettled: (_data, error) => {
+ expect(error).toBeNull();
+ events.push('configured-settled');
+ },
+ });
+
+ const promise = mutation.mutateAsync(
+ { input: 'callbacks' },
+ {
+ onSuccess: () => {
+ events.push('execution-success');
+ },
+ onError: () => {
+ events.push('execution-error');
+ },
+ onSettled: () => {
+ events.push('execution-settled');
+ },
+ }
+ );
+
+ await vi.waitFor(() => expect(executions).toHaveLength(1));
+ const result: OperationResult<Data, Variables> = {
+ operation: operation(),
+ data: { updateValue: 'saved' },
+ stale: false,
+ hasNext: false,
+ };
+ executions[0].deferred.resolve(result);
+ await expect(promise).resolves.toBe(result);
+
+ expect(events).toEqual([
+ 'mutate:callbacks',
+ 'configured-success',
+ 'execution-success',
+ 'configured-settled',
+ 'execution-settled',
+ ]);
+ });
+
+ it('runs error callbacks for GraphQL results without rejecting', async () => {
+ const { client, executions } = makeFakeClient();
+ const onSuccess = vi.fn();
+ const onError = vi.fn();
+ const onSettled = vi.fn();
+ const mutation = setup({
+ mutation: DOCUMENT,
+ client,
+ onSuccess,
+ onError,
+ onSettled,
+ });
+ const promise = mutation.mutateAsync({ input: 'graphql-error' });
+ const error = new CombinedError({
+ graphQLErrors: [new Error('mutation failed')],
+ });
+ const result: OperationResult<Data, Variables> = {
+ operation: operation(),
+ error,
+ stale: false,
+ hasNext: false,
+ };
+ executions[0].deferred.resolve(result);
+
+ await expect(promise).resolves.toBe(result);
+ expect(onSuccess).not.toHaveBeenCalled();
+ expect(onError).toHaveBeenCalledWith(
+ error,
+ { input: 'graphql-error' },
+ undefined,
+ result
+ );
+ expect(onSettled).toHaveBeenCalledWith(
+ undefined,
+ error,
+ { input: 'graphql-error' },
+ undefined,
+ result
+ );
+ });
+
+ it('keeps the latest execution result during overlapping mutations', async () => {
+ const { client, executions } = makeFakeClient();
+ const mutation = setup({ mutation: DOCUMENT, client });
+
+ const first = mutation.mutateAsync({ input: 'first' });
+ const second = mutation.mutateAsync({ input: 'second' });
+
+ const secondResult: OperationResult<Data, Variables> = {
+ operation: operation(),
+ data: { updateValue: 'second' },
+ stale: false,
+ hasNext: false,
+ };
+ executions[1].deferred.resolve(secondResult);
+ await second;
+
+ expect(mutation.data).toEqual({ updateValue: 'second' });
+ expect(mutation.isPending).toBe(true);
+
+ const firstResult: OperationResult<Data, Variables> = {
+ operation: operation(),
+ data: { updateValue: 'first' },
+ stale: false,
+ hasNext: false,
+ };
+ executions[0].deferred.resolve(firstResult);
+ await first;
+
+ expect(mutation.data).toEqual({ updateValue: 'second' });
+ expect(mutation.isPending).toBe(false);
+ });
+
+ it('stores and reports execution failures as CombinedError', async () => {
+ const { client, executions } = makeFakeClient();
+ const onError = vi.fn();
+ const onSettled = vi.fn();
+ const mutation = setup({
+ mutation: DOCUMENT,
+ client,
+ onError,
+ onSettled,
+ });
+ const promise = mutation.mutateAsync({ input: 'failure' });
+
+ executions[0].deferred.reject(new Error('offline executor failed'));
+
+ await expect(promise).rejects.toBeInstanceOf(CombinedError);
+ expect(mutation.isPending).toBe(false);
+ expect(mutation.error?.networkError?.message).toBe(
+ 'offline executor failed'
+ );
+ expect(onError).toHaveBeenCalledWith(
+ mutation.error,
+ { input: 'failure' },
+ undefined,
+ undefined
+ );
+ expect(onSettled).toHaveBeenCalledWith(
+ undefined,
+ mutation.error,
+ { input: 'failure' },
+ undefined,
+ undefined
+ );
+ });
+});
diff --git a/apps/web/src/lib/urql-solid/create-urql-mutation.ts b/apps/web/src/lib/urql-solid/create-urql-mutation.ts
new file mode 100644
index 0000000000..9386d7eb21
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/create-urql-mutation.ts
@@ -0,0 +1,19 @@
+import type { AnyVariables } from '@urql/core';
+import type { Accessor } from 'solid-js';
+import { createBaseQuery } from './create-base-query';
+import { createMutationObserver } from './mutation-observer';
+import type { UrqlMutationOptions, UrqlMutationResult } from './types';
+
+/** Creates reactive state for imperative urql mutation executions. */
+export function createUrqlMutation<
+ MutationData,
+ Variables extends AnyVariables,
+ Input = Variables,
+ OnMutateResult = void,
+>(
+ options: Accessor<
+ UrqlMutationOptions<MutationData, Variables, Input, OnMutateResult>
+ >
+): UrqlMutationResult<MutationData, Variables, Input, OnMutateResult> {
+ return createBaseQuery(options, createMutationObserver, 'createUrqlMutation');
+}
diff --git a/apps/web/src/lib/urql-solid/create-urql-query.test.tsx b/apps/web/src/lib/urql-solid/create-urql-query.test.tsx
new file mode 100644
index 0000000000..a9208e7fa4
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/create-urql-query.test.tsx
@@ -0,0 +1,683 @@
+import {
+ type AnyVariables,
+ type Client,
+ CombinedError,
+ type GraphQLRequest,
+ gql,
+ type Operation,
+ type OperationContext,
+ type OperationResult,
+} from '@urql/core';
+import {
+ type Accessor,
+ createComponent,
+ createRenderEffect,
+ createRoot,
+ createSignal,
+} from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { fromValue, makeSubject, onEnd, pipe } from 'wonka';
+import { UrqlProvider } from './context';
+import { createUrqlQuery } from './create-urql-query';
+import type {
+ UrqlClientSource,
+ UrqlQueryOptions,
+ UrqlQueryResult,
+} from './types';
+
+type Data = {
+ value: string;
+ nested?: { count: number; removed?: string };
+};
+type Variables = { input: string };
+type RuntimeResult<D, V extends AnyVariables> = Omit<
+ Partial<OperationResult<D, V>>,
+ 'data'
+> & {
+ data?: D | null;
+};
+
+type FakeExecution<D, V extends AnyVariables> = {
+ document: unknown;
+ variables: V;
+ context: Partial<OperationContext>;
+ next(result: RuntimeResult<D, V>): void;
+ complete(): void;
+ readonly unsubscribed: boolean;
+};
+
+function makeFakeClient<D = Data, V extends AnyVariables = Variables>(): {
+ client: Client;
+ executions: FakeExecution<D, V>[];
+} {
+ const executions: FakeExecution<D, V>[] = [];
+ const execute = (
+ document: unknown,
+ variables: V,
+ context: Partial<OperationContext> = {}
+ ) => {
+ const subject = makeSubject<OperationResult<D, V>>();
+ let unsubscribed = false;
+ const operation = {
+ kind: 'query',
+ context,
+ } as Operation<D, V>;
+ const execution: FakeExecution<D, V> = {
+ document,
+ variables,
+ context,
+ next: (result) =>
+ subject.next({ operation, ...result } as OperationResult<D, V>),
+ complete: subject.complete,
+ get unsubscribed() {
+ return unsubscribed;
+ },
+ };
+ executions.push(execution);
+ return pipe(
+ subject.source,
+ onEnd(() => {
+ unsubscribed = true;
+ })
+ );
+ };
+ const client = {
+ query: execute,
+ executeQuery: (
+ request: GraphQLRequest<D, V>,
+ context: Partial<OperationContext> = {}
+ ) => execute(request.query, request.variables, context),
+ } as unknown as Client;
+ return { client, executions };
+}
+
+const DOCUMENT = gql`
+ query TestQuery($input: String!) {
+ test(input: $input)
+ }
+`;
+const OTHER_DOCUMENT = gql`
+ query OtherTestQuery($input: String!) {
+ otherTest(input: $input)
+ }
+`;
+
+const disabledWithoutVariables: UrqlQueryOptions<Data, Variables> = {
+ query: DOCUMENT,
+ enabled: false,
+};
+// @ts-expect-error Enabled requests retain generated variables requirements.
+const enabledWithoutVariables: UrqlQueryOptions<Data, Variables> = {
+ query: DOCUMENT,
+ enabled: true,
+};
+void disabledWithoutVariables;
+void enabledWithoutVariables;
+
+const disposals: Array<() => void> = [];
+afterEach(() => {
+ for (const dispose of disposals.splice(0)) dispose();
+ vi.restoreAllMocks();
+});
+
+function setup(
+ getOptions: Accessor<UrqlQueryOptions<Data, Variables>>,
+ provider?: UrqlClientSource
+): UrqlQueryResult<Data, Variables> {
+ let query!: UrqlQueryResult<Data, Variables>;
+ const dispose = createRoot((rootDispose) => {
+ if (provider) {
+ createComponent(UrqlProvider, {
+ client: provider,
+ get children() {
+ query = createUrqlQuery(getOptions);
+ return undefined;
+ },
+ });
+ } else {
+ query = createUrqlQuery(getOptions);
+ }
+ return rootDispose;
+ });
+ disposals.push(dispose);
+ return query;
+}
+
+function activeOptions(client?: Client): UrqlQueryOptions<Data, Variables> {
+ return {
+ query: DOCUMENT,
+ variables: { input: 'first' },
+ client,
+ };
+}
+
+describe('createUrqlQuery client resolution', () => {
+ it('uses the provider and reactively follows provider client changes', () => {
+ const first = makeFakeClient();
+ const second = makeFakeClient();
+ const [providerClient, setProviderClient] = createSignal(first.client);
+ setup(() => activeOptions(), providerClient);
+
+ expect(first.executions).toHaveLength(1);
+ setProviderClient(() => second.client);
+
+ expect(first.executions[0]?.unsubscribed).toBe(true);
+ expect(second.executions).toHaveLength(1);
+ });
+
+ it('uses the nearest provider', () => {
+ const outer = makeFakeClient();
+ const inner = makeFakeClient();
+ const dispose = createRoot((rootDispose) => {
+ createComponent(UrqlProvider, {
+ client: outer.client,
+ get children() {
+ return createComponent(UrqlProvider, {
+ client: inner.client,
+ get children() {
+ createUrqlQuery<Data, Variables>(() => activeOptions());
+ return undefined;
+ },
+ });
+ },
+ });
+ return rootDispose;
+ });
+ disposals.push(dispose);
+
+ expect(outer.executions).toHaveLength(0);
+ expect(inner.executions).toHaveLength(1);
+ });
+
+ it('prefers an optional override and reactively returns to the provider', () => {
+ const provided = makeFakeClient();
+ const overridden = makeFakeClient();
+ const [override, setOverride] = createSignal<Client | undefined>(undefined);
+ setup(
+ () => ({
+ ...activeOptions(),
+ client: override(),
+ }),
+ provided.client
+ );
+
+ expect(provided.executions).toHaveLength(1);
+ setOverride(() => overridden.client);
+ expect(provided.executions[0]?.unsubscribed).toBe(true);
+ expect(overridden.executions).toHaveLength(1);
+
+ setOverride(undefined);
+ expect(overridden.executions[0]?.unsubscribed).toBe(true);
+ expect(provided.executions).toHaveLength(2);
+ });
+
+ it('throws clearly without a provider or override', () => {
+ expect(() => setup(() => activeOptions())).toThrow(
+ 'createUrqlQuery requires an UrqlProvider or a client option override'
+ );
+ });
+});
+
+describe('createUrqlQuery reactive state', () => {
+ it('tracks cache, network, and pushed results over one live source', () => {
+ const fake = makeFakeClient();
+ const query = setup(() => activeOptions(fake.client));
+ const execution = fake.executions[0];
+
+ expect(query.status).toBe('pending');
+ expect(query.fetchStatus).toBe('fetching');
+ expect(query.fetching).toBe(true);
+ expect(query.isEnabled).toBe(true);
+ expect(query.isPending).toBe(true);
+ expect(query.isLoading).toBe(true);
+ expect(query.isInitialLoading).toBe(true);
+ expect(query.isFetched).toBe(false);
+
+ execution?.next({
+ data: { value: 'cache' },
+ stale: true,
+ extensions: { tier: 'cache' },
+ });
+ expect(query.data).toEqual({ value: 'cache' });
+ expect(query.status).toBe('success');
+ expect(query.fetching).toBe(false);
+ expect(query.isFetching).toBe(true);
+ expect(query.isRefetching).toBe(true);
+ expect(query.stale).toBe(true);
+ expect(query.extensions).toEqual({ tier: 'cache' });
+
+ execution?.next({ data: { value: 'network' }, stale: false });
+ expect(query.data).toEqual({ value: 'network' });
+ expect(query.fetchStatus).toBe('idle');
+ expect(query.isSuccess).toBe(true);
+ expect(query.isFetched).toBe(true);
+
+ execution?.next({ data: { value: 'pushed' } });
+ expect(query.data).toEqual({ value: 'pushed' });
+ expect(fake.executions).toHaveLength(1);
+ });
+
+ it('marks a completed data-less result as successful', () => {
+ const fake = makeFakeClient();
+ const query = setup(() => activeOptions(fake.client));
+
+ fake.executions[0]?.next({});
+
+ expect(query.data).toBeUndefined();
+ expect(query.status).toBe('success');
+ expect(query.isFetched).toBe(true);
+ expect(query.isLoading).toBe(false);
+ });
+
+ it('replaces subscriptions when query, variables, or context change', () => {
+ const fake = makeFakeClient();
+ const [input, setInput] = createSignal('first');
+ const [document, setDocument] = createSignal(DOCUMENT);
+ const [header, setHeader] = createSignal('one');
+ const query = setup(() => ({
+ query: document(),
+ variables: { input: input() },
+ context: { fetchOptions: { headers: { 'x-test': header() } } },
+ client: fake.client,
+ }));
+
+ fake.executions[0]?.next({ data: { value: 'first' } });
+ setInput('second');
+ expect(fake.executions[0]?.unsubscribed).toBe(true);
+ expect(fake.executions[1]?.variables).toEqual({ input: 'second' });
+
+ fake.executions[0]?.next({ data: { value: 'late' } });
+ expect(query.data).toEqual({ value: 'first' });
+
+ setHeader('two');
+ expect(fake.executions[1]?.unsubscribed).toBe(true);
+ expect(fake.executions[2]?.context.fetchOptions).toEqual({
+ headers: { 'x-test': 'two' },
+ });
+
+ setDocument(OTHER_DOCUMENT);
+ expect(fake.executions[2]?.unsubscribed).toBe(true);
+ expect(fake.executions[3]?.document).toBe(OTHER_DOCUMENT);
+ });
+
+ it('disables synchronously, preserves state, and re-enables', () => {
+ const fake = makeFakeClient();
+ const [enabled, setEnabled] = createSignal(true);
+ const query = setup(() => ({
+ query: DOCUMENT,
+ variables: { input: 'first' },
+ client: fake.client,
+ enabled: enabled(),
+ }));
+
+ fake.executions[0]?.next({
+ data: { value: 'existing' },
+ stale: true,
+ hasNext: true,
+ });
+ setEnabled(false);
+ expect(fake.executions[0]?.unsubscribed).toBe(true);
+ expect(query.isEnabled).toBe(false);
+ expect(query.fetchStatus).toBe('idle');
+ expect(query.stale).toBe(false);
+ expect(query.hasNext).toBe(false);
+ expect(query.data).toEqual({ value: 'existing' });
+
+ fake.executions[0]?.next({ data: { value: 'late' } });
+ expect(query.data).toEqual({ value: 'existing' });
+
+ setEnabled(true);
+ expect(query.isEnabled).toBe(true);
+ expect(query.isRefetching).toBe(true);
+ expect(fake.executions).toHaveLength(2);
+ });
+
+ it('clears prior result state for a new identity when configured', () => {
+ const fake = makeFakeClient();
+ const [input, setInput] = createSignal('first');
+ const query = setup(() => ({
+ query: DOCUMENT,
+ variables: { input: input() },
+ client: fake.client,
+ keepPreviousData: false,
+ }));
+ const priorError = new CombinedError({ graphQLErrors: ['old error'] });
+
+ fake.executions[0]?.next({
+ data: { value: 'first' },
+ error: priorError,
+ stale: true,
+ });
+ setInput('second');
+
+ expect(query.data).toBeUndefined();
+ expect(query.error).toBeNull();
+ expect(query.stale).toBe(false);
+ expect(query.status).toBe('pending');
+ expect(query.isLoading).toBe(true);
+ });
+
+ it('retains valid data while exposing partial and root-null errors', () => {
+ const fake = makeFakeClient();
+ const query = setup(() => activeOptions(fake.client));
+ const partialError = new CombinedError({ graphQLErrors: ['partial'] });
+ const rootError = new CombinedError({ graphQLErrors: ['root null'] });
+
+ fake.executions[0]?.next({
+ data: { value: 'partial-data' },
+ error: partialError,
+ });
+ expect(query.data).toEqual({ value: 'partial-data' });
+ expect(query.error).toBe(partialError);
+ expect(query.isError).toBe(true);
+
+ fake.executions[0]?.next({ data: { value: 'valid' } });
+ fake.executions[0]?.next({ data: null, error: rootError });
+ expect(query.data).toEqual({ value: 'valid' });
+ expect(query.error).toBe(rootError);
+ expect(query.status).toBe('error');
+ });
+
+ it('calls the result observer after updating state', () => {
+ const fake = makeFakeClient();
+ let observed: string | undefined;
+ let query!: UrqlQueryResult<Data, Variables>;
+ query = setup(() => ({
+ ...activeOptions(fake.client),
+ onResult: () => {
+ observed = query.data?.value;
+ },
+ }));
+
+ fake.executions[0]?.next({ data: { value: 'observed' } });
+ expect(observed).toBe('observed');
+ });
+
+ it('returns a stable proxy backed by deeply reactive reconciled data', () => {
+ const fake = makeFakeClient();
+ const observed: Array<[number | undefined, string | undefined]> = [];
+ let query!: UrqlQueryResult<Data, Variables>;
+ const dispose = createRoot((rootDispose) => {
+ query = createUrqlQuery(() => activeOptions(fake.client));
+ createRenderEffect(() => {
+ observed.push([query.data?.nested?.count, query.data?.nested?.removed]);
+ });
+ return rootDispose;
+ });
+ disposals.push(dispose);
+
+ fake.executions[0]?.next({
+ data: { value: 'first', nested: { count: 1, removed: 'old' } },
+ });
+ const firstData = query.data;
+ expect(observed.at(-1)).toEqual([1, 'old']);
+
+ fake.executions[0]?.next({
+ data: { value: 'second', nested: { count: 2 } },
+ });
+ expect(query.data).toBe(firstData);
+ expect(observed.at(-1)).toEqual([2, undefined]);
+ });
+
+ it('normalizes stale and incremental state when a source completes', () => {
+ const fake = makeFakeClient();
+ const query = setup(() => activeOptions(fake.client));
+
+ fake.executions[0]?.next({
+ data: { value: 'partial' },
+ stale: true,
+ hasNext: true,
+ });
+ expect(query.fetching).toBe(false);
+ expect(query.isFetching).toBe(true);
+ expect(query.stale).toBe(true);
+ expect(query.hasNext).toBe(true);
+
+ fake.executions[0]?.complete();
+ expect(query.fetching).toBe(false);
+ expect(query.isFetching).toBe(false);
+ expect(query.stale).toBe(false);
+ expect(query.hasNext).toBe(false);
+ });
+
+ it('does not track synchronous result-observer dependencies as options', () => {
+ const [observerDependency, setObserverDependency] = createSignal(0);
+ let executions = 0;
+ const client = {
+ executeQuery: () => {
+ executions += 1;
+ return fromValue({
+ operation: { kind: 'query', context: {} } as Operation<
+ Data,
+ Variables
+ >,
+ data: { value: 'synchronous' },
+ stale: false,
+ hasNext: false,
+ });
+ },
+ } as unknown as Client;
+ const query = setup(() => ({
+ ...activeOptions(client),
+ onResult: () => observerDependency(),
+ }));
+
+ expect(query.data).toEqual({ value: 'synchronous' });
+ expect(query.status).toBe('success');
+ expect(query.fetchStatus).toBe('idle');
+ expect(executions).toBe(1);
+
+ setObserverDependency(1);
+ expect(executions).toBe(1);
+ });
+});
+
+describe('createUrqlQuery refetch', () => {
+ it('applies overrides and resolves only after the final fresh result', async () => {
+ const fake = makeFakeClient();
+ const query = setup(() => ({
+ ...activeOptions(fake.client),
+ requestPolicy: 'cache-first',
+ context: { fetchOptions: { headers: { base: 'yes' } } },
+ }));
+ fake.executions[0]?.next({ data: { value: 'initial' } });
+
+ let settled = false;
+ const refetch = query
+ .refetch({
+ requestPolicy: 'network-only',
+ context: { fetchOptions: { headers: { refresh: 'yes' } } },
+ })
+ .then((value) => {
+ settled = true;
+ return value;
+ });
+ const execution = fake.executions[1];
+ expect(execution?.context.requestPolicy).toBe('network-only');
+ expect(execution?.context.fetchOptions).toEqual({
+ headers: { refresh: 'yes' },
+ });
+
+ execution?.next({ data: { value: 'stale' }, stale: true });
+ await Promise.resolve();
+ expect(settled).toBe(false);
+
+ execution?.next({ data: { value: 'part' }, hasNext: true });
+ await Promise.resolve();
+ expect(settled).toBe(false);
+
+ execution?.next({ data: { value: 'fresh' }, hasNext: false });
+ await expect(refetch).resolves.toBe(query);
+ expect(query.data).toEqual({ value: 'fresh' });
+ });
+
+ it('retains data for a same-identity refetch when configured to clear new identities', async () => {
+ const fake = makeFakeClient();
+ const query = setup(() => ({
+ ...activeOptions(fake.client),
+ keepPreviousData: false,
+ }));
+ fake.executions[0]?.next({ data: { value: 'existing' } });
+
+ const refetch = query.refetch();
+ expect(query.data).toEqual({ value: 'existing' });
+ expect(query.isRefetching).toBe(true);
+
+ fake.executions[1]?.next({ data: { value: 'refetched' } });
+ await expect(refetch).resolves.toBe(query);
+ });
+
+ it('resolves errors by default and rejects with throwOnError', async () => {
+ const fake = makeFakeClient();
+ const query = setup(() => activeOptions(fake.client));
+ const firstError = new CombinedError({ graphQLErrors: ['first'] });
+ const secondError = new CombinedError({ graphQLErrors: ['second'] });
+
+ const first = query.refetch();
+ fake.executions[1]?.next({ error: firstError });
+ await expect(first).resolves.toBe(query);
+ expect(query.error).toBe(firstError);
+
+ const second = query.refetch({ throwOnError: true });
+ fake.executions[2]?.next({ error: secondError });
+ await expect(second).rejects.toBe(secondError);
+ expect(query.error).toBe(secondError);
+ });
+
+ it('rejects a final stale error when its source completes', async () => {
+ const fake = makeFakeClient();
+ const query = setup(() => activeOptions(fake.client));
+ const error = new CombinedError({ graphQLErrors: ['stale terminal'] });
+
+ const refetch = query.refetch({ throwOnError: true });
+ fake.executions[1]?.next({ error, stale: true });
+ fake.executions[1]?.complete();
+
+ await expect(refetch).rejects.toBe(error);
+ expect(query.fetchStatus).toBe('idle');
+ expect(query.stale).toBe(false);
+ });
+
+ it('settles before invoking throwing or reentrant result observers', async () => {
+ const fake = makeFakeClient();
+ const consoleError = vi
+ .spyOn(console, 'error')
+ .mockImplementation(() => {});
+ let query!: UrqlQueryResult<Data, Variables>;
+ let reentrant: Promise<UrqlQueryResult<Data, Variables>> | undefined;
+ let shouldReenter = false;
+ query = setup(() => ({
+ ...activeOptions(fake.client),
+ onResult: () => {
+ if (shouldReenter) {
+ shouldReenter = false;
+ reentrant = query.refetch();
+ return;
+ }
+ throw new Error('observer failed');
+ },
+ }));
+
+ const throwing = query.refetch();
+ expect(() =>
+ fake.executions[1]?.next({ data: { value: 'first' } })
+ ).not.toThrow();
+ await expect(throwing).resolves.toBe(query);
+ expect(consoleError).toHaveBeenCalledOnce();
+
+ shouldReenter = true;
+ const outer = query.refetch();
+ fake.executions[2]?.next({ data: { value: 'outer' } });
+ await expect(outer).resolves.toBe(query);
+ expect(reentrant).toBeDefined();
+
+ let reentrantSettled = false;
+ void reentrant?.then(() => {
+ reentrantSettled = true;
+ });
+ await Promise.resolve();
+ expect(reentrantSettled).toBe(false);
+ fake.executions[3]?.next({ data: { value: 'inner' } });
+ await expect(reentrant).resolves.toBe(query);
+ consoleError.mockRestore();
+ });
+
+ it('settles refetches from synchronously completing sources', async () => {
+ const client = {
+ executeQuery: () =>
+ fromValue({
+ operation: { kind: 'query', context: {} } as Operation<
+ Data,
+ Variables
+ >,
+ data: { value: 'synchronous' },
+ stale: false,
+ hasNext: false,
+ }),
+ } as unknown as Client;
+ const query = setup(() => activeOptions(client));
+
+ await expect(query.refetch()).resolves.toBe(query);
+ expect(query.data).toEqual({ value: 'synchronous' });
+ expect(query.fetchStatus).toBe('idle');
+ });
+
+ it('manually executes a disabled query without changing its configured state', async () => {
+ const fake = makeFakeClient();
+ const query = setup(
+ () => ({
+ query: DOCUMENT,
+ variables: { input: 'manual' },
+ enabled: false,
+ }),
+ fake.client
+ );
+
+ expect(fake.executions).toHaveLength(0);
+ expect(query.isEnabled).toBe(false);
+
+ const refetch = query.refetch();
+ expect(fake.executions).toHaveLength(1);
+ expect(query.isEnabled).toBe(false);
+ expect(query.isFetching).toBe(true);
+
+ fake.executions[0]?.next({ data: { value: 'manual result' } });
+ await expect(refetch).resolves.toBe(query);
+ expect(query.data).toEqual({ value: 'manual result' });
+ expect(query.isEnabled).toBe(false);
+ expect(query.isFetching).toBe(false);
+ });
+
+ it('is a safe no-op for a disabled query without variables', async () => {
+ const fake = makeFakeClient();
+ const query = setup(
+ () => ({
+ query: DOCUMENT,
+ enabled: false,
+ }),
+ fake.client
+ );
+
+ await expect(query.refetch()).resolves.toBe(query);
+ expect(fake.executions).toHaveLength(0);
+ expect(query.isEnabled).toBe(false);
+ });
+
+ it('settles superseded and disposed refetches without leaking promises', async () => {
+ const fake = makeFakeClient();
+ const query = setup(() => activeOptions(fake.client));
+
+ const superseded = query.refetch();
+ const active = query.refetch();
+ await expect(superseded).resolves.toBe(query);
+ expect(fake.executions[1]?.unsubscribed).toBe(true);
+
+ fake.executions[2]?.next({ data: { value: 'active' } });
+ await expect(active).resolves.toBe(query);
+
+ const disposed = query.refetch();
+ disposals.pop()?.();
+ await expect(disposed).resolves.toBe(query);
+ expect(fake.executions[3]?.unsubscribed).toBe(true);
+ });
+});
diff --git a/apps/web/src/lib/urql-solid/create-urql-query.ts b/apps/web/src/lib/urql-solid/create-urql-query.ts
new file mode 100644
index 0000000000..433f472295
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/create-urql-query.ts
@@ -0,0 +1,20 @@
+import type { AnyVariables } from '@urql/core';
+import type { Accessor } from 'solid-js';
+import { createBaseQuery } from './create-base-query';
+import { createQueryObserver } from './query-observer';
+import type { UrqlQueryOptions, UrqlQueryResult } from './types';
+
+/** Creates a live Solid binding over one urql query observer. */
+export function createUrqlQuery<
+ QueryData = unknown,
+ Variables extends AnyVariables = AnyVariables,
+ Data = QueryData,
+>(
+ getOptions: Accessor<UrqlQueryOptions<QueryData, Variables, Data>>
+): UrqlQueryResult<Data, Variables, QueryData> {
+ return createBaseQuery(
+ getOptions,
+ createQueryObserver<QueryData, Variables, Data>,
+ 'createUrqlQuery'
+ );
+}
diff --git a/apps/web/src/lib/urql-solid/index.ts b/apps/web/src/lib/urql-solid/index.ts
new file mode 100644
index 0000000000..cd6f7f7546
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/index.ts
@@ -0,0 +1,27 @@
+/** Application-local Solid bindings for urql query operations. */
+
+export {
+ UrqlProvider,
+ type UrqlProviderProps,
+ useUrqlClient,
+} from './context';
+export { createUrqlInfiniteQuery } from './create-urql-infinite-query';
+export { createUrqlMutation } from './create-urql-mutation';
+export { createUrqlQuery } from './create-urql-query';
+export type {
+ UrqlClientSource,
+ UrqlInfiniteData,
+ UrqlInfiniteQueryOptions,
+ UrqlInfiniteQueryPageContext,
+ UrqlInfiniteQueryResult,
+ UrqlMutationExecutionOptions,
+ UrqlMutationExecutor,
+ UrqlMutationExecutorArgs,
+ UrqlMutationOptions,
+ UrqlMutationResult,
+ UrqlQueryFetchStatus,
+ UrqlQueryOptions,
+ UrqlQueryRefetchOptions,
+ UrqlQueryResult,
+ UrqlQueryStatus,
+} from './types';
diff --git a/apps/web/src/lib/urql-solid/infinite-query-observer.ts b/apps/web/src/lib/urql-solid/infinite-query-observer.ts
new file mode 100644
index 0000000000..b65934f7b0
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/infinite-query-observer.ts
@@ -0,0 +1,678 @@
+import {
+ type AnyVariables,
+ type Client,
+ type CombinedError,
+ createRequest,
+ type OperationContext,
+ type OperationResult,
+} from '@urql/core';
+import type { UrqlObserver } from './observer';
+import { QueryObserver } from './query-observer';
+import type {
+ UrqlInfiniteData,
+ UrqlInfiniteQueryOptions,
+ UrqlInfiniteQueryResult,
+ UrqlQueryOptions,
+ UrqlQueryRefetchOptions,
+} from './types';
+import { getQueryStatus, ObserverResult, toCombinedError } from './utils';
+
+type InfiniteOptions<
+ PageData,
+ Variables extends AnyVariables,
+ PageParam,
+ SelectedData,
+> = UrqlInfiniteQueryOptions<PageData, Variables, PageParam, SelectedData>;
+
+type InfiniteResult<
+ PageData,
+ Variables extends AnyVariables,
+ PageParam,
+ SelectedData,
+> = UrqlInfiniteQueryResult<PageData, Variables, PageParam, SelectedData>;
+
+type Page<PageData, Variables extends AnyVariables, PageParam> = {
+ pageIndex: number;
+ pageParam: PageParam;
+ variables: Variables;
+ observer: QueryObserver<PageData, Variables>;
+ unsubscribe: () => void;
+};
+
+type InfiniteQueryKey<PageParam> = {
+ key: number;
+ initialPageParam: PageParam;
+ requestPolicy: unknown;
+ context: Partial<OperationContext> | undefined;
+};
+
+type InfiniteQueryObserverState<SelectedData> = {
+ previousData: SelectedData | undefined;
+ enabled: boolean;
+ fetchingNextPage: boolean;
+ refetching: boolean;
+ paginationError: CombinedError | undefined;
+};
+
+type NextPageParamResult<PageParam> = {
+ pageParam: PageParam | null | undefined;
+ error: CombinedError | null;
+};
+
+function shallowEqualContext(
+ left: Partial<OperationContext> | undefined,
+ right: Partial<OperationContext> | undefined
+): boolean {
+ if (left === right) return true;
+ if (!left || !right) return false;
+ const leftKeys = Object.keys(left) as (keyof OperationContext)[];
+ const rightKeys = Object.keys(right) as (keyof OperationContext)[];
+ if (leftKeys.length !== rightKeys.length) return false;
+ return leftKeys.every((key) => Object.is(left[key], right[key]));
+}
+
+function sameQuery<PageParam>(
+ left: InfiniteQueryKey<PageParam> | undefined,
+ right: InfiniteQueryKey<PageParam>
+): boolean {
+ return (
+ left !== undefined &&
+ left.key === right.key &&
+ Object.is(left.initialPageParam, right.initialPageParam) &&
+ left.requestPolicy === right.requestPolicy &&
+ shallowEqualContext(left.context, right.context)
+ );
+}
+
+/** Observer for a paginated set of live urql queries. */
+export class InfiniteQueryObserver<
+ PageData,
+ Variables extends AnyVariables,
+ PageParam,
+ SelectedData = UrqlInfiniteData<PageData, PageParam>,
+> implements
+ UrqlObserver<
+ InfiniteOptions<PageData, Variables, PageParam, SelectedData>,
+ InfiniteResult<PageData, Variables, PageParam, SelectedData>
+ >
+{
+ private client: Client;
+ private options: InfiniteOptions<
+ PageData,
+ Variables,
+ PageParam,
+ SelectedData
+ >;
+ private queryKey: InfiniteQueryKey<PageParam> | undefined;
+ private readonly pages: Page<PageData, Variables, PageParam>[] = [];
+ private state: InfiniteQueryObserverState<SelectedData> = {
+ previousData: undefined,
+ enabled: true,
+ fetchingNextPage: false,
+ refetching: false,
+ paginationError: undefined,
+ };
+ private failedNextPage: Page<PageData, Variables, PageParam> | undefined;
+ private currentResult!: InfiniteResult<
+ PageData,
+ Variables,
+ PageParam,
+ SelectedData
+ >;
+ private readonly result = new ObserverResult(() => this.getCurrentResult());
+ private actionController = new AbortController();
+ private destroyed = false;
+ private fetchNextPromise:
+ | Promise<InfiniteResult<PageData, Variables, PageParam, SelectedData>>
+ | undefined;
+ private refetchPromise:
+ | Promise<InfiniteResult<PageData, Variables, PageParam, SelectedData>>
+ | undefined;
+
+ constructor(
+ client: Client,
+ options: InfiniteOptions<PageData, Variables, PageParam, SelectedData>
+ ) {
+ this.client = client;
+ this.options = options;
+ this.currentResult = this.buildResult();
+ this.applyOptions(options, client);
+ }
+
+ getCurrentResult(): InfiniteResult<
+ PageData,
+ Variables,
+ PageParam,
+ SelectedData
+ > {
+ return this.currentResult;
+ }
+
+ private buildResult(): InfiniteResult<
+ PageData,
+ Variables,
+ PageParam,
+ SelectedData
+ > {
+ const infiniteData = this.successfulPages();
+ let data = this.state.previousData;
+ let derivationError: CombinedError | null = null;
+
+ if (infiniteData.pages.length > 0) {
+ try {
+ data = this.options.select
+ ? this.options.select(infiniteData)
+ : (infiniteData as SelectedData);
+ } catch (cause) {
+ derivationError = toCombinedError(cause);
+ }
+ }
+
+ const pageResults = this.pages.map((page) =>
+ page.observer.getCurrentResult()
+ );
+ const pageError = pageResults.find((page) => page.error)?.error ?? null;
+ const fetching = pageResults.some((page) => page.fetching);
+ const stale = pageResults.some((page) => page.stale);
+ const pageIsFetching = pageResults.some((page) => page.isFetching);
+ const fetched =
+ pageResults.some((page) => page.isFetched) ||
+ this.state.previousData !== undefined;
+ let nextPageParam: PageParam | null | undefined;
+
+ if (!derivationError) {
+ const nextPage = this.resolveNextPageParam(infiniteData);
+ nextPageParam = nextPage.pageParam;
+ derivationError = nextPage.error;
+ }
+
+ const error = this.state.paginationError ?? derivationError ?? pageError;
+ const hasNextPage =
+ !this.state.paginationError &&
+ !derivationError &&
+ nextPageParam !== null &&
+ nextPageParam !== undefined;
+ const isFetching =
+ pageIsFetching || this.state.fetchingNextPage || this.state.refetching;
+ const status = getQueryStatus(error, fetched);
+
+ return {
+ data,
+ error,
+ fetching,
+ stale,
+ status,
+ fetchStatus: isFetching ? 'fetching' : 'idle',
+ isPending: status === 'pending',
+ isLoading: status === 'pending' && isFetching,
+ isInitialLoading: status === 'pending' && isFetching,
+ isFetching,
+ isRefetching:
+ this.state.refetching ||
+ (fetched && !this.state.fetchingNextPage && pageIsFetching),
+ isSuccess: status === 'success',
+ isError: status === 'error',
+ isEnabled: this.state.enabled,
+ isFetched: fetched,
+ hasNextPage,
+ isFetchingNextPage: this.state.fetchingNextPage,
+ isFetchNextPageError:
+ this.state.paginationError !== undefined ||
+ this.failedNextPage !== undefined,
+ fetchNextPage: this.fetchNextPage,
+ refetch: this.refetch,
+ };
+ }
+
+ setReference(
+ result: InfiniteResult<PageData, Variables, PageParam, SelectedData>
+ ): void {
+ this.result.setReference(result);
+ }
+
+ setOptions(
+ options: InfiniteOptions<PageData, Variables, PageParam, SelectedData>,
+ client: Client
+ ): void {
+ if (this.destroyed) return;
+ this.applyOptions(options, client);
+ }
+
+ subscribe(
+ listener: (
+ result: InfiniteResult<PageData, Variables, PageParam, SelectedData>
+ ) => void
+ ): () => void {
+ return this.result.subscribe(listener);
+ }
+
+ destroy(): void {
+ if (this.destroyed) return;
+ this.destroyed = true;
+ this.cancelActions();
+ this.destroyPages();
+ this.result.clear();
+ }
+
+ readonly fetchNextPage = (
+ refetchOptions: UrqlQueryRefetchOptions = {}
+ ): Promise<InfiniteResult<PageData, Variables, PageParam, SelectedData>> => {
+ if (this.fetchNextPromise) return this.fetchNextPromise;
+
+ const signal = this.actionController.signal;
+ const pendingRefetch = this.refetchPromise;
+ const action = pendingRefetch
+ ? pendingRefetch.then(() => this.runFetchNextPage(refetchOptions, signal))
+ : this.runFetchNextPage(refetchOptions, signal);
+ const trackedAction = action.finally(() => {
+ if (this.fetchNextPromise === trackedAction) {
+ this.fetchNextPromise = undefined;
+ }
+ });
+
+ this.fetchNextPromise = trackedAction;
+
+ return trackedAction;
+ };
+
+ readonly refetch = (
+ refetchOptions: UrqlQueryRefetchOptions = {}
+ ): Promise<InfiniteResult<PageData, Variables, PageParam, SelectedData>> => {
+ if (this.refetchPromise) return this.refetchPromise;
+
+ const signal = this.actionController.signal;
+ const pendingFetchNext = this.fetchNextPromise;
+ const action = pendingFetchNext
+ ? pendingFetchNext.then(() => this.runRefetch(refetchOptions, signal))
+ : this.runRefetch(refetchOptions, signal);
+ const trackedAction = action.finally(() => {
+ if (this.refetchPromise === trackedAction) {
+ this.refetchPromise = undefined;
+ }
+ });
+
+ this.refetchPromise = trackedAction;
+
+ return trackedAction;
+ };
+
+ private applyOptions(
+ options: InfiniteOptions<PageData, Variables, PageParam, SelectedData>,
+ client: Client
+ ): void {
+ const wasEnabled = this.state.enabled;
+ const previousResult = this.getCurrentResult();
+ this.options = options;
+ this.client = client;
+
+ if (options.enabled === false) {
+ this.cancelActions();
+ this.setState({ enabled: false });
+
+ for (const page of this.pages) {
+ page.observer.setOptions(this.pageOptions(page, false), client);
+ }
+ this.emit();
+ return;
+ }
+
+ const initialVariables = options.variables(options.initialPageParam, 0);
+ const request = createRequest<PageData, Variables>(
+ options.query,
+ initialVariables
+ );
+ const queryKey: InfiniteQueryKey<PageParam> = {
+ key: request.key,
+ initialPageParam: options.initialPageParam,
+ requestPolicy: options.requestPolicy,
+ context: options.context,
+ };
+ const queryChanged = !sameQuery(this.queryKey, queryKey);
+
+ if (queryChanged) {
+ this.cancelActions();
+ this.setState({
+ previousData:
+ options.keepPreviousData !== false ? previousResult.data : undefined,
+ paginationError: undefined,
+ });
+ this.queryKey = queryKey;
+ this.destroyPages();
+ }
+
+ this.setState({ enabled: true });
+ if (this.pages.length === 0) {
+ this.appendPage(options.initialPageParam, 0, initialVariables);
+ } else if (!wasEnabled) {
+ for (const page of this.pages) {
+ page.observer.setOptions(this.pageOptions(page, true), client);
+ }
+ }
+ this.emit();
+ }
+
+ private pageOptions(
+ page: Pick<
+ Page<PageData, Variables, PageParam>,
+ 'pageIndex' | 'pageParam' | 'variables'
+ >,
+ enabled: boolean
+ ): UrqlQueryOptions<PageData, Variables> {
+ return {
+ query: this.options.query,
+ variables: page.variables,
+ client: this.client,
+ enabled,
+ requestPolicy: this.options.requestPolicy,
+ context: this.options.context,
+ keepPreviousData: true,
+ onResult: (result: OperationResult<PageData, Variables>) =>
+ this.options.onResult?.(result, {
+ pageIndex: page.pageIndex,
+ pageParam: page.pageParam,
+ }),
+ };
+ }
+
+ private appendPage(
+ pageParam: PageParam,
+ pageIndex: number,
+ variables = this.options.variables(pageParam, pageIndex),
+ executeImmediately = true
+ ): Page<PageData, Variables, PageParam> {
+ const descriptor = { pageIndex, pageParam, variables };
+ const observer = new QueryObserver<PageData, Variables>(
+ this.client,
+ this.pageOptions(descriptor, this.state.enabled),
+ executeImmediately
+ );
+ const page: Page<PageData, Variables, PageParam> = {
+ ...descriptor,
+ observer,
+ unsubscribe: () => undefined,
+ };
+ page.unsubscribe = observer.subscribe(() => this.handlePageUpdate(page));
+
+ this.pages.push(page);
+ this.emit();
+
+ return page;
+ }
+
+ private handlePageUpdate(page: Page<PageData, Variables, PageParam>): void {
+ const result = page.observer.getCurrentResult();
+
+ if (
+ this.failedNextPage === page &&
+ result.isFetched &&
+ !result.isFetching &&
+ !result.error
+ ) {
+ this.failedNextPage = undefined;
+ }
+
+ this.emit();
+ }
+
+ private cancelActions(): void {
+ this.actionController.abort();
+ this.actionController = new AbortController();
+ this.fetchNextPromise = undefined;
+ this.refetchPromise = undefined;
+ this.failedNextPage = undefined;
+ this.setState({
+ fetchingNextPage: false,
+ refetching: false,
+ });
+ }
+
+ private destroyPages(fromIndex = 0): void {
+ const removed = this.pages.splice(fromIndex);
+ for (const page of removed) {
+ page.unsubscribe();
+ page.observer.destroy();
+ }
+ }
+
+ private successfulPages(
+ pages = this.pages
+ ): UrqlInfiniteData<PageData, PageParam> {
+ const data: PageData[] = [];
+ const pageParams: PageParam[] = [];
+ for (const page of pages) {
+ const result = page.observer.getCurrentResult();
+ if (result.data !== undefined) {
+ data.push(result.data);
+ pageParams.push(page.pageParam);
+ }
+ }
+ return { pages: data, pageParams };
+ }
+
+ private resolveNextPageParam(
+ data = this.successfulPages()
+ ): NextPageParamResult<PageParam> {
+ const lastPage = data.pages.at(-1);
+ if (lastPage === undefined || data.pageParams.length === 0) {
+ return { pageParam: undefined, error: null };
+ }
+
+ const lastPageParam = data.pageParams[
+ data.pageParams.length - 1
+ ] as PageParam;
+
+ try {
+ return {
+ pageParam: this.options.getNextPageParam(
+ lastPage,
+ data.pages,
+ lastPageParam,
+ data.pageParams
+ ),
+ error: null,
+ };
+ } catch (cause) {
+ return { pageParam: undefined, error: toCombinedError(cause) };
+ }
+ }
+
+ private async runFetchNextPage(
+ refetchOptions: UrqlQueryRefetchOptions,
+ signal: AbortSignal
+ ): Promise<InfiniteResult<PageData, Variables, PageParam, SelectedData>> {
+ if (signal.aborted || this.destroyed || !this.state.enabled) {
+ return this.actionResult();
+ }
+
+ const nextPage = this.resolveNextPageParam();
+
+ if (nextPage.error) {
+ this.setState({ paginationError: nextPage.error });
+ this.emit();
+
+ if (refetchOptions.throwOnError) throw nextPage.error;
+
+ return this.actionResult();
+ }
+
+ const pageParam = nextPage.pageParam;
+ if (pageParam === null || pageParam === undefined) {
+ return this.actionResult();
+ }
+
+ const existing = this.pages.find(
+ (page) =>
+ Object.is(page.pageParam, pageParam) &&
+ page.observer.getCurrentResult().data === undefined
+ );
+ const duplicate = this.pages.some(
+ (page) => Object.is(page.pageParam, pageParam) && page !== existing
+ );
+
+ if (duplicate) {
+ const error = toCombinedError(
+ new Error('infinite query returned a repeated page parameter')
+ );
+
+ this.setState({ paginationError: error });
+ this.emit();
+
+ if (refetchOptions.throwOnError) throw error;
+
+ return this.actionResult();
+ }
+
+ this.failedNextPage = undefined;
+ this.setState({ fetchingNextPage: true });
+ this.emit();
+
+ const page =
+ existing ??
+ this.appendPage(pageParam, this.pages.length, undefined, false);
+
+ try {
+ await page.observer.refetch(refetchOptions);
+
+ if (signal.aborted) return this.actionResult();
+
+ const error = page.observer.getCurrentResult().error;
+
+ this.failedNextPage = error ? page : undefined;
+ this.emit();
+
+ return this.actionResult();
+ } catch (cause) {
+ if (signal.aborted) return this.actionResult();
+
+ this.failedNextPage = page;
+ this.emit();
+
+ throw cause;
+ } finally {
+ if (!signal.aborted) {
+ this.setState({ fetchingNextPage: false });
+ this.emit();
+ }
+ }
+ }
+
+ private async runRefetch(
+ refetchOptions: UrqlQueryRefetchOptions,
+ signal: AbortSignal
+ ): Promise<InfiniteResult<PageData, Variables, PageParam, SelectedData>> {
+ if (signal.aborted || this.destroyed || !this.state.enabled) {
+ return this.actionResult();
+ }
+
+ const targetPageCount = Math.max(1, this.pages.length);
+
+ this.failedNextPage = undefined;
+ this.setState({
+ refetching: true,
+ paginationError: undefined,
+ });
+ this.emit();
+
+ try {
+ if (this.pages.length === 0) {
+ const firstPage = this.appendPage(
+ this.options.initialPageParam,
+ 0,
+ undefined,
+ false
+ );
+
+ await firstPage.observer.refetch(refetchOptions);
+ } else {
+ await this.pages[0]?.observer.refetch(refetchOptions);
+ }
+
+ if (signal.aborted) return this.actionResult();
+
+ for (let pageIndex = 1; pageIndex < targetPageCount; pageIndex += 1) {
+ if (signal.aborted || this.destroyed || !this.state.enabled) break;
+
+ const previousData = this.successfulPages(
+ this.pages.slice(0, pageIndex)
+ );
+
+ if (previousData.pages.length !== pageIndex) {
+ this.destroyPages(pageIndex);
+ break;
+ }
+
+ const nextPage = this.resolveNextPageParam(previousData);
+
+ if (nextPage.error) {
+ this.setState({ paginationError: nextPage.error });
+ this.emit();
+ if (refetchOptions.throwOnError) throw nextPage.error;
+ break;
+ }
+
+ const expectedPageParam = nextPage.pageParam;
+ if (expectedPageParam === null || expectedPageParam === undefined) {
+ this.destroyPages(pageIndex);
+ break;
+ }
+
+ let page = this.pages[pageIndex];
+
+ if (!page || !Object.is(page.pageParam, expectedPageParam)) {
+ this.destroyPages(pageIndex);
+ page = this.appendPage(
+ expectedPageParam,
+ pageIndex,
+ undefined,
+ false
+ );
+ }
+
+ await page.observer.refetch(refetchOptions);
+ }
+
+ return this.actionResult();
+ } catch (cause) {
+ if (signal.aborted) return this.actionResult();
+ throw cause;
+ } finally {
+ if (!signal.aborted) {
+ this.setState({ refetching: false });
+ this.emit();
+ }
+ }
+ }
+
+ private setState(
+ nextState: Partial<InfiniteQueryObserverState<SelectedData>>
+ ): void {
+ this.state = { ...this.state, ...nextState };
+ }
+
+ private actionResult(): InfiniteResult<
+ PageData,
+ Variables,
+ PageParam,
+ SelectedData
+ > {
+ return this.result.getActionResult();
+ }
+
+ private emit(): void {
+ this.currentResult = this.buildResult();
+ this.result.notify();
+ }
+}
+
+/** Creates an observer for {@link createUrqlInfiniteQuery}. */
+export function createInfiniteQueryObserver<
+ PageData,
+ Variables extends AnyVariables,
+ PageParam,
+ SelectedData = UrqlInfiniteData<PageData, PageParam>,
+>(
+ client: Client,
+ options: InfiniteOptions<PageData, Variables, PageParam, SelectedData>
+): InfiniteQueryObserver<PageData, Variables, PageParam, SelectedData> {
+ return new InfiniteQueryObserver(client, options);
+}
diff --git a/apps/web/src/lib/urql-solid/mutation-observer.ts b/apps/web/src/lib/urql-solid/mutation-observer.ts
new file mode 100644
index 0000000000..180089a307
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/mutation-observer.ts
@@ -0,0 +1,294 @@
+import type {
+ AnyVariables,
+ Client,
+ Operation,
+ OperationResult,
+ OperationResultSource,
+} from '@urql/core';
+import type { UrqlObserver } from './observer';
+import type {
+ UrqlMutationExecutionOptions,
+ UrqlMutationOptions,
+ UrqlMutationResult,
+} from './types';
+import { ObserverResult, toCombinedError } from './utils';
+
+type MutationOptions<
+ MutationData,
+ Variables extends AnyVariables,
+ Input,
+ OnMutateResult,
+> = UrqlMutationOptions<MutationData, Variables, Input, OnMutateResult>;
+
+type ExecutionOptions<
+ MutationData,
+ Variables extends AnyVariables,
+ Input,
+ OnMutateResult,
+> = UrqlMutationExecutionOptions<
+ MutationData,
+ Variables,
+ Input,
+ OnMutateResult
+>;
+
+type MutationResult<
+ MutationData,
+ Variables extends AnyVariables,
+ Input,
+ OnMutateResult,
+> = UrqlMutationResult<MutationData, Variables, Input, OnMutateResult>;
+
+type MutationState<MutationData, Variables extends AnyVariables> = {
+ data: MutationData | undefined;
+ error: UrqlMutationResult<MutationData, Variables>['error'];
+ isPending: boolean;
+ stale: boolean;
+ operation: Operation<MutationData, Variables> | undefined;
+};
+
+function isOperationResultSource<MutationData, Variables extends AnyVariables>(
+ value:
+ | OperationResultSource<OperationResult<MutationData, Variables>>
+ | Promise<OperationResult<MutationData, Variables>>
+): value is OperationResultSource<OperationResult<MutationData, Variables>> {
+ return 'toPromise' in value && typeof value.toPromise === 'function';
+}
+
+/** Framework-neutral observer for imperative urql mutations. */
+export class MutationObserver<
+ MutationData,
+ Variables extends AnyVariables,
+ Input = Variables,
+ OnMutateResult = void,
+> implements
+ UrqlObserver<
+ MutationOptions<MutationData, Variables, Input, OnMutateResult>,
+ MutationResult<MutationData, Variables, Input, OnMutateResult>
+ >
+{
+ private client: Client;
+ private options: MutationOptions<
+ MutationData,
+ Variables,
+ Input,
+ OnMutateResult
+ >;
+ private state: MutationState<MutationData, Variables> = {
+ data: undefined,
+ error: null,
+ isPending: false,
+ stale: false,
+ operation: undefined,
+ };
+ private readonly result = new ObserverResult(() => this.getCurrentResult());
+ private latestExecution: object | undefined;
+ private activeExecutions = 0;
+ private destroyed = false;
+
+ constructor(
+ client: Client,
+ options: MutationOptions<MutationData, Variables, Input, OnMutateResult>
+ ) {
+ this.client = client;
+ this.options = options;
+ }
+
+ getCurrentResult(): MutationResult<
+ MutationData,
+ Variables,
+ Input,
+ OnMutateResult
+ > {
+ return {
+ ...this.state,
+ mutate: this.mutate,
+ mutateAsync: this.mutateAsync,
+ };
+ }
+
+ setOptions(
+ options: MutationOptions<MutationData, Variables, Input, OnMutateResult>,
+ client: Client
+ ): void {
+ if (this.destroyed) return;
+
+ this.options = options;
+ this.client = client;
+ }
+
+ subscribe(
+ listener: (
+ result: MutationResult<MutationData, Variables, Input, OnMutateResult>
+ ) => void
+ ): () => void {
+ return this.result.subscribe(listener);
+ }
+
+ destroy(): void {
+ if (this.destroyed) return;
+
+ this.destroyed = true;
+ this.result.clear();
+ }
+
+ readonly mutate = (
+ input: Input,
+ options: ExecutionOptions<
+ MutationData,
+ Variables,
+ Input,
+ OnMutateResult
+ > = {}
+ ): void => {
+ void this.mutateAsync(input, options).catch(() => undefined);
+ };
+
+ readonly mutateAsync = async (
+ input: Input,
+ executionOptions: ExecutionOptions<
+ MutationData,
+ Variables,
+ Input,
+ OnMutateResult
+ > = {}
+ ): Promise<OperationResult<MutationData, Variables>> => {
+ if (this.destroyed) {
+ throw new Error('cannot execute a destroyed mutation observer');
+ }
+
+ const execution = {};
+ const options = this.options;
+ const client = this.client;
+ const mergedContext = {
+ ...options.context,
+ ...executionOptions.context,
+ };
+ let onMutateResult: OnMutateResult | undefined;
+
+ this.latestExecution = execution;
+ this.activeExecutions += 1;
+ this.setState({ isPending: true });
+ this.result.notify();
+
+ try {
+ let result: OperationResult<MutationData, Variables>;
+ try {
+ onMutateResult = options.onMutate
+ ? await options.onMutate(input)
+ : undefined;
+
+ if (options.execute) {
+ const executionResult = options.execute({
+ client,
+ mutation: options.mutation,
+ input,
+ context: mergedContext,
+ });
+ result = isOperationResultSource(executionResult)
+ ? await executionResult.toPromise()
+ : await executionResult;
+ } else {
+ result = await client
+ .mutation(
+ options.mutation,
+ input as unknown as Variables,
+ mergedContext
+ )
+ .toPromise();
+ }
+ } catch (cause) {
+ const error = toCombinedError(cause);
+ if (!this.destroyed && this.latestExecution === execution) {
+ this.setState({ error, stale: false });
+ this.result.notify();
+ }
+
+ const errorArgs = [error, input, onMutateResult, undefined] as const;
+ const settledArgs = [
+ undefined,
+ error,
+ input,
+ onMutateResult,
+ undefined,
+ ] as const;
+
+ try {
+ await options.onError?.(...errorArgs);
+ await executionOptions.onError?.(...errorArgs);
+ } finally {
+ await options.onSettled?.(...settledArgs);
+ await executionOptions.onSettled?.(...settledArgs);
+ }
+
+ throw error;
+ }
+
+ const error = result.error ?? null;
+ if (!this.destroyed && this.latestExecution === execution) {
+ this.setState({
+ data: result.data,
+ error,
+ stale: result.stale === true,
+ operation: result.operation,
+ });
+ this.result.notify();
+ }
+
+ const settledArgs = [
+ result.data,
+ error,
+ input,
+ onMutateResult,
+ result,
+ ] as const;
+
+ try {
+ if (error) {
+ const errorArgs = [error, input, onMutateResult, result] as const;
+ await options.onError?.(...errorArgs);
+ await executionOptions.onError?.(...errorArgs);
+ } else {
+ const successArgs = [
+ result.data,
+ input,
+ onMutateResult,
+ result,
+ ] as const;
+ await options.onSuccess?.(...successArgs);
+ await executionOptions.onSuccess?.(...successArgs);
+ }
+ } finally {
+ await options.onSettled?.(...settledArgs);
+ await executionOptions.onSettled?.(...settledArgs);
+ }
+
+ return result;
+ } finally {
+ this.activeExecutions -= 1;
+ if (!this.destroyed) {
+ this.setState({ isPending: this.activeExecutions > 0 });
+ this.result.notify();
+ }
+ }
+ };
+
+ private setState(
+ nextState: Partial<MutationState<MutationData, Variables>>
+ ): void {
+ this.state = { ...this.state, ...nextState };
+ }
+}
+
+/** Creates an observer for {@link createUrqlMutation}. */
+export function createMutationObserver<
+ MutationData,
+ Variables extends AnyVariables,
+ Input = Variables,
+ OnMutateResult = void,
+>(
+ client: Client,
+ options: MutationOptions<MutationData, Variables, Input, OnMutateResult>
+): MutationObserver<MutationData, Variables, Input, OnMutateResult> {
+ return new MutationObserver(client, options);
+}
diff --git a/apps/web/src/lib/urql-solid/observer.ts b/apps/web/src/lib/urql-solid/observer.ts
new file mode 100644
index 0000000000..3911b677c0
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/observer.ts
@@ -0,0 +1,29 @@
+import type { Client } from '@urql/core';
+
+/** Query options accepted by the shared Solid observer adapter. */
+export type ObserverClientOptions = {
+ client?: Client;
+};
+
+/** Why an active urql execution reached its terminal lifecycle handler. */
+export type ObserverEndReason = 'cancelled' | 'completed';
+
+/** Observer contract consumed by the Solid base-query adapter. */
+export type UrqlObserver<Options, Result extends object> = {
+ /** Returns the observer's latest complete result snapshot. */
+ getCurrentResult(): Result;
+ /** Supplies the stable Solid result returned by the base adapter. */
+ setReference?(result: Result): void;
+ /** Applies reactive options or a replacement client. */
+ setOptions(options: Options, client: Client): void;
+ /** Subscribes to complete result snapshots. */
+ subscribe(listener: (result: Result) => void): () => void;
+ /** Releases all active urql subscriptions and pending actions. */
+ destroy(): void;
+};
+
+/** Creates one query observer. */
+export type UrqlObserverFactory<Options, Result extends object> = (
+ client: Client,
+ options: Options
+) => UrqlObserver<Options, Result>;
diff --git a/apps/web/src/lib/urql-solid/query-observer.ts b/apps/web/src/lib/urql-solid/query-observer.ts
new file mode 100644
index 0000000000..69977b8fc9
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/query-observer.ts
@@ -0,0 +1,399 @@
+import {
+ type AnyVariables,
+ type Client,
+ type CombinedError,
+ createRequest,
+ type OperationContext,
+ type OperationResult,
+ type OperationResultSource,
+} from '@urql/core';
+import { onEnd, pipe, type Subscription, subscribe } from 'wonka';
+import type { ObserverEndReason, UrqlObserver } from './observer';
+import type {
+ UrqlQueryOptions,
+ UrqlQueryRefetchOptions,
+ UrqlQueryResult,
+} from './types';
+import { getQueryStatus, ObserverResult, toCombinedError } from './utils';
+
+type PendingRefetch<QueryData, Variables extends AnyVariables, Data> = {
+ resolve: (result: UrqlQueryResult<Data, Variables, QueryData>) => void;
+ reject: (error: unknown) => void;
+ throwOnError: boolean;
+};
+
+type QueryExecution<QueryData, Variables extends AnyVariables, Data> = {
+ options: UrqlQueryOptions<QueryData, Variables, Data>;
+ source: OperationResultSource<OperationResult<QueryData, Variables>>;
+ subscription?: Subscription;
+ pending?: PendingRefetch<QueryData, Variables, Data>;
+ lastError?: CombinedError;
+};
+
+type QueryObserverState<QueryData, Variables extends AnyVariables, Data> = {
+ data: Data | undefined;
+ error: CombinedError | null;
+ fetching: boolean;
+ stale: boolean;
+ hasNext: boolean;
+ operation: OperationResult<QueryData, Variables>['operation'] | undefined;
+ extensions: Record<string, unknown> | undefined;
+ enabled: boolean;
+ fetched: boolean;
+};
+
+/** Observer for one live urql query source. */
+export class QueryObserver<
+ QueryData,
+ Variables extends AnyVariables,
+ Data = QueryData,
+> implements
+ UrqlObserver<
+ UrqlQueryOptions<QueryData, Variables, Data>,
+ UrqlQueryResult<Data, Variables, QueryData>
+ >
+{
+ private client: Client;
+ private options: UrqlQueryOptions<QueryData, Variables, Data>;
+ private execution: QueryExecution<QueryData, Variables, Data> | undefined;
+ // Distinguishes a new query/variables pair from a same-request refetch when
+ // keepPreviousData is disabled. Client changes create a new observer.
+ private lastRequestKey: number | undefined;
+ private state: QueryObserverState<QueryData, Variables, Data> = {
+ data: undefined,
+ error: null,
+ fetching: false,
+ stale: false,
+ hasNext: false,
+ operation: undefined,
+ extensions: undefined,
+ enabled: true,
+ fetched: false,
+ };
+ private readonly result = new ObserverResult(() => this.getCurrentResult());
+ private destroyed = false;
+
+ constructor(
+ client: Client,
+ options: UrqlQueryOptions<QueryData, Variables, Data>,
+ executeImmediately = true
+ ) {
+ this.client = client;
+ this.options = options;
+
+ if (executeImmediately) {
+ this.setOptions(options, client);
+ } else {
+ this.setState({ enabled: options.enabled !== false });
+ }
+ }
+
+ getCurrentResult(): UrqlQueryResult<Data, Variables, QueryData> {
+ const status = getQueryStatus(this.state.error, this.state.fetched);
+
+ const isFetching =
+ this.state.fetching || this.state.stale || this.state.hasNext;
+
+ return {
+ data: this.state.data,
+ error: this.state.error,
+ fetching: this.state.fetching,
+ status,
+ fetchStatus: isFetching ? 'fetching' : 'idle',
+ isPending: status === 'pending',
+ isLoading: status === 'pending' && isFetching,
+ isInitialLoading: status === 'pending' && isFetching,
+ isFetching,
+ isRefetching: status !== 'pending' && isFetching,
+ isSuccess: status === 'success',
+ isError: status === 'error',
+ isEnabled: this.state.enabled,
+ isFetched: this.state.fetched,
+ stale: this.state.stale,
+ hasNext: this.state.hasNext,
+ operation: this.state.operation,
+ extensions: this.state.extensions,
+ refetch: this.refetch,
+ };
+ }
+
+ setReference(result: UrqlQueryResult<Data, Variables, QueryData>): void {
+ this.result.setReference(result);
+ }
+
+ setOptions(
+ options: UrqlQueryOptions<QueryData, Variables, Data>,
+ client: Client
+ ): void {
+ if (this.destroyed) return;
+
+ this.options = options;
+ this.client = client;
+
+ if (options.enabled === false) {
+ if (this.execution) {
+ this.onEnd(this.execution, 'cancelled');
+ }
+
+ this.setState({
+ enabled: false,
+ fetching: false,
+ stale: false,
+ hasNext: false,
+ });
+ this.result.notify();
+
+ return;
+ }
+
+ this.execute(options, client);
+ }
+
+ subscribe(
+ listener: (result: UrqlQueryResult<Data, Variables, QueryData>) => void
+ ): () => void {
+ return this.result.subscribe(listener);
+ }
+
+ destroy(): void {
+ if (this.destroyed) return;
+
+ this.destroyed = true;
+
+ if (this.execution) {
+ this.onEnd(this.execution, 'cancelled');
+ }
+
+ this.result.clear();
+ }
+
+ readonly refetch = (
+ refetchOptions: UrqlQueryRefetchOptions = {}
+ ): Promise<UrqlQueryResult<Data, Variables, QueryData>> => {
+ if (this.destroyed) {
+ return Promise.resolve(this.result.getActionResult());
+ }
+
+ if (
+ this.options.enabled === false &&
+ this.options.variables === undefined
+ ) {
+ return Promise.resolve(this.result.getActionResult());
+ }
+
+ return new Promise((resolve, reject) => {
+ this.execute(this.options, this.client, refetchOptions, {
+ resolve,
+ reject,
+ throwOnError: refetchOptions.throwOnError === true,
+ });
+ });
+ };
+
+ private execute(
+ options: UrqlQueryOptions<QueryData, Variables, Data>,
+ client: Client,
+ refetchOptions?: UrqlQueryRefetchOptions,
+ pending?: PendingRefetch<QueryData, Variables, Data>
+ ): void {
+ if (this.execution) {
+ this.onEnd(this.execution, 'cancelled');
+ }
+
+ let execution: QueryExecution<QueryData, Variables, Data> | undefined;
+
+ try {
+ const variables = options.variables as Variables;
+ const request = createRequest<QueryData, Variables>(
+ options.query,
+ variables
+ );
+
+ const context: Partial<OperationContext> = {
+ requestPolicy: options.requestPolicy,
+ ...options.context,
+ ...refetchOptions?.context,
+ ...(refetchOptions?.requestPolicy
+ ? { requestPolicy: refetchOptions.requestPolicy }
+ : {}),
+ };
+
+ const requestChanged =
+ this.lastRequestKey !== undefined &&
+ this.lastRequestKey !== request.key;
+
+ this.lastRequestKey = request.key;
+
+ if (options.keepPreviousData === false && requestChanged) {
+ this.setState({
+ data: undefined,
+ error: null,
+ operation: undefined,
+ extensions: undefined,
+ fetched: false,
+ });
+ }
+
+ const currentExecution: QueryExecution<QueryData, Variables, Data> = {
+ options,
+ source: client.executeQuery<QueryData, Variables>(request, context),
+ pending,
+ };
+
+ execution = currentExecution;
+ this.execution = currentExecution;
+
+ this.setState({
+ enabled: options.enabled !== false,
+ fetching: true,
+ stale: false,
+ hasNext: false,
+ });
+ this.result.notify();
+
+ const subscription = pipe(
+ currentExecution.source,
+ onEnd(() => this.onEnd(currentExecution, 'completed')),
+ subscribe((nextResult) =>
+ this.handleResult(currentExecution, nextResult)
+ )
+ );
+
+ if (this.execution === currentExecution) {
+ currentExecution.subscription = subscription;
+ } else {
+ subscription.unsubscribe();
+ }
+ } catch (cause) {
+ if (execution && this.execution === execution) {
+ this.execution = undefined;
+ execution.subscription?.unsubscribe();
+ }
+
+ const error = toCombinedError(cause);
+
+ this.setState({
+ error,
+ enabled: options.enabled !== false,
+ fetching: false,
+ stale: false,
+ hasNext: false,
+ fetched: true,
+ });
+
+ if (pending?.throwOnError) pending.reject(error);
+ else pending?.resolve(this.result.getActionResult());
+
+ this.result.notify();
+ }
+ }
+
+ private onEnd(
+ execution: QueryExecution<QueryData, Variables, Data>,
+ reason: ObserverEndReason
+ ): void {
+ if (this.execution !== execution) return;
+
+ this.execution = undefined;
+
+ if (reason === 'cancelled') {
+ this.settle(execution, reason);
+ execution.subscription?.unsubscribe();
+
+ return;
+ }
+
+ this.setState({
+ fetching: false,
+ stale: false,
+ hasNext: false,
+ });
+
+ this.settle(execution, reason);
+ this.result.notify();
+ }
+
+ private handleResult(
+ execution: QueryExecution<QueryData, Variables, Data>,
+ nextResult: OperationResult<QueryData, Variables>
+ ): void {
+ if (this.execution !== execution) return;
+
+ const stale = nextResult.stale === true;
+ const hasNext = nextResult.hasNext === true;
+ let data: Data | undefined;
+ let error = nextResult.error ?? null;
+
+ if (nextResult.data != null) {
+ try {
+ const select = execution.options.select;
+ data = select
+ ? select(nextResult.data as QueryData)
+ : (nextResult.data as Data);
+ } catch (cause) {
+ error = toCombinedError(cause);
+ }
+ }
+
+ execution.lastError = error ?? undefined;
+
+ this.setState({
+ ...(data !== undefined ? { data } : {}),
+ error,
+ fetching: false,
+ stale,
+ hasNext,
+ operation: nextResult.operation,
+ extensions: nextResult.extensions,
+ fetched: true,
+ });
+ this.result.notify();
+
+ if (!stale && !hasNext) {
+ this.settle(execution, 'completed');
+ }
+
+ try {
+ execution.options.onResult?.(nextResult);
+ } catch (cause) {
+ console.error('urql query result observer failed', cause);
+ }
+ }
+
+ private settle(
+ execution: QueryExecution<QueryData, Variables, Data>,
+ reason: ObserverEndReason
+ ): void {
+ const pending = execution.pending;
+
+ execution.pending = undefined;
+
+ if (
+ reason === 'completed' &&
+ pending?.throwOnError &&
+ execution.lastError
+ ) {
+ pending.reject(execution.lastError);
+ } else {
+ pending?.resolve(this.result.getActionResult());
+ }
+ }
+
+ private setState(
+ nextState: Partial<QueryObserverState<QueryData, Variables, Data>>
+ ): void {
+ this.state = { ...this.state, ...nextState };
+ }
+}
+
+/** Creates an observer for {@link createUrqlQuery}. */
+export function createQueryObserver<
+ QueryData,
+ Variables extends AnyVariables,
+ Data = QueryData,
+>(
+ client: Client,
+ options: UrqlQueryOptions<QueryData, Variables, Data>
+): QueryObserver<QueryData, Variables, Data> {
+ return new QueryObserver(client, options);
+}
diff --git a/apps/web/src/lib/urql-solid/types.ts b/apps/web/src/lib/urql-solid/types.ts
new file mode 100644
index 0000000000..a1a16a58fe
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/types.ts
@@ -0,0 +1,332 @@
+import type { MaybeAccessor } from '@app/lib/signals/access';
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import type {
+ AnyVariables,
+ Client,
+ CombinedError,
+ DocumentInput,
+ GraphQLRequestParams,
+ Operation,
+ OperationContext,
+ OperationResult,
+ OperationResultSource,
+ RequestPolicy,
+} from '@urql/core';
+
+/** Options shared by enabled and disabled urql queries. */
+type UrqlQueryCommonOptions<QueryData, Variables extends AnyVariables, Data> = {
+ /** Overrides the client supplied by the nearest {@link UrqlProvider}. */
+ client?: Client;
+ /** Enables automatic execution. Defaults to true. */
+ enabled?: boolean;
+ /** Default request policy for this query. */
+ requestPolicy?: RequestPolicy;
+ /** Additional operation context merged into each execution. */
+ context?: Partial<OperationContext>;
+ /** Retains prior data while a new request starts. Defaults to true. */
+ keepPreviousData?: boolean;
+ /** Transforms raw GraphQL data before exposing it through the result. */
+ select?: (data: QueryData) => Data;
+ /** Observes every raw result after the query state has been updated. */
+ onResult?: (result: OperationResult<QueryData, Variables>) => void;
+};
+
+/**
+ * Reactive urql query options.
+ *
+ * Enabled requests retain urql's conditional variable requirements. A disabled
+ * branch may omit variables so callers can represent unavailable inputs
+ * without manufacturing placeholder values.
+ */
+export type UrqlQueryOptions<
+ QueryData = unknown,
+ Variables extends AnyVariables = AnyVariables,
+ Data = QueryData,
+> =
+ | (GraphQLRequestParams<QueryData, Variables> &
+ UrqlQueryCommonOptions<QueryData, Variables, Data>)
+ | ({
+ query: DocumentInput<QueryData, Variables>;
+ variables?: Variables;
+ enabled: false;
+ } & UrqlQueryCommonOptions<QueryData, Variables, Data>);
+
+/** Overrides applied to a single imperative query reexecution. */
+export type UrqlQueryRefetchOptions = {
+ /** Overrides the base request policy, for example with `network-only`. */
+ requestPolicy?: RequestPolicy;
+ /** Merges over the query's base operation context. */
+ context?: Partial<OperationContext>;
+ /** Rejects the returned promise when the result contains a CombinedError. */
+ throwOnError?: boolean;
+};
+
+/** TanStack-style high-level status for an urql query. */
+export type UrqlQueryStatus = 'pending' | 'success' | 'error';
+
+/** Whether the binding is currently awaiting another result. */
+export type UrqlQueryFetchStatus = 'idle' | 'fetching';
+
+/**
+ * Stable reactive result returned by {@link createUrqlQuery}.
+ *
+ * Properties are read through a stable proxy over a Solid store and must be
+ * accessed reactively rather than destructured. urql-native result fields
+ * remain available alongside the TanStack-style status flags.
+ */
+export type UrqlQueryResult<
+ Data = unknown,
+ Variables extends AnyVariables = AnyVariables,
+ QueryData = Data,
+> = {
+ readonly data: Data | undefined;
+ readonly error: CombinedError | null;
+ /** urql execution activity before adapting stale results for TanStack. */
+ readonly fetching: boolean;
+ readonly status: UrqlQueryStatus;
+ readonly fetchStatus: UrqlQueryFetchStatus;
+ readonly isPending: boolean;
+ readonly isLoading: boolean;
+ readonly isInitialLoading: boolean;
+ readonly isFetching: boolean;
+ readonly isRefetching: boolean;
+ readonly isSuccess: boolean;
+ readonly isError: boolean;
+ readonly isEnabled: boolean;
+ readonly isFetched: boolean;
+ readonly stale: boolean;
+ readonly hasNext: boolean;
+ readonly operation: Operation<QueryData, Variables> | undefined;
+ readonly extensions: Record<string, unknown> | undefined;
+ /**
+ * Reexecutes the current request and resolves with this same stable result.
+ * Superseded or disposed reexecutions resolve instead of leaving a pending
+ * promise. A disabled query without variables is a no-op.
+ */
+ refetch(
+ options?: UrqlQueryRefetchOptions
+ ): Promise<UrqlQueryResult<Data, Variables, QueryData>>;
+};
+
+/** Ordered page data and the parameters used to load each page. */
+export type UrqlInfiniteData<PageData, PageParam> = {
+ readonly pages: PageData[];
+ readonly pageParams: PageParam[];
+};
+
+/** Metadata supplied to an infinite query's result observer. */
+export type UrqlInfiniteQueryPageContext<PageParam> = {
+ readonly pageIndex: number;
+ readonly pageParam: PageParam;
+};
+
+/** Reactive options for a paginated, live urql query. */
+export type UrqlInfiniteQueryOptions<
+ PageData,
+ Variables extends AnyVariables,
+ PageParam,
+ SelectedData = UrqlInfiniteData<PageData, PageParam>,
+> = {
+ /** Generated GraphQL document used for every page. */
+ query: DocumentInput<PageData, Variables>;
+ /** Parameter used for the first page. */
+ initialPageParam: PageParam;
+ /** Builds generated query variables for one page parameter. */
+ variables: (pageParam: PageParam, pageIndex: number) => Variables;
+ /** Returns the parameter for the page after the current final page. */
+ getNextPageParam: (
+ lastPage: PageData,
+ pages: readonly PageData[],
+ lastPageParam: PageParam,
+ pageParams: readonly PageParam[]
+ ) => PageParam | null | undefined;
+ /** Maps the accumulated pages to consumer-facing data. */
+ select?: (data: UrqlInfiniteData<PageData, PageParam>) => SelectedData;
+ /** Overrides the client supplied by the nearest {@link UrqlProvider}. */
+ client?: Client;
+ /** Enables page subscriptions. Defaults to true. */
+ enabled?: boolean;
+ /** Default request policy for every page. */
+ requestPolicy?: RequestPolicy;
+ /** Additional operation context merged into every page execution. */
+ context?: Partial<OperationContext>;
+ /** Retains accumulated data while the query identity changes. */
+ keepPreviousData?: boolean;
+ /** Observes page results after the corresponding page state updates. */
+ onResult?: (
+ result: OperationResult<PageData, Variables>,
+ page: UrqlInfiniteQueryPageContext<PageParam>
+ ) => void;
+};
+
+/** Stable reactive result returned by {@link createUrqlInfiniteQuery}. */
+export type UrqlInfiniteQueryResult<
+ PageData,
+ Variables extends AnyVariables,
+ PageParam,
+ SelectedData = UrqlInfiniteData<PageData, PageParam>,
+> = {
+ readonly data: SelectedData | undefined;
+ readonly error: CombinedError | null;
+ readonly fetching: boolean;
+ readonly stale: boolean;
+ readonly status: UrqlQueryStatus;
+ readonly fetchStatus: UrqlQueryFetchStatus;
+ readonly isPending: boolean;
+ readonly isLoading: boolean;
+ readonly isInitialLoading: boolean;
+ readonly isFetching: boolean;
+ readonly isRefetching: boolean;
+ readonly isSuccess: boolean;
+ readonly isError: boolean;
+ readonly isEnabled: boolean;
+ readonly isFetched: boolean;
+ readonly hasNextPage: boolean;
+ readonly isFetchingNextPage: boolean;
+ readonly isFetchNextPageError: boolean;
+ fetchNextPage(
+ options?: UrqlQueryRefetchOptions
+ ): Promise<
+ UrqlInfiniteQueryResult<PageData, Variables, PageParam, SelectedData>
+ >;
+ refetch(
+ options?: UrqlQueryRefetchOptions
+ ): Promise<
+ UrqlInfiniteQueryResult<PageData, Variables, PageParam, SelectedData>
+ >;
+};
+
+/** Inputs supplied to a custom mutation execution strategy. */
+export type UrqlMutationExecutorArgs<
+ MutationData,
+ Variables extends AnyVariables,
+ Input = Variables,
+> = {
+ /** Client resolved from the mutation override or nearest provider. */
+ client: Client;
+ /** Generated GraphQL mutation document configured for this mutation. */
+ mutation: TypedDocumentNode<MutationData, Variables>;
+ /** Consumer input supplied to the current mutation execution. */
+ input: Input;
+ /** Fully merged base and execution-specific operation context. */
+ context: Partial<OperationContext>;
+};
+
+/** Overrides how a mutation operation is submitted to urql. */
+export type UrqlMutationExecutor<
+ MutationData,
+ Variables extends AnyVariables,
+ Input = Variables,
+> = (
+ args: UrqlMutationExecutorArgs<MutationData, Variables, Input>
+) =>
+ | OperationResultSource<OperationResult<MutationData, Variables>>
+ | Promise<OperationResult<MutationData, Variables>>;
+
+type MutationCallbackResult = void | Promise<void>;
+
+type MutationCallbacks<
+ MutationData,
+ Variables extends AnyVariables,
+ Input,
+ OnMutateResult,
+> = {
+ /** Runs after a result without a GraphQL or network error is received. */
+ onSuccess?: (
+ data: MutationData | undefined,
+ input: Input,
+ onMutateResult: OnMutateResult | undefined,
+ result: OperationResult<MutationData, Variables>
+ ) => MutationCallbackResult;
+ /** Runs after a result error or mutation execution failure. */
+ onError?: (
+ error: CombinedError,
+ input: Input,
+ onMutateResult: OnMutateResult | undefined,
+ result: OperationResult<MutationData, Variables> | undefined
+ ) => MutationCallbackResult;
+ /** Runs after the immediate mutation submission settles. */
+ onSettled?: (
+ data: MutationData | undefined,
+ error: CombinedError | null,
+ input: Input,
+ onMutateResult: OnMutateResult | undefined,
+ result: OperationResult<MutationData, Variables> | undefined
+ ) => MutationCallbackResult;
+};
+
+/** Overrides applied to one mutation execution. */
+export type UrqlMutationExecutionOptions<
+ MutationData,
+ Variables extends AnyVariables,
+ Input = Variables,
+ OnMutateResult = void,
+> = MutationCallbacks<MutationData, Variables, Input, OnMutateResult> & {
+ /** Operation context merged over the mutation's base context. */
+ context?: Partial<OperationContext>;
+};
+
+type UrqlMutationExecutionOption<
+ MutationData,
+ Variables extends AnyVariables,
+ Input,
+> = [Input] extends [Variables]
+ ? { execute?: UrqlMutationExecutor<MutationData, Variables, Input> }
+ : { execute: UrqlMutationExecutor<MutationData, Variables, Input> };
+
+/** Reactive options for an imperative urql mutation. */
+export type UrqlMutationOptions<
+ MutationData = unknown,
+ Variables extends AnyVariables = AnyVariables,
+ Input = Variables,
+ OnMutateResult = void,
+> = MutationCallbacks<MutationData, Variables, Input, OnMutateResult> & {
+ /** Generated GraphQL mutation document. */
+ mutation: TypedDocumentNode<MutationData, Variables>;
+ /** Overrides the client supplied by the nearest {@link UrqlProvider}. */
+ client?: Client;
+ /** Base operation context merged into every execution. */
+ context?: Partial<OperationContext>;
+ /** Runs before submission and may return context for lifecycle callbacks. */
+ onMutate?: (input: Input) => OnMutateResult | Promise<OnMutateResult>;
+} & UrqlMutationExecutionOption<MutationData, Variables, Input>;
+
+/** Stable reactive state for an imperative urql mutation. */
+export type UrqlMutationResult<
+ MutationData = unknown,
+ Variables extends AnyVariables = AnyVariables,
+ Input = Variables,
+ OnMutateResult = void,
+> = {
+ readonly data: MutationData | undefined;
+ readonly error: CombinedError | null;
+ readonly isPending: boolean;
+ readonly stale: boolean;
+ readonly operation: Operation<MutationData, Variables> | undefined;
+ /** Submits one mutation without waiting for its raw urql result. */
+ mutate(
+ input: Input,
+ options?: UrqlMutationExecutionOptions<
+ MutationData,
+ Variables,
+ Input,
+ OnMutateResult
+ >
+ ): void;
+ /**
+ * Submits one mutation and resolves with its raw urql result. GraphQL and
+ * network errors remain represented on the result; execution failures throw.
+ */
+ mutateAsync(
+ input: Input,
+ options?: UrqlMutationExecutionOptions<
+ MutationData,
+ Variables,
+ Input,
+ OnMutateResult
+ >
+ ): Promise<OperationResult<MutationData, Variables>>;
+};
+
+/** One reactive source of urql clients accepted by {@link UrqlProvider}. */
+export type UrqlClientSource = MaybeAccessor<Client>;
diff --git a/apps/web/src/lib/urql-solid/utils.ts b/apps/web/src/lib/urql-solid/utils.ts
new file mode 100644
index 0000000000..273faac2c8
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/utils.ts
@@ -0,0 +1,53 @@
+import { CombinedError } from '@urql/core';
+import type { UrqlQueryStatus } from './types';
+
+/** Normalizes observer and selector failures to urql's public error type. */
+export function toCombinedError(cause: unknown): CombinedError {
+ if (cause instanceof CombinedError) return cause;
+
+ return new CombinedError({
+ networkError: cause instanceof Error ? cause : new Error(String(cause)),
+ });
+}
+
+/** Derives the shared high-level query status. */
+export function getQueryStatus(
+ error: CombinedError | null,
+ fetched: boolean
+): UrqlQueryStatus {
+ if (error) return 'error';
+ return fetched ? 'success' : 'pending';
+}
+
+/** Owns listener delivery and the stable Solid result used by actions. */
+export class ObserverResult<Result extends object> {
+ private readonly listeners = new Set<(result: Result) => void>();
+ private reference: Result | undefined;
+
+ constructor(private readonly getCurrentResult: () => Result) {}
+
+ setReference(result: Result): void {
+ this.reference = result;
+ }
+
+ subscribe(listener: (result: Result) => void): () => void {
+ this.listeners.add(listener);
+ return () => this.listeners.delete(listener);
+ }
+
+ getActionResult(): Result {
+ return this.reference ?? this.getCurrentResult();
+ }
+
+ notify(): void {
+ if (this.listeners.size === 0) return;
+
+ const result = this.getCurrentResult();
+
+ for (const listener of this.listeners) listener(result);
+ }
+
+ clear(): void {
+ this.listeners.clear();
+ }
+}
diff --git a/apps/web/vitest.config.ts b/apps/web/vitest.config.ts
index d41e53cf58..60a1db0bde 100644
--- a/apps/web/vitest.config.ts
+++ b/apps/web/vitest.config.ts
@@ -63,6 +63,19 @@ export default defineConfig({
name: 'graphql-cache',
},
},
+ {
+ plugins: [tsconfigPaths(), solidPlugin()],
+ ssr: {
+ resolve: {
+ conditions: ['browser', 'development'],
+ },
+ },
+ test: {
+ environment: 'jsdom',
+ include: ['src/lib/urql-solid/**/*.{test,spec}.{ts,tsx}'],
+ name: 'urql-solid',
+ },
+ },
{
test: {
include: ['scripts/**/*.{test,spec}.{ts,tsx}'],