@openapi-qraft/react 1.1.5 → 1.3.2

package/src/index.ts

@@ -1,11 +1,16 @@
-export { qraftAPIClient } from './qraftAPIClient.js';
-export type { QraftClientOptions } from './qraftAPIClient.js';
-export { QraftContext } from './QraftContext.js';
-export type { QraftContextValue } from './QraftContext.js';
-export { request, urlSerializer, bodySerializer } from './lib/request.js';
-export type { APIRequestInit, HeadersOptions } from './lib/request.js';
+export { qraftAPIClient, type QraftClientOptions } from './qraftAPIClient.js';
+export { QraftContext, type QraftContextValue } from './QraftContext.js';
+export {
+  requestFn,
+  baseRequestFn,
+  urlSerializer,
+  bodySerializer,
+  type RequestFnPayload,
+  type OperationSchema,
+  type RequestFnOptions,
+  type HeadersOptions,
+} from './lib/requestFn.js';
 export type {
   ServiceOperationQuery,
   ServiceOperationMutation,
 } from './ServiceOperation.js';
-export type { RequestClient } from './RequestClient.js';

package/src/lib/callQueryClientFetchMethod.ts

@@ -0,0 +1,90 @@
+import type { QueryClient } from '@tanstack/query-core';
+
+import { composeInfiniteQueryKey } from './composeInfiniteQueryKey.js';
+import { composeQueryKey } from './composeQueryKey.js';
+import type { OperationSchema, RequestFn } from './requestFn.js';
+import { shelfMerge } from './shelfMerge.js';
+
+/**
+ * Calls a query client fetch method with parameters and options,
+ * and automatically composes the `QueryKey` based on the schema and parameters.
+ */
+export function callQueryClientMethodWithQueryKey<
+  QFMethod extends QueryKeyMethods,
+>(
+  queryFilterMethod: QFMethod,
+  schema: OperationSchema,
+  infinite: boolean,
+  args: QueryClientMethodArgs<QFMethod>
+): ReturnType<(typeof QueryClient.prototype)[QFMethod]> {
+  const [{ requestFn, baseUrl, parameters, ...options }, queryClient] = args;
+
+  if (!queryClient) throw new Error('queryClient is required');
+  if (!queryClient[queryFilterMethod])
+    throw new Error(
+      `queryClient is invalid, ${queryFilterMethod} method does not exist`
+    );
+
+  if (options.queryKey && parameters) {
+    throw new Error(
+      'callQueryClientMethodWithQueryKey: options.queryKey and options.parameters are mutually exclusive'
+    );
+  }
+
+  if (options.queryFn && requestFn) {
+    throw new Error(
+      'callQueryClientMethodWithQueryKey: options.queryFn and requestFn are mutually exclusive'
+    );
+  }
+
+  const queryFn =
+    options.queryFn ??
+    (requestFn
+      ? // @ts-expect-error
+        function ({ queryKey: [, queryParams], signal, meta, pageParam }) {
+          return requestFn(schema, {
+            parameters: infinite
+              ? (shelfMerge(2, queryParams, pageParam) as never)
+              : queryParams,
+            baseUrl,
+            signal,
+            meta,
+          });
+        }
+      : undefined);
+
+  if (parameters) {
+    // @ts-expect-error
+    return queryClient[queryFilterMethod]({
+      ...options,
+      // Event if queryFn is undefined, it will override the default queryFn from `setQueryDefaults(...)`
+      ...(queryFn ? { queryFn } : {}),
+      queryKey: infinite
+        ? composeInfiniteQueryKey(schema, parameters)
+        : composeQueryKey(schema, parameters),
+    });
+  }
+
+  // @ts-expect-error
+  return queryClient[queryFilterMethod]({ ...options, queryFn });
+}
+
+type QueryClientMethodArgs<QMethod extends keyof QueryClientPrototype> = [
+  options: Parameters<QueryClientPrototype[QMethod]>[0] & {
+    parameters?: unknown;
+    baseUrl?: string;
+    requestFn?: RequestFn<unknown>;
+  },
+  queryClient: QueryClient,
+];
+
+type QueryKeyMethods =
+  | QueryKeyMethod<'fetchQuery'>
+  | QueryKeyMethod<'prefetchQuery'>
+  | QueryKeyMethod<'fetchInfiniteQuery'>
+  | QueryKeyMethod<'prefetchInfiniteQuery'>;
+
+type QueryClientPrototype = typeof QueryClient.prototype;
+
+type QueryKeyMethod<QFMethod extends keyof typeof QueryClient.prototype> =
+  QFMethod;

package/src/lib/callQueryClientMethodWithQueryFilters.ts

@@ -1,7 +1,7 @@
 import type { QueryClient } from '@tanstack/query-core';
 
-import type { RequestClientSchema } from '../RequestClient.js';
 import { composeQueryFilters } from './composeQueryFilters.js';
+import type { OperationSchema } from './requestFn.js';
 
 /**
  * Calls a query client method with query filters and options,
@@ -11,24 +11,11 @@ export function callQueryClientMethodWithQueryFilters<
   QFMethod extends QueryFilterMethods,
 >(
   queryFilterMethod: QFMethod,
-  schema: RequestClientSchema,
-  args: [QueryClient, ...Parameters<(typeof QueryClient.prototype)[QFMethod]>]
+  schema: OperationSchema,
+  args: [...Parameters<(typeof QueryClient.prototype)[QFMethod]>, QueryClient]
 ): ReturnType<(typeof QueryClient.prototype)[QFMethod]> {
-  const queryClient = (
-    args.length === 1
-      ? args[0]
-      : args.length === 2
-        ? args[1]
-        : args.length === 3
-          ? args[2]
-          : undefined
-  ) as QueryClient | undefined;
-
-  const filters = composeQueryFilters(
-    schema,
-    args.length === 1 ? undefined : args[0]
-  );
-  const options = args.length === 3 ? args[1] : undefined;
+  const filters = args[0];
+  const queryClient = args[args.length - 1] as QueryClient | undefined;
 
   if (!queryClient) throw new Error('queryClient is required');
   if (!queryClient[queryFilterMethod])
@@ -36,12 +23,12 @@ export function callQueryClientMethodWithQueryFilters<
       `queryClient is invalid, ${queryFilterMethod} method does not exist`
     );
 
-  if (options)
-    // @ts-expect-error
-    return queryClient[queryFilterMethod](filters, options);
-
   // @ts-expect-error
-  return queryClient[queryFilterMethod](filters);
+  return queryClient[queryFilterMethod](
+    composeQueryFilters(schema, filters as never),
+    // @ts-expect-error
+    ...args.slice(1, -1)
+  );
 }
 
 type QueryFiltersMethod<QFMethod extends keyof typeof QueryClient.prototype> =

package/src/lib/callQueryClientMethodWithQueryKey.ts

@@ -0,0 +1,46 @@
+import type { QueryClient } from '@tanstack/query-core';
+
+import { composeInfiniteQueryKey } from './composeInfiniteQueryKey.js';
+import { composeQueryKey } from './composeQueryKey.js';
+import type { OperationSchema } from './requestFn.js';
+
+/**
+ * Calls a query client method with parameters and options,
+ * and automatically composes the `QueryKey` based on the schema and parameters.
+ */
+export function callQueryClientMethodWithQueryKey<
+  QFMethod extends QueryKeyMethods,
+>(
+  queryFilterMethod: QFMethod,
+  schema: OperationSchema,
+  infinite: boolean,
+  args: [...Parameters<(typeof QueryClient.prototype)[QFMethod]>, QueryClient]
+): ReturnType<(typeof QueryClient.prototype)[QFMethod]> {
+  const parameters = args[0];
+  const queryClient = args[args.length - 1] as QueryClient | undefined;
+
+  if (!queryClient) throw new Error('queryClient is required');
+  if (!queryClient[queryFilterMethod])
+    throw new Error(
+      `queryClient is invalid, ${queryFilterMethod} method does not exist`
+    );
+
+  const queryKey = Array.isArray(parameters)
+    ? parameters
+    : infinite
+      ? composeInfiniteQueryKey(schema, parameters)
+      : composeQueryKey(schema, parameters);
+
+  // @ts-expect-error
+  return queryClient[queryFilterMethod](queryKey, ...args.slice(1, -1));
+}
+
+type QueryKeyMethod<QFMethod extends keyof typeof QueryClient.prototype> =
+  QFMethod;
+
+type QueryKeyMethods =
+  | QueryKeyMethod<'setQueryData'>
+  | QueryKeyMethod<'getQueryData'>
+  | QueryKeyMethod<'getQueryState'>
+  | QueryKeyMethod<'setQueryDefaults'>
+  | QueryKeyMethod<'getQueryDefaults'>;

package/src/lib/composeInfiniteQueryKey.ts

@@ -1,8 +1,8 @@
-import type { RequestClientSchema } from '../RequestClient.js';
-import { ServiceOperationInfiniteQueryKey } from '../ServiceOperation.js';
+import type { ServiceOperationInfiniteQueryKey } from '../ServiceOperation.js';
+import type { OperationSchema } from './requestFn.js';
 
 export function composeInfiniteQueryKey<
-  TSchema extends RequestClientSchema,
+  TSchema extends OperationSchema,
   TParams,
 >(
   schema: TSchema,

package/src/lib/composeMutationKey.ts

@@ -1,26 +1,23 @@
-import type { RequestClientSchema } from '../RequestClient.js';
-import { ServiceOperationMutationKey } from '../ServiceOperation.js';
+import type { ServiceOperationMutationKey } from '../ServiceOperation.js';
+import type { OperationSchema } from './requestFn.js';
 
 /**
  * Omit `body` or `requestBody` from mutation parameters if exists
  * and return the rest of the parameters
  */
 export function composeMutationKey<
-  TSchema extends RequestClientSchema,
+  TSchema extends OperationSchema,
   TParams = undefined,
 >(
   schema: TSchema,
   parameters: undefined
 ): ServiceOperationMutationKey<TSchema, undefined>;
-export function composeMutationKey<
-  TSchema extends RequestClientSchema,
-  TParams,
->(
+export function composeMutationKey<TSchema extends OperationSchema, TParams>(
   schema: TSchema,
   parameters: TParams
 ): ServiceOperationMutationKey<TSchema, TParams>;
 export function composeMutationKey<
-  TSchema extends RequestClientSchema,
+  TSchema extends OperationSchema,
   TParams = unknown,
 >(schema: TSchema, parameters: TParams | undefined) {
   return parameters === undefined

package/src/lib/composeQueryFilters.ts

@@ -1,5 +1,5 @@
-import type { RequestClientSchema } from '../RequestClient.js';
 import { composeQueryKey } from './composeQueryKey.js';
+import type { OperationSchema } from './requestFn.js';
 
 /**
  * Replaces the `parameters` field in the filters with a `queryKey` field based on the schema.
@@ -8,7 +8,7 @@ import { composeQueryKey } from './composeQueryKey.js';
  * @param filters
  */
 export function composeQueryFilters<Filters extends object>(
-  schema: RequestClientSchema,
+  schema: OperationSchema,
   filters: Filters | undefined
 ) {
   if (!filters) {

package/src/lib/composeQueryKey.ts

@@ -1,7 +1,7 @@
-import type { RequestClientSchema } from '../RequestClient.js';
-import { ServiceOperationQueryKey } from '../ServiceOperation.js';
+import type { ServiceOperationQueryKey } from '../ServiceOperation.js';
+import type { OperationSchema } from './requestFn.js';
 
-export function composeQueryKey<TSchema extends RequestClientSchema, TParams>(
+export function composeQueryKey<TSchema extends OperationSchema, TParams>(
   schema: TSchema,
   parameters: TParams | undefined
 ): ServiceOperationQueryKey<TSchema, TParams> {

package/src/lib/{request.ts → requestFn.ts}

@@ -1,50 +1,52 @@
 /**
  * @throws {error: object|string, response: Response} if the request fails
  */
-export async function request<T>(
-  config: { baseUrl: string },
-  requestInit: APIRequestInit,
-  {
-    urlSerializer: urlSerializerFunc,
-    bodySerializer: bodySerializerFunc,
-  }: {
-    urlSerializer: typeof urlSerializer;
-    bodySerializer: typeof bodySerializer;
-  }
+export async function requestFn<T>(
+  schema: OperationSchema,
+  requestInfo: RequestFnInfo,
+  options?: RequestFnOptions
 ): Promise<T> {
-  const {
-    method,
-    url,
-    parameters,
-    mediaType,
-    headers,
-    body,
-    ...requestInitRest
-  } = requestInit;
-
-  const requestBody = bodySerializerFunc({
-    method,
-    mediaType,
-    body,
+  return baseRequestFn(schema, requestInfo, {
+    urlSerializer,
+    bodySerializer,
+    ...options,
   });
+}
 
-  const response = await fetch(urlSerializerFunc(config, { url, parameters }), {
-    method: method.toUpperCase(),
-    body: requestBody,
-    headers: mergeHeaders(
-      {
-        Accept: 'application/json',
-        'Content-Type': mediaType ?? getBodyContentType(body),
-      },
-      headers,
-      parameters?.header,
-      requestBody instanceof FormData
-        ? // remove `Content-Type` if serialized body is FormData; browser will correctly set Content-Type & boundary expression
-          { 'Content-Type': null }
-        : undefined
-    ),
-    ...requestInitRest,
-  });
+/**
+ * @throws {error: object|string, response: Response} if the request fails
+ */
+export async function baseRequestFn<T>(
+  requestSchema: OperationSchema,
+  requestInfo: RequestFnInfo,
+  options: WithRequired<RequestFnOptions, 'urlSerializer' | 'bodySerializer'>
+): Promise<T> {
+  const { parameters, headers, body, ...requestInfoRest } = requestInfo;
+
+  const requestBody = options.bodySerializer(requestSchema, requestInfo);
+
+  const baseFetch = options.fetch ?? fetch;
+
+  const response = await baseFetch(
+    options.urlSerializer(requestSchema, requestInfo),
+    {
+      method: requestSchema.method.toUpperCase(),
+      body: requestBody,
+      headers: mergeHeaders(
+        {
+          Accept: 'application/json',
+          'Content-Type': requestSchema.mediaType ?? getBodyContentType(body),
+        },
+        headers,
+        parameters?.header,
+        requestBody instanceof FormData
+          ? // remove `Content-Type` if serialized body is FormData; browser will correctly set Content-Type & boundary expression
+            { 'Content-Type': null }
+          : undefined
+      ),
+      ...requestInfoRest,
+    }
+  );
 
   // clone response to allow multiple reads
   const clonedResponse = response.clone();
@@ -57,21 +59,26 @@ export async function request<T>(
 }
 
 export function urlSerializer(
-  config: { baseUrl: string },
-  { url, parameters }: Pick<APIRequestInit, 'url' | 'parameters'>
+  schema: OperationSchema,
+  info: RequestFnPayload
 ): string {
-  const path = url.replace(/{(.*?)}/g, (substring: string, group: string) => {
-    if (parameters?.path?.hasOwnProperty(group)) {
-      return encodeURI(String(parameters?.path[group]));
+  const path = schema.url.replace(
+    /{(.*?)}/g,
+    (substring: string, group: string) => {
+      if (info.parameters?.path?.hasOwnProperty(group)) {
+        return encodeURI(String(info.parameters?.path[group]));
+      }
+      return substring;
     }
-    return substring;
-  });
+  );
 
-  if (parameters?.query) {
-    return `${config.baseUrl}${path}${getQueryString(parameters.query)}`;
+  const baseUrl = info.baseUrl ?? '';
+
+  if (info.parameters?.query) {
+    return `${baseUrl}${path}${getQueryString(info.parameters.query)}`;
   }
 
-  return `${config.baseUrl}${path}`;
+  return `${baseUrl}${path}`;
 }
 
 function getQueryString(params: Record<string, any>): string {
@@ -133,38 +140,37 @@ function mergeHeaders(...allHeaders: (HeadersOptions | undefined)[]) {
   return headers;
 }
 
-export function bodySerializer(options: {
-  method: APIRequestInit['method'];
-  mediaType: APIRequestInit['mediaType'];
-  body: APIRequestInit['body'];
-}) {
-  if (options.body === undefined) return;
+export function bodySerializer(
+  schema: OperationSchema,
+  info: RequestFnPayload
+) {
+  if (info.body === undefined) return;
 
   if (
-    options.method === 'get' ||
-    options.method === 'head' ||
-    options.method === 'options'
+    schema.method === 'get' ||
+    schema.method === 'head' ||
+    schema.method === 'options'
   )
     return;
 
-  if (options.mediaType?.includes('/form-data'))
-    return getRequestBodyFormData(options);
+  if (schema.mediaType?.includes('/form-data'))
+    return getRequestBodyFormData(info);
 
   if (
-    !options.mediaType?.includes('/json') &&
-    (typeof options.body === 'string' ||
-      options.body instanceof Blob ||
-      options.body instanceof FormData)
+    !schema.mediaType?.includes('/json') &&
+    (typeof info.body === 'string' ||
+      info.body instanceof Blob ||
+      info.body instanceof FormData)
   ) {
-    return options.body;
+    return info.body;
   }
 
-  return JSON.stringify(options.body);
+  return JSON.stringify(info.body);
 }
 
 function getRequestBodyFormData({
   body,
-}: Pick<APIRequestInit, 'body'>): FormData | undefined {
+}: Pick<RequestFnPayload, 'body'>): FormData | undefined {
   if (body instanceof FormData) return body;
   if (body === null) return;
 
@@ -203,7 +209,7 @@ function getRequestBodyFormData({
   return formData;
 }
 
-function getBodyContentType(body: APIRequestInit['body']) {
+function getBodyContentType(body: RequestFnPayload['body']) {
   if (!body) return;
   if (body instanceof Blob) return body.type || 'application/octet-stream';
   if (typeof body === 'string') return 'text/plain';
@@ -225,11 +231,7 @@ async function getResponseBody<T>(response: Response): Promise<T | undefined> {
     const errorFallbackResponse = response.clone(); // clone to allow multiple reads
 
     return response.json().catch(() => {
-      if (
-        typeof process !== 'undefined' &&
-        typeof process.env !== 'undefined' &&
-        process.env.NODE_ENV === 'development'
-      ) {
+      if (process.env.NODE_ENV === 'development') {
         console.warn(
           'Failed to parse response body as JSON. Falling back to .text()'
         );
@@ -247,7 +249,16 @@ export type HeadersOptions =
   | HeadersInit
   | Record<string, string | number | boolean | null | undefined>;
 
-export type APIRequestInit = {
+export interface OperationSchema {
+  /**
+   * Operation path
+   * @example /user/{id}
+   */
+  readonly url: string;
+
+  /**
+   * Operation method
+   */
   readonly method:
     | 'get'
     | 'put'
@@ -257,14 +268,67 @@ export type APIRequestInit = {
     | 'options'
     | 'head'
     | 'trace';
-  readonly url: string;
+
+  /**
+   * Media type of the request body
+   * @example application/json
+   */
+  readonly mediaType?: string;
+}
+
+export interface RequestFnPayload {
+  /**
+   * Base URL to use for the request
+   */
+  baseUrl: string | undefined;
+
+  /**
+   * OpenAPI parameters
+   * @example
+   * ```ts
+   * { path: {id: 1}, query: {search: 'hello'} }
+   * ```
+   */
   readonly parameters?: {
     readonly path?: Record<string, any>;
     readonly cookie?: Record<string, any>;
     readonly header?: Record<string, any>;
     readonly query?: Record<string, any>;
   };
+
+  /**
+   * Request body
+   * @example { name: 'John' }
+   */
   readonly body?: BodyInit | Record<string, unknown> | null;
-  readonly mediaType?: string;
+
+  /**
+   * Tanstack Query Meta
+   */
+  meta?: Record<string, unknown>;
+
+  /** An AbortSignal to set request's signal. */
+  signal?: AbortSignal | null;
+}
+
+interface RequestFnInfo
+  extends RequestFnPayload,
+    Omit<RequestInit, 'headers' | 'method' | 'body' | 'signal'> {
+  /**
+   * Request headers
+   * @example { 'X-Auth': '123' }
+   */
   readonly headers?: HeadersOptions;
-} & Omit<RequestInit, 'headers' | 'method' | 'body'>;
+}
+
+export interface RequestFnOptions {
+  urlSerializer?: typeof urlSerializer;
+  bodySerializer?: typeof bodySerializer;
+  fetch?: typeof fetch;
+}
+
+export type RequestFn<T> = typeof requestFn<T>;
+
+type WithRequired<T, K extends keyof T> = T & {
+  [_ in K]: {};
+};

package/src/lib/useComposeUseQueryOptions.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import { useContext } from 'react';
+
+import type { QueryClient } from '@tanstack/query-core';
+import type { UseQueryOptions } from '@tanstack/react-query';
+
+import type { QraftClientOptions } from '../qraftAPIClient.js';
+import { QraftContext } from '../QraftContext.js';
+import type { ServiceOperationQueryKey } from '../ServiceOperation.js';
+import { composeInfiniteQueryKey } from './composeInfiniteQueryKey.js';
+import { composeQueryKey } from './composeQueryKey.js';
+import type { OperationSchema } from './requestFn.js';
+import { shelfMerge } from './shelfMerge.js';
+import { useQueryClient } from './useQueryClient.js';
+
+/**
+ * Composes the options for useQuery, useInfiniteQuery, useSuspenseQuery, and useSuspenseQueries.
+ * @internal
+ */
+export function useComposeUseQueryOptions(
+  qraftOptions: QraftClientOptions | undefined,
+  schema: OperationSchema,
+  args: UseQueryOptionsArgs,
+  infinite: boolean
+): never {
+  const [parameters, options, queryClient] = args;
+
+  const contextValue = useContext(qraftOptions?.context ?? QraftContext);
+  if (!contextValue?.requestFn)
+    throw new Error(`QraftContext.requestFn not found`);
+
+  const queryFn =
+    options?.queryFn ??
+    // @ts-expect-error
+    function ({ queryKey: [, queryParams], signal, meta, pageParam }) {
+      return contextValue.requestFn(schema, {
+        // @ts-expect-error
+        parameters: infinite
+          ? (shelfMerge(2, queryParams, pageParam) as never)
+          : queryParams,
+        baseUrl: contextValue.baseUrl,
+        signal,
+        meta,
+      });
+    };
+
+  const queryKey = Array.isArray(parameters)
+    ? (parameters as ServiceOperationQueryKey<OperationSchema, unknown>)
+    : infinite
+      ? composeInfiniteQueryKey(schema, parameters)
+      : composeQueryKey(schema, parameters);
+
+  return [
+    { ...options, queryFn, queryKey },
+    useQueryClient(qraftOptions, queryClient),
+  ] as never;
+}
+
+type UseQueryOptionsArgs = [
+  parameters: unknown,
+  options?: UseQueryOptions,
+  queryClient?: QueryClient,
+];

package/src/lib/useQueryClient.ts

@@ -0,0 +1,26 @@
+'use client';
+
+import { useContext } from 'react';
+
+import {
+  QueryClient,
+  useQueryClient as useQueryClientTanstack,
+} from '@tanstack/react-query';
+
+import type { QraftClientOptions } from '../qraftAPIClient.js';
+import { QraftContext } from '../QraftContext.js';
+
+/**
+ * Get the QueryClient from the QraftContext or the provided QueryClient argument.
+ * @param qraftOptions if `queryClient` is not provided, will be taken from context
+ * @param queryClient If not provided, will be taken this instance
+ */
+export function useQueryClient(
+  qraftOptions: QraftClientOptions | undefined,
+  queryClient: QueryClient | undefined
+) {
+  const queryClientByContext = useContext(qraftOptions?.context ?? QraftContext)
+    ?.queryClient;
+
+  return useQueryClientTanstack(queryClient ?? queryClientByContext);
+}