@openapi-qraft/react 2.15.0-beta.3 → 2.15.0-beta.5

package/src/qraftAPIClient.ts

@@ -36,32 +36,6 @@ export type CreateAPIClientOptions =
   | CreateAPIBasicQueryClientOptions
   | CreateAPIQueryClientOptions;
 
-/**
- * Creates a QueryClient compatible API Client which contains all operations
- * such as `useQuery`, `useMutation`.
- *
- * @example Fetching data with QueryClient
- * ```ts
- * const api = qraftAPIClient(services, callbacks, {
- *   requestFn: requestFn,
- *   baseUrl: 'https://api.example.com',
- *   queryClient: new QueryClient(),
- * });
- *
- * api.service.operation({
- *   parameters: { path: { id: 1 } },
- * });
- * ```
- */
-export function qraftAPIClient<
-  Services extends UnionServiceOperationsDeclaration<Services>,
-  Callbacks extends ServiceMethods,
->(
-  services: Services,
-  callbacks: Callbacks,
-  options: CreateAPIQueryClientOptions
-): APIDefaultQueryClientServices<Services>;
-
 /**
  * Creates a QueryClient compatible API Client which contains all operations
  * such as `useQuery`, `useMutation`.
@@ -389,7 +363,7 @@ export type UnionServiceOperationsDeclaration<Services> =
   | OperationsDeclaration<Services>
   | OperationDeclaration;
 
-type QueryOperationHookCallbacks = Extract<
+export type QueryOperationHookCallbacks = Extract<
   keyof ServiceMethods,
   | 'useInfiniteQuery'
   | 'useQueries'
@@ -436,7 +410,7 @@ type QueryOperationStateCallbacks =
     >
   | QueryOperationStateHookCallbacks;
 
-type MutationOperationHookCallbacks = Extract<
+export type MutationOperationHookCallbacks = Extract<
   keyof ServiceMethods,
   'useMutation'
 >;
@@ -447,7 +421,7 @@ type MutationOperationStateHookCallbacks = Extract<
 >;
 
 type MutationOperationStateCallbacks =
-  | Extract<keyof ServiceMethods, 'isMutating'>
+  | Extract<keyof ServiceMethods, 'getMutationCache' | 'isMutating'>
   | MutationOperationStateHookCallbacks;
 
 type InvokeOperationCallback = Extract<
@@ -455,7 +429,7 @@ type InvokeOperationCallback = Extract<
   'operationInvokeFn'
 >;
 
-type UtilityOperationCallbacks = Extract<
+export type UtilityOperationCallbacks = Extract<
   keyof ServiceMethods,
   | 'getQueryKey'
   | 'getInfiniteQueryKey'
@@ -533,7 +507,7 @@ export type APIUtilityClientServices<
   Extract<keyof Callbacks, UtilityOperationCallbacks>
 >;
 
-type ServicesFilteredByCallbacks<
+export type ServicesFilteredByCallbacks<
   Services extends UnionServiceOperationsDeclaration<Services>,
   CallbackList extends OperationCallbackList,
 > = Services extends OperationDeclaration

package/src/qraftReactAPIClient.ts

@@ -0,0 +1,273 @@
+'use client';
+
+import type { Context } from 'react';
+import type * as callbacks from './callbacks/index.js';
+import type { OperationSchema } from './lib/requestFn.js';
+import type {
+  APIBasicClientServices,
+  APIBasicQueryClientServices,
+  APIDefaultQueryClientServices,
+  APIQueryClientServices,
+  APIUtilityClientServices,
+  CreateAPIBasicClientOptions,
+  CreateAPIBasicQueryClientOptions,
+  CreateAPIClientOptions,
+  CreateAPIQueryClientOptions,
+  MutationOperationHookCallbacks,
+  QueryOperationHookCallbacks,
+  ServicesFilteredByCallbacks,
+  UnionServiceOperationsDeclaration,
+  UtilityOperationCallbacks,
+} from './qraftAPIClient.js';
+import { useContext } from 'react';
+import { qraftAPIClient } from './qraftAPIClient.js';
+
+type ServiceMethods = typeof callbacks;
+
+type PartialServiceMethods = Partial<ServiceMethods>;
+
+/**
+ * Creates a QueryClient compatible API Client which contains all operations
+ * such as `useQuery`, `useMutation` with React Context support.
+ *
+ * @example Fetching data with QueryClient
+ * ```ts
+ * const api = qraftReactAPIClient(services, callbacks, {
+ *   requestFn: requestFn,
+ *   baseUrl: 'https://api.example.com',
+ *   queryClient: new QueryClient(),
+ * });
+ *
+ * api.service.operation({
+ *   parameters: { path: { id: 1 } },
+ * });
+ * ```
+ */
+export function qraftReactAPIClient<
+  Services extends UnionServiceOperationsDeclaration<Services>,
+  Callbacks extends ServiceMethods,
+>(
+  services: Services,
+  callbacks: Callbacks,
+  options:
+    | CreateAPIQueryClientOptions
+    | Context<CreateAPIQueryClientOptions | undefined>
+): APIDefaultQueryClientServices<Services>;
+
+/**
+ * It creates a QueryClient-compatible API client that contains all the hooks
+ * (useQuery, useMutation) and utilities for non-context operations,
+ * such as `getQueryKey`.
+ *
+ * @example Fetching data with QueryClient from React Context
+ * ```ts
+ * const api = qraftReactAPIClient(services, callbacks, context);
+ *
+ * api.service.operation.useQuery({
+ *   parameters: { path: { id: 1 } },
+ * });
+ * ```
+ */
+export function qraftReactAPIClient<
+  Services extends UnionServiceOperationsDeclaration<Services>,
+  Callbacks extends PartialServiceMethods,
+>(
+  services: Services,
+  callbacks: Callbacks,
+  options: Context<CreateAPIQueryClientOptions | undefined>
+): APIContextQueryClientServices<Services, Callbacks>;
+
+/**
+ * Creates a QueryClient compatible API Client which contains all operations
+ * such as `useQuery`, `useMutation`.
+ *
+ * @example Fetching data with QueryClient
+ * ```ts
+ * const api = qraftReactAPIClient(services, callbacks, {
+ *   requestFn: requestFn,
+ *   baseUrl: 'https://api.example.com',
+ *   queryClient: new QueryClient(),
+ * });
+ *
+ * api.service.operation({
+ *   parameters: { path: { id: 1 } },
+ * });
+ * ```
+ */
+export function qraftReactAPIClient<
+  Services extends UnionServiceOperationsDeclaration<Services>,
+  Callbacks extends PartialServiceMethods,
+>(
+  services: Services,
+  callbacks: Callbacks,
+  options: CreateAPIQueryClientOptions
+): APIQueryClientServices<Services, Callbacks>;
+
+/**
+ * Creates a QueryClient compatible API Client which contains
+ * only state management manipulations such as `useIsMutating`,
+ * `setQueryData`, `getQueryData` and `invalidateQueries`.
+ *
+ * @example Invalidating queries with QueryClient
+ * ```ts
+ * const api = qraftReactAPIClient(services, callbacks, {
+ *   // an instance of QueryClient shared between all clients
+ *   queryClient: sharedQueryClient
+ * });
+ *
+ * api.service.operation.invalidateQueries({
+ *   parameters: { path: { id: 1 } },
+ * });
+ */
+export function qraftReactAPIClient<
+  Services extends UnionServiceOperationsDeclaration<Services>,
+  Callbacks extends PartialServiceMethods,
+>(
+  services: Services,
+  callbacks: Callbacks,
+  options: CreateAPIBasicQueryClientOptions
+): APIBasicQueryClientServices<Services, Callbacks>;
+
+/**
+ * Creates a basic API Client which contains all hooks and methods
+ * that don't require an explicitly provided QueryClient.
+ * Hooks like `useQuery` and `useMutation` will automatically retrieve
+ * the QueryClient from the `<QueryClientProvider />` context.
+ *
+ * @example Fetching data with QueryClient from context
+ * ```ts
+ * const api = qraftReactAPIClient(services, callbacks, {
+ *   requestFn: requestFn,
+ *   baseUrl: 'https://api.example.com',
+ * });
+ *
+ * // QueryClient will be retrieved from React context
+ * api.service.operation.useQuery({
+ *   parameters: { path: { id: 1 } },
+ * });
+ * ```
+ *
+ * @example Fetching data without QueryClient
+ * ```ts
+ * const api = qraftReactAPIClient(services, callbacks, {
+ *   requestFn: requestFn,
+ *   baseUrl: 'https://api.example.com',
+ * });
+ *
+ * api.service.operation({
+ *   parameters: { path: { id: 1 } },
+ * });
+ * ```
+ */
+export function qraftReactAPIClient<
+  Services extends UnionServiceOperationsDeclaration<Services>,
+  Callbacks extends PartialServiceMethods,
+>(
+  services: Services,
+  callbacks: Callbacks,
+  options: CreateAPIBasicClientOptions
+): APIBasicClientServices<Services, Callbacks>;
+
+/**
+ * Creates a utility API Client which contains utility operations
+ * such as `getQueryKey`, `getInfiniteQueryKey`, `getMutationKey` and state hooks
+ * like `useIsFetching` and `useMutationData`.
+ *
+ * @example Using state hooks
+ * ```ts
+ * const api = qraftReactAPIClient(services, callbacks);
+ *
+ * // Check if any query is currently fetching
+ * const isFetching = api.service.operation.useIsFetching();
+ * ```
+ *
+ * @example Getting query keys with utility client
+ * ```ts
+ * const api = qraftReactAPIClient(services, callbacks);
+ *
+ * api.service.operation.getQueryKey({
+ *   parameters: { path: { id: 1 } },
+ * });
+ * ```
+ */
+export function qraftReactAPIClient<
+  Services extends UnionServiceOperationsDeclaration<Services>,
+  Callbacks extends Pick<PartialServiceMethods, UtilityOperationCallbacks>,
+>(
+  services: Services,
+  callbacks: Callbacks
+): APIUtilityClientServices<Services, Callbacks>;
+
+export function qraftReactAPIClient<
+  Services extends UnionServiceOperationsDeclaration<Services>,
+  Callbacks extends PartialServiceMethods,
+>(
+  services: Services,
+  callbacks: Callbacks,
+  options?:
+    | CreateAPIClientOptions
+    | Context<CreateAPIQueryClientOptions | undefined>
+):
+  | APIQueryClientServices<Services, Callbacks>
+  | APIDefaultQueryClientServices<Services>
+  | APIBasicQueryClientServices<Services, Callbacks>
+  | APIUtilityClientServices<Services, Callbacks>
+  | APIContextQueryClientServices<Services, Callbacks> {
+  if (options && 'Provider' in options && 'Consumer' in options) {
+    const wrappedCallbacks = wrapHookCallbacks(callbacks, options);
+    return qraftAPIClient(services, wrappedCallbacks) as never;
+  }
+
+  return qraftAPIClient(services, callbacks, options as never) as never;
+}
+
+function wrapHookCallbacks<Callbacks extends PartialServiceMethods>(
+  callbacks: Callbacks,
+  context: Context<CreateAPIQueryClientOptions | undefined>
+): Callbacks {
+  return Object.fromEntries(
+    Object.entries(callbacks).map(([callbackName, callback]) => {
+      if (!callbackName.startsWith('use')) return [callbackName, callback];
+
+      return [
+        callbackName,
+        wrapHookCallbackWithUseContext(context, callback as never),
+      ];
+    })
+  ) as Callbacks;
+}
+
+function wrapHookCallbackWithUseContext(
+  context: Context<CreateAPIQueryClientOptions | undefined>,
+  callback: (
+    options: CreateAPIClientOptions,
+    schema: OperationSchema,
+    args: unknown[]
+  ) => any
+) {
+  function useCallbackContext(
+    _options: CreateAPIQueryClientOptions | undefined,
+    schema: OperationSchema,
+    args: unknown[]
+  ) {
+    const options = useContext(context);
+    if (!options) throw new Error('No API Client context found');
+
+    return callback(options, schema, args);
+  }
+
+  return useCallbackContext;
+}
+
+export type APIContextQueryClientServices<
+  Services extends UnionServiceOperationsDeclaration<Services>,
+  Callbacks extends PartialServiceMethods,
+> = ServicesFilteredByCallbacks<
+  Services,
+  Extract<keyof Callbacks, HookOperationCallbackList>
+>;
+
+type HookOperationCallbackList =
+  | UtilityOperationCallbacks
+  | QueryOperationHookCallbacks
+  | MutationOperationHookCallbacks;