@openapi-qraft/react 1.14.0 → 2.0.0-next.1

package/src/lib/callQueryClientMethodWithQueryKey.ts

@@ -1,4 +1,5 @@
 import type { QueryClient } from '@tanstack/query-core';
+import type { CreateAPIQueryClientOptions } from '../qraftAPIClient.js';
 import type { OperationSchema } from './requestFn.js';
 import { composeInfiniteQueryKey } from './composeInfiniteQueryKey.js';
 import { composeQueryKey } from './composeQueryKey.js';
@@ -10,19 +11,13 @@ import { composeQueryKey } from './composeQueryKey.js';
 export function callQueryClientMethodWithQueryKey<
   QFMethod extends QueryKeyMethods,
 >(
-  queryFilterMethod: QFMethod,
+  qraftOptions: CreateAPIQueryClientOptions,
+  queryClientMethod: QFMethod,
   schema: OperationSchema,
   infinite: boolean,
   args: [...Parameters<(typeof QueryClient.prototype)[QFMethod]>, QueryClient]
 ): ReturnType<(typeof QueryClient.prototype)[QFMethod]> {
-  const parameters = args.length > 1 ? args[0] : undefined;
-  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 parameters = args[0];
 
   const queryKey = Array.isArray(parameters)
     ? parameters
@@ -30,8 +25,13 @@ export function callQueryClientMethodWithQueryKey<
       ? composeInfiniteQueryKey(schema, parameters)
       : composeQueryKey(schema, parameters);
 
+  const queryClient = qraftOptions.queryClient;
+
   // @ts-expect-error - Too complex to type
-  return queryClient[queryFilterMethod](queryKey, ...args.slice(1, -1));
+  return queryClient[queryClientMethod](
+    queryKey,
+    ...args.slice(1, args.length)
+  );
 }
 
 type QueryKeyMethod<QFMethod extends keyof typeof QueryClient.prototype> =

package/src/lib/requestFn.ts

@@ -11,12 +11,12 @@
  *
  * @throws {error: object|string, response: Response} Throws an error if the request fails. The error includes the error message and the response from the server.
  */
-export async function requestFn<T>(
+export async function requestFn<TData, TError>(
   schema: OperationSchema,
   requestInfo: RequestFnInfo,
   options?: RequestFnOptions
-): Promise<T> {
-  return baseRequestFn(schema, requestInfo, {
+): Promise<RequestFnResponse<TData, TError>> {
+  return baseRequestFn<TData, TError>(schema, requestInfo, {
     urlSerializer,
     bodySerializer,
     ...options,
@@ -39,46 +39,36 @@ export async function requestFn<T>(
  *
  * @throws {error: object|string, response: Response} Throws an error if the request fails. The error includes the error message and the response from the server.
  */
-export async function baseRequestFn<T>(
+export async function baseRequestFn<TData, TError>(
   requestSchema: OperationSchema,
   requestInfo: RequestFnInfo,
   options: WithRequired<RequestFnOptions, 'urlSerializer' | 'bodySerializer'>
-): Promise<T> {
+): Promise<RequestFnResponse<TData, TError>> {
   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();
-
-  if (!response.ok) {
-    throw await getResponseBody(clonedResponse);
-  }
-
-  return (await getResponseBody(clonedResponse)) as T;
+  return 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 the serialized body is FormData; the browser will correctly set Content-Type & boundary expression
+          { 'Content-Type': null }
+        : undefined
+    ),
+    ...requestInfoRest,
+  })
+    .then(processResponse as typeof processResponse<TData, TError>)
+    .catch(resolveResponse as typeof resolveResponse<TData, TError>);
 }
 
 /**
@@ -257,27 +247,72 @@ function getBodyContentType(body: RequestFnPayload['body']) {
   if (!(body instanceof FormData)) return 'application/json';
 }
 
-async function getResponseBody<T>(response: Response): Promise<T | undefined> {
+async function processResponse<TData, TError>(
+  response: Response
+): Promise<RequestFnResponse<TData, TError>> {
   if (response.status === 204 || response.headers.get('Content-Length') === '0')
-    return undefined;
-
-  const contentType = response.headers.get('Content-Type')?.toLowerCase();
-  const isJSON =
-    contentType?.includes('/json') || contentType?.includes('+json');
+    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)
+    );
+  }
 
-  if (isJSON) {
+  const jsonResponse = new Promise<TData>((resolve, reject) =>
     // attempt to parse JSON for successful responses, otherwise fail
-    if (response.ok) return response.json();
+    response.clone().text().then(JSON.parse).then(resolve, reject)
+  );
 
-    const errorFallbackResponse = response.clone(); // clone to allow multiple reads
+  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');
+}
 
-    return response.json().catch(() => {
-      // falling back to .text() when necessary for error messages
-      return errorFallbackResponse.text();
+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 response.text() as Promise<T>;
+  return responsePromise
+    .then(
+      (data) =>
+        ({ data, response: responseToReturn }) as RequestFnResponse<
+          TData,
+          TError
+        >
+    )
+    .catch(
+      (error) =>
+        ({ error, response: responseToReturn }) as RequestFnResponse<
+          TData,
+          TError
+        >
+    );
 }
 
 // To have definitely typed headers without a conversion to stings
@@ -319,7 +354,7 @@ export interface RequestFnPayload {
    * Base URL to use for the request
    * @example 'https://api.example.com'
    */
-  baseUrl: string | undefined;
+  baseUrl?: string;
 
   /**
    * OpenAPI parameters
@@ -365,7 +400,26 @@ export interface RequestFnOptions {
   fetch?: typeof fetch;
 }
 
-export type RequestFn<T> = typeof requestFn<T>;
+export type RequestFn<TData, TError> = typeof requestFn<TData, TError>;
+
+export type RequestFnResponse<TData, TError> =
+  | {
+      data?: TData;
+      response: Response;
+      error?: never;
+    }
+  | {
+      // server error
+      error?: TError | Error;
+      response: Response;
+      data?: never;
+    }
+  | {
+      // network error
+      error?: Error;
+      data?: never;
+      response?: never;
+    };
 
 type WithRequired<T, K extends keyof T> = T & {
   [_ in K]: {};

package/src/lib/requestFnResponseResolver.ts

@@ -0,0 +1,8 @@
+import { RequestFnResponse } from './requestFn.js';
+
+export function requestFnResponseResolver<TData, TError>(
+  requestFnResponse: RequestFnResponse<TData, TError>
+): TData | undefined {
+  if ('error' in requestFnResponse) throw requestFnResponse.error;
+  return requestFnResponse.data;
+}

package/src/lib/urlSerializer.test.ts

@@ -45,7 +45,6 @@ describe('urlSerializer', () => {
     expect(
       urlSerializer(
         { url: '/users/{userId}/posts', method: 'get' },
-        // @ts-expect-error - Missing baseUrl fallback
         {
           parameters: { path: { userId: '123' } },
         }

package/src/lib/useComposeUseQueryOptions.ts

@@ -2,46 +2,41 @@
 
 import type { QueryClient } from '@tanstack/query-core';
 import type { UseQueryOptions } from '@tanstack/react-query';
-import type { QraftClientOptions } from '../qraftAPIClient.js';
+import type { CreateAPIQueryClientOptions } from '../qraftAPIClient.js';
 import type { ServiceOperationQueryKey } from '../service-operation/ServiceOperationKey.js';
 import type { OperationSchema } from './requestFn.js';
-import { useContext } from 'react';
-import { QraftContext } from '../QraftContext.js';
 import { composeInfiniteQueryKey } from './composeInfiniteQueryKey.js';
 import { composeQueryKey } from './composeQueryKey.js';
+import { requestFnResponseResolver } from './requestFnResponseResolver.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,
+  qraftOptions: CreateAPIQueryClientOptions,
   schema: OperationSchema,
   args: UseQueryOptionsArgs,
   infinite: boolean
 ): never {
-  const [parameters, options, queryClient] = args;
-
-  const contextValue = useContext(qraftOptions?.context ?? QraftContext);
+  const [parameters, options] = args;
 
   const queryFn =
     options?.queryFn ??
     // @ts-expect-error - Too complex to type
     function ({ queryKey: [, queryParams], signal, meta, pageParam }) {
-      if (!contextValue?.requestFn)
-        throw new Error(`QraftContext.requestFn not found`);
-
-      return contextValue.requestFn(schema, {
-        // @ts-expect-error - Too complex to type
-        parameters: infinite
-          ? (shelfMerge(2, queryParams, pageParam) as never)
-          : queryParams,
-        baseUrl: contextValue.baseUrl,
-        signal,
-        meta,
-      });
+      return qraftOptions
+        .requestFn(schema, {
+          // @ts-expect-error - Too complex to type
+          parameters: infinite
+            ? (shelfMerge(2, queryParams, pageParam) as never)
+            : queryParams,
+          baseUrl: qraftOptions.baseUrl,
+          signal,
+          meta,
+        })
+        .then(requestFnResponseResolver, requestFnResponseResolver);
     };
 
   const queryKey = Array.isArray(parameters)
@@ -50,10 +45,7 @@ export function useComposeUseQueryOptions(
       ? composeInfiniteQueryKey(schema, parameters)
       : composeQueryKey(schema, parameters);
 
-  return [
-    { ...options, queryFn, queryKey },
-    useQueryClient(qraftOptions, queryClient),
-  ] as never;
+  return [{ ...options, queryFn, queryKey }, qraftOptions.queryClient] as never;
 }
 
 type UseQueryOptionsArgs = [

package/src/qraftAPIClient.ts

@@ -1,21 +1,78 @@
-import type { Context } from 'react';
+import type { QueryClient } from '@tanstack/query-core';
+import type * as callbacks from './callbacks/index.js';
 import type * as operationInvokeModule from './callbacks/operationInvokeFn.js';
-import type { OperationSchema } from './lib/requestFn.js';
-import type { QraftContextValue } from './QraftContext.js';
+import type {
+  OperationSchema,
+  RequestFnInfo,
+  RequestFnResponse,
+} from './lib/requestFn.js';
+import type {
+  ServiceOperationMutation,
+  ServiceOperationQuery,
+} from './service-operation/index.js';
+import type { ServiceOperationMutationFn } from './service-operation/ServiceOperationMutationFn.js';
+import type { ServiceOperationQueryFn } from './service-operation/ServiceOperationQueryFn.js';
 import { createRecursiveProxy } from './lib/createRecursiveProxy.js';
 
-export interface QraftClientOptions {
-  context?: Context<QraftContextValue>;
+export interface CreateAPIBasicClientOptions {
+  requestFn<TData, TError>(
+    schema: OperationSchema,
+    requestInfo: RequestFnInfo
+  ): Promise<RequestFnResponse<TData, TError>>;
+  baseUrl: string;
 }
 
-export const qraftAPIClient = <
-  Services extends ServicesBaseDeclaration<Services>,
-  Callbacks extends ServicesCallbacks,
+export interface CreateAPIQueryClientOptions
+  extends CreateAPIBasicClientOptions {
+  queryClient: QueryClient;
+}
+
+/**
+ * @deprecated use `CreateAPIClientOptions` instead
+ */
+export type QraftClientOptions =
+  | CreateAPIBasicClientOptions
+  | CreateAPIQueryClientOptions;
+
+export type CreateAPIClientOptions =
+  | CreateAPIBasicClientOptions
+  | CreateAPIQueryClientOptions;
+
+export function qraftAPIClient<
+  Services extends ServicesDeclaration<Services>,
+  TCallbacks extends Callbacks,
+>(
+  services: ServiceSchemasDeclaration<Services>,
+  callbacks: TCallbacks,
+  options: CreateAPIBasicClientOptions
+): APIBasicClientServices<Services, TCallbacks>;
+
+export function qraftAPIClient<
+  Services extends ServicesDeclaration<Services>,
+  TCallbacks extends Required<Callbacks>,
 >(
-  services: ServicesDeclaration<Services>,
-  callbacks: Callbacks,
-  options?: QraftClientOptions
-): Services => {
+  services: ServiceSchemasDeclaration<Services>,
+  callbacks: TCallbacks,
+  options: CreateAPIQueryClientOptions
+): Services;
+
+export function qraftAPIClient<
+  Services extends ServicesDeclaration<Services>,
+  TCallbacks extends Callbacks,
+>(
+  services: ServiceSchemasDeclaration<Services>,
+  callbacks: TCallbacks,
+  options: CreateAPIQueryClientOptions
+): APIQueryClientServices<Services, TCallbacks>;
+
+export function qraftAPIClient<
+  Services extends ServicesDeclaration<Services>,
+  TCallbacks extends Callbacks,
+>(
+  services: ServiceSchemasDeclaration<Services>,
+  callbacks: TCallbacks,
+  options: CreateAPIClientOptions
+): APIQueryClientServices<Services, TCallbacks> | Services {
   return createRecursiveProxy(
     function getCallback(getPath, key) {
       if (getPath.length !== 2 || key !== 'schema') return; // todo::maybe return callback?
@@ -28,23 +85,46 @@ export const qraftAPIClient = <
     function applyCallback(applyPath, args) {
       const { path, callbackName } = extractCallbackDetails(applyPath);
 
-      if (!(callbackName in callbacks))
-        throw new Error(`Function ${callbackName} is not supported`);
+      assertValidCallbackName(callbackName, callbacks);
 
       const serviceOperation = getByPath(services, path);
 
       if (!isServiceOperation(serviceOperation))
         throw new Error(`Service operation not found: ${path.join('.')}`);
 
-      return callbacks[callbackName as keyof Callbacks](
-        options,
-        serviceOperation.schema,
-        args
-      );
+      if (
+        callbackName !== 'operationInvokeFn' &&
+        callbackName !== 'getQueryKey' &&
+        callbackName !== 'getMutationKey'
+      )
+        if (!('queryClient' in options && options.queryClient))
+          throw new Error(
+            `'qraft.<service>.<operation>.${String(callbackName)}()' requires 'queryClient' in options.`
+          );
+
+      // @ts-expect-error - Too complex union type
+      return callbacks[callbackName](options, serviceOperation.schema, args);
     },
     []
   ) as never;
-};
+}
+
+function assertValidCallbackName<
+  TCallbacks extends Record<string, (...rest: any[]) => unknown>,
+>(
+  callbackName: string | number | symbol,
+  callbacks: TCallbacks
+): asserts callbackName is keyof TCallbacks {
+  if (!(callbackName in callbacks)) {
+    if ((callbackName as OperationInvokeFnName) === 'operationInvokeFn')
+      throw new Error(
+        `Callback 'operationInvokeFn' is required for executing 'qraft.<service>.<operation>()', but it is not provided in the 'callbacks' object.`
+      );
+    throw new Error(
+      `Callback for 'qraft.<service>.<operation>.${String(callbackName)}()' is not provided in the 'callbacks' object.`
+    );
+  }
+}
 
 /**
  * Extracts Callback details from the applyPath
@@ -55,10 +135,7 @@ function extractCallbackDetails(applyPath: string[]) {
   if (applyPath.length === 2) {
     return {
       path: applyPath,
-      callbackName: 'operationInvokeFn' satisfies Extract<
-        keyof typeof operationInvokeModule,
-        'operationInvokeFn'
-      >,
+      callbackName: 'operationInvokeFn' satisfies OperationInvokeFnName,
     };
   } else {
     // <service>.<operation>.<method>()
@@ -83,18 +160,146 @@ function getByPath(obj: Record<string, unknown>, path: string[]) {
   }, obj);
 }
 
-type ServicesBaseDeclaration<Services> = {
+type Callbacks = Partial<typeof callbacks>;
+
+type ServicesDeclaration<Services> = {
   [service in keyof Services]: {
-    [method in keyof Services[service]]: { schema: OperationSchema };
+    [method in keyof Services[service]]: {
+      schema: OperationSchema;
+      types: {
+        parameters?: any;
+        data?: any;
+        error?: any;
+        body?: any;
+      };
+    };
   };
 };
 
-type ServicesDeclaration<Services extends ServicesBaseDeclaration<Services>> = {
-  [service in keyof Services]: {
-    [method in keyof Services[service]]: {
-      schema: Services[service][method]['schema'];
+type ServiceSchemasDeclaration<Services extends ServicesDeclaration<Services>> =
+  {
+    [service in keyof Services]: {
+      [method in keyof Services[service]]: {
+        schema: Services[service][method]['schema'];
+      };
     };
   };
+
+type QueryOperationCallbacks = Extract<
+  keyof Callbacks,
+  | 'cancelQueries'
+  | 'fetchInfiniteQuery'
+  | 'fetchQuery'
+  | 'getInfiniteQueryData'
+  | 'getInfiniteQueryKey'
+  | 'getInfiniteQueryState'
+  | 'getQueriesData'
+  | 'getQueryData'
+  | 'getQueryKey'
+  | 'getQueryState'
+  | 'invalidateQueries'
+  | 'isFetching'
+  | 'prefetchInfiniteQuery'
+  | 'prefetchQuery'
+  | 'refetchQueries'
+  | 'removeQueries'
+  | 'resetQueries'
+  | 'setInfiniteQueryData'
+  | 'setQueriesData'
+  | 'setQueryData'
+  | 'useInfiniteQuery'
+  | 'useIsFetching'
+  | 'useQueries'
+  | 'useQuery'
+  | 'useSuspenseInfiniteQuery'
+  | 'useSuspenseQueries'
+  | 'useSuspenseQuery'
+>;
+
+type MutationOperationCallbacks = Extract<
+  keyof Callbacks,
+  | 'getMutationKey'
+  | 'isMutating'
+  | 'useIsMutating'
+  | 'useMutation'
+  | 'useMutationState'
+>;
+
+export type APIQueryClientServices<
+  TServices extends ServicesDeclaration<TServices>,
+  TCallbacks extends Callbacks,
+> = ServicesFilteredByCallbacks<
+  TServices,
+  TCallbacks,
+  QueryOperationCallbacks,
+  MutationOperationCallbacks
+>;
+
+export type APIBasicClientServices<
+  TServices extends ServicesDeclaration<TServices>,
+  TCallbacks extends Callbacks,
+> = ServicesFilteredByCallbacks<
+  TServices,
+  TCallbacks,
+  Extract<QueryOperationCallbacks, 'getQueryKey'>,
+  Extract<MutationOperationCallbacks, 'getMutationKey'>
+>;
+
+type ServicesFilteredByCallbacks<
+  TServices extends ServicesDeclaration<TServices>,
+  TCallbacks extends Callbacks,
+  TQueryOperationCallbacks extends QueryOperationCallbacks,
+  TMutationOperationCallbacks extends MutationOperationCallbacks,
+> = {
+  [serviceName in keyof TServices]: {
+    [method in keyof TServices[serviceName]]: TServices[serviceName][method]['schema']['method'] extends
+      | 'get'
+      | 'head'
+      | 'options'
+      ? Pick<
+          ServiceOperationQuery<
+            TServices[serviceName][method]['schema'],
+            TServices[serviceName][method]['types']['data'],
+            TServices[serviceName][method]['types']['parameters'],
+            TServices[serviceName][method]['types']['error']
+          >,
+          | Extract<keyof TCallbacks, TQueryOperationCallbacks>
+          | 'types'
+          | 'schema'
+        > &
+          (OperationInvokeFnName extends keyof TCallbacks
+            ? ServiceOperationQueryFn<
+                TServices[serviceName][method]['schema'],
+                TServices[serviceName][method]['types']['data'],
+                TServices[serviceName][method]['types']['parameters'],
+                TServices[serviceName][method]['types']['error']
+              >
+            : {})
+      : Pick<
+          ServiceOperationMutation<
+            TServices[serviceName][method]['schema'],
+            TServices[serviceName][method]['types']['body'],
+            TServices[serviceName][method]['types']['data'],
+            TServices[serviceName][method]['types']['parameters'],
+            TServices[serviceName][method]['types']['error']
+          >,
+          | Extract<keyof TCallbacks, TMutationOperationCallbacks>
+          | 'types'
+          | 'schema'
+        > &
+          (OperationInvokeFnName extends keyof TCallbacks
+            ? ServiceOperationMutationFn<
+                TServices[serviceName][method]['schema'],
+                TServices[serviceName][method]['types']['body'],
+                TServices[serviceName][method]['types']['data'],
+                TServices[serviceName][method]['types']['parameters'],
+                TServices[serviceName][method]['types']['error']
+              >
+            : {});
+  };
 };
 
-type ServicesCallbacks = Record<string, (...rest: any[]) => unknown>;
+type OperationInvokeFnName = Extract<
+  keyof typeof operationInvokeModule,
+  'operationInvokeFn'
+>;