@openapi-qraft/react 1.7.0 → 1.9.0

package/src/callbacks/useQueries.ts

@@ -40,7 +40,7 @@ export const useQueries: (
                   },
                   queryOptions
                 );
-                // @ts-expect-error
+                // @ts-expect-error - `parameters` is not inferred as a property of `queryOptionsCopy`
                 delete queryOptionsCopy.parameters;
                 return queryOptionsCopy;
               })()

package/src/callbacks/useQuery.ts

@@ -19,7 +19,7 @@ export const useQuery: <TData = unknown, TError = DefaultError>(
   >
 ) => UseQueryResult<TData, TError> = (qraftOptions, schema, args) => {
   return useQueryTanstack(
-    // @ts-expect-error
+    // @ts-expect-error - Too complex to type
     ...useComposeUseQueryOptions(qraftOptions, schema, args, false)
   ) as never;
 };

package/src/callbacks/useSuspenseInfiniteQuery.ts

@@ -31,7 +31,7 @@ export const useSuspenseInfiniteQuery: <
   args
 ) => {
   return useSuspenseInfiniteQueryTanstack(
-    // @ts-expect-error
+    // @ts-expect-error - Too complex to type
     ...useComposeUseQueryOptions(qraftOptions, schema, args, true)
   ) as never;
 };

package/src/callbacks/useSuspenseQueries.ts

@@ -44,7 +44,7 @@ export const useSuspenseQueries: (
                   },
                   queryOptions
                 );
-                // @ts-expect-error
+                // @ts-expect-error - `parameters` is not inferred as a property of `queryOptionsCopy`
                 delete queryOptionsCopy.parameters;
                 return queryOptionsCopy;
               })()

package/src/callbacks/useSuspenseQuery.ts

@@ -23,7 +23,7 @@ export const useSuspenseQuery: <
   >
 ) => UseQueryResult<TData, TError> = (qraftOptions, schema, args) => {
   return useSuspenseQueryTanstack(
-    // @ts-expect-error
+    // @ts-expect-error - Too complex to type
     ...useComposeUseQueryOptions(qraftOptions, schema, args, false)
   ) as never;
 };

package/src/lib/callQueryClientFetchMethod.ts

@@ -40,7 +40,7 @@ export function callQueryClientMethodWithQueryKey<
   const queryFn =
     options.queryFn ??
     (requestFn
-      ? // @ts-expect-error
+      ? // @ts-expect-error - Not inferring the correct type for `queryFn`
         function ({ queryKey: [, queryParams], signal, meta, pageParam }) {
           return requestFn(schema, {
             parameters: infinite
@@ -54,7 +54,7 @@ export function callQueryClientMethodWithQueryKey<
       : undefined);
 
   if (parameters) {
-    // @ts-expect-error
+    // @ts-expect-error - Too complex union to type
     return queryClient[queryFilterMethod]({
       ...options,
       // Event if queryFn is undefined, it will override the default queryFn from `setQueryDefaults(...)`
@@ -65,7 +65,7 @@ export function callQueryClientMethodWithQueryKey<
     });
   }
 
-  // @ts-expect-error
+  // @ts-expect-error - Too complex union to type
   return queryClient[queryFilterMethod]({ ...options, queryFn });
 }
 

package/src/lib/callQueryClientMethodWithMutationFilters.ts

@@ -23,10 +23,10 @@ export function callQueryClientMethodWithMutationFilters<
       `queryClient is invalid, ${queryFilterMethod} method does not exist`
     );
 
-  // @ts-expect-error
+  // @ts-expect-error - Too complex to type
   return queryClient[queryFilterMethod](
     composeMutationFilters(schema, filters as never),
-    // @ts-expect-error
+    // @ts-expect-error - Argument types are too complex
     ...args.slice(1, -1)
   );
 }

package/src/lib/callQueryClientMethodWithQueryFilters.ts

@@ -23,10 +23,10 @@ export function callQueryClientMethodWithQueryFilters<
       `queryClient is invalid, ${queryFilterMethod} method does not exist`
     );
 
-  // @ts-expect-error
+  // @ts-expect-error - Too complex to type
   return queryClient[queryFilterMethod](
     composeQueryFilters(schema, filters as never),
-    // @ts-expect-error
+    // @ts-expect-error - Argument types are too complex
     ...args.slice(1, -1)
   );
 }

package/src/lib/callQueryClientMethodWithQueryKey.ts

@@ -31,7 +31,7 @@ export function callQueryClientMethodWithQueryKey<
       ? composeInfiniteQueryKey(schema, parameters)
       : composeQueryKey(schema, parameters);
 
-  // @ts-expect-error
+  // @ts-expect-error - Too complex to type
   return queryClient[queryFilterMethod](queryKey, ...args.slice(1, -1));
 }
 

package/src/lib/composeMutationKey.ts

@@ -5,10 +5,7 @@ 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 OperationSchema,
-  TParams = undefined,
->(
+export function composeMutationKey<TSchema extends OperationSchema>(
   schema: TSchema,
   parameters: undefined
 ): ServiceOperationMutationKey<TSchema, undefined>;
@@ -36,10 +33,11 @@ export function omitMutationPayload<T>(params: T) {
     throw new Error('`params` must be object');
 
   if ('body' in params || 'requestBody' in params) {
-    const { body, requestBody, ...paramsRest } = params as Record<
-      'body' | 'requestBody',
-      unknown
-    >;
+    const {
+      body: _,
+      requestBody: __,
+      ...paramsRest
+    } = params as Record<'body' | 'requestBody', unknown>;
     return paramsRest;
   }
 

package/src/lib/createRecursiveProxy.ts

@@ -5,6 +5,13 @@ type ProxyApplyCallback = (path: string[], args: unknown[]) => unknown;
  */
 type ProxyGetCallback = (path: string[], key: string) => unknown | undefined;
 
+// todo::rename to `qraftRecursiveProxy` with deprecated `createRecursiveProxy`
+/**
+ * Creates a recursive proxy that calls the `getCallback` and `applyCallback` functions
+ * @param getCallback The callback to call when a proxy property is accessed
+ * @param applyCallback The callback to call when a proxy is called as a function
+ * @param path The current path of the proxy
+ */
 export function createRecursiveProxy(
   getCallback: ProxyGetCallback,
   applyCallback: ProxyApplyCallback,

package/src/lib/requestFn.ts

@@ -1,5 +1,15 @@
 /**
- * @throws {error: object|string, response: Response} if the request fails
+ * This function is used to make a request to a specified endpoint.
+ *
+ * @template T The expected return type of the request.
+ *
+ * @param schema The schema of the operation to be performed. It includes the OpenAPI path, HTTP method and media type.
+ * @param requestInfo The information required to make the request. It includes parameters, headers, body, etc.
+ * @param [options] Optional. Additional options for the request. It includes custom urlSerializer, bodySerializer, and fetch function.
+ *
+ * @returns {Promise<T>} Returns a promise that resolves with the response of the request.
+ *
+ * @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>(
   schema: OperationSchema,
@@ -14,7 +24,20 @@ export async function requestFn<T>(
 }
 
 /**
- * @throws {error: object|string, response: Response} if the request fails
+ * This function is used to make a request to a specified endpoint.
+ * It's needed to create a custom `requestFn` with a custom `urlSerializer`
+ * and `bodySerializer`, with the tree-shaking of the default `requestFn`
+ * and its serializers.
+ *
+ * @template T The expected return type of the request.
+ *
+ * @param requestSchema The schema of the operation to be performed. It includes the OpenAPI path, HTTP method and media type.
+ * @param requestInfo The information required to make the request. It includes parameters, headers, body, etc.
+ * @param options The options for the request. It includes urlSerializer, bodySerializer, and fetch function. The 'urlSerializer' and 'bodySerializer' are required.
+ *
+ * @returns {Promise<T>} Returns a promise that resolves with the response of the request.
+ *
+ * @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>(
   requestSchema: OperationSchema,
@@ -65,7 +88,10 @@ export function urlSerializer(
   const path = schema.url.replace(
     /{(.*?)}/g,
     (substring: string, group: string) => {
-      if (info.parameters?.path?.hasOwnProperty(group)) {
+      if (
+        info.parameters?.path &&
+        Object.prototype.hasOwnProperty.call(info.parameters.path, group)
+      ) {
         return encodeURI(String(info.parameters?.path[group]));
       }
       return substring;
@@ -254,7 +280,7 @@ export interface OperationSchema {
    * Operation path
    * @example /user/{id}
    */
-  readonly url: string;
+  readonly url: string; //todo::rename to `path`
 
   /**
    * Operation method
@@ -279,6 +305,7 @@ export interface OperationSchema {
 export interface RequestFnPayload {
   /**
    * Base URL to use for the request
+   * @example 'https://api.example.com'
    */
   baseUrl: string | undefined;
 
@@ -291,7 +318,6 @@ export interface RequestFnPayload {
    */
   readonly parameters?: {
     readonly path?: Record<string, any>;
-    readonly cookie?: Record<string, any>;
     readonly header?: Record<string, any>;
     readonly query?: Record<string, any>;
   };

package/src/lib/useComposeUseQueryOptions.ts

@@ -32,10 +32,10 @@ export function useComposeUseQueryOptions(
 
   const queryFn =
     options?.queryFn ??
-    // @ts-expect-error
+    // @ts-expect-error - Too complex to type
     function ({ queryKey: [, queryParams], signal, meta, pageParam }) {
       return contextValue.requestFn(schema, {
-        // @ts-expect-error
+        // @ts-expect-error - Too complex to type
         parameters: infinite
           ? (shelfMerge(2, queryParams, pageParam) as never)
           : queryParams,

package/src/lib/useQueryClient.ts

@@ -19,8 +19,9 @@ export function useQueryClient(
   qraftOptions: QraftClientOptions | undefined,
   queryClient: QueryClient | undefined
 ) {
-  const queryClientByContext = useContext(qraftOptions?.context ?? QraftContext)
-    ?.queryClient;
+  const queryClientByContext = useContext(
+    qraftOptions?.context ?? QraftContext
+  )?.queryClient;
 
   return useQueryClientTanstack(queryClient ?? queryClientByContext);
 }

package/src/qraftAPIClient.ts

@@ -1,5 +1,6 @@
 import type { Context } from 'react';
 
+import type * as operationInvokeModule from './callbacks/operationInvokeFn.js';
 import { createRecursiveProxy } from './lib/createRecursiveProxy.js';
 import type { OperationSchema } from './lib/requestFn.js';
 import type { QraftContextValue } from './QraftContext.js';
@@ -9,36 +10,34 @@ export interface QraftClientOptions {
 }
 
 export const qraftAPIClient = <
-  Services extends ServicesOutput<Services>,
+  Services extends ServicesBaseDeclaration<Services>,
   Callbacks extends ServicesCallbacks,
 >(
   services: ServicesDeclaration<Services>,
   callbacks: Callbacks,
   options?: QraftClientOptions
-): ServicesCallbacksFilter<Services, keyof Callbacks> => {
+): Services => {
   return createRecursiveProxy(
-    (getPath, key) => {
-      if (getPath.length !== 2 || key !== 'schema') return;
+    function getCallback(getPath, key) {
+      if (getPath.length !== 2 || key !== 'schema') return; // todo::maybe return callback?
 
       const serviceOperation = getByPath(services, getPath);
       if (!isServiceOperation(serviceOperation))
         throw new Error(`Service operation not found: ${getPath.join('.')}`);
       return serviceOperation.schema;
     },
-    (applyPath, args) => {
-      const path = applyPath.slice(0, -1);
+    function applyCallback(applyPath, args) {
+      const { path, callbackName } = extractCallbackDetails(applyPath);
+
+      if (!(callbackName in callbacks))
+        throw new Error(`Function ${callbackName} is not supported`);
+
       const serviceOperation = getByPath(services, path);
 
       if (!isServiceOperation(serviceOperation))
         throw new Error(`Service operation not found: ${path.join('.')}`);
 
-      // The last arg is for instance `.useMutation` or `.useQuery()`
-      const functionName = applyPath[applyPath.length - 1];
-
-      if (!(functionName in callbacks))
-        throw new Error(`Function ${functionName} is not supported`);
-
-      return callbacks[functionName as keyof Callbacks](
+      return callbacks[callbackName as keyof Callbacks](
         options,
         serviceOperation.schema,
         args
@@ -48,6 +47,30 @@ export const qraftAPIClient = <
   ) as never;
 };
 
+/**
+ * Extracts Callback details from the applyPath
+ * @param applyPath
+ */
+function extractCallbackDetails(applyPath: string[]) {
+  // <service>.<operation>()
+  if (applyPath.length === 2) {
+    return {
+      path: applyPath,
+      callbackName: 'operationInvokeFn' satisfies Extract<
+        keyof typeof operationInvokeModule,
+        'operationInvokeFn'
+      >,
+    };
+  } else {
+    // <service>.<operation>.<method>()
+    return {
+      path: applyPath.slice(0, -1),
+      // The last arg is for instance `.useMutation` or `.useQuery()`
+      callbackName: applyPath[applyPath.length - 1],
+    };
+  }
+}
+
 function isServiceOperation(
   input: unknown
 ): input is { schema: OperationSchema } {
@@ -61,13 +84,13 @@ function getByPath(obj: Record<string, unknown>, path: string[]) {
   }, obj);
 }
 
-type ServicesOutput<Services> = {
+type ServicesBaseDeclaration<Services> = {
   [service in keyof Services]: {
     [method in keyof Services[service]]: { schema: OperationSchema };
   };
 };
 
-type ServicesDeclaration<Services extends ServicesOutput<Services>> = {
+type ServicesDeclaration<Services extends ServicesBaseDeclaration<Services>> = {
   [service in keyof Services]: {
     [method in keyof Services[service]]: {
       schema: Services[service][method]['schema'];
@@ -75,27 +98,4 @@ type ServicesDeclaration<Services extends ServicesOutput<Services>> = {
   };
 };
 
-type ServicesCallbacks = Record<string, (...rest: any[]) => any>;
-
-type ServicesCallbacksFilter<
-  Services extends ServicesOutput<Services>,
-  Callbacks,
-> = Services extends {
-  [serviceName in keyof Services]: {
-    [method in keyof Services[serviceName]]: { schema: OperationSchema };
-  };
-}
-  ? {
-      [serviceName in keyof Services]: {
-        [method in keyof Services[serviceName]]: Pick<
-          Services[serviceName][method],
-          FilterKeys<
-            keyof Services[serviceName][method],
-            Callbacks | 'schema' | 'types'
-          >
-        >;
-      };
-    }
-  : never;
-
-type FilterKeys<T, K> = K extends T ? K : never;
+type ServicesCallbacks = Record<string, (...rest: any[]) => unknown>;

package/src/service-operation/ServiceOperationKey.ts

@@ -16,5 +16,5 @@ export type ServiceOperationInfiniteQueryKey<
 
 export type ServiceOperationMutationKey<
   S extends Record<'url' | 'method', string>,
-  T extends unknown,
+  T,
 > = NonNullable<T> extends never ? [S] : [S, T];

package/src/service-operation/ServiceOperationMutationFn.ts

@@ -1,9 +1,34 @@
+interface QueryFnBaseUrlOptions {
+  /**
+   * Base URL to use for the request
+   * @example 'https://api.example.com'
+   */
+  baseUrl: string;
+}
+
+interface ServiceOperationMutationFnOptionsBase<TBody, TParams> {
+  parameters: TParams;
+  body: TBody;
+}
+
+interface ServiceOperationMutationFnOptions<TBody, TParams>
+  extends ServiceOperationMutationFnOptionsBase<TBody, TParams> {
+  baseUrl?: never;
+}
+
+interface ServiceOperationMutationFnOptionsWithBaseUrl<TBody, TParams>
+  extends ServiceOperationMutationFnOptionsBase<TBody, TParams>,
+    QueryFnBaseUrlOptions {}
+
 export interface ServiceOperationMutationFn<
   TSchema extends { url: string; method: string },
   TBody,
   TData,
   TParams,
 > {
+  /**
+   * @deprecated Use `<service>.<operation>(...)` instead.
+   */
   mutationFn(
     client: (
       schema: TSchema,
@@ -18,6 +43,9 @@ export interface ServiceOperationMutationFn<
     }
   ): TData;
 
+  /**
+   * @deprecated Use `<service>.<operation>(...)` instead.
+   */
   mutationFn(
     client: (
       schema: TSchema,
@@ -31,4 +59,34 @@ export interface ServiceOperationMutationFn<
       body: TBody;
     }
   ): Promise<TData>;
+
+  <TOptions extends ServiceOperationMutationFnOptions<TBody, TParams>>(
+    options: TOptions,
+    client: (schema: TSchema, options: TOptions) => TData
+  ): TData;
+
+  <
+    TOptions extends ServiceOperationMutationFnOptionsWithBaseUrl<
+      TBody,
+      TParams
+    >,
+  >(
+    options: TOptions,
+    client: (schema: TSchema, options: TOptions) => TData
+  ): TData;
+
+  <TOptions extends ServiceOperationMutationFnOptions<TBody, TParams>>(
+    options: TOptions,
+    client: (schema: TSchema, options: TOptions) => Promise<TData>
+  ): Promise<TData>;
+
+  <
+    TOptions extends ServiceOperationMutationFnOptionsWithBaseUrl<
+      TBody,
+      TParams
+    >,
+  >(
+    options: TOptions,
+    client: (schema: TSchema, options: TOptions) => Promise<TData>
+  ): Promise<TData>;
 }

package/src/service-operation/ServiceOperationQueryFn.ts

@@ -14,6 +14,19 @@ interface QueryFnOptionsByParameters<
   TSignal extends AbortSignal = AbortSignal,
 > extends QueryFnOptionsBase<TMeta, TSignal> {
   parameters: TParams;
+
+  queryKey?: never;
+  baseUrl?: never;
+}
+
+interface QueryFnOptionsByParametersWithBaseUrl<
+  TParams,
+  TMeta extends Record<string, any>,
+  TSignal extends AbortSignal = AbortSignal,
+> extends QueryFnOptionsBase<TMeta, TSignal>,
+    QueryFnBaseUrlOptions {
+  parameters: TParams;
+
   queryKey?: never;
 }
 
@@ -24,6 +37,29 @@ interface QueryFnOptionsByQueryKey<
   TSignal extends AbortSignal = AbortSignal,
 > extends QueryFnOptionsBase<TMeta, TSignal> {
   queryKey: ServiceOperationQueryKey<TSchema, TParams>;
+
+  parameters?: never;
+  baseUrl?: never;
+}
+
+interface QueryFnOptionsByQueryKeyWithBaseUrl<
+  TSchema extends { url: string; method: string },
+  TParams,
+  TMeta extends Record<string, any>,
+  TSignal extends AbortSignal = AbortSignal,
+> extends QueryFnOptionsBase<TMeta, TSignal>,
+    QueryFnBaseUrlOptions {
+  queryKey: ServiceOperationQueryKey<TSchema, TParams>;
+
+  parameters?: never;
+}
+
+interface QueryFnBaseUrlOptions {
+  /**
+   * Base URL to use for the request
+   * @example 'https://api.example.com'
+   */
+  baseUrl: string;
 }
 
 export interface ServiceOperationQueryFn<
@@ -31,6 +67,9 @@ export interface ServiceOperationQueryFn<
   TData,
   TParams,
 > {
+  /**
+   * @deprecated Use `<service>.<operation>(...)` instead.
+   */
   queryFn<
     TMeta extends Record<string, any>,
     TSignal extends AbortSignal = AbortSignal,
@@ -48,6 +87,9 @@ export interface ServiceOperationQueryFn<
     ) => TData
   ): TData;
 
+  /**
+   * @deprecated Use `<service>.<operation>(...)` instead.
+   */
   queryFn<
     TMeta extends Record<string, any>,
     TSignal extends AbortSignal = AbortSignal,
@@ -64,4 +106,72 @@ export interface ServiceOperationQueryFn<
       }
     ) => Promise<TData>
   ): Promise<TData>;
+
+  <
+    TMeta extends Record<string, any>,
+    TSignal extends AbortSignal = AbortSignal,
+  >(
+    options:
+      | QueryFnOptionsByParameters<TParams, TMeta, TSignal>
+      | QueryFnOptionsByQueryKey<TSchema, TParams, TMeta, TSignal>,
+    client: (
+      schema: TSchema,
+      options: {
+        parameters: TParams;
+        signal?: TSignal;
+        meta?: TMeta;
+      }
+    ) => TData
+  ): TData;
+
+  <
+    TMeta extends Record<string, any>,
+    TSignal extends AbortSignal = AbortSignal,
+  >(
+    options:
+      | QueryFnOptionsByParametersWithBaseUrl<TParams, TMeta, TSignal>
+      | QueryFnOptionsByQueryKeyWithBaseUrl<TSchema, TParams, TMeta, TSignal>,
+    client: (
+      schema: TSchema,
+      options: {
+        parameters: TParams;
+        signal?: TSignal;
+        meta?: TMeta;
+      } & QueryFnBaseUrlOptions
+    ) => TData
+  ): TData;
+
+  <
+    TMeta extends Record<string, any>,
+    TSignal extends AbortSignal = AbortSignal,
+  >(
+    options:
+      | QueryFnOptionsByParameters<TParams, TMeta, TSignal>
+      | QueryFnOptionsByQueryKey<TSchema, TParams, TMeta, TSignal>,
+    client: (
+      schema: TSchema,
+      options: {
+        parameters: TParams;
+        signal?: TSignal;
+        meta?: TMeta;
+      }
+    ) => Promise<TData>
+  ): Promise<TData>;
+
+  <
+    TMeta extends Record<string, any>,
+    TSignal extends AbortSignal = AbortSignal,
+  >(
+    options:
+      | QueryFnOptionsByParametersWithBaseUrl<TParams, TMeta, TSignal>
+      | QueryFnOptionsByQueryKeyWithBaseUrl<TSchema, TParams, TMeta, TSignal>,
+    client: (
+      schema: TSchema,
+      options: {
+        parameters: TParams;
+        signal?: TSignal;
+        meta?: TMeta;
+      } & QueryFnBaseUrlOptions
+    ) => Promise<TData>
+  ): Promise<TData>;
 }