@openapi-qraft/react 1.6.0 → 1.8.0

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

@@ -7,7 +7,7 @@ import type { UseQueryOptions } from '@tanstack/react-query';
 
 import type { QraftClientOptions } from '../qraftAPIClient.js';
 import { QraftContext } from '../QraftContext.js';
-import type { ServiceOperationQueryKey } from '../ServiceOperation.js';
+import type { ServiceOperationQueryKey } from '../service-operation/ServiceOperationKey.js';
 import { composeInfiniteQueryKey } from './composeInfiniteQueryKey.js';
 import { composeQueryKey } from './composeQueryKey.js';
 import type { OperationSchema } from './requestFn.js';
@@ -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/OperationInfiniteData.ts

@@ -0,0 +1,8 @@
+import type { InfiniteData } from '@tanstack/query-core';
+
+import type { PartialParameters } from '../lib/PartialParameters.type.js';
+
+export type OperationInfiniteData<TData, TParams> = InfiniteData<
+  TData,
+  PartialParameters<TParams>
+>;

package/src/service-operation/QueryFilters.ts

@@ -0,0 +1,227 @@
+import type { DefaultError, FetchStatus, Query } from '@tanstack/query-core';
+
+import type { PartialParameters } from '../lib/PartialParameters.type.js';
+import type { OperationInfiniteData } from './OperationInfiniteData.js';
+import type {
+  ServiceOperationBaseQueryKey,
+  ServiceOperationInfiniteQueryKey,
+  ServiceOperationQueryKey,
+} from './ServiceOperationKey.js';
+
+export type QueryTypeFilter = 'all' | 'active' | 'inactive';
+
+interface QueryFiltersBase<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> {
+  /**
+   * Include queries matching this predicate function
+   */
+  predicate?: TInfinite extends true
+    ? QueryFilterInfinitePredicate<TSchema, TData, TParams, TError>
+    : TInfinite extends false
+      ? QueryFilterRegularPredicate<TSchema, TData, TParams, TError>
+      : (query: string) => boolean;
+
+  /**
+   * Filter to active queries, inactive queries or all queries
+   */
+  type?: QueryTypeFilter;
+
+  /**
+   * Include or exclude stale queries
+   */
+  stale?: boolean;
+
+  /**
+   * Include queries matching their fetchStatus
+   */
+  fetchStatus?: FetchStatus;
+}
+
+interface QueryFiltersByQueryKeyBase<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> extends QueryFiltersBase<TSchema, TData, TInfinite, TParams, TError> {
+  infinite?: never;
+  parameters?: never;
+}
+
+interface QueryFiltersByExactQueryKey<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> extends QueryFiltersByQueryKeyBase<
+    TSchema,
+    TData,
+    TInfinite,
+    TParams,
+    TError
+  > {
+  /**
+   * Include queries matching this query key
+   */
+  queryKey: ServiceOperationBaseQueryKey<TSchema, TInfinite, TParams>;
+
+  /**
+   * Match query key exactly
+   */
+  exact: true;
+}
+
+interface QueryFiltersWeakExactQueryKey<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> extends QueryFiltersByQueryKeyBase<
+    TSchema,
+    TData,
+    TInfinite,
+    TParams,
+    TError
+  > {
+  /**
+   * Include queries matching this query key
+   */
+  queryKey?: ServiceOperationBaseQueryKey<
+    TSchema,
+    TInfinite,
+    PartialParameters<TParams>
+  >;
+
+  /**
+   * Match query key exactly
+   */
+  exact?: false;
+}
+
+export type QueryFiltersByQueryKey<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> =
+  | QueryFiltersByExactQueryKey<TSchema, TData, TInfinite, TParams, TError>
+  | QueryFiltersWeakExactQueryKey<TSchema, TData, TInfinite, TParams, TError>;
+
+interface QueryFiltersByParametersBase<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> extends QueryFiltersBase<TSchema, TData, TInfinite, TParams, TError> {
+  /**
+   * Is the query infinite
+   */
+  infinite?: TInfinite;
+
+  queryKey?: never;
+}
+
+interface QueryFiltersByExactParameters<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> extends QueryFiltersByParametersBase<
+    TSchema,
+    TData,
+    TInfinite,
+    TParams,
+    TError
+  > {
+  /**
+   * Match query key exactly
+   */
+  exact: true;
+
+  /**
+   * Include queries matching parameters
+   */
+  parameters: TParams;
+}
+
+interface QueryFiltersByWeakParameters<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> extends QueryFiltersByParametersBase<
+    TSchema,
+    TData,
+    TInfinite,
+    TParams,
+    TError
+  > {
+  /**
+   * Match query key exactly
+   */
+  exact?: false;
+
+  /**
+   * Include queries matching parameters
+   */
+  parameters?: PartialParameters<TParams>;
+}
+
+export type QueryFiltersByParameters<
+  TSchema extends { url: string; method: string },
+  TData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> =
+  | QueryFiltersByExactParameters<TSchema, TData, TInfinite, TParams, TError>
+  | QueryFiltersByWeakParameters<TSchema, TData, TInfinite, TParams, TError>;
+
+interface QueryFilterInfinitePredicate<
+  TSchema extends { url: string; method: string },
+  TData,
+  TParams = {},
+  TError = DefaultError,
+> {
+  /**
+   * Include queries matching this predicate function
+   */
+  (
+    query: Query<
+      OperationInfiniteData<TData, TParams>,
+      TError,
+      OperationInfiniteData<TData, TParams>,
+      ServiceOperationInfiniteQueryKey<TSchema, TParams>
+    >
+  ): boolean;
+}
+
+interface QueryFilterRegularPredicate<
+  TSchema extends { url: string; method: string },
+  TData,
+  TParams = {},
+  TError = DefaultError,
+> {
+  /**
+   * Include queries matching this predicate function
+   */
+  (
+    query: Query<
+      TData,
+      TError,
+      TData,
+      ServiceOperationQueryKey<TSchema, TParams>
+    >
+  ): boolean;
+}

package/src/service-operation/ServiceOperation.ts

@@ -0,0 +1,86 @@
+import type { DefaultError } from '@tanstack/query-core';
+
+import type { ServiceOperationCancelQueries } from './ServiceOperationCancelQueries.js';
+import type { ServiceOperationFetchInfiniteQuery } from './ServiceOperationFetchInfiniteQuery.js';
+import type { ServiceOperationFetchQuery } from './ServiceOperationFetchQuery.js';
+import type { ServiceOperationGetInfiniteQueryData } from './ServiceOperationGetInfiniteQueryData.js';
+import type { ServiceOperationGetQueriesData } from './ServiceOperationGetQueriesData.js';
+import type { ServiceOperationGetQueryData } from './ServiceOperationGetQueryData.js';
+import type { ServiceOperationGetQueryState } from './ServiceOperationGetQueryState.js';
+import type { ServiceOperationInvalidateQueries } from './ServiceOperationInvalidateQueries.js';
+import type { ServiceOperationIsFetchingQueries } from './ServiceOperationIsFetchingQueries.js';
+import type { ServiceOperationIsMutatingQueries } from './ServiceOperationIsMutatingQueries.js';
+import type { ServiceOperationMutationFn } from './ServiceOperationMutationFn.js';
+import type { ServiceOperationQueryFn } from './ServiceOperationQueryFn.js';
+import type { ServiceOperationRefetchQueries } from './ServiceOperationRefetchQueries.js';
+import type { ServiceOperationRemoveQueries } from './ServiceOperationRemoveQueries.js';
+import type { ServiceOperationResetQueries } from './ServiceOperationResetQueries.js';
+import type { ServiceOperationSetInfiniteQueryData } from './ServiceOperationSetInfiniteQueryData.js';
+import type { ServiceOperationSetQueriesData } from './ServiceOperationSetQueriesData.js';
+import type { ServiceOperationSetQueryData } from './ServiceOperationSetQueryData.js';
+import type { ServiceOperationUseInfiniteQuery } from './ServiceOperationUseInfiniteQuery.js';
+import type { ServiceOperationUseIsFetchingQueries } from './ServiceOperationUseIsFetchingQueries.js';
+import type { ServiceOperationUseIsMutating } from './ServiceOperationUseIsMutating.js';
+import type { ServiceOperationUseMutation } from './ServiceOperationUseMutation.js';
+import type { ServiceOperationUseMutationState } from './ServiceOperationUseMutationState.js';
+import type { ServiceOperationUseQueries } from './ServiceOperationUseQueries.js';
+import type { ServiceOperationUseQuery } from './ServiceOperationUseQuery.js';
+import type { ServiceOperationUseSuspenseInfiniteQuery } from './ServiceOperationUseSuspenseInfiniteQuery.js';
+import type { ServiceOperationUseSuspenseQueries } from './ServiceOperationUseSuspenseQueries.js';
+import type { ServiceOperationUseSuspenseQueryQuery } from './ServiceOperationUseSuspenseQueryQuery.js';
+
+export interface ServiceOperationQuery<
+  TSchema extends { url: string; method: string },
+  TData,
+  TParams,
+  TError = DefaultError,
+> extends ServiceOperationUseQuery<TSchema, TData, TParams, TError>,
+    ServiceOperationUseQueries<TSchema, TData, TParams, TError>,
+    ServiceOperationUseSuspenseQueries<TSchema, TData, TParams, TError>,
+    ServiceOperationUseInfiniteQuery<TSchema, TData, TParams, TError>,
+    ServiceOperationUseSuspenseQueryQuery<TSchema, TData, TParams, TError>,
+    ServiceOperationUseSuspenseInfiniteQuery<TSchema, TData, TParams, TError>,
+    ServiceOperationUseIsFetchingQueries<TSchema, TData, TParams, TError>,
+    ServiceOperationQueryFn<TSchema, TData, TParams>,
+    ServiceOperationFetchQuery<TSchema, TData, TParams, TError>,
+    ServiceOperationFetchInfiniteQuery<TSchema, TData, TParams, TError>,
+    ServiceOperationGetQueryData<TSchema, TData, TParams>,
+    ServiceOperationGetQueryState<TSchema, TData, TParams, TError>,
+    ServiceOperationGetQueriesData<TSchema, TData, TParams, TError>,
+    ServiceOperationGetInfiniteQueryData<TSchema, TData, TParams>,
+    ServiceOperationSetQueryData<TSchema, TData, TParams>,
+    ServiceOperationSetQueriesData<TSchema, TData, TParams, TError>,
+    ServiceOperationSetInfiniteQueryData<TSchema, TData, TParams>,
+    ServiceOperationInvalidateQueries<TSchema, TData, TParams, TError>,
+    ServiceOperationCancelQueries<TSchema, TData, TParams, TError>,
+    ServiceOperationRemoveQueries<TSchema, TData, TParams, TError>,
+    ServiceOperationResetQueries<TSchema, TData, TParams, TError>,
+    ServiceOperationRefetchQueries<TSchema, TData, TParams, TError>,
+    ServiceOperationIsFetchingQueries<TSchema, TData, TParams, TError> {
+  schema: TSchema;
+  types: {
+    parameters: TParams;
+    data: TData;
+    error: TError;
+  };
+}
+
+export interface ServiceOperationMutation<
+  TSchema extends { url: string; method: string },
+  TBody,
+  TData,
+  TParams,
+  TError = DefaultError,
+> extends ServiceOperationUseMutation<TSchema, TBody, TData, TParams, TError>,
+    ServiceOperationUseIsMutating<TSchema, TBody, TData, TParams, TError>,
+    ServiceOperationUseMutationState<TSchema, TBody, TData, TParams, TError>,
+    ServiceOperationIsMutatingQueries<TSchema, TBody, TData, TParams, TError>,
+    ServiceOperationMutationFn<TSchema, TBody, TData, TParams> {
+  schema: TSchema;
+  types: {
+    parameters: TParams;
+    data: TData;
+    error: TError;
+    body: TBody;
+  };
+}

package/src/service-operation/ServiceOperationCancelQueries.ts

@@ -0,0 +1,53 @@
+import type {
+  CancelOptions,
+  DefaultError,
+  QueryClient,
+} from '@tanstack/query-core';
+
+import type {
+  QueryFiltersByParameters,
+  QueryFiltersByQueryKey,
+} from './QueryFilters.js';
+
+export interface ServiceOperationCancelQueries<
+  TSchema extends { url: string; method: string },
+  TData,
+  TParams = {},
+  TError = DefaultError,
+> {
+  cancelQueries<TInfinite extends boolean>(
+    filters:
+      | QueryFiltersByParameters<TSchema, TData, TInfinite, TParams, TError>
+      | QueryFiltersByQueryKey<TSchema, TData, TInfinite, TParams, TError>,
+    options: CancelOptions,
+    queryClient: QueryClient
+  ): Promise<void>;
+
+  cancelQueries<TInfinite extends boolean>(
+    filters:
+      | QueryFiltersByParameters<TSchema, TData, TInfinite, TParams, TError>
+      | QueryFiltersByQueryKey<TSchema, TData, TInfinite, TParams, TError>,
+    queryClient: QueryClient
+  ): Promise<void>;
+
+  cancelQueries(queryClient: QueryClient): Promise<void>;
+}
+
+/**
+ * @internal
+ */
+export interface ServiceOperationCancelQueriesCallback<
+  TSchema extends { url: string; method: string },
+  TData,
+  TParams = {},
+  TError = DefaultError,
+> extends ServiceOperationCancelQueries<TSchema, TData, TParams, TError> {
+  cancelQueries<TInfinite extends boolean>(
+    filters:
+      | QueryFiltersByParameters<TSchema, TData, TInfinite, TParams, TError>
+      | QueryFiltersByQueryKey<TSchema, TData, TInfinite, TParams, TError>
+      | QueryClient,
+    options?: CancelOptions | QueryClient,
+    queryClient?: QueryClient
+  ): Promise<void>;
+}