@openapi-qraft/react 1.7.0 → 1.8.0

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>;
 }