@beignet/react-query 0.0.2 → 0.0.4

package/src/index.ts

@@ -2,7 +2,10 @@ import type {
   Client,
   Endpoint,
   EndpointCallArgs,
+  InferBody,
   InferEndpointContractError,
+  InferPathParams,
+  InferQuery,
   InferSuccessResponse,
 } from "@beignet/core/client";
 import {
@@ -14,22 +17,50 @@ import {
 
 import type {
   InfiniteQueryObserverOptions,
-  MutationOptions,
+  InvalidateQueryFilters,
+  QueryClient,
+  QueryFunction,
   QueryKey,
-  QueryOptions,
+  UseMutationOptions,
+  UseQueryOptions,
 } from "@tanstack/react-query";
 
-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">;
+> = Omit<
+  EndpointCallArgs<TContract, TProvidedHeaders>,
+  "rawBody" | "signal" | "idempotencyKey"
+>;
+
+type EndpointArgValue<
+  TArgs,
+  TKey extends "path" | "query" | "body" | "headers",
+> = TKey extends keyof TArgs ? TArgs[TKey] : undefined;
+
+type IsRequiredValue<T> = undefined extends T ? false : true;
+
+type RequiresQueryOptionsArgs<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string,
+> =
+  IsRequiredValue<InferPathParams<TContract>> extends true
+    ? true
+    : IsRequiredValue<InferQuery<TContract>> extends true
+      ? true
+      : IsRequiredValue<InferBody<TContract>> extends true
+        ? true
+        : IsRequiredValue<
+              EndpointArgValue<
+                EndpointCallArgs<TContract, TProvidedHeaders>,
+                "headers"
+              >
+            > extends true
+          ? true
+          : false;
 
 type ContractQueryOptionsBase<TContract extends HttpContractConfig> = Omit<
-  QueryOptions<
+  UseQueryOptions<
     InferSuccessResponse<TContract>,
     InferEndpointContractError<TContract>,
     InferSuccessResponse<TContract>,
@@ -38,6 +69,12 @@ type ContractQueryOptionsBase<TContract extends HttpContractConfig> = Omit<
   "queryKey" | "queryFn"
 >;
 
+type ContractQueryOptionsResult<TContract extends HttpContractConfig> =
+  ContractQueryOptionsBase<TContract> & {
+    queryKey: QueryKey;
+    queryFn: QueryFunction<InferSuccessResponse<TContract>, QueryKey>;
+  };
+
 /**
  * Options accepted by `ReactQueryContractHelper.queryOptions(...)`.
  *
@@ -56,9 +93,31 @@ type ContractQueryOptionsCallArgs<
   TContract extends HttpContractConfig,
   TProvidedHeaders extends string,
 > =
-  HasRequiredKeys<EndpointQueryArgs<TContract, TProvidedHeaders>> extends never
-    ? [args?: ContractUseQueryOptions<TContract, TProvidedHeaders>]
-    : [args: ContractUseQueryOptions<TContract, TProvidedHeaders>];
+  RequiresQueryOptionsArgs<TContract, TProvidedHeaders> extends true
+    ? [args: ContractUseQueryOptions<TContract, TProvidedHeaders>]
+    : [args?: ContractUseQueryOptions<TContract, TProvidedHeaders>];
+
+export type ContractQueryKeyParams<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string = never,
+> = {
+  path?: EndpointArgValue<
+    EndpointQueryArgs<TContract, TProvidedHeaders>,
+    "path"
+  >;
+  query?: EndpointArgValue<
+    EndpointQueryArgs<TContract, TProvidedHeaders>,
+    "query"
+  >;
+  body?: EndpointArgValue<
+    EndpointQueryArgs<TContract, TProvidedHeaders>,
+    "body"
+  >;
+  headers?: EndpointArgValue<
+    EndpointQueryArgs<TContract, TProvidedHeaders>,
+    "headers"
+  >;
+};
 
 /**
  * Options accepted by `ReactQueryContractHelper.mutationOptions(...)`.
@@ -70,7 +129,7 @@ export type ContractUseMutationOptions<
   TContract extends HttpContractConfig,
   TProvidedHeaders extends string = never,
 > = Omit<
-  MutationOptions<
+  UseMutationOptions<
     InferSuccessResponse<TContract>,
     InferEndpointContractError<TContract>,
     EndpointCallArgs<TContract, TProvidedHeaders>,
@@ -79,12 +138,26 @@ export type ContractUseMutationOptions<
   "mutationFn"
 >;
 
+/**
+ * Body input for infinite queries.
+ *
+ * Object bodies are shallow-partial because the full request body is the
+ * merge of the static `body` and each `page(...).body`, so neither side has
+ * to satisfy required body fields alone. The merged body is still validated
+ * by the endpoint call.
+ */
+type InfiniteQueryBody<TContract extends HttpContractConfig> =
+  InferBody<TContract> extends Record<string, unknown>
+    ? Partial<InferBody<TContract>>
+    : EndpointCallArgs<TContract>["body"];
+
 type InfiniteQueryResolvedParams<
   TContract extends HttpContractConfig,
   TProvidedHeaders extends string = never,
 > = {
   path?: EndpointCallArgs<TContract>["path"];
   query?: EndpointCallArgs<TContract>["query"];
+  body?: InfiniteQueryBody<TContract>;
   headers?: EndpointCallArgs<TContract, TProvidedHeaders>["headers"];
 };
 
@@ -95,6 +168,7 @@ type SafeInfiniteQueryArgs<
 > = {
   path?: EndpointCallArgs<TContract>["path"];
   query?: EndpointCallArgs<TContract>["query"];
+  body?: InfiniteQueryBody<TContract>;
   headers?: EndpointCallArgs<TContract, TProvidedHeaders>["headers"];
   page?: (ctx: {
     pageParam: TPageParam;
@@ -114,6 +188,7 @@ type DynamicInfiniteQueryArgs<
   key: readonly unknown[];
   path?: never;
   query?: never;
+  body?: never;
   page?: never;
 };
 
@@ -140,6 +215,15 @@ function mergeParamObjects<T>(base?: T, patch?: T): T | undefined {
   if (base == null) return patch;
   if (patch == null) return base;
 
+  if (
+    typeof base !== "object" ||
+    typeof patch !== "object" ||
+    Array.isArray(base) ||
+    Array.isArray(patch)
+  ) {
+    return patch;
+  }
+
   return {
     ...(base as Record<string, unknown>),
     ...(patch as Record<string, unknown>),
@@ -166,6 +250,16 @@ function normalizeKeyValue(value: unknown): unknown | undefined {
 const BEIGNET_QUERY_KEY_SCOPE = "beignet";
 const UNNAMESPACED_QUERY_KEY_NAMESPACE = null;
 
+/**
+ * Idempotency keys generated per `mutate(...)` invocation, keyed by variables
+ * object identity.
+ *
+ * TanStack Query re-invokes `mutationFn` with the same variables object on
+ * every HTTP retry attempt, so one key per variables object means retries
+ * reuse the key while separate `mutate(...)` calls get fresh keys.
+ */
+const idempotencyKeyForVariables = new WeakMap<object, string>();
+
 /**
  * Query key for all contracts in one Beignet namespace.
  */
@@ -176,11 +270,15 @@ export type ContractQueryNamespaceKey = readonly [
 
 /**
  * Query key for one contract without path/query/body params.
+ *
+ * The fourth element is the contract route (`"GET /todos"`), so contracts
+ * with the same derived local name but different routes never share a key.
  */
 export type ContractQueryContractKey = readonly [
   typeof BEIGNET_QUERY_KEY_SCOPE,
   string | null,
   string,
+  string,
 ];
 
 /**
@@ -190,9 +288,36 @@ export type ContractQueryKey = readonly [
   typeof BEIGNET_QUERY_KEY_SCOPE,
   string | null,
   string,
+  string,
   unknown?,
 ];
 
+export type ContractQueryFilterOptions = Omit<
+  InvalidateQueryFilters<QueryKey>,
+  "queryKey"
+>;
+
+export type ContractQueryFilter<TKey extends QueryKey> =
+  ContractQueryFilterOptions & {
+    queryKey: TKey;
+  };
+
+/**
+ * Options accepted by `createReactQuery(client, options?)`.
+ */
+export type CreateReactQueryOptions = {
+  /**
+   * Header names to include in generated query keys.
+   *
+   * Headers are excluded from query keys by default because persisted caches
+   * would otherwise store credentials such as `Authorization` tokens. Opt in
+   * per adapter with the specific identity headers that change response data,
+   * such as a tenant header. Names are matched case-insensitively and stored
+   * lowercased in the key.
+   */
+  keyHeaders?: readonly string[];
+};
+
 /**
  * TanStack Query helper bound to one Beignet contract.
  *
@@ -207,6 +332,7 @@ export class ReactQueryContractHelper<
   constructor(
     private contract: TContract,
     private _endpoint: Endpoint<TContract, TProvidedHeaders>,
+    private options: CreateReactQueryOptions = {},
   ) {}
 
   /**
@@ -216,6 +342,14 @@ export class ReactQueryContractHelper<
     return this.contract.name;
   }
 
+  /**
+   * Contract route used as the key segment that disambiguates contracts with
+   * the same local name, such as `/v1/todos` and `/v2/todos` list contracts.
+   */
+  get route(): string {
+    return `${this.contract.method} ${this.contract.path}`;
+  }
+
   /**
    * Resource namespace used for query-key grouping.
    */
@@ -241,7 +375,68 @@ export class ReactQueryContractHelper<
    * Build a contract-level query key without path/query params.
    */
   contractKey(): ContractQueryContractKey {
-    return [BEIGNET_QUERY_KEY_SCOPE, this.namespace, this.localName] as const;
+    return [
+      BEIGNET_QUERY_KEY_SCOPE,
+      this.namespace,
+      this.localName,
+      this.route,
+    ] as const;
+  }
+
+  /**
+   * Build TanStack Query filters for all contracts in this namespace.
+   */
+  namespaceFilter(
+    options: ContractQueryFilterOptions = {},
+  ): ContractQueryFilter<ContractQueryNamespaceKey> {
+    return {
+      ...options,
+      queryKey: this.namespaceKey(),
+    };
+  }
+
+  /**
+   * Build TanStack Query filters for every cached call to this contract.
+   */
+  contractFilter(
+    options: ContractQueryFilterOptions = {},
+  ): ContractQueryFilter<ContractQueryContractKey> {
+    return {
+      ...options,
+      queryKey: this.contractKey(),
+    };
+  }
+
+  /**
+   * Pick the adapter-whitelisted `keyHeaders` out of call headers.
+   *
+   * Returns `undefined` unless the adapter opted in with `keyHeaders` and the
+   * call provides at least one whitelisted header. Header names are matched
+   * case-insensitively and lowercased in the key component.
+   */
+  private pickKeyHeaders(
+    headers: unknown,
+  ): Record<string, unknown> | undefined {
+    const keyHeaders = this.options.keyHeaders;
+    if (!keyHeaders || keyHeaders.length === 0) return undefined;
+    if (
+      headers === null ||
+      headers === undefined ||
+      typeof headers !== "object" ||
+      Array.isArray(headers)
+    ) {
+      return undefined;
+    }
+
+    const allowed = new Set(keyHeaders.map((name) => name.toLowerCase()));
+    const picked: Record<string, unknown> = {};
+    for (const [name, value] of Object.entries(
+      headers as Record<string, unknown>,
+    )) {
+      const lowered = name.toLowerCase();
+      if (allowed.has(lowered)) picked[lowered] = value;
+    }
+    return picked;
   }
 
   /**
@@ -251,17 +446,28 @@ export class ReactQueryContractHelper<
    * 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.
+   *
+   * Headers are never included unless the adapter opted in with
+   * `createReactQuery(client, { keyHeaders })`, and then only the whitelisted
+   * header names are included.
    */
   key(params?: {
     path?: unknown;
     query?: unknown;
     body?: unknown;
+    headers?: unknown;
   }): ContractQueryKey {
     const path = normalizeKeyValue(params?.path);
     const query = normalizeKeyValue(params?.query);
     const body = normalizeKeyValue(params?.body);
-
-    if (path === undefined && query === undefined && body === undefined) {
+    const headers = normalizeKeyValue(this.pickKeyHeaders(params?.headers));
+
+    if (
+      path === undefined &&
+      query === undefined &&
+      body === undefined &&
+      headers === undefined
+    ) {
       return this.contractKey();
     }
 
@@ -269,9 +475,37 @@ export class ReactQueryContractHelper<
     if (path !== undefined) cleanParams.path = path;
     if (query !== undefined) cleanParams.query = query;
     if (body !== undefined) cleanParams.body = body;
+    if (headers !== undefined) cleanParams.headers = headers;
     return [...this.contractKey(), cleanParams] as const;
   }
 
+  /**
+   * Build TanStack Query filters for one contract call or parameter prefix.
+   */
+  filter(
+    params?: ContractQueryKeyParams<TContract, TProvidedHeaders>,
+    options: ContractQueryFilterOptions = {},
+  ): ContractQueryFilter<ContractQueryKey> {
+    return {
+      ...options,
+      queryKey: this.key(params),
+    };
+  }
+
+  /**
+   * Invalidate cached data for this contract.
+   *
+   * With no params this invalidates every cached call to the contract. Pass
+   * path/query/body params to target a single call or parameter prefix.
+   */
+  invalidate(
+    queryClient: QueryClient,
+    params?: ContractQueryKeyParams<TContract, TProvidedHeaders>,
+    options?: ContractQueryFilterOptions,
+  ): Promise<void> {
+    return queryClient.invalidateQueries(this.filter(params, options));
+  }
+
   /**
    * Create query options for TanStack Query.
    *
@@ -280,19 +514,15 @@ export class ReactQueryContractHelper<
    */
   queryOptions(
     ...callArgs: ContractQueryOptionsCallArgs<TContract, TProvidedHeaders>
-  ): QueryOptions<
-    InferSuccessResponse<TContract>,
-    InferEndpointContractError<TContract>,
-    InferSuccessResponse<TContract>,
-    QueryKey
-  > & { queryKey: QueryKey } {
+  ): ContractQueryOptionsResult<TContract> {
     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 queryKey = (customKey ||
+      this.key({ path, query, body, headers })) as QueryKey;
 
     const queryFn = async (context: { signal?: AbortSignal }) => {
       return await this._endpoint.call({
@@ -308,12 +538,7 @@ export class ReactQueryContractHelper<
       ...rest,
       queryKey,
       queryFn,
-    } as QueryOptions<
-      InferSuccessResponse<TContract>,
-      InferEndpointContractError<TContract>,
-      InferSuccessResponse<TContract>,
-      QueryKey
-    > & { queryKey: QueryKey };
+    } as ContractQueryOptionsResult<TContract>;
   }
 
   /**
@@ -321,33 +546,50 @@ export class ReactQueryContractHelper<
    *
    * The generated `mutationFn` accepts the same variables shape as the
    * underlying contract endpoint call.
+   *
+   * For contracts with idempotency metadata, the generated `mutationFn`
+   * derives one idempotency key per `mutate(...)` invocation and keeps it
+   * stable across TanStack retry attempts, which re-invoke `mutationFn` with
+   * the same variables object. Pass `idempotencyKey` in the variables to
+   * control the key explicitly. Calling `mutate()` with no variables falls
+   * back to per-attempt key generation in the client.
    */
   mutationOptions(
-    args: Omit<
-      MutationOptions<
-        InferSuccessResponse<TContract>,
-        InferEndpointContractError<TContract>,
-        EndpointCallArgs<TContract, TProvidedHeaders>,
-        unknown
-      >,
-      "mutationFn"
-    > = {},
-  ): MutationOptions<
+    args: ContractUseMutationOptions<TContract, TProvidedHeaders> = {},
+  ): UseMutationOptions<
     InferSuccessResponse<TContract>,
     InferEndpointContractError<TContract>,
     EndpointCallArgs<TContract, TProvidedHeaders>,
     unknown
   > {
+    const hasIdempotencyMetadata = Boolean(this.contract.metadata?.idempotency);
     const mutationFn = async (
       vars: EndpointCallArgs<TContract, TProvidedHeaders>,
     ) => {
-      return await this._endpoint.call(vars);
+      let idempotencyKey = vars?.idempotencyKey;
+      if (
+        !idempotencyKey &&
+        hasIdempotencyMetadata &&
+        vars &&
+        typeof vars === "object"
+      ) {
+        idempotencyKey =
+          idempotencyKeyForVariables.get(vars) ?? crypto.randomUUID();
+        idempotencyKeyForVariables.set(vars, idempotencyKey);
+      }
+      if (idempotencyKey === undefined) {
+        return await this._endpoint.call(vars);
+      }
+      return await this._endpoint.call({
+        ...vars,
+        idempotencyKey,
+      } as EndpointCallArgs<TContract, TProvidedHeaders>);
     };
 
     return {
       ...args,
       mutationFn,
-    } as MutationOptions<
+    } as UseMutationOptions<
       InferSuccessResponse<TContract>,
       InferEndpointContractError<TContract>,
       EndpointCallArgs<TContract, TProvidedHeaders>,
@@ -374,7 +616,7 @@ export class ReactQueryContractHelper<
     let queryKey: QueryKey;
     let rest: Omit<
       ContractInfiniteQueryOptions<TContract, TPageParam, TProvidedHeaders>,
-      "path" | "query" | "headers" | "page" | "params" | "key"
+      "path" | "query" | "body" | "headers" | "page" | "params" | "key"
     >;
     let resolveParams: (context: {
       pageParam: TPageParam;
@@ -391,14 +633,15 @@ export class ReactQueryContractHelper<
       rest = other;
       resolveParams = params;
     } else {
-      const { path, query, headers, page, key, ...other } = args;
-      queryKey = (key || this.key({ path, query })) as QueryKey;
+      const { path, query, body, headers, page, key, ...other } = args;
+      queryKey = (key || this.key({ path, query, body, headers })) as QueryKey;
       rest = other;
       resolveParams = (context) => {
         const pageParams = page?.(context);
         return {
           path: mergeParamObjects(path, pageParams?.path),
           query: mergeParamObjects(query, pageParams?.query),
+          body: mergeParamObjects(body, pageParams?.body),
           headers: mergeParamObjects(headers, pageParams?.headers),
         };
       };
@@ -412,6 +655,7 @@ export class ReactQueryContractHelper<
       return await this._endpoint.call({
         path: resolvedParams.path,
         query: resolvedParams.query,
+        body: resolvedParams.body,
         headers: resolvedParams.headers,
         signal: context.signal,
       } as unknown as EndpointCallArgs<TContract, TProvidedHeaders>);
@@ -443,9 +687,14 @@ export class ReactQueryContractHelper<
  *
  * Create this once near client setup, then bind contracts with the returned
  * `rq(contract)` function.
+ *
+ * Pass `keyHeaders` to include specific identity headers, such as a tenant
+ * header, in generated query keys. Headers are excluded by default so
+ * persisted caches never store credentials.
  */
 export function createReactQuery<TProvidedHeaders extends string = never>(
   client: Client<TProvidedHeaders>,
+  options: CreateReactQueryOptions = {},
 ) {
   return function rq<TContractLike extends ContractLike>(
     contract: TContractLike,
@@ -458,6 +707,6 @@ export function createReactQuery<TProvidedHeaders extends string = never>(
       ResolveContract<TContractLike>,
       TProvidedHeaders
     >;
-    return new ReactQueryContractHelper(resolved, endpoint);
+    return new ReactQueryContractHelper(resolved, endpoint, options);
   };
 }