@stack-spot/portal-network 0.1.0 → 0.2.0

package/src/network/ReactQueryNetworkClient.ts

@@ -2,24 +2,31 @@
 
 import { Defaults, HttpError, RequestOpts } from '@oazapfts/runtime'
 import { StackspotAPIError } from '../error/StackspotAPIError'
+import { AutoInfiniteQuery } from './AutoInfiniteQuery'
 import { AutoMutation } from './AutoMutation'
 import { AutoQuery } from './AutoQuery'
+import { ManualInfiniteQuery } from './ManualInfiniteQuery'
 import { ManualMutation } from './ManualMutation'
 import { ManualQuery } from './ManualQuery'
 import { NetworkClient } from './NetworkClient'
-import { Env, HTTPMethod, MutationObject, OperationConfig, OperationObject, QueryObject } from './types'
+import { Env, HTTPMethod, InfiniteQueryConfig, InfiniteQueryObject, InfiniteQueryOptions, MutationObject, OperationConfig, OperationObject, QueryObject } from './types'
 
 const DUMMY_ULID = '01HSTZ5471CBG4AW9BFJ0VTVG9'
 const PERMISSION_ERROR = 'permission-error'
+export const DEFAULT_PAGE_SIZE = 20
 
+/**
+ * A Network Client that uses oazapfts for making requests and React Query for managing responses.
+ */
 export abstract class ReactQueryNetworkClient extends NetworkClient {
+  /**
+   * @param baseURL An object with the keys "dev", "stg" and "prd". The values must be the url for each of these environments.
+   * @param defaults the `default` object of the API this client is for (provided by the code generated by oazapfts).
+   */
   constructor(baseURL: Record<Env, string>, defaults: Defaults<any>) {
     super(baseURL)
     defaults.baseUrl = ''
-    // eslint-disable-next-line arrow-body-style
-    defaults.fetch = (...args) => {
-      return this.#onFetch(...args)
-    }
+    defaults.fetch = (...args) => this.#onFetch(...args)
   }
 
   #getMappedHeaders(headers: HeadersInit | undefined) {
@@ -77,9 +84,13 @@ export abstract class ReactQueryNetworkClient extends NetworkClient {
     const [path, method, body, headers] = input instanceof Request
       ? [input.url, input.method as HTTPMethod, input.body, input.headers]
       : [`${input}`, (init?.method?.toLowerCase() || 'get') as HTTPMethod, init?.body, init?.headers]
-    return this[method](path, { body: body as any, headers: this.#getMappedHeaders(headers) })
+    return this[method](path, { body: body as any, headers: this.#getMappedHeaders(headers), signal: init?.signal })
   }
 
+  /**
+   * Receives an HttpError and returns a StackspotAPIError.
+   * @param error the original HttpError created by oazapfts.
+   */
   protected abstract buildStackSpotError(error: HttpError): StackspotAPIError
 
   async #onFetchPermission(input: string | URL | Request, init?: RequestInit | undefined): Promise<Response> {
@@ -97,15 +108,27 @@ export abstract class ReactQueryNetworkClient extends NetworkClient {
     }
   }
 
-  protected query<Args extends [opts?: RequestOpts] | [variables: Record<string, any>, opts?: RequestOpts], Result>(
-    fn: (...args: Args) => Promise<Result>
-  ): Args extends [variables: infer Variables, opts?: RequestOpts] ? QueryObject<Variables, Result> : QueryObject<void, Result>
+  /**
+   * Builds a query manually by using a configuration object. 
+   * @param config the configuration object containing the name, a request function and a permission function.
+   */
   protected query<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result>(
     config: OperationConfig<Args, Result>,
   ): QueryObject<Args extends [AbortSignal] ? void : Args[1], Result>
+  /**
+   * Builds a query manually by using a configuration object. 
+   * @param config the configuration object containing the name and a request function. 
+   */
   protected query<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result>(
     config: Omit<OperationConfig<Args, Result>, 'permission'>,
   ): Omit<QueryObject<Args extends [AbortSignal] ? void : Args[1], Result>, 'isAllowed' | 'useAllowed' | 'getPermissionKey'>
+  /**
+   * Builds a query automatically by using a function generated by oazapfts. 
+   * @param fn the oazapfts function.
+   */
+  protected query<Args extends [opts?: RequestOpts] | [variables: Record<string, any>, opts?: RequestOpts], Result>(
+    fn: (...args: Args) => Promise<Result>
+  ): Args extends [variables: infer Variables, opts?: RequestOpts] ? QueryObject<Variables, Result> : QueryObject<void, Result>
   protected query(fnOrConfig: any): QueryObject<any, any> {
     return typeof fnOrConfig === 'function'
       ? new AutoQuery(
@@ -124,15 +147,110 @@ export abstract class ReactQueryNetworkClient extends NetworkClient {
       })
   }
 
-  protected mutation<Args extends [opts?: RequestOpts] | [variables: Record<string, any>, opts?: RequestOpts], Result>(
-    fn: (...args: Args) => Promise<Result>,
-  ): Args extends [variables: infer Variables, opts?: RequestOpts] ? MutationObject<Variables, Result> : MutationObject<void, Result>
+  /**
+   * Builds a query manually by using a configuration object. 
+   * @param config the configuration object containing the name, a request function and a permission function.
+   */
+  protected infiniteQuery<
+    Variables extends Record<string, any>,
+    Result,
+    PageParamName extends keyof Variables,
+    Accumulator extends keyof Result | '',
+  >(config: InfiniteQueryConfig<Variables, Result, PageParamName, Accumulator>): InfiniteQueryObject<Variables, Result, Accumulator>
+  /**
+   * Builds a query manually by using a configuration object. 
+   * @param config the configuration object containing the name and a request function. 
+   */
+  protected infiniteQuery<
+    Variables extends Record<string, any>,
+    Result,
+    PageParamName extends keyof Variables,
+    Accumulator extends keyof Result | '',
+  >(
+    config: Omit<InfiniteQueryConfig<Variables, Result, PageParamName, Accumulator>, 'permission'>,
+  ): Omit<InfiniteQueryObject<Variables, Result, Accumulator>, 'isAllowed' | 'useAllowed' | 'getPermissionKey'>
+  /**
+   * Builds a query automatically by using a function generated by oazapfts with the variables `page` and `size`. 
+   * @param fn the oazapfts function that returns an array.
+   * @param options optional configuration for the infinite query. By default, it will use the variables page and size of the function
+   * passed in the first parameter.
+   */
+  protected infiniteQuery<
+    Variables extends { page?: number, size?: number },
+    Result extends any[],
+    PageParamName extends keyof Variables = 'page',
+    Accumulator extends keyof Result | '' = '',
+  >(
+    fn: (variables: Variables, opts?: RequestOpts) => Promise<Result>,
+    options?: Partial<InfiniteQueryOptions<Variables, Result, PageParamName, Accumulator>>,
+  ): InfiniteQueryObject<Variables, Result, Accumulator>
+  /**
+   * Builds a query automatically by using a function generated by oazapfts. 
+   * @param fn the oazapfts function.
+   * @param options the configuration for the infinite query.
+   */
+  protected infiniteQuery<
+    Variables extends Record<string, any>,
+    Result,
+    PageParamName extends keyof Variables,
+    Accumulator extends keyof Result,
+  >(
+    fn: (variables: Variables, opts?: RequestOpts) => Promise<Result>,
+    options: InfiniteQueryOptions<Variables, Result, PageParamName, Accumulator>,
+  ): InfiniteQueryObject<Variables, Result, Accumulator>
+  protected infiniteQuery(fnOrConfig: any, options?: InfiniteQueryOptions<any, any, any, any>): InfiniteQueryObject<any, any, any> {
+    return typeof fnOrConfig === 'function'
+      ? new AutoInfiniteQuery(
+        {
+          apiName: this.constructor.name,
+          fn: fnOrConfig,
+          onFetchPermission: (...args) => this.#onFetchPermission(...args),
+          transformError: error => this.#transformError(error),
+        },
+        {
+          accumulator: options?.accumulator ?? '',
+          pageParamName: options?.pageParamName ?? 'page',
+          initialPageParam: options?.initialPageParam ?? 1,
+          defaultVariables: options?.defaultVariables ?? { size: DEFAULT_PAGE_SIZE },
+          getNextPageParam: options?.getNextPageParam ?? (({ variables, lastPage, lastPageParam }) => {
+            const size = variables.size ?? 1
+            const isLastPageTheLast = lastPage && (
+              (Array.isArray(lastPage) && lastPage.length < size)
+              || (options?.accumulator !== undefined && options?.accumulator !== '' && lastPage[options?.accumulator]?.length < size)
+            )
+            return isLastPageTheLast ? undefined : lastPageParam + 1
+          }),
+        },
+      )
+      : new ManualInfiniteQuery({
+        ...fnOrConfig,
+        apiName: this.constructor.name,
+        request: this.#withErrorTreatment(fnOrConfig.request),
+        permission: fnOrConfig.permission ? this.#withErrorTreatment(fnOrConfig.permission) : undefined,
+      })
+  }
+
+  /**
+   * Builds a mutation manually by using a configuration object. 
+   * @param config the configuration object containing the name, a request function and a permission function.
+   */
   protected mutation<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result>(
     config: OperationConfig<Args, Result>,
   ): MutationObject<Args extends [AbortSignal] ? void : Args[1], Result>
+  /**
+   * Builds a mutation manually by using a configuration object. 
+   * @param config the configuration object containing the name and a request function. 
+   */
   protected mutation<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result>(
     config: Omit<OperationConfig<Args, Result>, 'permission'>,
   ): Omit<MutationObject<Args extends [AbortSignal] ? void : Args[1], Result>, keyof OperationObject<any>>
+  /**
+   * Builds a mutation automatically by using a function generated by oazapfts. 
+   * @param fn the oazapfts function.
+   */
+  protected mutation<Args extends [opts?: RequestOpts] | [variables: Record<string, any>, opts?: RequestOpts], Result>(
+    fn: (...args: Args) => Promise<Result>,
+  ): Args extends [variables: infer Variables, opts?: RequestOpts] ? MutationObject<Variables, Result> : MutationObject<void, Result>
   protected mutation(fnOrConfig: any): MutationObject<any, any> {
     if (typeof fnOrConfig === 'function') {
       return new AutoMutation(

package/src/network/react-query-client.ts

@@ -1,3 +1,6 @@
 import { QueryClient } from '@tanstack/react-query'
 
+/**
+ * The global, unique, Query Client for React Query.
+ */
 export const queryClient = new QueryClient({ defaultOptions: { queries: { refetchOnWindowFocus: false, retry: 3 } } })

package/src/network/types.ts

@@ -1,6 +1,6 @@
 import type { RequestOpts } from '@oazapfts/runtime'
 import { Session } from '@stack-spot/auth'
-import { MutateOptions, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query'
+import { InfiniteData, MutateOptions, UseInfiniteQueryOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query'
 import { StackspotAPIError } from '../error/StackspotAPIError'
 
 export interface SessionManager {
@@ -12,6 +12,7 @@ export interface SessionManager {
 export interface RequestOptions {
   params?: Record<string, string | undefined>,
   headers?: Record<string, string>,
+  signal?: AbortSignal | null,
 }
 
 export interface RequestWithBody extends RequestOptions {
@@ -23,44 +24,233 @@ export type Env = 'dev' | 'stg' | 'prd'
 export type HTTPMethod = 'post' | 'patch' | 'delete' | 'put' | 'get'
 
 export interface OperationConfig<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result> {
+  /**
+   * The operation name. To be used as key in React Query.
+   */
   name: string,
+  /**
+   * The function to run once the operation is called.
+   * @param abortSignal the AbortSignal to pass to any request made.
+   * @param variables if this operation accepts variables, the second parameter is the variables object.
+   * @returns the operation result (this should not be a Response object, but it could be its body).
+   */
   request: (...args: Args) => Promise<Result>,
+  /**
+   * The function to run once one asks if the operation is allowed.
+   * @param variables if this operation accepts variables, the single parameter is the variables object.
+   * @returns a promise that resolves to true if the operation is allowed and false otherwise.
+   */
   permission: (...args: Args extends [AbortSignal] ? [] : [Args[1]]) => Promise<boolean>,
 }
 
+
+export interface InfiniteQueryOptions<Variables, Result, PageParamName extends keyof Variables, Accumulator extends keyof Result | ''> {
+  /**
+   * The name of the variable that controls the current page.
+   */
+  pageParamName: PageParamName,
+  /**
+   * The name of the property in the Result that contains the items of a page. If the result itself is the array of items, use an empty
+   * string ('').
+   */
+  accumulator?: Accumulator,
+  /**
+   * The initial value for page variable.
+   */
+  initialPageParam: Variables[PageParamName],
+  /**
+   * Some defaults to be used when a variable is not specified.
+   */
+  defaultVariables?: Partial<Variables>,
+  /**
+   * A function that determines the value of the page variable in order to get the next page.
+   * @parar context the current context with the variables and page details.
+   * @returns undefined or null if there are no more pages. The next value for the page variable otherwise.
+   */
+  getNextPageParam: (context: {
+    /**
+     * the original set of variables passed to the hook `useInfiniteQuery`.
+     */
+    variables: Variables,
+    /**
+     * the last page Result.
+     */
+    lastPage: Result,
+    /**
+     * the Results of each page.
+     */
+    allPages: Result[],
+    /**
+     * the value of the page variable used to retrieve the last page.
+     */
+    lastPageParam: Variables[PageParamName],
+    /**
+     * the values of the page variable for requesting each of the pages.
+     */
+    allPageParams:  Variables[PageParamName][],
+  }) => Variables[PageParamName] | undefined | null,
+}
+
 export interface FullOperationConfig<
   Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result
 > extends OperationConfig<Args, Result>  {
+  /**
+   * The name of the API where this operation is called: used for composing a query key.
+   */
   apiName: string,
 }
 
+export type InfiniteQueryConfig<
+  Variables extends Record<string, any>,
+  Result,
+  PageParamName extends keyof Variables,
+  Accumulator extends keyof Result | '',
+> = OperationConfig<[AbortSignal, Variables], Result> & InfiniteQueryOptions<Variables, Result, PageParamName, Accumulator>
+
 export interface OperationObject<Variables> {
+  /**
+   * Checks if this operation is allowed for the user currently logged in.
+   * @param variables the variables for the operation, if a required url parameter is not provided, it's replaced by a default string.
+   * @returns a promise that resolves to true if the operation is allowed or false otherwise.
+   * @throws `StackspotAPIError`
+   */
   isAllowed: (...args: Variables extends void ? [] : [variables?: Partial<Variables>]) => Promise<boolean>,
+  /**
+   * Same as `isAllowed`, but a React Hook instead.
+   * @param args if this operation accepts variables, the first argument should be the variables and the second the query options
+   * (optional). If it doesn't accept variables, the single optional argument must be the query options. Moreover, if a required url
+   * parameter is not provided, it's replaced by a default string.
+   * @returns an array with 4 items:
+   * - [0]: true if allowed, false if not allowed, undefined if not fetched.
+   * - [1]: true if pending, false otherwise.
+   * - [2]: a StackspotAPIError if an error happens, null or undefined otherwise.
+   * - [3]: the original UseQueryResult object, from ReactQuery.
+   */
   useAllowed: (
     ...args: Variables extends void
       ? [options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
       : [variables?: Partial<Variables>, options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
   ) => Readonly<[boolean | undefined, boolean, StackspotAPIError | null | undefined, UseQueryResult<boolean, StackspotAPIError>]>,
+  /**
+   * Gets the key for the query used to verify if this operation is allowed.
+   * 
+   * Attention: invalidating this key won't clear the cache, since the `@stack-spot/opa` library doesn't support individual cache
+   * invalidation.
+   * @param args if this operation accepts variables, the first argument should be the variables and the second the query options
+   * (optional). If it doesn't accept variables, the single optional argument must be the query options. Moreover, if a required url
+   * parameter is not provided, it's replaced by a default string.
+   * @returns the query key.
+   */
   getPermissionKey: (...args: Variables extends void ? [] : [variables?: Partial<Variables>]) => any[],
+  /**
+   * Cancels the request if it hasn't finished yet.
+   * 
+   * A canceled request will fail by throwing a `CanceledError`.
+   * 
+   * @param variables the variables for the operation. If not provided, this will cancel all requests in progress for this operation.
+   * @returns true if any request has been canceled, false otherwise.
+   */
   cancel: (variables?: Partial<Variables>) => boolean,
 }
 
 export interface QueryObject<Variables, Result> extends OperationObject<Variables> {
+  /**
+   * Runs the query operation.
+   * @param variables the request variables if this query accepts variables. 
+   * @returns a Promise with the response data
+   * @throws `StackspotAPIError`
+   */
   query: (...args: Variables extends void ? [] : [variables: Variables]) => Promise<Result>,
+  /**
+   * Same as `query`, but, instead of an async function, this is a React Hook that expects a React Suspense environment.
+   * 
+   * If you want a hook that performs a stateful query instead of relying in Suspense, call `useStatefulQuery` instead.
+   * 
+   * @param args if this query accepts variables, the first argument should be the variables and the second the query options
+   * (optional). If it doesn't accept variables, the single optional argument must be the query options.
+   * @returns the response data or undefined if not fetched.
+   * @throws `StackspotAPIError`
+   * @throws `Promise<Result>`
+   */
   useQuery: (
     ...args: Variables extends void
       ? [options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
       : [variables: Variables, options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
   ) => Result | undefined,
+  /**
+   * Same as `query`, but a React Hook instead.
+   * @param args if this query accepts variables, the first argument should be the variables and the second the query options
+   * (optional). If it doesn't accept variables, the single optional argument must be the query options.
+   * @returns an array with 4 items:
+   * - [0]: the response data or undefined if not fetched.
+   * - [1]: true if pending, false otherwise.
+   * - [2]: a StackspotAPIError if an error happens, null or undefined otherwise.
+   * - [3]: the original UseQueryResult object, from ReactQuery.
+   */
   useStatefulQuery: (
     ...args: Variables extends void
       ? [options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
       : [variables: Variables, options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
   ) => Readonly<[Result | undefined, boolean, StackspotAPIError | null | undefined, UseQueryResult<Result, StackspotAPIError>]>,
+  /**
+   * Invalidates the cache for this query. A specific query can be invalidated by passing an argument (variables).
+   * @param variables if this query accepts variables, a query with specific variables can be invalidated.
+   * @returns a promise that resolves once the cache is invalidated.
+   */
   invalidate: (...args: Variables extends void ? [] : [variables?: Partial<Variables>]) => Promise<void>,
+  /**
+   * Gets the key for this query.
+   * @param variables the variables for the query. 
+   * @returns the query key.
+   */
   getKey: (...args: Variables extends void ? [] : [variables?: Partial<Variables>]) => any[],
 }
 
+export type UseInfiniteQueryObjectOptions = Omit<UseInfiniteQueryOptions, 'queryFn' | 'queryKey' | 'getNextPageParam' | 'initialPageParam'>
+
+export interface InfiniteQueryObject<Variables, Result, Accumulator extends keyof Result | ''> extends QueryObject<Variables, Result> {
+  /**
+   * Builds up a list with the result of multiple pages. This relies on React Suspense for error and first-loading feedbacks.
+   * 
+   * Equivalent to React Query's `useSuspenseInfiniteQuery`.
+   * @param variables the variables for the query.
+   * @param options the options for the query.
+   * @returns an array with 2 items:
+   * - [0]: the list of items.
+   * - [1]: the original UseInfiniteQueryResult object, from ReactQuery.
+   */
+  useInfiniteQuery: (
+    ...args: Partial<Variables> extends Variables
+      ? [variables?: Variables, options?: UseInfiniteQueryObjectOptions]
+      : [variables: Variables, options?: UseInfiniteQueryObjectOptions]
+  ) => Readonly<[
+    (Accumulator extends keyof Result ? Result[Accumulator] : Result) | undefined,
+    UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>,
+  ]>,
+  /**
+   * Builds up a list with the result of multiple pages.
+   * 
+   * Equivalent to React Query's `useInfiniteQuery`.
+   * @param variables the variables for the query.
+   * @param options the options for the query.
+   * @returns an array with 4 items:
+   * - [0]: the list of items.
+   * - [1]: true if fetching the first page, false otherwise.
+   * - [2]: a StackspotAPIError if an error happens, null or undefined otherwise.
+   * - [3]: the original UseInfiniteQueryResult object, from ReactQuery.
+   */
+  useStatefulInfiniteQuery: (
+    ...args: Partial<Variables> extends Variables
+      ? [variables?: Variables, options?: Omit<UseInfiniteQueryOptions, 'queryFn' | 'queryKey' | 'getNextPageParam' | 'initialPageParam'>]
+      : [variables: Variables, options?: Omit<UseInfiniteQueryOptions, 'queryFn' | 'queryKey' | 'getNextPageParam' | 'initialPageParam'>]
+  ) => Readonly<[
+    (Accumulator extends keyof Result ? Result[Accumulator] : Result) | undefined,
+    boolean,
+    StackspotAPIError | undefined | null,
+    UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>,
+  ]>,
+}
+
 export interface AutoQueryObjectParams<Variables, Result> {
   apiName: string,
   fn: ((variables: Variables, opts?: RequestOpts) => Promise<Result>) | ((opts?: RequestOpts) => Promise<Result>),
@@ -69,14 +259,30 @@ export interface AutoQueryObjectParams<Variables, Result> {
 }
 
 export interface MutationObject<Variables, Result> extends OperationObject<Variables> {
+  /**
+   * Runs the mutation and returns a promise.
+   * @param args the variables for the mutation.
+   * @returns a promise that resolves to the response's data.
+   */
   mutate: (...args: Variables extends void ? [] : [variables: Variables]) => Promise<Result>,
+  /**
+   * A React hook equivalent to React Query's `useMutation`. It creates a mutation function and the mutation states.
+   * @param options the options for `useMutation`
+   * @returns an array with 4 items:
+   * - [0]: the mutation function (equivalent to `mutateAsync` from the result of a `useMutation`).
+   * - [1]: true if pending, false otherwise.
+   * - [2]: a StackspotAPIError if an error happens, undefined otherwise.
+   * - [3]: the original UseMutationResult object, from ReactQuery.
+   * 
+   */
   useMutation: (options?: Omit<UseMutationOptions<Result, StackspotAPIError, Variables>, 'mutationFn'>) =>
     Readonly<[
       (...args: Variables extends void
         ? [options?:  MutateOptions<Result, StackspotAPIError>]
         : [variables: Variables, options?: MutateOptions<Result, StackspotAPIError, Variables>]
       ) => Promise<Result>,
-      boolean, StackspotAPIError | undefined,
+      boolean,
+      StackspotAPIError | undefined,
       UseMutationResult<Result, StackspotAPIError, Variables>,
     ]>,
 }

package/.generate-api.failed.json

@@ -1 +0,0 @@
-["apiManagement","content","dataPlatform"]