@beignet/react-query 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/react-query
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,407 @@
+# @beignet/react-query
+
+> TanStack Query integration for Beignet
+
+This package provides **options-first** TanStack Query integration that's automatically typed based on your contracts. Generate `queryOptions`, `mutationOptions`, and `infiniteQueryOptions` that work with all TanStack Query primitives (`useQuery`, `useMutation`, `useInfiniteQuery`, `prefetchQuery`, `fetchQuery`, etc.) with full type inference.
+
+## Installation
+
+```bash
+npm install @beignet/react-query @beignet/core @tanstack/react-query react
+```
+
+
+## TypeScript requirements
+
+This package requires TypeScript 5.0 or higher for proper type inference.
+
+## Setup
+
+### 1. Create your client
+
+```ts
+// lib/api-client.ts
+import { createClient } from "@beignet/core/client";
+
+export const apiClient = createClient({
+  baseUrl: "https://api.example.com",
+  headers: async () => ({
+    Authorization: `Bearer ${getToken()}`,
+  }),
+});
+```
+
+### 2. Create the React Query adapter
+
+```ts
+// lib/rq.ts
+import { createReactQuery } from "@beignet/react-query";
+import { apiClient } from "./api-client";
+
+export const rq = createReactQuery(apiClient);
+```
+
+### 3. Set up QueryClientProvider
+
+```tsx
+// app/providers.tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function Providers({ children }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+```
+
+## Usage
+
+### Options-first API (recommended)
+
+The options-first API generates options objects that can be used with any TanStack Query primitive.
+
+#### Query options
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { rq } from "@/client/rq";
+import { getTodo } from "@/features/todos/contracts";
+
+function TodoDetail({ id }: { id: string }) {
+  // Generate query options
+  const todoQuery = rq(getTodo).queryOptions({
+    path: { id },
+    staleTime: 30_000,
+  });
+
+  // Use with any TanStack Query primitive
+  const { data, isLoading, error } = useQuery(todoQuery);
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h1>{data.title}</h1>
+      <p>Completed: {data.completed ? "Yes" : "No"}</p>
+    </div>
+  );
+}
+```
+
+#### Prefetching
+
+```tsx
+import { useQueryClient } from "@tanstack/react-query";
+import { rq } from "@/client/rq";
+import { getTodo } from "@/features/todos/contracts";
+
+function TodoList() {
+  const queryClient = useQueryClient();
+
+  const handleHover = (id: string) => {
+    // Prefetch on hover using queryOptions
+    const todoQuery = rq(getTodo).queryOptions({
+      path: { id },
+    });
+    
+    queryClient.prefetchQuery(todoQuery);
+  };
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+#### Server-side data fetching
+
+```tsx
+import { QueryClient, dehydrate, HydrationBoundary } from "@tanstack/react-query";
+import { rq } from "@/client/rq";
+import { getTodo } from "@/features/todos/contracts";
+
+export async function TodoPage({ params }: { params: { id: string } }) {
+  const queryClient = new QueryClient();
+
+  // Fetch on the server
+  const todoQuery = rq(getTodo).queryOptions({
+    path: { id: params.id },
+  });
+
+  await queryClient.prefetchQuery(todoQuery);
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <TodoDetail id={params.id} />
+    </HydrationBoundary>
+  );
+}
+```
+
+#### Mutation options
+
+```tsx
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { rq } from "@/client/rq";
+import { createTodo, listTodos } from "@/features/todos/contracts";
+
+function CreateTodoForm() {
+  const queryClient = useQueryClient();
+
+  // Generate mutation options
+  const createTodoMutation = rq(createTodo).mutationOptions({
+    onSuccess: (data, vars, onMutateResult, context) => {
+      // Invalidate queries
+      queryClient.invalidateQueries({ queryKey: rq(listTodos).contractKey() });
+    },
+  });
+
+  const mutation = useMutation(createTodoMutation);
+
+  const handleSubmit = (data: { title: string }) => {
+    mutation.mutate({ body: data });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* form fields */}
+      <button disabled={mutation.isPending}>
+        {mutation.isPending ? "Creating..." : "Create Todo"}
+      </button>
+    </form>
+  );
+}
+```
+
+#### Infinite query options
+
+```tsx
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { rq } from "@/client/rq";
+import { listTodos } from "@/features/todos/contracts";
+
+function InfiniteTodoList() {
+  const todosInfiniteQuery = rq(listTodos).infiniteQueryOptions({
+    query: { status: "open" },
+    page: ({ pageParam }) => ({
+      query: { cursor: pageParam ?? null },
+    }),
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+    initialPageParam: null,
+  });
+
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useInfiniteQuery(todosInfiniteQuery);
+
+  return (
+    <div>
+      {data?.pages.map((page) =>
+        page.items.map((todo) => <div key={todo.id}>{todo.title}</div>)
+      )}
+      
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={!hasNextPage || isFetchingNextPage}
+      >
+        {isFetchingNextPage ? "Loading more..." : "Load More"}
+      </button>
+    </div>
+  );
+}
+```
+
+## API reference
+
+### `createReactQuery(client)`
+
+Creates a React Query adapter factory.
+
+```ts
+const rq = createReactQuery(apiClient);
+```
+
+### `rq(contract)`
+
+Creates a contract helper with query/mutation options methods.
+
+```ts
+const helper = rq(getTodo);
+```
+
+### `helper.queryOptions(options)`
+
+**[Recommended]** Generate query options that can be passed to any TanStack Query primitive.
+
+```ts
+const queryOpts = helper.queryOptions({
+  path: { ... },            // Required when the contract has required path params
+  query?: { ... },          // Required when the contract has required query params
+  body?: { ... },           // Required when the contract has a required body
+  key?: readonly unknown[], // Custom query key
+  // ...any other TanStack Query options (staleTime, enabled, etc.)
+});
+
+// Use with any primitive
+useQuery(queryOpts);
+queryClient.prefetchQuery(queryOpts);
+queryClient.fetchQuery(queryOpts);
+queryClient.ensureQueryData(queryOpts);
+```
+
+### `helper.mutationOptions(options)`
+
+**[Recommended]** Generate mutation options that can be passed to `useMutation`.
+
+```ts
+const mutationOpts = helper.mutationOptions({
+  // ...any TanStack Query mutation options (onSuccess, onError, retry, etc.)
+});
+
+useMutation(mutationOpts);
+```
+
+### `helper.infiniteQueryOptions(options)`
+
+**[Recommended]** Generate infinite query options for pagination.
+
+```ts
+const infiniteOpts = helper.infiniteQueryOptions({
+  path?: { ... },          // Static path params included in the cache key
+  query?: { ... },         // Static query params included in the cache key
+  page?: (ctx: { pageParam }) => ({
+    path?: { ... },        // Page-specific path params
+    query?: { ... },       // Page-specific query params (cursor, offset, etc.)
+  }),
+  initialPageParam: ...,
+  getNextPageParam: (lastPage) => ...,
+  getPreviousPageParam: (firstPage) => ...,
+  key?: readonly unknown[], // Optional custom query key
+  // ...any other TanStack Query infinite query options
+});
+
+useInfiniteQuery(infiniteOpts);
+```
+
+If you need fully dynamic params, pass a custom `key` and use `params(...)` instead:
+
+```ts
+const infiniteOpts = helper.infiniteQueryOptions({
+  key: ["todos", { status: "open" }],
+  params: ({ pageParam }) => ({
+    query: { status: "open", cursor: pageParam ?? null },
+  }),
+  initialPageParam: null,
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+});
+```
+
+### `helper.namespaceKey()`
+
+Generate a namespace-level key for broad cache operations. Contracts created
+from `createContractGroup().namespace("todos")` use that namespace.
+Non-namespaced contracts use `null` so they cannot collide with a real
+namespace string.
+
+```ts
+helper.namespaceKey(); // ["beignet", "todos"]
+```
+
+### `helper.contractKey()`
+
+Generate a contract-level key without path, query, or body params.
+
+```ts
+helper.contractKey(); // ["beignet", "todos", "getTodo"]
+```
+
+### `helper.key(params?)`
+
+Generate a stable query key for cache operations.
+
+```ts
+helper.key();                      // ["beignet", "todos", "getTodo"]
+helper.key({ path: { id: "1" } }); // ["beignet", "todos", "getTodo", { path: { id: "1" } }]
+```
+
+`key(...)` normalizes params the same way the client serializes them: `null`
+and `undefined` object entries are omitted, while meaningful values like `0`,
+`false`, and empty strings are preserved. Request bodies are included in query
+keys when passed to `queryOptions(...)`.
+
+These keys are plain TanStack Query keys, so prefix invalidation works as
+expected:
+
+```ts
+queryClient.invalidateQueries({ queryKey: rq(getTodo).namespaceKey() });
+queryClient.invalidateQueries({ queryKey: rq(getTodo).contractKey() });
+queryClient.invalidateQueries({
+  queryKey: rq(getTodo).key({ path: { id: "1" } }),
+});
+```
+
+### `helper.endpoint`
+
+Access the underlying endpoint for manual calls.
+
+```ts
+const data = await helper.endpoint.call({ path: { id: "123" } });
+```
+
+## Type inference
+
+All options are fully typed based on your contracts:
+
+```ts
+const { data } = useQuery(rq(getTodo).queryOptions({ path: { id: "123" } }));
+// data is typed as: { id: string; title: string; completed: boolean }
+
+const mutation = useMutation(rq(createTodo).mutationOptions());
+mutation.mutate({ body: { title: "New Todo" } });
+// body is typed as: { title: string; completed?: boolean }
+```
+
+## Error handling
+
+React Query errors are typed from the endpoint contract, including declared
+catalog errors and non-2xx response bodies:
+
+```ts
+const todo = rq(getTodo);
+const { error } = useQuery(todo.queryOptions({ path: { id: "123" } }));
+
+if (todo.endpoint.isError(error, { code: "TODO_NOT_FOUND" })) {
+  console.log(error.details); // typed from the catalog details schema
+} else if (error) {
+  console.log(error.message);
+}
+```
+
+## Migration from hook-first API
+
+If you were using the hook-first API, you can migrate to the options-first API:
+
+**Before (hook-first):**
+```tsx
+const { data } = rq(getTodo).useQuery({ path: { id } });
+```
+
+**After (options-first):**
+```tsx
+const { data } = useQuery(rq(getTodo).queryOptions({ path: { id } }));
+```
+
+Hook wrappers have been removed—use the options-first API for all queries and mutations.
+
+## Related packages
+
+- [`@beignet/core/contracts`](https://beignet.dev/contracts) - Core contract definitions
+- [`@beignet/core/client`](https://beignet.dev/client) - HTTP client
+- [`@beignet/nuqs`](https://beignet.dev/nuqs) - URL query state integration
+- [`@beignet/react-hook-form`](https://beignet.dev/react-hook-form) - Form integration
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+import type { Client, Endpoint, EndpointCallArgs, InferEndpointContractError, InferSuccessResponse } from "@beignet/core/client";
+import { type ContractLike, type HttpContractConfig, type ResolveContract } from "@beignet/core/contracts";
+import type { InfiniteQueryObserverOptions, MutationOptions, QueryKey, QueryOptions } from "@tanstack/react-query";
+/**
+ * Options for useQuery hook
+ */
+type HasRequiredKeys<T> = {
+    [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
+}[keyof T];
+type EndpointQueryArgs<TContract extends HttpContractConfig, TProvidedHeaders extends string> = Omit<EndpointCallArgs<TContract, TProvidedHeaders>, "rawBody" | "signal">;
+type ContractQueryOptionsBase<TContract extends HttpContractConfig> = Omit<QueryOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, InferSuccessResponse<TContract>, QueryKey>, "queryKey" | "queryFn">;
+export type ContractUseQueryOptions<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> = EndpointQueryArgs<TContract, TProvidedHeaders> & {
+    key?: readonly unknown[];
+} & ContractQueryOptionsBase<TContract>;
+type ContractQueryOptionsCallArgs<TContract extends HttpContractConfig, TProvidedHeaders extends string> = HasRequiredKeys<EndpointQueryArgs<TContract, TProvidedHeaders>> extends never ? [args?: ContractUseQueryOptions<TContract, TProvidedHeaders>] : [args: ContractUseQueryOptions<TContract, TProvidedHeaders>];
+/**
+ * Options for useMutation hook
+ */
+export type ContractUseMutationOptions<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> = Omit<MutationOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, EndpointCallArgs<TContract, TProvidedHeaders>, unknown>, "mutationFn">;
+type InfiniteQueryResolvedParams<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> = {
+    path?: EndpointCallArgs<TContract>["path"];
+    query?: EndpointCallArgs<TContract>["query"];
+    headers?: EndpointCallArgs<TContract, TProvidedHeaders>["headers"];
+};
+type SafeInfiniteQueryArgs<TContract extends HttpContractConfig, TPageParam, TProvidedHeaders extends string> = {
+    path?: EndpointCallArgs<TContract>["path"];
+    query?: EndpointCallArgs<TContract>["query"];
+    headers?: EndpointCallArgs<TContract, TProvidedHeaders>["headers"];
+    page?: (ctx: {
+        pageParam: TPageParam;
+    }) => InfiniteQueryResolvedParams<TContract, TProvidedHeaders>;
+    key?: readonly unknown[];
+    params?: never;
+};
+type DynamicInfiniteQueryArgs<TContract extends HttpContractConfig, TPageParam, TProvidedHeaders extends string> = {
+    params: (ctx: {
+        pageParam: TPageParam;
+    }) => InfiniteQueryResolvedParams<TContract, TProvidedHeaders>;
+    key: readonly unknown[];
+    path?: never;
+    query?: never;
+    page?: never;
+};
+type ContractInfiniteQueryOptions<TContract extends HttpContractConfig, TPageParam, TProvidedHeaders extends string> = (SafeInfiniteQueryArgs<TContract, TPageParam, TProvidedHeaders> | DynamicInfiniteQueryArgs<TContract, TPageParam, TProvidedHeaders>) & Omit<InfiniteQueryObserverOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, InferSuccessResponse<TContract>, QueryKey, TPageParam>, "queryKey" | "queryFn">;
+declare const BEIGNET_QUERY_KEY_SCOPE = "beignet";
+export type ContractQueryNamespaceKey = readonly [
+    typeof BEIGNET_QUERY_KEY_SCOPE,
+    string | null
+];
+export type ContractQueryContractKey = readonly [
+    typeof BEIGNET_QUERY_KEY_SCOPE,
+    string | null,
+    string
+];
+export type ContractQueryKey = readonly [
+    typeof BEIGNET_QUERY_KEY_SCOPE,
+    string | null,
+    string,
+    unknown?
+];
+/**
+ * React Query contract helper
+ */
+export declare class ReactQueryContractHelper<TContract extends HttpContractConfig, TProvidedHeaders extends string = never> {
+    private contract;
+    private _endpoint;
+    constructor(contract: TContract, _endpoint: Endpoint<TContract, TProvidedHeaders>);
+    /**
+     * Fully qualified contract name.
+     */
+    get name(): string;
+    /**
+     * Resource namespace used for query-key grouping.
+     */
+    get namespace(): string | null;
+    /**
+     * Contract name without the resource namespace.
+     */
+    get localName(): string;
+    /**
+     * Build a namespace-level query key for resource-wide cache operations.
+     */
+    namespaceKey(): ContractQueryNamespaceKey;
+    /**
+     * Build a contract-level query key without path/query params.
+     */
+    contractKey(): ContractQueryContractKey;
+    /**
+     * Build a stable query key for this contract
+     *
+     * Only includes path/query in the key when they have defined values.
+     * This ensures consistent serialization between server (dehydrate) and
+     * client (hydrate), since undefined object values may serialize
+     * differently across React's RSC boundary vs JSON.stringify.
+     */
+    key(params?: {
+        path?: unknown;
+        query?: unknown;
+        body?: unknown;
+    }): ContractQueryKey;
+    /**
+     * Create query options for TanStack Query
+     * This can be passed to useQuery, prefetchQuery, fetchQuery, etc.
+     */
+    queryOptions(...callArgs: ContractQueryOptionsCallArgs<TContract, TProvidedHeaders>): QueryOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, InferSuccessResponse<TContract>, QueryKey> & {
+        queryKey: QueryKey;
+    };
+    /**
+     * Create mutation options for TanStack Query
+     * This can be passed to useMutation
+     */
+    mutationOptions(args?: Omit<MutationOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, EndpointCallArgs<TContract, TProvidedHeaders>, unknown>, "mutationFn">): MutationOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, EndpointCallArgs<TContract, TProvidedHeaders>, unknown>;
+    /**
+     * Create infinite query options for TanStack Query
+     * This can be passed to useInfiniteQuery
+     */
+    infiniteQueryOptions<TPageParam = unknown>(args: ContractInfiniteQueryOptions<TContract, TPageParam, TProvidedHeaders>): InfiniteQueryObserverOptions<InferSuccessResponse<TContract>, InferEndpointContractError<TContract>, InferSuccessResponse<TContract>, QueryKey, TPageParam>;
+    /**
+     * Access to the underlying endpoint
+     */
+    get endpoint(): Endpoint<TContract, TProvidedHeaders>;
+}
+/**
+ * Create React Query adapter for a client
+ */
+export declare function createReactQuery<TProvidedHeaders extends string = never>(client: Client<TProvidedHeaders>): <TContractLike extends ContractLike>(contract: TContractLike) => ReactQueryContractHelper<ResolveContract<TContractLike>, TProvidedHeaders>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,190 @@
+import { resolveContract, } from "@beignet/core/contracts";
+function mergeParamObjects(base, patch) {
+    if (base == null)
+        return patch;
+    if (patch == null)
+        return base;
+    return {
+        ...base,
+        ...patch,
+    };
+}
+function normalizeKeyValue(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return value;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined && entryValue !== null)
+        .sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0)
+        return undefined;
+    return Object.fromEntries(entries);
+}
+const BEIGNET_QUERY_KEY_SCOPE = "beignet";
+const UNNAMESPACED_QUERY_KEY_NAMESPACE = null;
+/**
+ * React Query contract helper
+ */
+export class ReactQueryContractHelper {
+    contract;
+    _endpoint;
+    constructor(contract, _endpoint) {
+        this.contract = contract;
+        this._endpoint = _endpoint;
+    }
+    /**
+     * Fully qualified contract name.
+     */
+    get name() {
+        return this.contract.name;
+    }
+    /**
+     * Resource namespace used for query-key grouping.
+     */
+    get namespace() {
+        return this.contract.namespace ?? UNNAMESPACED_QUERY_KEY_NAMESPACE;
+    }
+    /**
+     * Contract name without the resource namespace.
+     */
+    get localName() {
+        return this.contract.localName ?? this.contract.name;
+    }
+    /**
+     * Build a namespace-level query key for resource-wide cache operations.
+     */
+    namespaceKey() {
+        return [BEIGNET_QUERY_KEY_SCOPE, this.namespace];
+    }
+    /**
+     * Build a contract-level query key without path/query params.
+     */
+    contractKey() {
+        return [BEIGNET_QUERY_KEY_SCOPE, this.namespace, this.localName];
+    }
+    /**
+     * Build a stable query key for this contract
+     *
+     * Only includes path/query in the key when they have defined values.
+     * This ensures consistent serialization between server (dehydrate) and
+     * client (hydrate), since undefined object values may serialize
+     * differently across React's RSC boundary vs JSON.stringify.
+     */
+    key(params) {
+        const path = normalizeKeyValue(params?.path);
+        const query = normalizeKeyValue(params?.query);
+        const body = normalizeKeyValue(params?.body);
+        if (path === undefined && query === undefined && body === undefined) {
+            return this.contractKey();
+        }
+        const cleanParams = {};
+        if (path !== undefined)
+            cleanParams.path = path;
+        if (query !== undefined)
+            cleanParams.query = query;
+        if (body !== undefined)
+            cleanParams.body = body;
+        return [...this.contractKey(), cleanParams];
+    }
+    /**
+     * Create query options for TanStack Query
+     * This can be passed to useQuery, prefetchQuery, fetchQuery, etc.
+     */
+    queryOptions(...callArgs) {
+        const args = (callArgs[0] ?? {});
+        const { path, query, body, headers, key: customKey, ...rest } = args;
+        const queryKey = (customKey || this.key({ path, query, body }));
+        const queryFn = async (context) => {
+            return await this._endpoint.call({
+                path,
+                query,
+                body,
+                headers,
+                signal: context.signal,
+            });
+        };
+        return {
+            ...rest,
+            queryKey,
+            queryFn,
+        };
+    }
+    /**
+     * Create mutation options for TanStack Query
+     * This can be passed to useMutation
+     */
+    mutationOptions(args = {}) {
+        const mutationFn = async (vars) => {
+            return await this._endpoint.call(vars);
+        };
+        return {
+            ...args,
+            mutationFn,
+        };
+    }
+    /**
+     * Create infinite query options for TanStack Query
+     * This can be passed to useInfiniteQuery
+     */
+    infiniteQueryOptions(args) {
+        let queryKey;
+        let rest;
+        let resolveParams;
+        if ("params" in args && typeof args.params === "function") {
+            const { params, key, ...other } = args;
+            if (!key) {
+                throw new Error("infiniteQueryOptions({ params }) requires a custom key. Use static path/query for the cache key, or pass key explicitly.");
+            }
+            queryKey = key;
+            rest = other;
+            resolveParams = params;
+        }
+        else {
+            const { path, query, headers, page, key, ...other } = args;
+            queryKey = (key || this.key({ path, query }));
+            rest = other;
+            resolveParams = (context) => {
+                const pageParams = page?.(context);
+                return {
+                    path: mergeParamObjects(path, pageParams?.path),
+                    query: mergeParamObjects(query, pageParams?.query),
+                    headers: mergeParamObjects(headers, pageParams?.headers),
+                };
+            };
+        }
+        const queryFn = async (context) => {
+            const resolvedParams = resolveParams(context);
+            return await this._endpoint.call({
+                path: resolvedParams.path,
+                query: resolvedParams.query,
+                headers: resolvedParams.headers,
+                signal: context.signal,
+            });
+        };
+        return {
+            ...rest,
+            queryKey,
+            queryFn,
+        };
+    }
+    /**
+     * Access to the underlying endpoint
+     */
+    get endpoint() {
+        return this._endpoint;
+    }
+}
+/**
+ * Create React Query adapter for a client
+ */
+export function createReactQuery(client) {
+    return function rq(contract) {
+        const resolved = resolveContract(contract);
+        const endpoint = client.endpoint(contract);
+        return new ReactQueryContractHelper(resolved, endpoint);
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@beignet/react-query",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "TanStack Query integration for Beignet",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "contract",
+    "api",
+    "typescript",
+    "react-query",
+    "tanstack"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/react-query"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@testing-library/dom": "^9.3.4",
+    "@testing-library/react": "^14.3.1",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "@types/react": "^18.2.0",
+    "happy-dom": "^20.0.11",
+    "react": "^18.2.0",
+    "typescript": "^5.3.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,433 @@
+import type {
+  Client,
+  Endpoint,
+  EndpointCallArgs,
+  InferEndpointContractError,
+  InferSuccessResponse,
+} from "@beignet/core/client";
+import {
+  type ContractLike,
+  type HttpContractConfig,
+  type ResolveContract,
+  resolveContract,
+} from "@beignet/core/contracts";
+
+import type {
+  InfiniteQueryObserverOptions,
+  MutationOptions,
+  QueryKey,
+  QueryOptions,
+} from "@tanstack/react-query";
+
+/**
+ * Options for useQuery hook
+ */
+type HasRequiredKeys<T> = {
+  [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
+}[keyof T];
+
+type EndpointQueryArgs<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string,
+> = Omit<EndpointCallArgs<TContract, TProvidedHeaders>, "rawBody" | "signal">;
+
+type ContractQueryOptionsBase<TContract extends HttpContractConfig> = Omit<
+  QueryOptions<
+    InferSuccessResponse<TContract>,
+    InferEndpointContractError<TContract>,
+    InferSuccessResponse<TContract>,
+    QueryKey
+  >,
+  "queryKey" | "queryFn"
+>;
+
+export type ContractUseQueryOptions<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string = never,
+> = EndpointQueryArgs<TContract, TProvidedHeaders> & {
+  key?: readonly unknown[];
+} & ContractQueryOptionsBase<TContract>;
+
+type ContractQueryOptionsCallArgs<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string,
+> =
+  HasRequiredKeys<EndpointQueryArgs<TContract, TProvidedHeaders>> extends never
+    ? [args?: ContractUseQueryOptions<TContract, TProvidedHeaders>]
+    : [args: ContractUseQueryOptions<TContract, TProvidedHeaders>];
+
+/**
+ * Options for useMutation hook
+ */
+export type ContractUseMutationOptions<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string = never,
+> = Omit<
+  MutationOptions<
+    InferSuccessResponse<TContract>,
+    InferEndpointContractError<TContract>,
+    EndpointCallArgs<TContract, TProvidedHeaders>,
+    unknown
+  >,
+  "mutationFn"
+>;
+
+type InfiniteQueryResolvedParams<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string = never,
+> = {
+  path?: EndpointCallArgs<TContract>["path"];
+  query?: EndpointCallArgs<TContract>["query"];
+  headers?: EndpointCallArgs<TContract, TProvidedHeaders>["headers"];
+};
+
+type SafeInfiniteQueryArgs<
+  TContract extends HttpContractConfig,
+  TPageParam,
+  TProvidedHeaders extends string,
+> = {
+  path?: EndpointCallArgs<TContract>["path"];
+  query?: EndpointCallArgs<TContract>["query"];
+  headers?: EndpointCallArgs<TContract, TProvidedHeaders>["headers"];
+  page?: (ctx: {
+    pageParam: TPageParam;
+  }) => InfiniteQueryResolvedParams<TContract, TProvidedHeaders>;
+  key?: readonly unknown[];
+  params?: never;
+};
+
+type DynamicInfiniteQueryArgs<
+  TContract extends HttpContractConfig,
+  TPageParam,
+  TProvidedHeaders extends string,
+> = {
+  params: (ctx: {
+    pageParam: TPageParam;
+  }) => InfiniteQueryResolvedParams<TContract, TProvidedHeaders>;
+  key: readonly unknown[];
+  path?: never;
+  query?: never;
+  page?: never;
+};
+
+type ContractInfiniteQueryOptions<
+  TContract extends HttpContractConfig,
+  TPageParam,
+  TProvidedHeaders extends string,
+> = (
+  | SafeInfiniteQueryArgs<TContract, TPageParam, TProvidedHeaders>
+  | DynamicInfiniteQueryArgs<TContract, TPageParam, TProvidedHeaders>
+) &
+  Omit<
+    InfiniteQueryObserverOptions<
+      InferSuccessResponse<TContract>,
+      InferEndpointContractError<TContract>,
+      InferSuccessResponse<TContract>,
+      QueryKey,
+      TPageParam
+    >,
+    "queryKey" | "queryFn"
+  >;
+
+function mergeParamObjects<T>(base?: T, patch?: T): T | undefined {
+  if (base == null) return patch;
+  if (patch == null) return base;
+
+  return {
+    ...(base as Record<string, unknown>),
+    ...(patch as Record<string, unknown>),
+  } as T;
+}
+
+function normalizeKeyValue(value: unknown): unknown | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, entryValue]) => entryValue !== undefined && entryValue !== null)
+    .sort(([a], [b]) => a.localeCompare(b));
+
+  if (entries.length === 0) return undefined;
+  return Object.fromEntries(entries);
+}
+
+const BEIGNET_QUERY_KEY_SCOPE = "beignet";
+const UNNAMESPACED_QUERY_KEY_NAMESPACE = null;
+
+export type ContractQueryNamespaceKey = readonly [
+  typeof BEIGNET_QUERY_KEY_SCOPE,
+  string | null,
+];
+
+export type ContractQueryContractKey = readonly [
+  typeof BEIGNET_QUERY_KEY_SCOPE,
+  string | null,
+  string,
+];
+
+export type ContractQueryKey = readonly [
+  typeof BEIGNET_QUERY_KEY_SCOPE,
+  string | null,
+  string,
+  unknown?,
+];
+
+/**
+ * React Query contract helper
+ */
+export class ReactQueryContractHelper<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string = never,
+> {
+  constructor(
+    private contract: TContract,
+    private _endpoint: Endpoint<TContract, TProvidedHeaders>,
+  ) {}
+
+  /**
+   * Fully qualified contract name.
+   */
+  get name(): string {
+    return this.contract.name;
+  }
+
+  /**
+   * Resource namespace used for query-key grouping.
+   */
+  get namespace(): string | null {
+    return this.contract.namespace ?? UNNAMESPACED_QUERY_KEY_NAMESPACE;
+  }
+
+  /**
+   * Contract name without the resource namespace.
+   */
+  get localName(): string {
+    return this.contract.localName ?? this.contract.name;
+  }
+
+  /**
+   * Build a namespace-level query key for resource-wide cache operations.
+   */
+  namespaceKey(): ContractQueryNamespaceKey {
+    return [BEIGNET_QUERY_KEY_SCOPE, this.namespace] as const;
+  }
+
+  /**
+   * Build a contract-level query key without path/query params.
+   */
+  contractKey(): ContractQueryContractKey {
+    return [BEIGNET_QUERY_KEY_SCOPE, this.namespace, this.localName] as const;
+  }
+
+  /**
+   * Build a stable query key for this contract
+   *
+   * Only includes path/query in the key when they have defined values.
+   * This ensures consistent serialization between server (dehydrate) and
+   * client (hydrate), since undefined object values may serialize
+   * differently across React's RSC boundary vs JSON.stringify.
+   */
+  key(params?: {
+    path?: unknown;
+    query?: unknown;
+    body?: unknown;
+  }): ContractQueryKey {
+    const path = normalizeKeyValue(params?.path);
+    const query = normalizeKeyValue(params?.query);
+    const body = normalizeKeyValue(params?.body);
+
+    if (path === undefined && query === undefined && body === undefined) {
+      return this.contractKey();
+    }
+
+    const cleanParams: Record<string, unknown> = {};
+    if (path !== undefined) cleanParams.path = path;
+    if (query !== undefined) cleanParams.query = query;
+    if (body !== undefined) cleanParams.body = body;
+    return [...this.contractKey(), cleanParams] as const;
+  }
+
+  /**
+   * Create query options for TanStack Query
+   * This can be passed to useQuery, prefetchQuery, fetchQuery, etc.
+   */
+  queryOptions(
+    ...callArgs: ContractQueryOptionsCallArgs<TContract, TProvidedHeaders>
+  ): QueryOptions<
+    InferSuccessResponse<TContract>,
+    InferEndpointContractError<TContract>,
+    InferSuccessResponse<TContract>,
+    QueryKey
+  > & { queryKey: QueryKey } {
+    const args = (callArgs[0] ?? {}) as ContractUseQueryOptions<
+      TContract,
+      TProvidedHeaders
+    >;
+    const { path, query, body, headers, key: customKey, ...rest } = args;
+
+    const queryKey = (customKey || this.key({ path, query, body })) as QueryKey;
+
+    const queryFn = async (context: { signal?: AbortSignal }) => {
+      return await this._endpoint.call({
+        path,
+        query,
+        body,
+        headers,
+        signal: context.signal,
+      } as unknown as EndpointCallArgs<TContract, TProvidedHeaders>);
+    };
+
+    return {
+      ...rest,
+      queryKey,
+      queryFn,
+    } as QueryOptions<
+      InferSuccessResponse<TContract>,
+      InferEndpointContractError<TContract>,
+      InferSuccessResponse<TContract>,
+      QueryKey
+    > & { queryKey: QueryKey };
+  }
+
+  /**
+   * Create mutation options for TanStack Query
+   * This can be passed to useMutation
+   */
+  mutationOptions(
+    args: Omit<
+      MutationOptions<
+        InferSuccessResponse<TContract>,
+        InferEndpointContractError<TContract>,
+        EndpointCallArgs<TContract, TProvidedHeaders>,
+        unknown
+      >,
+      "mutationFn"
+    > = {},
+  ): MutationOptions<
+    InferSuccessResponse<TContract>,
+    InferEndpointContractError<TContract>,
+    EndpointCallArgs<TContract, TProvidedHeaders>,
+    unknown
+  > {
+    const mutationFn = async (
+      vars: EndpointCallArgs<TContract, TProvidedHeaders>,
+    ) => {
+      return await this._endpoint.call(vars);
+    };
+
+    return {
+      ...args,
+      mutationFn,
+    } as MutationOptions<
+      InferSuccessResponse<TContract>,
+      InferEndpointContractError<TContract>,
+      EndpointCallArgs<TContract, TProvidedHeaders>,
+      unknown
+    >;
+  }
+
+  /**
+   * Create infinite query options for TanStack Query
+   * This can be passed to useInfiniteQuery
+   */
+  infiniteQueryOptions<TPageParam = unknown>(
+    args: ContractInfiniteQueryOptions<TContract, TPageParam, TProvidedHeaders>,
+  ): InfiniteQueryObserverOptions<
+    InferSuccessResponse<TContract>,
+    InferEndpointContractError<TContract>,
+    InferSuccessResponse<TContract>,
+    QueryKey,
+    TPageParam
+  > {
+    let queryKey: QueryKey;
+    let rest: Omit<
+      ContractInfiniteQueryOptions<TContract, TPageParam, TProvidedHeaders>,
+      "path" | "query" | "headers" | "page" | "params" | "key"
+    >;
+    let resolveParams: (context: {
+      pageParam: TPageParam;
+    }) => InfiniteQueryResolvedParams<TContract, TProvidedHeaders>;
+
+    if ("params" in args && typeof args.params === "function") {
+      const { params, key, ...other } = args;
+      if (!key) {
+        throw new Error(
+          "infiniteQueryOptions({ params }) requires a custom key. Use static path/query for the cache key, or pass key explicitly.",
+        );
+      }
+      queryKey = key as QueryKey;
+      rest = other;
+      resolveParams = params;
+    } else {
+      const { path, query, headers, page, key, ...other } = args;
+      queryKey = (key || this.key({ path, query })) as QueryKey;
+      rest = other;
+      resolveParams = (context) => {
+        const pageParams = page?.(context);
+        return {
+          path: mergeParamObjects(path, pageParams?.path),
+          query: mergeParamObjects(query, pageParams?.query),
+          headers: mergeParamObjects(headers, pageParams?.headers),
+        };
+      };
+    }
+
+    const queryFn = async (context: {
+      pageParam: TPageParam;
+      signal?: AbortSignal;
+    }) => {
+      const resolvedParams = resolveParams(context);
+      return await this._endpoint.call({
+        path: resolvedParams.path,
+        query: resolvedParams.query,
+        headers: resolvedParams.headers,
+        signal: context.signal,
+      } as unknown as EndpointCallArgs<TContract, TProvidedHeaders>);
+    };
+
+    return {
+      ...rest,
+      queryKey,
+      queryFn,
+    } as unknown as InfiniteQueryObserverOptions<
+      InferSuccessResponse<TContract>,
+      InferEndpointContractError<TContract>,
+      InferSuccessResponse<TContract>,
+      QueryKey,
+      TPageParam
+    >;
+  }
+
+  /**
+   * Access to the underlying endpoint
+   */
+  get endpoint(): Endpoint<TContract, TProvidedHeaders> {
+    return this._endpoint;
+  }
+}
+
+/**
+ * Create React Query adapter for a client
+ */
+export function createReactQuery<TProvidedHeaders extends string = never>(
+  client: Client<TProvidedHeaders>,
+) {
+  return function rq<TContractLike extends ContractLike>(
+    contract: TContractLike,
+  ): ReactQueryContractHelper<
+    ResolveContract<TContractLike>,
+    TProvidedHeaders
+  > {
+    const resolved = resolveContract(contract);
+    const endpoint = client.endpoint(contract) as Endpoint<
+      ResolveContract<TContractLike>,
+      TProvidedHeaders
+    >;
+    return new ReactQueryContractHelper(resolved, endpoint);
+  };
+}