@openapi-qraft/react 2.0.0-next.8 → 2.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openapi-qraft/react",
-  "version": "2.0.0-next.8",
-  "description": "API client for React, providing type-safe requests and dynamic Tanstack Query React Hooks via a modular, Proxy-based architecture.",
+  "version": "2.0.0",
+  "description": "OpenAPI client for React, providing type-safe requests and dynamic TanStack Query React Hooks via a modular, Proxy-based architecture.",
   "scripts": {
     "build": "NODE_ENV=production rollup --config rollup.config.mjs && tsc --project tsconfig.build.json --emitDeclarationOnly",
     "dev": "rimraf dist/ && tsc --project tsconfig.build.json --watch --outDir ./dist/esm --noEmitOnError false",
@@ -15,34 +15,34 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@openapi-qraft/tanstack-query-react-types": "2.0.0-next.8"
+    "@openapi-qraft/tanstack-query-react-types": "2.0.0"
   },
   "devDependencies": {
-    "@openapi-qraft/cli": "2.0.0-next.8",
+    "@openapi-qraft/cli": "2.0.0",
     "@openapi-qraft/eslint-config": "1.0.0",
-    "@openapi-qraft/openapi-typescript-plugin": "^1.2.0-next.8",
-    "@openapi-qraft/rollup-config": "1.1.0-next.0",
-    "@openapi-qraft/tanstack-query-react-plugin": "2.0.0-next.8",
+    "@openapi-qraft/openapi-typescript-plugin": "^1.2.0",
+    "@openapi-qraft/rollup-config": "1.1.0",
+    "@openapi-qraft/tanstack-query-react-plugin": "2.0.0",
     "@openapi-qraft/test-fixtures": "1.0.0",
-    "@tanstack/react-query": "^5.17.3",
+    "@tanstack/react-query": "^5.56.2",
     "@testing-library/jest-dom": "^5.17.0",
     "@testing-library/react": "^13.4.0",
     "@testing-library/user-event": "^14.5.2",
     "@types/jscodeshift": "^0.11.11",
-    "@types/react": "^18.2.47",
-    "@vitejs/plugin-react": "latest",
-    "@vitest/coverage-v8": "^1.1.3",
-    "eslint": "^9.0.0",
-    "globals": "^15.0.0",
+    "@types/react": "^18.3.5",
+    "@vitejs/plugin-react": "^4.3.1",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.16.0",
+    "globals": "^15.9.0",
     "jscodeshift": "^17.0.0",
-    "jsdom": "latest",
-    "msw": "^2.0.12",
+    "jsdom": "^25.0.0",
+    "msw": "^2.6.8",
     "prettier": "^3.3.3",
-    "query-string": "^8.1.0",
-    "react": "^18.2.0",
+    "query-string": "^8.2.0",
+    "react": "^18.3.1",
     "rimraf": "^5.0.10",
-    "rollup": "~4.18.0",
-    "vitest": "^1.4.0"
+    "rollup": "~4.22.4",
+    "vitest": "^2.1.8"
   },
   "peerDependencies": {
     "@tanstack/query-core": "^5.0.0",
@@ -77,6 +77,11 @@
       "require": "./dist/cjs/qraftPredefinedParametersRequestFn.cjs",
       "types": "./dist/types/qraftPredefinedParametersRequestFn.d.ts"
     },
+    "./unstable__responseUtils": {
+      "import": "./dist/esm/unstable__responseUtils.js",
+      "require": "./dist/cjs/unstable__responseUtils.cjs",
+      "types": "./dist/types/unstable__responseUtils.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {

package/src/callbacks/ensureInfiniteQueryData.ts

@@ -0,0 +1,29 @@
+import type { ServiceOperationFetchInfiniteQuery } from '@openapi-qraft/tanstack-query-react-types';
+import type { DefaultError } from '@tanstack/query-core';
+import type { CreateAPIQueryClientOptions } from '../qraftAPIClient.js';
+import { callQueryClientMethodWithQueryKey } from '../lib/callQueryClientFetchMethod.js';
+
+export const ensureInfiniteQueryData: <
+  TSchema extends { url: string; method: 'get' | 'head' | 'options' },
+  TData,
+  TParams,
+>(
+  qraftOptions: CreateAPIQueryClientOptions,
+  schema: TSchema,
+  args: Parameters<
+    ServiceOperationFetchInfiniteQuery<
+      TSchema,
+      TData,
+      TParams,
+      DefaultError
+    >['ensureInfiniteQueryData']
+  >
+) => Promise<TData> = (qraftOptions, schema, args) => {
+  return callQueryClientMethodWithQueryKey(
+    qraftOptions,
+    'ensureInfiniteQueryData',
+    schema,
+    true,
+    args as never
+  ) as never;
+};

package/src/callbacks/ensureQueryData.ts

@@ -0,0 +1,29 @@
+import type { ServiceOperationFetchQuery } from '@openapi-qraft/tanstack-query-react-types';
+import type { DefaultError } from '@tanstack/query-core';
+import type { CreateAPIQueryClientOptions } from '../qraftAPIClient.js';
+import { callQueryClientMethodWithQueryKey } from '../lib/callQueryClientFetchMethod.js';
+
+export const ensureQueryData: <
+  TSchema extends { url: string; method: 'get' | 'head' | 'options' },
+  TData,
+  TParams,
+>(
+  qraftOptions: CreateAPIQueryClientOptions,
+  schema: TSchema,
+  args: Parameters<
+    ServiceOperationFetchQuery<
+      TSchema,
+      TData,
+      TParams,
+      DefaultError
+    >['ensureQueryData']
+  >
+) => Promise<TData> = (qraftOptions, schema, args) => {
+  return callQueryClientMethodWithQueryKey(
+    qraftOptions,
+    'ensureQueryData',
+    schema,
+    false,
+    args as never
+  ) as never;
+};

package/src/callbacks/index.ts

@@ -26,8 +26,10 @@ export { isMutating } from './isMutating.js';
 export { useIsFetching } from './useIsFetching.js';
 export { fetchQuery } from './fetchQuery.js';
 export { prefetchQuery } from './prefetchQuery.js';
+export { ensureQueryData } from './ensureQueryData.js';
 export { fetchInfiniteQuery } from './fetchInfiniteQuery.js';
 export { prefetchInfiniteQuery } from './prefetchInfiniteQuery.js';
+export { ensureInfiniteQueryData } from './ensureInfiniteQueryData.js';
 export { getQueryState } from './getQueryState.js';
 export { getInfiniteQueryState } from './getInfiniteQueryState.js';
 export { operationInvokeFn } from './operationInvokeFn.js';

package/src/callbacks/useQueries.ts

@@ -28,6 +28,7 @@ export const useQueries: (
   return useQueriesTanstack(
     {
       ...options,
+      // @ts-expect-error - Too complex to type
       queries: options.queries.map((queryOptions) => {
         const optionsWithQueryKey =
           'parameters' in queryOptions

package/src/callbacks/useSuspenseQueries.ts

@@ -28,6 +28,7 @@ export const useSuspenseQueries: (
   return useSuspenseQueriesTanstack(
     {
       ...options,
+      // @ts-expect-error - Too complex to type
       queries: options.queries.map((queryOptions) => {
         const optionsWithQueryKey =
           'parameters' in queryOptions

package/src/index.ts

@@ -16,13 +16,11 @@ export {
   urlSerializer,
   bodySerializer,
   mergeHeaders,
+  type RequestFn,
   type RequestFnResponse,
-} from './lib/requestFn.js';
-
-export type {
-  RequestFnPayload,
-  RequestFnOptions,
-  HeadersOptions,
-  OperationSchema,
-  RequestFn,
+  type HeadersOptions,
+  type RequestFnOptions,
+  type RequestFnInfo,
+  type OperationSchema,
+  type RequestFnPayload,
 } from './lib/requestFn.js';

package/src/lib/callQueryClientFetchMethod.ts

@@ -84,8 +84,10 @@ type QueryClientMethodArgs<QMethod extends keyof QueryClientPrototype> = [
 type QueryKeyMethods =
   | QueryKeyMethod<'fetchQuery'>
   | QueryKeyMethod<'prefetchQuery'>
+  | QueryKeyMethod<'ensureQueryData'>
   | QueryKeyMethod<'fetchInfiniteQuery'>
-  | QueryKeyMethod<'prefetchInfiniteQuery'>;
+  | QueryKeyMethod<'prefetchInfiniteQuery'>
+  | QueryKeyMethod<'ensureInfiniteQueryData'>;
 
 type QueryClientPrototype = typeof QueryClient.prototype;
 

package/src/lib/requestFn.ts

@@ -1,12 +1,11 @@
 import type {
   HeadersOptions,
   OperationSchema,
-  RequestFn,
   RequestFnInfo,
   RequestFnOptions,
-  RequestFnPayload,
   RequestFnResponse,
 } from '@openapi-qraft/tanstack-query-react-types';
+import { processResponse, resolveResponse } from './responseUtils.js';
 
 /**
  * This function is used to make a request to a specified endpoint.
@@ -35,7 +34,7 @@ export async function requestFn<TData, TError>(
 
 /**
  * This function is used to make a request to a specified endpoint.
- * It's needed to create a custom `requestFn` with a custom `urlSerializer`
+ * It's necessary to create a custom `requestFn` with a custom `urlSerializer`
  * and `bodySerializer`, with the tree-shaking of the default `requestFn`
  * and its serializers.
  *
@@ -56,24 +55,18 @@ export async function baseRequestFn<TData, TError>(
 ): Promise<RequestFnResponse<TData, TError>> {
   const { parameters, headers, body, ...requestInfoRest } = requestInfo;
 
-  const requestBody = options.bodySerializer(requestSchema, requestInfo);
+  const requestPayload = options.bodySerializer(requestSchema, body);
 
   const baseFetch = options.fetch ?? fetch;
 
   return baseFetch(options.urlSerializer(requestSchema, requestInfo), {
     method: requestSchema.method.toUpperCase(),
-    body: requestBody,
+    body: requestPayload?.body,
     headers: mergeHeaders(
-      {
-        Accept: 'application/json',
-        'Content-Type': requestSchema.mediaType ?? getBodyContentType(body),
-      },
+      { Accept: 'application/json' },
+      requestPayload?.headers,
       headers,
-      parameters?.header,
-      requestBody instanceof FormData
-        ? // remove `Content-Type` if the serialized body is FormData; the browser will correctly set Content-Type & boundary expression
-          { 'Content-Type': null }
-        : undefined
+      parameters?.header
     ),
     ...requestInfoRest,
   })
@@ -98,7 +91,7 @@ export async function baseRequestFn<TData, TError>(
  */
 export function urlSerializer(
   schema: OperationSchema,
-  info: RequestFnPayload
+  info: Pick<RequestFnInfo, 'baseUrl' | 'parameters'>
 ): string {
   const path = schema.url.replace(
     /{(.*?)}/g,
@@ -183,47 +176,101 @@ export function mergeHeaders(...allHeaders: (HeadersOptions | undefined)[]) {
 
 export function bodySerializer(
   schema: OperationSchema,
-  info: RequestFnPayload
+  body: RequestFnInfo['body']
 ) {
-  if (info.body === undefined) return;
-
   if (
     schema.method === 'get' ||
     schema.method === 'head' ||
     schema.method === 'options'
   )
-    return;
+    return undefined;
+
+  if (body === undefined || body === null) return undefined;
+
+  if (typeof body === 'string') {
+    return {
+      body,
+      headers: {
+        'Content-Type':
+          // prefer text/* media type
+          schema.mediaType?.find((mediaType) => mediaType.includes('text/')) ??
+          // prefer JSON media type, assume that body is serialized as JSON
+          schema.mediaType?.find((mediaType) => mediaType.includes('/json')) ??
+          'text/plain',
+      },
+    };
+  }
 
-  if (schema.mediaType?.includes('/form-data'))
-    return getRequestBodyFormData(info);
+  if (body instanceof FormData) {
+    return {
+      body,
+      headers: {
+        // remove `Content-Type` if the serialized body is FormData;
+        // the browser will correctly set Content-Type & boundary expression
+        'Content-Type': null,
+      },
+    };
+  }
 
-  if (
-    !schema.mediaType?.includes('/json') &&
-    (typeof info.body === 'string' ||
-      info.body instanceof Blob ||
-      info.body instanceof FormData)
-  ) {
-    return info.body;
+  if (body instanceof Blob) {
+    return {
+      body,
+      headers: {
+        'Content-Type':
+          body.type ||
+          schema.mediaType?.find(
+            (mediaType) =>
+              !(
+                mediaType.includes('text/') &&
+                mediaType.includes('/form-data') &&
+                mediaType.includes('/json')
+              )
+          ) ||
+          'application/octet-stream',
+      },
+    };
+  }
+
+  let jsonMediaType: string | null = null;
+  let formDataMediaType: string | null = null;
+
+  if (schema.mediaType) {
+    for (let i = 0; i < schema.mediaType.length; i++) {
+      const mediaType = schema.mediaType[i];
+      if (mediaType.includes('/json')) jsonMediaType = mediaType;
+      else if (mediaType.includes('/form-data')) formDataMediaType = mediaType;
+    }
+  }
+
+  if (formDataMediaType) {
+    if (
+      !jsonMediaType ||
+      // Prefer FormData serialization if one of the fields is a Blob
+      Object.values(body).some((value) => value instanceof Blob)
+    ) {
+      return {
+        body: getRequestBodyFormData(body),
+        headers: {
+          // remove `Content-Type` if the serialized body is FormData;
+          // the browser will correctly set Content-Type & boundary expression
+          'Content-Type': null,
+        },
+      };
+    }
   }
 
-  return JSON.stringify(info.body);
+  return {
+    body: JSON.stringify(body),
+    headers: {
+      'Content-Type': jsonMediaType ?? 'application/json',
+    },
+  };
 }
 
-function getRequestBodyFormData({
-  body,
-}: Pick<RequestFnPayload, 'body'>): FormData | undefined {
+function getRequestBodyFormData(
+  body: NonNullable<RequestFnInfo['body']>
+): FormData {
   if (body instanceof FormData) return body;
-  if (body === null) return;
-
-  if (body instanceof Blob) throw new Error('Blob not supported in form-data');
-  if (body instanceof ArrayBuffer)
-    throw new Error('ArrayBuffer not supported in form-data');
-  if (body instanceof URLSearchParams)
-    throw new Error('URLSearchParams not supported in form-data');
-  if (body instanceof ReadableStream)
-    throw new Error('ReadableStream not supported in form-data');
-  if (typeof body === 'string')
-    throw new Error('String not supported in form-data');
   if (typeof body !== 'object')
     throw new Error(`Unsupported body type ${typeof body} in form-data.`);
 
@@ -250,81 +297,6 @@ function getRequestBodyFormData({
   return formData;
 }
 
-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';
-  if (!(body instanceof FormData)) return 'application/json';
-}
-
-async function processResponse<TData, TError>(
-  response: Response
-): Promise<RequestFnResponse<TData, TError>> {
-  if (response.status === 204 || response.headers.get('Content-Length') === '0')
-    return (
-      response.ok ? { data: {}, response } : { error: {}, response }
-    ) as RequestFnResponse<TData, TError>;
-
-  if (isJsonResponse(response)) {
-    // clone response before parsing every time to allow multiple reads
-    const jsonResponse = response.clone().json();
-    return resolveResponse(
-      response,
-      response.ok ? jsonResponse : Promise.reject(await jsonResponse)
-    );
-  }
-
-  const jsonResponse = new Promise<TData>((resolve, reject) =>
-    // attempt to parse JSON for successful responses, otherwise fail
-    response.clone().text().then(JSON.parse).then(resolve, reject)
-  );
-
-  return resolveResponse(
-    response,
-    response.ok ? jsonResponse : Promise.reject(await jsonResponse)
-  );
-}
-
-function isJsonResponse(response: Response) {
-  const contentType = response.headers.get('Content-Type')?.toLowerCase();
-  return contentType?.includes('/json') || contentType?.includes('+json');
-}
-
-function resolveResponse<TData, TError>(
-  error: Error
-): Promise<RequestFnResponse<TData, TError>>;
-function resolveResponse<TData, TError>(
-  responseToReturn: Response,
-  responsePromise: Promise<TData>
-): Promise<RequestFnResponse<TData, TError>>;
-function resolveResponse<TData, TError>(
-  responseToReturn: Response | Error,
-  responsePromise?: Promise<TData>
-): Promise<RequestFnResponse<TData, TError>> {
-  if (!responsePromise)
-    return Promise.reject({
-      error: responseToReturn,
-      response: undefined,
-      data: undefined,
-    });
-
-  return responsePromise
-    .then(
-      (data) =>
-        ({ data, response: responseToReturn }) as RequestFnResponse<
-          TData,
-          TError
-        >
-    )
-    .catch(
-      (error) =>
-        ({ error, response: responseToReturn }) as RequestFnResponse<
-          TData,
-          TError
-        >
-    );
-}
-
 type WithRequired<T, K extends keyof T> = T & {
   [_ in K]: {};
 };
@@ -333,8 +305,12 @@ export type {
   RequestFn,
   RequestFnResponse,
   HeadersOptions,
-  RequestFnPayload,
   RequestFnOptions,
   RequestFnInfo,
   OperationSchema,
-};
+} from '@openapi-qraft/tanstack-query-react-types';
+
+/**
+ * @deprecated use `RequestFnInfo` instead
+ */
+export type RequestFnPayload = RequestFnInfo;

package/src/lib/responseUtils.ts

@@ -0,0 +1,74 @@
+import type { RequestFnResponse } from '@openapi-qraft/tanstack-query-react-types';
+
+/**
+ * Processes the response from the server.
+ * @beta
+ */
+export async function processResponse<TData, TError>(
+  response: Response
+): Promise<RequestFnResponse<TData, TError>> {
+  if (response.status === 204 || response.headers.get('Content-Length') === '0')
+    return (
+      response.ok ? { data: {}, response } : { error: {}, response }
+    ) as RequestFnResponse<TData, TError>;
+
+  const contentType = response.headers.get('Content-Type')?.toLowerCase();
+
+  const isJsonResponse =
+    contentType?.includes('/json') || contentType?.includes('+json');
+
+  if (isJsonResponse) {
+    // clone response before parsing every time to allow multiple reads
+    const jsonResponse = response.clone().json();
+    return resolveResponse(
+      response,
+      response.ok ? jsonResponse : Promise.reject(await jsonResponse)
+    );
+  }
+
+  const textResponse = response.clone().text() as Promise<TData>;
+
+  return resolveResponse(
+    response,
+    response.ok ? textResponse : Promise.reject(await textResponse)
+  );
+}
+
+/**
+ * Resolves the response from the server.
+ * @beta
+ */
+export function resolveResponse<TData, TError>(
+  error: Error
+): Promise<RequestFnResponse<TData, TError>>;
+export function resolveResponse<TData, TError>(
+  responseToReturn: Response,
+  responsePromise: Promise<TData>
+): Promise<RequestFnResponse<TData, TError>>;
+export function resolveResponse<TData, TError>(
+  responseToReturn: Response | Error,
+  responsePromise?: Promise<TData>
+): Promise<RequestFnResponse<TData, TError>> {
+  if (!responsePromise)
+    return Promise.reject({
+      error: responseToReturn,
+      response: undefined,
+      data: undefined,
+    });
+
+  return responsePromise
+    .then(
+      (data) =>
+        ({ data, response: responseToReturn }) as RequestFnResponse<
+          TData,
+          TError
+        >
+    )
+    .catch(
+      (error) =>
+        ({ error, response: responseToReturn }) as RequestFnResponse<
+          TData,
+          TError
+        >
+    );
+}

package/src/lib/useComposeUseQueryOptions.ts

@@ -24,7 +24,6 @@ export function useComposeUseQueryOptions(
 
   const queryFn =
     options?.queryFn ??
-    // @ts-expect-error - Too complex to type
     function ({ queryKey: [, queryParams], signal, meta, pageParam }) {
       return qraftOptions
         .requestFn(schema, {

package/src/qraftAPIClient.ts

@@ -116,11 +116,12 @@ export function qraftAPIClient<
       if (
         callbackName !== 'operationInvokeFn' &&
         callbackName !== 'getQueryKey' &&
-        callbackName !== 'getMutationKey'
+        callbackName !== 'getMutationKey' &&
+        callbackName !== 'getInfiniteQueryKey'
       )
         if (!options || !('queryClient' in options && options.queryClient))
           throw new Error(
-            `'qraft.<service>.<operation>.${String(callbackName)}()' requires 'queryClient' in options.`
+            `'qraft.<service>.<operation>.${String(callbackName)}()' requires 'queryClient' in 'createAPIClient(...)' options.`
           );
 
       // @ts-expect-error - Too complex union type
@@ -223,6 +224,8 @@ type QueryOperationCallbacks = Extract<
   | 'prefetchInfiniteQuery'
   | 'prefetchQuery'
   | 'refetchQueries'
+  | 'ensureQueryData'
+  | 'ensureInfiniteQueryData'
   | 'removeQueries'
   | 'resetQueries'
   | 'setInfiniteQueryData'

package/src/unstable__responseUtils.ts

@@ -0,0 +1 @@
+export { resolveResponse, processResponse } from './lib/responseUtils.js';