@ethlete/query 5.15.1 → 5.16.0

package/src/lib/infinite-query/infinity-query.ts

@@ -0,0 +1,245 @@
+import { BehaviorSubject, Observable, combineLatest, map, of, shareReplay, switchMap, tap } from 'rxjs';
+import { filterSuccess } from '../query';
+import { AnyQueryCreator, ConstructQuery, QueryArgsOf, QueryDataOf } from '../query-creator';
+import { InfinityQueryConfig, InfinityQueryParamLocation } from './infinity-query.types';
+
+export class InfinityQuery<
+  QueryCreator extends AnyQueryCreator,
+  Query extends ConstructQuery<QueryCreator>,
+  Args extends QueryArgsOf<QueryCreator>,
+  QueryResponse extends QueryDataOf<QueryCreator>,
+  InfinityResponse extends unknown[],
+> {
+  private readonly _queries$ = new BehaviorSubject<Query[]>([]);
+  private readonly _currentPage$ = new BehaviorSubject<number | null>(null);
+  private readonly _currentCalculatedPage$ = new BehaviorSubject<number | null>(null);
+  private readonly _totalPages$ = new BehaviorSubject<number | null>(null);
+  private readonly _itemsPerPage$ = new BehaviorSubject<number>(this._config.limitParam?.value ?? 10);
+
+  private readonly _data$ = this._queries$.pipe(
+    switchMap((queries) => {
+      if (!queries.length) {
+        return of([]);
+      }
+
+      return combineLatest(
+        queries.map((query) =>
+          query.state$.pipe(
+            filterSuccess(),
+            map((state) => ({ state, query })),
+          ),
+        ),
+      );
+    }),
+    tap((stateMaps) => {
+      const lastState = stateMaps[stateMaps.length - 1]?.state;
+      const lastQuery = stateMaps[stateMaps.length - 1]?.query;
+
+      if (!lastState || !lastQuery) {
+        return;
+      }
+
+      const totalPages =
+        this._config.response.totalPagesExtractor?.({
+          response: lastState.response as QueryResponse,
+          itemsPerPage: this.itemsPerPage,
+          args: lastQuery._arguments,
+        }) ??
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (lastState.response as any)?.totalPages ??
+        null;
+
+      this._totalPages$.next(totalPages);
+    }),
+    map((stateMaps) => {
+      if (!stateMaps.length) {
+        return null;
+      }
+
+      const fullData = stateMaps.reduce(
+        (acc, stateMap) => {
+          const valExtractFn = this._config?.response?.valueExtractor;
+          let data = valExtractFn
+            ? valExtractFn?.(stateMap.state.response as QueryResponse)
+            : (stateMap.state.response as InfinityResponse);
+
+          if (this._config.response.reverse) {
+            data = [...data].reverse() as InfinityResponse;
+          }
+
+          if (this._config.response.appendItemsTo === 'start') {
+            acc.unshift(...data);
+          } else {
+            acc.push(...data);
+          }
+          return acc;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        [] as any as InfinityResponse,
+      );
+
+      return fullData;
+    }),
+    shareReplay({ bufferSize: 1, refCount: true }),
+  );
+
+  private readonly _lastQuery$ = this._queries$.pipe(
+    map((queries) => queries[queries.length - 1] ?? null),
+    shareReplay({ bufferSize: 1, refCount: true }),
+  );
+
+  get currentPage$() {
+    return this._currentPage$.asObservable();
+  }
+
+  get currentPage() {
+    return this._currentPage$.getValue();
+  }
+
+  get currentCalculatedPage$() {
+    return this._currentCalculatedPage$.asObservable();
+  }
+
+  get currentCalculatedPage() {
+    return this._currentCalculatedPage$.getValue();
+  }
+
+  get totalPages$() {
+    return this._totalPages$.asObservable();
+  }
+
+  get totalPages() {
+    return this._totalPages$.getValue();
+  }
+
+  get itemsPerPage$() {
+    return this._itemsPerPage$.asObservable();
+  }
+
+  get itemsPerPage() {
+    return this._itemsPerPage$.getValue();
+  }
+
+  get data$() {
+    return this._data$;
+  }
+
+  get currentQuery$() {
+    return this._lastQuery$;
+  }
+
+  constructor(
+    private _config: InfinityQueryConfig<QueryCreator, Args, QueryResponse, InfinityResponse>,
+    private _destroy$: Observable<boolean>,
+  ) {}
+
+  nextPage() {
+    const newPage = (this._currentPage$.value ?? 0) + 1;
+    const calculatedPage =
+      this._config?.pageParam?.valueCalculator?.({
+        page: newPage,
+        totalPages: this.totalPages,
+        itemsPerPage: this.itemsPerPage,
+      }) ?? newPage;
+
+    if (this.totalPages !== null && newPage > this.totalPages) {
+      console.error(
+        'Cannot load more pages, already at the end. Make sure to not render the infinity query trigger using *ngIf canLoadMore',
+      );
+      return;
+    }
+
+    const args = this._prepareArgs(this._config, calculatedPage);
+
+    const query = this._config.queryCreator.prepare(args).execute() as Query;
+
+    if (this._config.pollingInterval) {
+      query.poll({ interval: this._config.pollingInterval, takeUntil: this._destroy$ });
+    }
+
+    this._queries$.next([...this._queries$.value, query]);
+
+    this._currentPage$.next(newPage);
+    this._currentCalculatedPage$.next(calculatedPage);
+  }
+
+  reset(
+    newConfig?: Omit<
+      InfinityQueryConfig<QueryCreator, Args, QueryResponse, InfinityResponse>,
+      'queryCreator' | 'response'
+    >,
+  ) {
+    this._config = { ...this._config, ...(newConfig ?? {}) };
+
+    this._currentPage$.next(null);
+    this._currentCalculatedPage$.next(null);
+    this._totalPages$.next(null);
+    this._itemsPerPage$.next(this._config.limitParam?.value ?? 10);
+    this._queries$.next([]);
+
+    this.nextPage();
+  }
+
+  private _prepareArgs(config: InfinityQueryConfig<QueryCreator, Args, QueryResponse, InfinityResponse>, page: number) {
+    const pageParamLocation = this._getPageParamLocation(config?.pageParam?.location);
+
+    const pageArgs = {
+      [pageParamLocation]: {
+        [config?.pageParam?.key ?? 'page']: page,
+      },
+    };
+
+    const limitParamLocation = this._getPageParamLocation(config?.limitParam?.location);
+
+    const limitArgs = {
+      [limitParamLocation]: {
+        [config?.limitParam?.key ?? 'limit']: config?.limitParam?.value ?? 10,
+      },
+    };
+
+    const defaultConfig = config?.defaultArgs ?? {};
+
+    const mergedArgs =
+      pageParamLocation === limitParamLocation
+        ? {
+            ...defaultConfig,
+            [pageParamLocation]: {
+              ...(config?.defaultArgs?.[pageParamLocation] ?? {}),
+              ...pageArgs[limitParamLocation],
+              ...limitArgs[limitParamLocation],
+            },
+          }
+        : {
+            ...defaultConfig,
+            [pageParamLocation]: {
+              ...(config?.defaultArgs?.[pageParamLocation] ?? {}),
+              ...pageArgs[pageParamLocation],
+            },
+            [limitParamLocation]: {
+              ...(config?.defaultArgs?.[limitParamLocation] ?? {}),
+              ...limitArgs[limitParamLocation],
+            },
+          };
+
+    return mergedArgs;
+  }
+
+  private _getPageParamLocation(location: InfinityQueryParamLocation | undefined) {
+    const loc = location ?? 'query';
+
+    switch (loc) {
+      case 'path':
+        return 'pathParams';
+      case 'query':
+        return 'queryParams';
+      case 'body':
+        return 'body';
+      case 'header':
+        return 'headers';
+      case 'variable':
+        return 'variables';
+      default:
+        throw new Error(`Invalid pageParamLocation: ${loc}`);
+    }
+  }
+}

package/src/lib/infinite-query/infinity-query.types.ts

@@ -0,0 +1,149 @@
+import { BaseArguments, WithHeaders } from '../query';
+import { AnyQueryCreator, ConstructQuery, QueryArgsOf, QueryDataOf } from '../query-creator';
+import { InfinityQuery } from './infinity-query';
+
+export type InfinityQueryParamLocation = 'path' | 'query' | 'body' | 'header' | 'variable';
+
+export type AppendItemsLocation = 'start' | 'end';
+
+export interface PageParamCalculatorOptions {
+  page: number;
+  totalPages: number | null;
+  itemsPerPage: number;
+}
+
+export interface TotalPagesExtractorOptions<Arguments extends BaseArguments | undefined, QueryResponse> {
+  response: QueryResponse;
+  itemsPerPage: number;
+  args: Arguments;
+}
+
+export interface InfinityQueryConfig<
+  QueryCreator extends AnyQueryCreator,
+  Arguments extends BaseArguments | undefined,
+  QueryResponse,
+  InfinityResponse extends unknown[],
+> {
+  /**
+   * The query creator to use for fetching pages.
+   */
+  queryCreator: QueryCreator;
+
+  /**
+   * The interval in milliseconds to poll on. If not provided, polling will be disabled.
+   * @default undefined
+   */
+  pollingInterval?: number;
+
+  /**
+   * The args that will be merged with the page arg.
+   */
+  defaultArgs?: Arguments & WithHeaders;
+
+  pageParam?: {
+    /**
+     * The location where the page param is in request.
+     *
+     * @default "query"
+     */
+    location?: InfinityQueryParamLocation;
+
+    /**
+     * Used as page param name.
+     *
+     * @default "page"
+     */
+    key?: string;
+
+    /**
+     * A function that calculates the page value for the next request.
+     * E.g. if the pagination is done with a `skip` param, the `pageParamName` should be `skip` and this function should return the correct value.
+     */
+    valueCalculator?: (data: PageParamCalculatorOptions) => number;
+  };
+
+  limitParam?: {
+    /**
+     * The location where the limit param is in request.
+     *
+     * @default "query"
+     */
+    location?: InfinityQueryParamLocation;
+
+    /**
+     * Used as limit param name.
+     *
+     * @default "limit"
+     */
+    key?: string;
+
+    /**
+     * The value of the limit param.
+     *
+     * @default 10
+     */
+    value?: number;
+  };
+
+  response: {
+    /**
+     * Determines if the response should get reversed before appending to the data array.
+     *
+     * @default false
+     */
+    reverse?: boolean;
+
+    /**
+     * Determines where to put the new items in the data array.
+     *
+     * @default "end"
+     */
+    appendItemsTo?: AppendItemsLocation;
+
+    /**
+     * The type of the array that will be created by the infinite query.
+     */
+    arrayType: InfinityResponse;
+
+    /**
+     * A function that returns the data array from the response.
+     * This function should return the type provided in `responseArrayType`.
+     */
+    valueExtractor?: (response: QueryResponse) => InfinityResponse;
+
+    /**
+     * The property in the response that contains the total page count.
+     *
+     * @default "totalPages"
+     */
+    totalPagesExtractor?: (
+      data: TotalPagesExtractorOptions<QueryArgsOf<QueryCreator> & WithHeaders, QueryResponse>,
+    ) => number;
+  };
+}
+
+type OmitUndefined<T> = T extends undefined ? never : T;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyInfinityQueryConfig = InfinityQueryConfig<any, any, any, any>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyInfinityQuery = InfinityQuery<any, any, any, any, any>;
+
+export type InfinityQueryConfigType<
+  QueryCreator extends AnyQueryCreator,
+  InfinityResponse extends unknown[],
+> = InfinityQueryConfig<
+  QueryCreator,
+  OmitUndefined<QueryArgsOf<QueryCreator>>,
+  QueryDataOf<QueryCreator>,
+  InfinityResponse
+>;
+
+export type InfinityQueryOf<Cfg extends AnyInfinityQueryConfig | null> = InfinityQuery<
+  NonNullable<Cfg>['queryCreator'],
+  ConstructQuery<NonNullable<Cfg>['queryCreator']>,
+  QueryArgsOf<NonNullable<Cfg>['queryCreator']>,
+  QueryDataOf<NonNullable<Cfg>['queryCreator']>,
+  NonNullable<Cfg>['response']['arrayType']
+>;

package/src/lib/infinite-query/infinity-query.utils.ts

@@ -0,0 +1,14 @@
+import { AnyQueryCreator, QueryArgsOf, QueryDataOf } from '../query-creator';
+import { InfinityQueryConfig, PageParamCalculatorOptions } from './infinity-query.types';
+
+export const createInfinityQueryConfig = <
+  QueryCreator extends AnyQueryCreator,
+  Args extends QueryArgsOf<QueryCreator>,
+  QueryResponse extends QueryDataOf<QueryCreator>,
+  InfinityResponse extends unknown[],
+>(
+  config: InfinityQueryConfig<QueryCreator, Args, QueryResponse, InfinityResponse>,
+) => config;
+
+export const skipPaginationPageParamCalculator = ({ page, itemsPerPage }: PageParamCalculatorOptions) =>
+  itemsPerPage * (page - 1);

package/src/lib/logger/logger.ts

@@ -0,0 +1,30 @@
+export const buildErrorMessage = (code: string, message: string) => `[@ethlete\\query:${code}] ${message}`;
+
+export class QueryError extends Error {
+  data?: unknown;
+
+  constructor(code: string, message: string, data?: unknown) {
+    super(buildErrorMessage(code, message));
+    this.name = 'QueryError';
+    this.data = data;
+  }
+}
+
+export const invalidBaseRouteError = (data: unknown) =>
+  new QueryError('001', 'The baseRoute must not end with a slash', data);
+
+export const invalidRouteError = (data: unknown) => new QueryError('002', 'The route must start with a slash', data);
+
+export const pathParamsMissingInRouteFunctionError = (data: unknown) =>
+  new QueryError('003', 'The route is a function but pathParams are missing', data);
+
+export const queryStateAlreadyHasKeyError = (data: unknown) =>
+  new QueryError('004', 'The query state already contains the provided key', data);
+
+export const queryStateDoesNotContainKeyError = (data: unknown) =>
+  new QueryError('005', 'The query state does not contain the provided key', data);
+
+export const queryStateCannotTransformError = (data: unknown) =>
+  new QueryError('006', 'The query state cannot be transformed because it is not loading', data);
+
+export const invalidBodyError = (data: unknown) => new QueryError('007', 'The body is not valid or upsupported', data);