@ethlete/query 5.15.0 → 5.16.0

package/src/lib/query-client/query-client.ts

@@ -0,0 +1,195 @@
+import { BehaviorSubject } from 'rxjs';
+import { AuthProvider } from '../auth';
+import { EntityStore } from '../entity';
+import {
+  BaseArguments,
+  GqlQueryConfig,
+  GqlQueryConfigWithoutMethod,
+  QueryConfigWithoutMethod,
+  RestQueryConfig,
+  RouteType,
+} from '../query';
+import { QueryCreator } from '../query-creator';
+import { QueryStore } from '../query-store';
+import { RequestHeaders, RequestHeadersMethodMap } from '../request';
+import { QueryClientConfig } from './query-client.types';
+
+export class QueryClient {
+  /**
+   * @internal
+   */
+  readonly _store: QueryStore;
+
+  get config() {
+    return this._clientConfig;
+  }
+
+  get authProvider() {
+    return this._authProvider$.getValue() ?? this._clientConfig.parent?._authProvider$.getValue() ?? null;
+  }
+  get authProvider$() {
+    return this._authProvider$.asObservable() ?? this._clientConfig.parent?._authProvider$.asObservable() ?? null;
+  }
+  private readonly _authProvider$ = new BehaviorSubject<AuthProvider | null>(null);
+
+  constructor(private _clientConfig: QueryClientConfig) {
+    this._store = new QueryStore({
+      enableChangeLogging: _clientConfig.logging?.queryStateChanges,
+      enableGarbageCollectorLogging: _clientConfig.logging?.queryStateGarbageCollector,
+      autoRefreshQueriesOnWindowFocus: _clientConfig.request?.autoRefreshQueriesOnWindowFocus ?? true,
+      enableSmartPolling: _clientConfig.request?.enableSmartPolling ?? true,
+    });
+  }
+
+  get = <
+    Route extends RouteType<Arguments>,
+    Response,
+    Id,
+    Data = Response,
+    Arguments extends BaseArguments | undefined = undefined,
+    Store extends EntityStore<unknown> = EntityStore<unknown>,
+  >(
+    queryConfig: QueryConfigWithoutMethod<Route, Response, Arguments, Store, Data, Id>,
+  ) =>
+    this.fetch<Route, Response, Arguments, Id, Store, Data>({
+      ...queryConfig,
+      method: 'GET',
+    });
+
+  post = <
+    Route extends RouteType<Arguments>,
+    Response,
+    Id,
+    Data = Response,
+    Arguments extends BaseArguments | undefined = undefined,
+    Store extends EntityStore<unknown> = EntityStore<unknown>,
+  >(
+    queryConfig: QueryConfigWithoutMethod<Route, Response, Arguments, Store, Data, Id>,
+  ) =>
+    this.fetch<Route, Response, Arguments, Id, Store, Data>({
+      ...queryConfig,
+      method: 'POST',
+    });
+
+  put = <
+    Route extends RouteType<Arguments>,
+    Response,
+    Id,
+    Data = Response,
+    Arguments extends BaseArguments | undefined = undefined,
+    Store extends EntityStore<unknown> = EntityStore<unknown>,
+  >(
+    queryConfig: QueryConfigWithoutMethod<Route, Response, Arguments, Store, Data, Id>,
+  ) =>
+    this.fetch<Route, Response, Arguments, Id, Store, Data>({
+      ...queryConfig,
+      method: 'PUT',
+    });
+
+  patch = <
+    Route extends RouteType<Arguments>,
+    Response,
+    Id,
+    Data = Response,
+    Arguments extends BaseArguments | undefined = undefined,
+    Store extends EntityStore<unknown> = EntityStore<unknown>,
+  >(
+    queryConfig: QueryConfigWithoutMethod<Route, Response, Arguments, Store, Data, Id>,
+  ) =>
+    this.fetch<Route, Response, Arguments, Id, Store, Data>({
+      ...queryConfig,
+      method: 'PATCH',
+    });
+
+  delete = <
+    Route extends RouteType<Arguments>,
+    Response,
+    Id,
+    Data = Response,
+    Arguments extends BaseArguments | undefined = undefined,
+    Store extends EntityStore<unknown> = EntityStore<unknown>,
+  >(
+    queryConfig: QueryConfigWithoutMethod<Route, Response, Arguments, Store, Data, Id>,
+  ) =>
+    this.fetch<Route, Response, Arguments, Id, Store, Data>({
+      ...queryConfig,
+      method: 'DELETE',
+    });
+
+  gqlQuery = <
+    Route extends RouteType<Arguments>,
+    Response,
+    Id,
+    Data = Response,
+    Arguments extends BaseArguments | undefined = undefined,
+    Store extends EntityStore<unknown> = EntityStore<unknown>,
+  >(
+    queryConfig: GqlQueryConfigWithoutMethod<Route, Response, Arguments, Store, Data, Id>,
+  ) =>
+    this.fetch<Route, Response, Arguments, Id, Store, Data>({
+      ...queryConfig,
+      method: 'GQL_QUERY',
+    });
+
+  gqlMutate = <
+    Route extends RouteType<Arguments>,
+    Response,
+    Id,
+    Data = Response,
+    Arguments extends BaseArguments | undefined = undefined,
+    Store extends EntityStore<unknown> = EntityStore<unknown>,
+  >(
+    queryConfig: GqlQueryConfigWithoutMethod<Route, Response, Arguments, Store, Data, Id>,
+  ) =>
+    this.fetch<Route, Response, Arguments, Id, Store, Data>({
+      ...queryConfig,
+      method: 'GQL_MUTATE',
+    });
+
+  fetch = <
+    Route extends RouteType<Arguments>,
+    Response,
+    Arguments extends BaseArguments | undefined,
+    Id,
+    Store extends EntityStore<unknown> = EntityStore<unknown>,
+    Data = Response,
+  >(
+    queryConfig:
+      | RestQueryConfig<Route, Response, Arguments, Store, Data, Id>
+      | GqlQueryConfig<Route, Response, Arguments, Store, Data, Id>,
+  ) => new QueryCreator<Arguments, Response, Route, Store, Data, Id>(queryConfig, this, this._store);
+
+  setAuthProvider = (authProvider: AuthProvider) => {
+    if (this.authProvider) {
+      this.authProvider?.cleanUp();
+    }
+
+    this._authProvider$.next(authProvider);
+  };
+
+  setDefaultHeaders = (config: {
+    headers: RequestHeaders | RequestHeadersMethodMap | null;
+    refreshQueriesInUse?: boolean;
+  }) => {
+    if (!this._clientConfig.request) {
+      this._clientConfig.request = {
+        headers: config.headers ?? undefined,
+      };
+    } else {
+      this._clientConfig.request.headers = config.headers ?? undefined;
+    }
+
+    if (config.refreshQueriesInUse) {
+      this._store.refreshQueriesInUse({ purgeUnused: true, ignoreCacheValidity: true });
+    }
+  };
+
+  clearAuthProvider = () => {
+    this.authProvider?.cleanUp();
+    this._authProvider$.next(null);
+  };
+
+  _updateBaseRoute = (route: string) => {
+    this._clientConfig.baseRoute = route;
+  };
+}

package/src/lib/query-client/query-client.types.ts

@@ -0,0 +1,101 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { GqlTransferOption } from '../query/query.types';
+import {
+  BuildQueryStringConfig,
+  CacheAdapterFn,
+  RequestHeaders,
+  RequestHeadersMethodMap,
+  RequestRetryFn,
+} from '../request';
+import { QueryClient } from './query-client';
+
+export interface QueryClientConfig {
+  /**
+   * The api base route. Should **not** end with a trailing slash.
+   * @example 'https://api.example.com'
+   */
+  baseRoute: string;
+
+  /**
+   * Logging configuration for debugging.
+   */
+  logging?: {
+    /**
+     * Log all query state changes.
+     */
+    queryStateChanges?: boolean;
+
+    /**
+     * Log query state garbage collector runs.
+     */
+    queryStateGarbageCollector?: boolean;
+
+    /**
+     * Log if subscriptions are made to queries that are in the `prepared` state.
+     * This usually indicates that the `.execute()` method was forgotten.
+     */
+    preparedQuerySubscriptions?: boolean;
+  };
+
+  /**
+   * Request options.
+   */
+  request?: {
+    /**
+     * Adapter function used for extracting the time until the response is invalid.
+     * The default uses the `cache-control` (`max-age` & `s-maxage`), `age` and `expires` headers.
+     * Should return a number in seconds.
+     */
+    cacheAdapter?: CacheAdapterFn;
+
+    /**
+     * Default headers to be sent with every request.
+     * Will be overridden by headers passed to the query.
+     * Do not include the `Authorization` header here. Use an `AuthProvider` instead.
+     */
+    headers?: RequestHeaders | RequestHeadersMethodMap;
+
+    /**
+     * Whether to automatically refresh expired queries when the window regains focus.
+     * @default true
+     */
+    autoRefreshQueriesOnWindowFocus?: boolean;
+
+    /**
+     * Whether to automatically stop polling queries when the window loses focus.
+     * Polling will resume when the window regains focus.
+     * @default true
+     */
+    enableSmartPolling?: boolean;
+
+    /**
+     * A retry function to be used for all queries.
+     * @default shouldRetryRequest()
+     */
+    retryFn?: RequestRetryFn;
+
+    /**
+     * Configuration options for all graphql queries.
+     */
+    gql?: {
+      /**
+       * Determines if the query should be sent via GET or POST.
+       * - `GET`: The query will be sent via query parameters.
+       * - `POST`: The query will be sent via the body.
+       * @default 'POST'
+       */
+      transferVia?: GqlTransferOption;
+    };
+
+    /**
+     * Configuration options for all query strings.
+     */
+    queryParams?: BuildQueryStringConfig;
+  };
+
+  /**
+   * Parent query client.
+   * Used for sharing the same auth provider.
+   */
+  parent?: QueryClient;
+}

package/src/lib/query-client/query-client.utils.spec.ts

@@ -0,0 +1,61 @@
+import { BaseArguments } from '../query/query.types';
+import { buildQueryCacheKey, shouldCacheQuery } from './query-client.utils';
+
+describe('buildQueryCacheKey', () => {
+  it('should return a string with a shortened query and variables', () => {
+    const route = '/posts';
+    const args: BaseArguments = {
+      variables: {
+        id: 123,
+      },
+    };
+
+    const expectedCacheKey = '1769813287';
+
+    const cacheKey = buildQueryCacheKey(route, args);
+
+    expect(cacheKey).toBe(expectedCacheKey);
+  });
+});
+
+describe('shouldCacheQuery', () => {
+  it('should return true for GET requests', () => {
+    const method = 'GET';
+
+    const shouldCache = shouldCacheQuery(method);
+
+    expect(shouldCache).toBe(true);
+  });
+
+  it('should return true for OPTIONS requests', () => {
+    const method = 'OPTIONS';
+
+    const shouldCache = shouldCacheQuery(method);
+
+    expect(shouldCache).toBe(true);
+  });
+
+  it('should return true for HEAD requests', () => {
+    const method = 'HEAD';
+
+    const shouldCache = shouldCacheQuery(method);
+
+    expect(shouldCache).toBe(true);
+  });
+
+  it('should return true for GQL_QUERY requests', () => {
+    const method = 'GQL_QUERY';
+
+    const shouldCache = shouldCacheQuery(method);
+
+    expect(shouldCache).toBe(true);
+  });
+
+  it('should return false for other HTTP methods', () => {
+    const method = 'POST';
+
+    const shouldCache = shouldCacheQuery(method);
+
+    expect(shouldCache).toBe(false);
+  });
+});

package/src/lib/query-client/query-client.utils.ts

@@ -0,0 +1,28 @@
+import { BaseArguments } from '../query/query.types';
+import { Method } from '../request';
+
+export const shouldCacheQuery = (method: Method) => {
+  return method === 'GET' || method === 'OPTIONS' || method === 'HEAD' || method === 'GQL_QUERY';
+};
+
+export const buildQueryCacheKey = (route: string, args: BaseArguments | undefined) => {
+  const variables = JSON.stringify(args?.variables || {})
+    // replace all curly braces with empty string
+    .replace(/{|}/g, '')
+    // replace new lines and whitespaces with empty string
+    .replace(/\s/g, '');
+
+  const seed = `${route}...${variables}`;
+
+  let hash = 0;
+
+  for (const char of seed) {
+    hash = (Math.imul(31, hash) + char.charCodeAt(0)) << 0;
+  }
+
+  // Force positive number hash.
+  // 2147483647 = equivalent of Integer.MAX_VALUE.
+  hash += 2147483647 + 1;
+
+  return hash.toString();
+};

package/src/lib/query-creator/query-creator.ts

@@ -0,0 +1,103 @@
+import { assertInInjectionContext, signal } from '@angular/core';
+import { toObservable } from '@angular/core/rxjs-interop';
+import { BehaviorSubject } from 'rxjs';
+import { EntityStore } from '../entity';
+import { Query, computeQueryQueryParams } from '../query';
+import { QueryClient, buildQueryCacheKey, shouldCacheQuery } from '../query-client';
+import { QueryStore } from '../query-store';
+import {
+  AnyRoute,
+  BaseArguments,
+  GqlQueryConfig,
+  RestQueryConfig,
+  RouteType,
+  WithConfig,
+  WithHeaders,
+  WithMock,
+} from '../query/query.types';
+import { buildRoute } from '../request';
+import { QueryContainerConfig, addQueryContainerHandling } from '../utils';
+import { QueryPrepareFn } from './query-creator.types';
+
+export class QueryCreator<
+  Arguments extends BaseArguments | undefined,
+  Response,
+  Route extends RouteType<Arguments>,
+  Store extends EntityStore<unknown>,
+  Data,
+  Id,
+> {
+  constructor(
+    private _queryConfig:
+      | RestQueryConfig<Route, Response, Arguments, Store, Data, Id>
+      | GqlQueryConfig<Route, Response, Arguments, Store, Data, Id>,
+    private _client: QueryClient,
+    private _store: QueryStore,
+  ) {}
+
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  prepare: QueryPrepareFn<Arguments, Response, Route, Store, Data, Id> = (
+    args?: Arguments & WithHeaders & WithConfig & WithMock<Response>,
+  ) => {
+    const route = buildRoute({
+      base: this._client.config.baseRoute,
+      route: this._queryConfig.route as AnyRoute,
+      pathParams: args?.pathParams,
+      queryParams: computeQueryQueryParams({ config: this._queryConfig, client: this._client, args }),
+      queryParamConfig: this._client.config.request?.queryParams,
+    }) as Route;
+
+    const cacheKey = (args?.config?.queryStoreCacheKey ?? '') + buildQueryCacheKey(route as string, args);
+
+    if (shouldCacheQuery(this._queryConfig.method) && !args?.config?.skipQueryStore) {
+      const existingQuery = this._store.get<Query<Response, Arguments, Route, Store, Data, Id>>(cacheKey);
+
+      if (existingQuery) {
+        return existingQuery;
+      }
+    }
+
+    const query = new Query<Response, Arguments, Route, Store, Data, Id>(
+      this._client,
+      this._queryConfig,
+      route,
+      args ?? ({} as Arguments),
+      cacheKey,
+    );
+
+    if (shouldCacheQuery(this._queryConfig.method) && !args?.config?.skipQueryStore) {
+      this._store.add(cacheKey, query);
+    }
+
+    this._store._dispatchQueryCreated(query);
+
+    return query;
+  };
+
+  createSubject = (initialValue?: ReturnType<typeof this.prepare> | null, config?: QueryContainerConfig) => {
+    assertInInjectionContext(this.createSubject);
+
+    const subject = new BehaviorSubject<ReturnType<typeof this.prepare> | null>(initialValue ?? null);
+
+    addQueryContainerHandling(subject, () => subject.getValue(), config);
+
+    return subject;
+  };
+
+  createSignal = (initialValue?: ReturnType<typeof this.prepare> | null, config?: QueryContainerConfig) => {
+    assertInInjectionContext(this.createSignal);
+
+    const _signal = signal<ReturnType<typeof this.prepare> | null>(initialValue ?? null);
+
+    addQueryContainerHandling(toObservable(_signal), () => _signal(), config);
+
+    return _signal;
+  };
+
+  /**
+   * @deprecated Use `myQuery.createSubject()` or `myQuery.createSignal()` instead. Will be removed in v6.
+   */
+  behaviorSubject = (initialValue?: ReturnType<typeof this.prepare> | null) =>
+    new BehaviorSubject<ReturnType<typeof this.prepare> | null>(initialValue ?? null);
+}

package/src/lib/query-creator/query-creator.types.ts

@@ -0,0 +1,74 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { EntityStore } from '../entity';
+import { Query } from '../query/query';
+import {
+  AnyQuery,
+  BaseArguments,
+  EmptyObject,
+  RouteType,
+  WithConfig,
+  WithHeaders,
+  WithMock,
+} from '../query/query.types';
+import { QueryCreator } from './query-creator';
+
+export type QueryPrepareFn<
+  Arguments extends BaseArguments | undefined,
+  Response,
+  Route extends RouteType<Arguments>,
+  Store extends EntityStore<unknown>,
+  Data,
+  Id,
+> = Arguments extends BaseArguments
+  ? (
+      args: Arguments & WithHeaders & WithConfig & WithMock<Response>,
+    ) => Query<Response, Arguments, Route, Store, Data, Id>
+  : (
+      args?: (Arguments extends EmptyObject ? Arguments : EmptyObject) & WithHeaders & WithConfig & WithMock<Response>,
+    ) => Query<Response, Arguments, Route, Store, Data, Id>;
+
+export type AnyQueryCreator = QueryCreator<any, any, any, any, any, any>;
+
+export type QueryArgsOf<T extends AnyQueryCreator | AnyQuery | null> =
+  T extends QueryCreator<infer Args, any, any, any, any, any>
+    ? Args
+    : T extends Query<any, infer Args, any, any, any, any>
+      ? Args
+      : never;
+
+export type QueryResponseOf<T extends AnyQueryCreator | AnyQuery | null> =
+  T extends QueryCreator<any, infer Response, any, any, any, any>
+    ? Response
+    : T extends Query<infer Response, any, any, any, any, any>
+      ? Response
+      : never;
+
+export type QueryRouteOf<T extends AnyQueryCreator | AnyQuery | null> =
+  T extends QueryCreator<any, any, infer Route, any, any, any>
+    ? Route
+    : T extends Query<any, any, infer Route, any, any, any>
+      ? Route
+      : never;
+
+export type QueryStoreOf<T extends AnyQueryCreator | AnyQuery | null> =
+  T extends QueryCreator<any, any, any, infer Store, any, any>
+    ? Store
+    : T extends Query<any, any, any, infer Store, any, any>
+      ? Store
+      : never;
+
+export type QueryDataOf<T extends AnyQueryCreator | AnyQuery | null> =
+  T extends QueryCreator<any, any, any, any, infer Data, any>
+    ? Data
+    : T extends Query<any, any, any, any, infer Data, any>
+      ? Data
+      : never;
+
+export type QueryStoreIdOf<T extends AnyQueryCreator | AnyQuery | null> =
+  T extends QueryCreator<any, any, any, any, any, infer StoreId>
+    ? StoreId
+    : T extends Query<any, any, any, any, any, infer StoreId>
+      ? StoreId
+      : never;
+
+export type ConstructQuery<T extends AnyQueryCreator> = ReturnType<T['prepare']>;