@openapi-qraft/react 1.1.4 → 1.2.0

package/src/lib/composeQueryFilters.ts

@@ -0,0 +1,44 @@
+import { composeQueryKey } from './composeQueryKey.js';
+import type { OperationRequestSchema } from './request.js';
+
+/**
+ * Replaces the `parameters` field in the filters with a `queryKey` field based on the schema.
+ * If no filters are provided, a `queryKey` will be composed schema's base query key.
+ * @param schema
+ * @param filters
+ */
+export function composeQueryFilters<Filters extends object>(
+  schema: OperationRequestSchema,
+  filters: Filters | undefined
+) {
+  if (!filters) {
+    return {
+      queryKey: composeQueryKey(schema, undefined),
+    };
+  }
+
+  if (filters && 'queryKey' in filters && 'parameters' in filters) {
+    throw new Error(
+      `'composeQueryFilters': 'queryKey' and 'parameters' cannot be used together`
+    );
+  }
+
+  if ('queryKey' in filters) {
+    return filters;
+  }
+
+  if ('parameters' in filters) {
+    const { parameters, ...filtersWithoutParameters } = filters;
+
+    Object.assign(filtersWithoutParameters, {
+      queryKey: composeQueryKey(schema, parameters),
+    });
+
+    return filtersWithoutParameters;
+  }
+
+  return {
+    ...filters,
+    queryKey: composeQueryKey(schema, undefined),
+  };
+}

package/src/lib/composeQueryKey.ts

@@ -1,7 +1,10 @@
-import type { RequestClientSchema } from '../RequestClient.js';
-import { ServiceOperationQueryKey } from '../ServiceOperation.js';
+import type { ServiceOperationQueryKey } from '../ServiceOperation.js';
+import type { OperationRequestSchema } from './request.js';
 
-export function composeQueryKey<TSchema extends RequestClientSchema, TParams>(
+export function composeQueryKey<
+  TSchema extends OperationRequestSchema,
+  TParams,
+>(
   schema: TSchema,
   parameters: TParams | undefined
 ): ServiceOperationQueryKey<TSchema, TParams> {

package/src/lib/request.ts

@@ -2,49 +2,65 @@
  * @throws {error: object|string, response: Response} if the request fails
  */
 export async function request<T>(
-  config: { baseUrl: string },
-  requestInit: APIRequestInit,
-  {
-    urlSerializer: urlSerializerFunc,
-    bodySerializer: bodySerializerFunc,
-  }: {
-    urlSerializer: typeof urlSerializer;
-    bodySerializer: typeof bodySerializer;
-  }
+  options: RequestOptions,
+  schema: OperationRequestSchema,
+  requestInfo: OperationRequestInfo
 ): Promise<T> {
-  const {
-    method,
-    url,
-    parameters,
-    mediaType,
-    headers,
-    body,
-    ...requestInitRest
-  } = requestInit;
-
-  const requestBody = bodySerializerFunc({
-    method,
-    mediaType,
-    body,
-  });
+  return baseRequest(
+    isRequiredRequestOptions(options)
+      ? options
+      : {
+          urlSerializer,
+          bodySerializer,
+          ...options,
+        },
+    schema,
+    requestInfo
+  );
+}
 
-  const response = await fetch(urlSerializerFunc(config, { url, parameters }), {
-    method: method.toUpperCase(),
-    body: requestBody,
-    headers: mergeHeaders(
-      {
-        Accept: 'application/json',
-        'Content-Type': 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
-    ),
-    ...requestInitRest,
-  });
+export interface RequestOptions {
+  baseUrl: string;
+  urlSerializer?: URLSerializer;
+  bodySerializer?: BodySerializer;
+}
+
+type URLSerializer = typeof urlSerializer;
+type BodySerializer = typeof bodySerializer;
+
+/**
+ * @throws {error: object|string, response: Response} if the request fails
+ */
+export async function baseRequest<T>(
+  options: Required<RequestOptions>,
+  schema: OperationRequestSchema,
+  requestInfo: OperationRequestInfo,
+  customFetch = fetch
+): Promise<T> {
+  const { parameters, headers, body, ...requestInfoRest } = requestInfo;
+
+  const requestBody = options.bodySerializer(schema, requestInfo);
+
+  const response = await customFetch(
+    options.urlSerializer(options.baseUrl, schema, requestInfo),
+    {
+      method: schema.method.toUpperCase(),
+      body: requestBody,
+      headers: mergeHeaders(
+        {
+          Accept: 'application/json',
+          'Content-Type': schema.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();
@@ -57,21 +73,25 @@ export async function request<T>(
 }
 
 export function urlSerializer(
-  config: { baseUrl: string },
-  { url, parameters }: Pick<APIRequestInit, 'url' | 'parameters'>
+  baseUrl: string,
+  schema: OperationRequestSchema,
+  info: OperationRequestInfo
 ): string {
-  const path = url.replace(/{(.*?)}/g, (substring: string, group: string) => {
-    if (parameters?.path?.hasOwnProperty(group)) {
-      return encodeURI(String(parameters?.path[group]));
+  const path = schema.url.replace(
+    /{(.*?)}/g,
+    (substring: string, group: string) => {
+      if (info.parameters?.path?.hasOwnProperty(group)) {
+        return encodeURI(String(info.parameters?.path[group]));
+      }
+      return substring;
     }
-    return substring;
-  });
+  );
 
-  if (parameters?.query) {
-    return `${config.baseUrl}${path}${getQueryString(parameters.query)}`;
+  if (info.parameters?.query) {
+    return `${baseUrl}${path}${getQueryString(info.parameters.query)}`;
   }
 
-  return `${config.baseUrl}${path}`;
+  return `${baseUrl}${path}`;
 }
 
 function getQueryString(params: Record<string, any>): string {
@@ -133,38 +153,37 @@ function mergeHeaders(...allHeaders: (HeadersOptions | undefined)[]) {
   return headers;
 }
 
-export function bodySerializer(options: {
-  method: APIRequestInit['method'];
-  mediaType: APIRequestInit['mediaType'];
-  body: APIRequestInit['body'];
-}) {
-  if (options.body === undefined) return;
+export function bodySerializer(
+  schema: OperationRequestSchema,
+  info: OperationRequestInfo
+) {
+  if (info.body === undefined) return;
 
   if (
-    options.method === 'get' ||
-    options.method === 'head' ||
-    options.method === 'options'
+    schema.method === 'get' ||
+    schema.method === 'head' ||
+    schema.method === 'options'
   )
     return;
 
-  if (options.mediaType?.includes('/form-data'))
-    return getRequestBodyFormData(options);
+  if (schema.mediaType?.includes('/form-data'))
+    return getRequestBodyFormData(info);
 
   if (
-    !options.mediaType?.includes('/json') &&
-    (typeof options.body === 'string' ||
-      options.body instanceof Blob ||
-      options.body instanceof FormData)
+    !schema.mediaType?.includes('/json') &&
+    (typeof info.body === 'string' ||
+      info.body instanceof Blob ||
+      info.body instanceof FormData)
   ) {
-    return options.body;
+    return info.body;
   }
 
-  return JSON.stringify(options.body);
+  return JSON.stringify(info.body);
 }
 
 function getRequestBodyFormData({
   body,
-}: Pick<APIRequestInit, 'body'>): FormData | undefined {
+}: Pick<OperationRequestInfo, 'body'>): FormData | undefined {
   if (body instanceof FormData) return body;
   if (body === null) return;
 
@@ -203,7 +222,7 @@ function getRequestBodyFormData({
   return formData;
 }
 
-function getBodyContentType(body: APIRequestInit['body']) {
+function getBodyContentType(body: OperationRequestInfo['body']) {
   if (!body) return;
   if (body instanceof Blob) return body.type || 'application/octet-stream';
   if (typeof body === 'string') return 'text/plain';
@@ -242,12 +261,27 @@ async function getResponseBody<T>(response: Response): Promise<T | undefined> {
   return response.text() as Promise<T>;
 }
 
+function isRequiredRequestOptions<T extends RequestOptions>(
+  options: RequestOptions
+): options is Required<RequestOptions> {
+  return Boolean(options.urlSerializer && options.bodySerializer);
+}
+
 // To have definitely typed headers without a conversion to stings
 export type HeadersOptions =
   | HeadersInit
   | Record<string, string | number | boolean | null | undefined>;
 
-export type APIRequestInit = {
+export interface OperationRequestSchema {
+  /**
+   * Operation path
+   * @example /user/{id}
+   */
+  readonly url: string;
+
+  /**
+   * Operation method
+   */
   readonly method:
     | 'get'
     | 'put'
@@ -257,14 +291,42 @@ export type APIRequestInit = {
     | 'options'
     | 'head'
     | 'trace';
-  readonly url: string;
+
+  /**
+   * Media type of the request body
+   * @example application/json
+   */
+  readonly mediaType?: string;
+}
+
+export interface OperationRequestInfo
+  extends Omit<RequestInit, 'headers' | 'method' | 'body'> {
+  /**
+   * OpenAPI parameters
+   * @example
+   * ```ts
+   * { path: {id: 1}, query: {search: 'hello'} }
+   * ```
+   */
   readonly parameters?: {
     readonly path?: Record<string, any>;
     readonly cookie?: Record<string, any>;
     readonly header?: Record<string, any>;
     readonly query?: Record<string, any>;
   };
+  /**
+   * Request body
+   * @example { name: 'John' }
+   */
   readonly body?: BodyInit | Record<string, unknown> | null;
-  readonly mediaType?: string;
+  /**
+   * Request headers
+   * @example { 'X-Auth': '123' }
+   */
   readonly headers?: HeadersOptions;
-} & Omit<RequestInit, 'headers' | 'method' | 'body'>;
+
+  /**
+   * Tanstack Query Meta
+   */
+  meta?: Record<string, unknown>;
+}

package/src/lib/useQueryClient.ts

@@ -0,0 +1,26 @@
+'use client';
+
+import { useContext } from 'react';
+
+import {
+  QueryClient,
+  useQueryClient as useQueryClientTanstack,
+} from '@tanstack/react-query';
+
+import type { QraftClientOptions } from '../qraftAPIClient.js';
+import { QraftContext } from '../QraftContext.js';
+
+/**
+ * Get the QueryClient from the QraftContext or the provided QueryClient argument.
+ * @param qraftOptions if `queryClient` is not provided, will be taken from context
+ * @param queryClient If not provided, will be taken this instance
+ */
+export function useQueryClient(
+  qraftOptions: QraftClientOptions | undefined,
+  queryClient: QueryClient | undefined
+) {
+  const queryClientByContext = useContext(qraftOptions?.context ?? QraftContext)
+    ?.queryClient;
+
+  return useQueryClientTanstack(queryClient ?? queryClientByContext);
+}

package/src/qraftAPIClient.ts

@@ -1,12 +1,12 @@
-import { Context } from 'react';
+import type { Context } from 'react';
 
 import { createRecursiveProxy } from './lib/createRecursiveProxy.js';
-import { QraftContextValue } from './QraftContext.js';
-import type { RequestClientSchema } from './RequestClient.js';
+import type { OperationRequestSchema } from './lib/request.js';
+import type { QraftContextValue } from './QraftContext.js';
 
-export type QraftClientOptions = {
+export interface QraftClientOptions {
   context?: Context<QraftContextValue>;
-};
+}
 
 export const qraftAPIClient = <
   Services extends ServicesOutput<Services>,
@@ -50,7 +50,7 @@ export const qraftAPIClient = <
 
 function isServiceOperation(
   input: unknown
-): input is { schema: RequestClientSchema } {
+): input is { schema: OperationRequestSchema } {
   return input !== null && typeof input === 'object' && 'schema' in input;
 }
 
@@ -63,7 +63,7 @@ function getByPath(obj: Record<string, unknown>, path: string[]) {
 
 type ServicesOutput<Services> = {
   [service in keyof Services]: {
-    [method in keyof Services[service]]: { schema: RequestClientSchema };
+    [method in keyof Services[service]]: { schema: OperationRequestSchema };
   };
 };
 
@@ -82,7 +82,7 @@ type ServicesCallbacksFilter<
   Callbacks,
 > = Services extends {
   [serviceName in keyof Services]: {
-    [method in keyof Services[serviceName]]: { schema: RequestClientSchema };
+    [method in keyof Services[serviceName]]: { schema: OperationRequestSchema };
   };
 }
   ? {