@openapi-qraft/tanstack-query-react-types 2.0.0-next.8

package/src/shared/FetchInfiniteQueryOptions.ts

@@ -0,0 +1,109 @@
+import type {
+  DefaultError,
+  FetchQueryOptions,
+  GetNextPageParamFunction,
+  InitialPageParam,
+  QueryFunction,
+} from '@tanstack/query-core';
+import type { OperationInfiniteData } from './OperationInfiniteData.js';
+import type { PartialParameters } from './PartialParameters.js';
+import type {
+  ServiceOperationInfiniteQueryKey,
+  ServiceOperationQueryKey,
+} from './ServiceOperationKey.js';
+import { RequestFn } from './RequestFn.js';
+
+type FetchInfiniteQueryPages<TQueryFnData = unknown, TPageParam = unknown> =
+  | {
+      pages?: never;
+    }
+  | {
+      pages: number;
+      getNextPageParam: GetNextPageParamFunction<
+        PartialParameters<TPageParam>,
+        TQueryFnData
+      >;
+    };
+
+type FetchInfiniteQueryOptionsBase<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams = {},
+  TPageParam = unknown,
+  TError = DefaultError,
+> = Omit<
+  FetchQueryOptions<
+    TQueryFnData,
+    TError,
+    OperationInfiniteData<TQueryFnData, TParams>,
+    ServiceOperationQueryKey<TSchema, TParams>,
+    TPageParam
+  >,
+  'queryKey'
+> &
+  InitialPageParam<PartialParameters<TPageParam>> &
+  FetchInfiniteQueryPages<TQueryFnData, TPageParam>;
+
+export type FetchInfiniteQueryOptionsByQueryKey<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams = {},
+  TPageParam = {},
+  TError = DefaultError,
+> = FetchInfiniteQueryOptionsBase<
+  TSchema,
+  TQueryFnData,
+  TParams,
+  TPageParam,
+  TError
+> & {
+  /**
+   * Fetch Queries by query key
+   */
+  queryKey?: ServiceOperationInfiniteQueryKey<TSchema, TParams>;
+  parameters?: never;
+};
+export type FetchInfiniteQueryOptionsByParameters<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams = {},
+  TPageParam = {},
+  TError = DefaultError,
+> = FetchInfiniteQueryOptionsBase<
+  TSchema,
+  TQueryFnData,
+  TParams,
+  TPageParam,
+  TError
+> & {
+  /**
+   * Fetch Queries by parameters
+   */
+  parameters?: TParams;
+  queryKey?: never;
+};
+
+export type FetchInfiniteQueryOptionsQueryFn<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams,
+  TError,
+> =
+  | {
+      queryFn: QueryFunction<
+        TQueryFnData,
+        ServiceOperationInfiniteQueryKey<TSchema, TParams>
+      >;
+    }
+  | {
+      /**
+       * Custom request function to use for the query
+       */
+      requestFn?: RequestFn<TQueryFnData, TError>;
+      /**
+       * Base URL to use for the request (used in the `queryFn`)
+       * @example 'https://api.example.com'
+       */
+      baseUrl?: string | undefined;
+      queryFn?: never; // Workaround to fix union type error
+    };

package/src/shared/InvalidateQueryFilters.ts

@@ -0,0 +1,19 @@
+import type { DefaultError } from '@tanstack/query-core';
+import type {
+  QueryFiltersByParameters,
+  QueryFiltersByQueryKey,
+  QueryTypeFilter,
+} from './QueryFilters.js';
+
+export type InvalidateQueryFilters<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TInfinite extends boolean,
+  TParams = {},
+  TError = DefaultError,
+> = (
+  | QueryFiltersByParameters<TSchema, TQueryFnData, TInfinite, TParams, TError>
+  | QueryFiltersByQueryKey<TSchema, TQueryFnData, TInfinite, TParams, TError>
+) & {
+  refetchType?: QueryTypeFilter | 'none';
+};

package/src/shared/MutationFilters.ts

@@ -0,0 +1,93 @@
+import type {
+  DefaultError,
+  Mutation,
+  MutationStatus,
+} from '@tanstack/query-core';
+import type { UseMutationOptions } from '@tanstack/react-query';
+import type { AreAllOptional } from './AreAllOptional.js';
+import type { PartialParameters } from './PartialParameters.js';
+import type { ServiceOperationMutationKey } from './ServiceOperationKey.js';
+
+interface UseMutationStateFiltersBase<
+  TBody,
+  TData,
+  TParams,
+  TError = DefaultError,
+  TContext = unknown,
+> {
+  /**
+   * Match mutation key exactly
+   */
+  exact?: boolean;
+  /**
+   * Include mutations matching this predicate function
+   */
+  predicate?: (
+    mutation: Mutation<
+      TData,
+      TError,
+      MutationVariables<TBody, TParams>,
+      TContext
+    >
+  ) => boolean;
+
+  /**
+   * Filter by mutation status
+   */
+  status?: MutationStatus;
+}
+
+export interface MutationFiltersByParameters<
+  TBody,
+  TData,
+  TParams,
+  TError = DefaultError,
+  TContext = unknown,
+> extends UseMutationStateFiltersBase<TBody, TData, TParams, TError, TContext> {
+  /**
+   * Include mutations matching these parameters
+   */
+  parameters?: PartialParameters<TParams>;
+  mutationKey?: never;
+}
+
+export interface MutationFiltersByMutationKey<
+  TSchema extends { url: string; method: string },
+  TBody,
+  TData,
+  TParams,
+  TError = DefaultError,
+  TContext = unknown,
+> extends UseMutationStateFiltersBase<TBody, TData, TParams, TError, TContext> {
+  /**
+   * Include mutations matching this mutation key
+   */
+  mutationKey?: ServiceOperationMutationKey<
+    TSchema,
+    PartialParameters<TParams>
+  >;
+  parameters?: never;
+}
+
+export type MutationVariables<TBody, TParams> =
+  AreAllOptional<TBody> extends true
+    ? AreAllOptional<TParams> extends true
+      ? ({ body?: TBody } & NonNullableObject<TParams>) | void
+      : { body?: TBody } & TParams
+    : { body: TBody } & NonNullableObject<TParams>;
+
+type NonNullableObject<T> = NonNullable<T> extends never ? {} : T;
+
+export type ServiceOperationUseMutationOptions<
+  TSchema extends { url: string; method: string },
+  TData,
+  TParams,
+  TVariables,
+  TError,
+  TContext = unknown,
+> = Omit<
+  UseMutationOptions<TData, TError, TVariables, TContext>,
+  'mutationKey'
+> & {
+  mutationKey?: ServiceOperationMutationKey<TSchema, TParams>;
+};

package/src/shared/OperationInfiniteData.ts

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

package/src/shared/PartialParameters.ts

@@ -0,0 +1,12 @@
+/**
+ * Shallow partial 'parameters'.
+ * @example
+ * ```ts
+ * {query?: {page: number, nested: {still: 'not_partial'}}}
+ * // =>
+ * {query?: {page?: number, nested?: {still: 'not_partial'}}}
+ * ```
+ */
+export type PartialParameters<T> = T extends object
+  ? { [K in keyof T]?: T[K] extends object ? Partial<T[K]> : T[K] }
+  : T;

package/src/shared/QueryFilters.ts

@@ -0,0 +1,226 @@
+import type { DefaultError, FetchStatus, Query } from '@tanstack/query-core';
+import type { OperationInfiniteData } from './OperationInfiniteData.js';
+import type { PartialParameters } from './PartialParameters.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/shared/RequestFn.ts

@@ -0,0 +1,121 @@
+export interface RequestFn<TData, TError> {
+  (
+    schema: OperationSchema,
+    requestInfo: RequestFnInfo,
+    options?: RequestFnOptions
+  ): Promise<RequestFnResponse<TData, TError>>;
+}
+
+export interface OperationSchema {
+  /**
+   * Operation path
+   * @example /user/{id}
+   */
+  readonly url: string; //todo::rename to `path`
+
+  /**
+   * Operation method
+   */
+  readonly method:
+    | 'get'
+    | 'put'
+    | 'post'
+    | 'patch'
+    | 'delete'
+    | 'options'
+    | 'head'
+    | 'trace';
+
+  /**
+   * Media type of the request body
+   * @example application/json
+   */
+  readonly mediaType?: string;
+
+  readonly security?: string[];
+}
+
+export interface RequestFnInfo
+  extends RequestFnPayload,
+    Omit<RequestInit, 'headers' | 'method' | 'body' | 'signal'> {
+  /**
+   * Request headers
+   * @example { 'X-Auth': '123' }
+   */
+  readonly headers?: HeadersOptions;
+}
+
+export interface RequestFnPayload {
+  /**
+   * Base URL to use for the request
+   * @example 'https://api.example.com'
+   */
+  baseUrl?: string;
+
+  /**
+   * OpenAPI parameters
+   * @example
+   * ```ts
+   * { path: {id: 1}, query: {search: 'hello'} }
+   * ```
+   */
+  readonly parameters?: {
+    readonly path?: 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;
+
+  /**
+   * Tanstack Query Meta
+   */
+  meta?: Record<string, unknown>;
+
+  /** An AbortSignal to set request's signal. */
+  signal?: AbortSignal | null;
+}
+
+export type RequestFnResponse<TData, TError> =
+  | {
+      data: TData;
+      response: Response;
+      error?: undefined;
+    }
+  | {
+      // server error
+      data?: undefined;
+      response: Response;
+      error: TError | Error;
+    }
+  | {
+      // network error
+      data?: undefined;
+      response?: undefined;
+      error: Error;
+    };
+
+export interface RequestFnOptions {
+  urlSerializer?: UrlSerializer;
+  bodySerializer?: BodySerializer;
+  fetch?: typeof fetch;
+}
+
+type BodySerializer = (
+  schema: OperationSchema,
+  info: RequestFnPayload
+) => string | FormData | Blob | undefined;
+
+type UrlSerializer = (
+  schema: OperationSchema,
+  info: RequestFnPayload
+) => string;
+
+// To have definitely typed headers without a conversion to stings
+export type HeadersOptions =
+  | HeadersInit
+  | Record<string, string | number | boolean | null | undefined>;

package/src/shared/ServiceOperationFetchQueryOptions.ts

@@ -0,0 +1,84 @@
+import type { RequestFn } from '@openapi-qraft/tanstack-query-react-types';
+import type {
+  DefaultError,
+  FetchQueryOptions,
+  QueryFunction,
+} from '@tanstack/query-core';
+import type { ServiceOperationQueryKey } from './ServiceOperationKey.js';
+
+export type ServiceOperationFetchQueryOptions<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams,
+  TError,
+> =
+  | (FetchQueryOptionsByQueryKey<TSchema, TQueryFnData, TParams, TError> &
+      FetchQueryOptionsQueryFn<TSchema, TQueryFnData, TParams, TError>)
+  | (FetchQueryOptionsByParameters<TSchema, TQueryFnData, TParams, TError> &
+      FetchQueryOptionsQueryFn<TSchema, TQueryFnData, TParams, TError>);
+
+type FetchQueryOptionsBase<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams = {},
+  TError = DefaultError,
+> = Omit<
+  FetchQueryOptions<
+    TQueryFnData,
+    TError,
+    TQueryFnData,
+    ServiceOperationQueryKey<TSchema, TParams>
+  >,
+  'queryKey' | 'queryFn'
+>;
+
+interface FetchQueryOptionsByQueryKey<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams = {},
+  TError = DefaultError,
+> extends FetchQueryOptionsBase<TSchema, TQueryFnData, TParams, TError> {
+  /**
+   * Fetch Queries by query key
+   */
+  queryKey: ServiceOperationQueryKey<TSchema, TParams>;
+  parameters?: never;
+}
+
+interface FetchQueryOptionsByParameters<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams = {},
+  TError = DefaultError,
+> extends FetchQueryOptionsBase<TSchema, TQueryFnData, TParams, TError> {
+  /**
+   * Fetch Queries by parameters
+   */
+  parameters: TParams;
+  queryKey?: never;
+}
+
+type FetchQueryOptionsQueryFn<
+  TSchema extends { url: string; method: string },
+  TQueryFnData,
+  TParams,
+  TError,
+> =
+  | {
+      queryFn: QueryFunction<
+        TQueryFnData,
+        ServiceOperationQueryKey<TSchema, TParams>
+      >;
+    }
+  | {
+      /**
+       * Custom request function to use for the query
+       */
+      requestFn?: RequestFn<TQueryFnData, TError>;
+      /**
+       * Base URL to use for the request (used in the `queryFn`)
+       * @example 'https://api.example.com'
+       */
+      baseUrl?: string | undefined;
+      queryFn?: never; // Workaround to fix union type error
+    };

package/src/shared/ServiceOperationKey.ts

@@ -0,0 +1,20 @@
+export type ServiceOperationBaseQueryKey<
+  S extends { url: string; method: string },
+  Infinite extends boolean,
+  T,
+> = [S & { infinite: Infinite }, T];
+
+export type ServiceOperationQueryKey<
+  S extends { url: string; method: string },
+  T,
+> = ServiceOperationBaseQueryKey<S, false, T>;
+
+export type ServiceOperationInfiniteQueryKey<
+  S extends { url: string; method: string },
+  T,
+> = ServiceOperationBaseQueryKey<S, true, T>;
+
+export type ServiceOperationMutationKey<
+  S extends Record<'url' | 'method', string>,
+  T,
+> = NonNullable<T> extends never ? [S] : [S, T];