feat: Implement BaseDataService

packages/base-data-service/package.json

@@ -47,12 +47,19 @@
     "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
   },
+  "dependencies": {
+    "@metamask/messenger": "^0.3.0",
+    "@metamask/utils": "^11.9.0",
+    "@tanstack/query-core": "^4.43.0",
+    "fast-deep-equal": "^3.1.3"
+  },
   "devDependencies": {
     "@metamask/auto-changelog": "^3.4.4",
     "@ts-bridge/cli": "^0.6.4",
     "@types/jest": "^29.5.14",
     "deepmerge": "^4.2.2",
     "jest": "^29.7.0",
+    "nock": "^13.3.1",
     "ts-jest": "^29.2.5",
     "typedoc": "^0.25.13",
     "typedoc-plugin-missing-exports": "^2.0.0",

packages/base-data-service/src/BaseDataService.test.ts

@@ -0,0 +1,108 @@
+import { Messenger } from '@metamask/messenger';
+
+import { ExampleDataService, serviceName } from '../tests/ExampleDataService';
+import {
+  mockAssets,
+  mockTransactionsPage1,
+  mockTransactionsPage2,
+  mockTransactionsPage3,
+  TRANSACTIONS_PAGE_2_CURSOR,
+  TRANSACTIONS_PAGE_3_CURSOR,
+} from '../tests/mocks';
+
+const TEST_ADDRESS = '0x4bbeEB066eD09B7AEd07bF39EEe0460DFa261520';
+
+describe('BaseDataService', () => {
+  beforeEach(() => {
+    mockAssets();
+    mockTransactionsPage1();
+    mockTransactionsPage2();
+    mockTransactionsPage3();
+  });
+
+  it('handles basic queries', async () => {
+    const messenger = new Messenger({ namespace: serviceName });
+    const service = new ExampleDataService(messenger);
+
+    expect(
+      await service.getAssets([
+        'eip155:1/slip44:60',
+        'bip122:000000000019d6689c085ae165831e93/slip44:0',
+        'eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f',
+      ]),
+    ).toStrictEqual([
+      {
+        assetId: 'eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f',
+        decimals: 18,
+        name: 'Dai Stablecoin',
+        symbol: 'DAI',
+      },
+      {
+        assetId: 'bip122:000000000019d6689c085ae165831e93/slip44:0',
+        decimals: 8,
+        name: 'Bitcoin',
+        symbol: 'BTC',
+      },
+      {
+        assetId: 'eip155:1/slip44:60',
+        decimals: 18,
+        name: 'Ethereum',
+        symbol: 'ETH',
+      },
+    ]);
+  });
+
+  it('handles paginated queries', async () => {
+    const messenger = new Messenger({ namespace: serviceName });
+    const service = new ExampleDataService(messenger);
+
+    const page1 = await service.getActivity(TEST_ADDRESS);
+
+    expect(page1.data).toHaveLength(3);
+
+    const page2 = await service.getActivity(TEST_ADDRESS, {
+      after: page1.pageInfo.endCursor,
+    });
+
+    expect(page2.data).toHaveLength(3);
+
+    expect(page2.data).not.toStrictEqual(page1.data);
+  });
+
+  it('handles paginated queries starting at a specific page', async () => {
+    const messenger = new Messenger({ namespace: serviceName });
+    const service = new ExampleDataService(messenger);
+
+    const page2 = await service.getActivity(TEST_ADDRESS, {
+      after: TRANSACTIONS_PAGE_2_CURSOR,
+    });
+
+    expect(page2.data).toHaveLength(3);
+
+    const page3 = await service.getActivity(TEST_ADDRESS, {
+      after: page2.pageInfo.endCursor,
+    });
+
+    expect(page3.data).toHaveLength(3);
+
+    expect(page3.data).not.toStrictEqual(page2.data);
+  });
+
+  it('handles backwards queries starting at a specific page', async () => {
+    const messenger = new Messenger({ namespace: serviceName });
+    const service = new ExampleDataService(messenger);
+
+    const page3 = await service.getActivity(TEST_ADDRESS, {
+      after: TRANSACTIONS_PAGE_3_CURSOR,
+    });
+
+    expect(page3.data).toHaveLength(3);
+
+    const page2 = await service.getActivity(TEST_ADDRESS, {
+      before: page3.pageInfo.startCursor,
+    });
+
+    expect(page2.data).toHaveLength(3);
+    expect(page2.data).not.toStrictEqual(page3.data);
+  });
+});

packages/base-data-service/src/BaseDataService.ts

@@ -0,0 +1,256 @@
+import {
+  Messenger,
+  ActionConstraint,
+  EventConstraint,
+  ActionHandler,
+} from '@metamask/messenger';
+import type { Json } from '@metamask/utils';
+import {
+  DehydratedState,
+  FetchInfiniteQueryOptions,
+  FetchQueryOptions,
+  InfiniteData,
+  InvalidateOptions,
+  InvalidateQueryFilters,
+  QueryClient,
+  QueryKey,
+  WithRequired,
+  dehydrate,
+  hashQueryKey,
+} from '@tanstack/query-core';
+import deepEqual from 'fast-deep-equal';
+
+export type SubscriptionPayload = { hash: string; state: DehydratedState };
+export type SubscriptionCallback = (payload: SubscriptionPayload) => void;
+
+export type DataServiceSubscribeAction<ServiceName extends string> = {
+  type: `${ServiceName}:subscribe`;
+  handler: (
+    queryKey: QueryKey,
+    callback: SubscriptionCallback,
+  ) => DehydratedState;
+};
+
+export type DataServiceUnsubscribeAction<ServiceName extends string> = {
+  type: `${ServiceName}:unsubscribe`;
+  handler: (queryKey: QueryKey, callback: SubscriptionCallback) => void;
+};
+
+export type DataServiceInvalidateQueriesAction<ServiceName extends string> = {
+  type: `${ServiceName}:invalidateQueries`;
+  handler: (
+    filters?: InvalidateQueryFilters<Json>,
+    options?: InvalidateOptions,
+  ) => Promise<void>;
+};
+
+export type DataServiceActions<ServiceName extends string> =
+  | DataServiceSubscribeAction<ServiceName>
+  | DataServiceUnsubscribeAction<ServiceName>
+  | DataServiceInvalidateQueriesAction<ServiceName>;
+
+export type DataServiceCacheUpdateEvent<ServiceName extends string> = {
+  type: `${ServiceName}:cacheUpdate`;
+  payload: [SubscriptionPayload];
+};
+
+export type DataServiceEvents<ServiceName extends string> =
+  DataServiceCacheUpdateEvent<ServiceName>;
+
+export class BaseDataService<
+  ServiceName extends string,
+  ServiceMessenger extends Messenger<
+    ServiceName,
+    ActionConstraint,
+    EventConstraint,
+    // Use `any` to allow any parent to be set. `any` is harmless in a type constraint anyway,
+    // it's the one totally safe place to use it.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any
+  >,
+> {
+  public readonly name: ServiceName;
+
+  readonly #messenger: Messenger<
+    ServiceName,
+    DataServiceActions<ServiceName>,
+    DataServiceEvents<ServiceName>
+  >;
+
+  readonly #client = new QueryClient();
+
+  readonly #subscriptions: Map<string, Set<SubscriptionCallback>> = new Map();
+
+  constructor({
+    name,
+    messenger,
+  }: {
+    name: ServiceName;
+    messenger: ServiceMessenger;
+  }) {
+    this.name = name;
+
+    this.#messenger = messenger as unknown as Messenger<
+      ServiceName,
+      DataServiceActions<ServiceName>,
+      DataServiceEvents<ServiceName>
+    >;
+
+    this.#registerMessageHandlers();
+    this.#setupCacheListener();
+  }
+
+  #registerMessageHandlers(): void {
+    // Casts are required since `registerActionHandler` isn't able to extract the method parameters correctly.
+    this.#messenger.registerActionHandler(`${this.name}:subscribe`, ((
+      queryKey: QueryKey,
+      callback: SubscriptionCallback,
+    ) => this.#handleSubscribe(queryKey, callback)) as ActionHandler<
+      DataServiceActions<ServiceName>
+    >);
+
+    this.#messenger.registerActionHandler(`${this.name}:unsubscribe`, ((
+      queryKey: QueryKey,
+      callback: SubscriptionCallback,
+    ) => this.#handleUnsubscribe(queryKey, callback)) as ActionHandler<
+      DataServiceActions<ServiceName>
+    >);
+
+    this.#messenger.registerActionHandler(`${this.name}:invalidateQueries`, ((
+      filters?: InvalidateQueryFilters<Json>,
+      options?: InvalidateOptions,
+    ) => this.invalidateQueries(filters, options)) as ActionHandler<
+      DataServiceActions<ServiceName>
+    >);
+  }
+
+  #setupCacheListener(): void {
+    this.#client.getQueryCache().subscribe((event) => {
+      if (['added', 'updated', 'removed'].includes(event.type)) {
+        this.#broadcastCacheUpdate(event.query.queryKey);
+      }
+    });
+  }
+
+  protected async fetchQuery<
+    TQueryFnData extends Json,
+    TError = unknown,
+    TData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
+  >(
+    options: WithRequired<
+      FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+      'queryKey' | 'queryFn'
+    >,
+  ): Promise<TData> {
+    return this.#client.fetchQuery(options);
+  }
+
+  protected async fetchInfiniteQuery<
+    TQueryFnData extends Json,
+    TError = unknown,
+    TData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
+    TPageParam extends Json = Json,
+  >(
+    options: WithRequired<
+      FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+      'queryKey' | 'queryFn'
+    >,
+    pageParam?: TPageParam,
+  ): Promise<TData> {
+    const query = this.#client
+      .getQueryCache()
+      .find<TQueryFnData, TError, TData>({ queryKey: options.queryKey });
+
+    if (!query || !pageParam) {
+      const result = await this.#client.fetchInfiniteQuery({
+        ...options,
+        queryFn: (context) =>
+          options.queryFn({
+            ...context,
+            pageParam: context.pageParam ?? pageParam,
+          }),
+      });
+
+      return result.pages[0];
+    }
+
+    const { pages } = query.state.data as InfiniteData<TQueryFnData>;
+    const previous = options.getPreviousPageParam?.(pages[0], pages);
+
+    const direction = deepEqual(pageParam, previous) ? 'backward' : 'forward';
+
+    const result = (await query.fetch(undefined, {
+      meta: {
+        fetchMore: {
+          direction,
+          pageParam,
+        },
+      },
+    })) as InfiniteData<TData>;
+
+    const pageIndex = result.pageParams.indexOf(pageParam);
+
+    return result.pages[pageIndex];
+  }
+
+  async invalidateQueries<TPageData extends Json>(
+    filters?: InvalidateQueryFilters<TPageData>,
+    options?: InvalidateOptions,
+  ): Promise<void> {
+    return this.#client.invalidateQueries(filters, options);
+  }
+
+  #handleSubscribe(
+    queryKey: QueryKey,
+    subscription: SubscriptionCallback,
+  ): DehydratedState {
+    const hash = hashQueryKey(queryKey);
+
+    if (!this.#subscriptions.has(hash)) {
+      this.#subscriptions.set(hash, new Set());
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    this.#subscriptions.get(hash)!.add(subscription);
+
+    return this.#getDehydratedState(queryKey);
+  }
+
+  #handleUnsubscribe(
+    queryKey: QueryKey,
+    subscription: SubscriptionCallback,
+  ): void {
+    const hash = hashQueryKey(queryKey);
+    const subscribers = this.#subscriptions.get(hash);
+
+    subscribers?.delete(subscription);
+    if (subscribers?.size === 0) {
+      this.#subscriptions.delete(hash);
+    }
+  }
+
+  #getDehydratedState(queryKey: QueryKey): DehydratedState {
+    const hash = hashQueryKey(queryKey);
+    return dehydrate(this.#client, {
+      shouldDehydrateQuery: (query) => query.queryHash === hash,
+    });
+  }
+
+  #broadcastCacheUpdate(queryKey: QueryKey): void {
+    const hash = hashQueryKey(queryKey);
+    const state = this.#getDehydratedState(queryKey);
+
+    const payload = {
+      hash,
+      state,
+    };
+
+    this.#messenger.publish(`${this.name}:cacheUpdate` as const, payload);
+
+    // TODO: Determine if we can leverage `messenger.publish` entirely in order to not keep track of subscriptions manually.
+    const subscribers = this.#subscriptions.get(hash);
+    subscribers?.forEach((subscriber) => subscriber(payload));
+  }
+}