@hub3js/core 0.0.0-experimental-03bf1f89-20260602

package/src/hub/helpers.ts

@@ -0,0 +1,11 @@
+/**
+ * Note: This only works native async, if we are going to support for old transpilers like Babel.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function isAsync(fn: Function) {
+  return fn.constructor.name === 'AsyncFunction';
+}
+
+export function generateStoreId(providerId: string, namespace: string) {
+  return `${providerId}$$${namespace}`;
+}

package/src/hub/hub.test.ts

@@ -0,0 +1,108 @@
+import type { Store } from './store/mod.js';
+
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { NamespaceBuilder } from '../builders/namespace.js';
+import { ProviderBuilder } from '../builders/provider.js';
+import { garbageWalletMetaData } from '../test-utils/fixtures.js';
+
+import { Hub } from './hub.js';
+import { createStore } from './store/mod.js';
+
+interface TestEvmActions {
+  connect: (chain: string) => Promise<{ accounts: string[]; network: string }>;
+}
+
+const buildEvmProvider = (id: string) => {
+  const evmNamespace = new NamespaceBuilder<TestEvmActions>('eip155', id)
+    .action('connect', async () => ({
+      accounts: ['eip155:0x1:0x000000000000000000000000000000000000dead'],
+      network: 'eth',
+    }))
+    .build();
+
+  return new ProviderBuilder(id)
+    .config('metadata', garbageWalletMetaData)
+    .add('evm', evmNamespace)
+    .build();
+};
+
+describe('Hub', () => {
+  let store: Store;
+
+  beforeEach(() => {
+    store = createStore();
+  });
+
+  test('add registers the provider in both the hub and the store', () => {
+    const provider = buildEvmProvider('wallet-a');
+    const hub = new Hub({ store }).add(provider.id, provider);
+
+    expect(hub.get('wallet-a')).toBe(provider);
+    expect(store.getState().providers.list['wallet-a']).toBeDefined();
+  });
+
+  test('get returns undefined for an unknown provider id', () => {
+    const hub = new Hub({ store });
+
+    expect(hub.get('does-not-exist')).toBeUndefined();
+  });
+
+  test('getAll returns every registered provider', () => {
+    const a = buildEvmProvider('wallet-a');
+    const b = buildEvmProvider('wallet-b');
+    const hub = new Hub({ store }).add(a.id, a).add(b.id, b);
+
+    const all = hub.getAll();
+    expect(all.size).toBe(2);
+    expect(all.get('wallet-a')).toBe(a);
+    expect(all.get('wallet-b')).toBe(b);
+  });
+
+  test('remove clears the provider from both the hub and the store', () => {
+    const provider = buildEvmProvider('wallet-a');
+    const hub = new Hub({ store }).add(provider.id, provider);
+
+    expect(store.getState().providers.list['wallet-a']).toBeDefined();
+
+    hub.remove('wallet-a');
+
+    expect(hub.get('wallet-a')).toBeUndefined();
+    expect(store.getState().providers.list['wallet-a']).toBeUndefined();
+  });
+
+  test('remove throws when the provider id is unknown', () => {
+    const hub = new Hub({ store });
+
+    expect(() => hub.remove('nope')).toThrowError(/Provider not found/);
+  });
+
+  test('init runs each provider init exactly once', () => {
+    const initSpy = vi.fn();
+    const provider = new ProviderBuilder('wallet-a')
+      .config('metadata', garbageWalletMetaData)
+      .init(initSpy)
+      .build();
+
+    const hub = new Hub({ store }).add(provider.id, provider);
+
+    expect(initSpy).toBeCalledTimes(0);
+
+    hub.init();
+    hub.init();
+
+    expect(initSpy).toBeCalledTimes(1);
+  });
+
+  test('state aggregates per-provider state and their namespaces', () => {
+    const provider = buildEvmProvider('wallet-a');
+    const hub = new Hub({ store }).add(provider.id, provider);
+
+    const state = hub.state();
+    expect(state['wallet-a']).toBeDefined();
+    expect(state['wallet-a'].installed).toBe(false);
+    expect(state['wallet-a'].connected).toBe(false);
+    expect(state['wallet-a'].namespaces).toHaveLength(1);
+    expect(state['wallet-a'].namespaces[0].connected).toBe(false);
+  });
+});

package/src/hub/hub.ts

@@ -0,0 +1,145 @@
+import type { Namespace, State as NamespaceState } from './namespaces/mod.js';
+import type { Provider, State as ProviderState } from './provider/mod.js';
+import type { Store } from './store/mod.js';
+
+/**
+ * Hub stores providers with heterogeneous `TNS` shapes. `Provider<TNS>` is
+ * invariant in `TNS` (TNS appears in both reading and writing positions via
+ * the internal `Map`), so the only universally-assignable upper bound is
+ * `Provider<any>`. Concrete TNS information is preserved on each `Provider`
+ * instance itself — consumers recover precise types via `provider.get('evm')`.
+ *
+ * TODO: consider making `Provider<TNS>` covariant in TNS so this `any` can be
+ * replaced with `Provider<unknown>`. Requires switching the internal storage
+ * to a covariant container (e.g. `ReadonlyMap` semantics), moving TNS-typed
+ * constructor inputs out of the public class surface (factory pattern or
+ * interface + impl), and dropping TNS info from `getAll()`'s return type.
+ * Bigger surgery than this PR; deserves its own review cycle.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyProvider = Provider<any>;
+
+type HubState = {
+  [key in string]: ProviderState & {
+    namespaces: NamespaceState[];
+  };
+};
+
+type RunAllResult = {
+  id: string;
+  provider: unknown;
+  namespaces: unknown[];
+};
+
+interface HubOptions {
+  store?: Store;
+}
+
+export class Hub {
+  #providers = new Map<string, AnyProvider>();
+  #options: HubOptions;
+
+  constructor(options?: HubOptions) {
+    this.#options = options ?? {};
+  }
+
+  init() {
+    this.runAll('init');
+  }
+
+  /*
+   * Running a specific action (e.g. init) on all namespaces and providers one by one.
+   *
+   *  TODO: Some of methods may accepts args, with this implementation we only limit to those one without any argument.
+   */
+  runAll(action: string): RunAllResult[] {
+    const output: RunAllResult[] = [];
+
+    const providers = this.#providers.values();
+
+    for (const provider of providers) {
+      const providerOutput: RunAllResult = {
+        id: provider.id,
+        provider: undefined,
+        namespaces: [],
+      };
+
+      const providerMethod = provider[action as keyof AnyProvider];
+      if (typeof providerMethod === 'function') {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore-next-line
+        providerOutput.provider = providerMethod.call(provider);
+      }
+
+      // Namespace instances can have their own `action` as well. we will call them as well.
+      const namespaces = provider.getAll().values();
+      for (const namespace of namespaces) {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore-next-line
+        const namespaceMethod = namespace[action];
+        if (typeof namespaceMethod === 'function') {
+          const result = namespaceMethod();
+          providerOutput.namespaces.push(result);
+        }
+      }
+
+      output.push(providerOutput);
+    }
+
+    return output;
+  }
+
+  add(id: string, provider: AnyProvider): this {
+    if (this.#options.store) {
+      provider.store(this.#options.store);
+    }
+    this.#providers.set(id, provider);
+    return this;
+  }
+
+  remove(id: string): this {
+    const providerToRemove = this.#providers.get(id);
+
+    if (!providerToRemove) {
+      throw new Error(`Provider not found: No provider exists with ID "${id}"`);
+    }
+
+    this.#options.store?.getState().providers.removeProvider(id);
+    this.#providers.delete(id);
+
+    return this;
+  }
+
+  get(providerId: string): AnyProvider | undefined {
+    return this.#providers.get(providerId);
+  }
+
+  getAll(): Map<string, AnyProvider> {
+    return this.#providers;
+  }
+
+  state(): HubState {
+    const output = this.runAll('state');
+    const res: HubState = {};
+
+    output.forEach((result) => {
+      const namespaces: NamespaceState[] = [];
+      result.namespaces.forEach((b) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const [getNamespaceState] = b as ReturnType<Namespace<any>['state']>;
+
+        namespaces.push(getNamespaceState());
+      });
+
+      const [getProviderState] = result.provider as ReturnType<
+        AnyProvider['state']
+      >;
+
+      res[result.id] = {
+        ...(getProviderState() || {}),
+        namespaces: namespaces,
+      };
+    });
+    return res;
+  }
+}

package/src/hub/mod.ts

@@ -0,0 +1,21 @@
+export type {
+  Actions,
+  Subscriber,
+  SubscriberCleanUp,
+  Context,
+} from './namespaces/mod.js';
+export { Namespace } from './namespaces/mod.js';
+
+export { Provider } from './provider/mod.js';
+export type { RegisteredNamespaces } from './provider/mod.js';
+
+export { Hub } from './hub.js';
+export type { Store, State, ProviderMetadata } from './store/mod.js';
+export {
+  createStore,
+  guessProviderStateSelector,
+  namespaceStateSelector,
+} from './store/mod.js';
+export { generateStoreId } from './helpers.js';
+export type { CanEagerConnect } from './namespaces/types.js';
+export type { FunctionWithContext, AnyFunction } from './types.js';

package/src/hub/namespaces/errors.ts

@@ -0,0 +1,11 @@
+export const ACTION_NOT_FOUND_ERROR = (name: string) =>
+  `Couldn't find "${name}" action. Are you sure you've added the action?`;
+
+export const OR_ELSE_ACTION_FAILED_ERROR = (name: string) =>
+  `An error occurred during running ${name}`;
+
+export const BEFORE_ACTION_FAILED_ERROR = (name: string) =>
+  `An error occurred during running before for "${name}" action`;
+
+export const NO_STORE_FOUND_ERROR =
+  'For setup store, you should set `store` first.';

package/src/hub/namespaces/mod.ts

@@ -0,0 +1,10 @@
+export type {
+  Subscriber,
+  SubscriberCleanUp,
+  State,
+  RegisteredActions as ActionsMap,
+  Context,
+  Actions,
+} from './types.js';
+
+export { Namespace } from './namespace.js';