feat(core): top-level whenClientChanged API (#1164)

Author: tien

.changeset/fresh-boxes-enjoy.md

@@ -0,0 +1,5 @@
+---
+"@reactive-dot/core": minor
+---
+
+Added top-level `whenClientChanged` API.

packages/core/src/apis/when-client-changed.test.ts

@@ -0,0 +1,41 @@
+import { getClient as baseGetClient } from "../actions/get-client.js";
+import { defineConfig } from "../config.js";
+import { whenClientChanged } from "./when-client-changed.js";
+import { firstValueFrom } from "rxjs";
+import { afterEach, expect, it, vi } from "vitest";
+
+vi.mock("../actions/get-client.js");
+
+const config = defineConfig({
+  chains: { test: { descriptor: {}, provider: {} } as never },
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+it("defers getClient until subscribing", async () => {
+  const mockClient = { id: "test-client" };
+  vi.mocked(baseGetClient).mockResolvedValue(mockClient as never);
+
+  const observable = whenClientChanged(config, { chainId: "test" });
+  expect(baseGetClient).not.toHaveBeenCalled();
+
+  const result = await firstValueFrom(observable);
+  expect(baseGetClient).toHaveBeenCalledTimes(1);
+  expect(result).toEqual(mockClient);
+});
+
+it("re-invokes getClient for each subscription", async () => {
+  const mockClient = { id: "test-client" };
+  vi.mocked(baseGetClient).mockResolvedValue(mockClient as never);
+
+  const observable = whenClientChanged(config, { chainId: "test" });
+
+  const promise1 = firstValueFrom(observable);
+  const promise2 = firstValueFrom(observable);
+
+  await Promise.all([promise1, promise2]);
+
+  expect(baseGetClient).toHaveBeenCalledTimes(2);
+});

packages/core/src/apis/when-client-changed.ts

@@ -0,0 +1,18 @@
+import type { InferChainId } from "../chains.js";
+import type { Config } from "../config.js";
+import { getClient } from "./get-client.js";
+import { defer } from "rxjs";
+
+/**
+ * Subscribe to client changes.
+ *
+ * @param config - The configuration
+ * @param options - Additional options
+ * @returns The currently configured client observable
+ */
+export function whenClientChanged<TConfig extends Config>(
+  config: TConfig,
+  options: { chainId: InferChainId<TConfig> },
+) {
+  return defer(() => getClient(config, options));
+}

packages/core/src/index.test.ts

@@ -5,6 +5,7 @@ it("should match inline snapshot", () =>
   expect(Object.keys(exports)).toMatchInlineSnapshot(`
     [
       "whenAccountsChanged",
+      "whenClientChanged",
       "whenConnectedWalletsChanged",
       "whenWalletsChanged",
       "defineConfig",

packages/core/src/index.ts

@@ -1,5 +1,6 @@
 export type { Address } from "./address.js";
 export { whenAccountsChanged } from "./apis/when-accounts-changed.js";
+export { whenClientChanged } from "./apis/when-client-changed.js";
 export { whenConnectedWalletsChanged } from "./apis/when-connected-wallets-changed.js";
 export { whenWalletsChanged } from "./apis/when-wallets-changed.js";
 export type { AsyncValue } from "./async-state.js";