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

package/src/hub/provider/provider.test.ts

@@ -0,0 +1,277 @@
+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 {
+  garbageWalletInfo,
+  garbageWalletMetaData,
+} from '../../test-utils/fixtures.js';
+import { createStore } from '../store/mod.js';
+
+import { Provider } from './provider.js';
+
+interface TestEvmActions {
+  connect: (chain: string) => Promise<{ accounts: string[]; network: string }>;
+}
+
+interface TestSolanaActions {
+  connect: () => Promise<string[]>;
+}
+
+type TestNamespaces = {
+  evm: TestEvmActions;
+  solana: TestSolanaActions;
+};
+
+describe('check providers', () => {
+  let namespaces: {
+    evm: NamespaceBuilder<TestEvmActions>;
+    solana: NamespaceBuilder<TestSolanaActions>;
+  };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let namespacesMap: Map<any, any>;
+  let store: Store;
+
+  beforeEach(() => {
+    store = createStore();
+    const evmNamespace = new NamespaceBuilder<TestEvmActions>(
+      'eip155',
+      'garbage',
+    );
+    const solanaNamespace = new NamespaceBuilder<TestSolanaActions>(
+      'solana',
+      'garbage',
+    );
+
+    namespaces = {
+      evm: evmNamespace,
+      solana: solanaNamespace,
+    };
+
+    namespacesMap = new Map();
+    namespacesMap.set('evm', evmNamespace.build());
+    namespacesMap.set('solana', solanaNamespace.build());
+
+    return () => {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore-next-line
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      ((store = undefined), (namespaces = undefined));
+    };
+  });
+
+  test('Initialize providers correctly', () => {
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+    );
+
+    const allNamespaces = provider.getAll();
+
+    expect(allNamespaces.size).toBe(2);
+  });
+
+  test('throw error if state() is called before store initialization', () => {
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+    );
+
+    expect(() => provider.state()).toThrowError();
+  });
+
+  test('should return wallet info via info() without store initialization', () => {
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+    );
+
+    expect(provider.info()).toBe(garbageWalletInfo);
+  });
+
+  test('should return wallet info via info() after store initialization', () => {
+    const store = createStore();
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+      {
+        store,
+      },
+    );
+
+    expect(provider.info()).toMatchObject(
+      store.getState().providers.list['garbage'].config,
+    );
+  });
+
+  test('access state correctly', () => {
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+      {
+        store: createStore(),
+      },
+    );
+
+    const [getState, setState] = provider.state();
+
+    expect(getState().connected).toBe(false);
+    expect(getState('connected')).toBe(false);
+    expect(() => {
+      // @ts-expect-error intentionally using an state that doesn't exist.
+      getState('not_exist_state');
+    }).toThrowError();
+    expect(() => {
+      // @ts-expect-error intentionally using an state that doesn't exist and try to update.
+      setState('another_not_exist_state');
+    }).toThrowError();
+  });
+  test('update state properly', () => {
+    const store = createStore();
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+      {
+        store,
+      },
+    );
+
+    const [getState, setState] = provider.state();
+
+    provider.store(store);
+    setState('installed', true);
+    const isInstalled = getState('installed');
+    expect(isInstalled).toBe(true);
+  });
+
+  test('run namespace actions from provider', async () => {
+    const { evm, solana } = namespaces;
+    solana.action('connect', async () => [
+      'solana:mainnet:0x000000000000000000000000000000000000dead',
+    ]);
+    const testNamespaces = new Map();
+    testNamespaces.set('evm', evm.build());
+    testNamespaces.set('solana', solana.build());
+
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      testNamespaces,
+      garbageWalletInfo,
+    );
+
+    const result = await provider.get('solana')?.connect();
+
+    expect(result).toStrictEqual([
+      'solana:mainnet:0x000000000000000000000000000000000000dead',
+    ]);
+    // Since we didn't add any action regarding connect for `evm`
+    await expect(async () =>
+      provider.get('evm')?.connect('0x1'),
+    ).rejects.toThrowError();
+  });
+
+  test('sets config properly', () => {
+    const builder = new ProviderBuilder('garbage');
+    builder.config('metadata', garbageWalletMetaData);
+    const provider = builder.build().store(store);
+
+    expect(provider.info()?.metadata).toStrictEqual(garbageWalletMetaData);
+  });
+
+  test('.init should works on Provider', () => {
+    const builder = new ProviderBuilder('garbage').config(
+      'metadata',
+      garbageWalletMetaData,
+    );
+    let count = 0;
+    builder.init(() => {
+      count++;
+    });
+    const provider = builder.build().store(store);
+    expect(count).toBe(0);
+    provider.init();
+    provider.init();
+    provider.init();
+    expect(count).toBe(1);
+  });
+
+  test(".init shouldn't do anything when use hasn't set anything", () => {
+    const builder = new ProviderBuilder('garbage').config(
+      'metadata',
+      garbageWalletMetaData,
+    );
+    const provider = builder.build().store(store);
+    expect(() => {
+      provider.init();
+      provider.init();
+      provider.init();
+    }).not.toThrow();
+  });
+
+  test('A provider can be found using its namespace', () => {
+    const builder = new ProviderBuilder('garbage', { store }).config(
+      'metadata',
+      garbageWalletMetaData,
+    );
+
+    const { evm, solana } = namespaces;
+    builder.add('evm', evm.build()).add('solana', solana.build());
+    const provider = builder.build();
+
+    const result = provider.findByNamespace('solana');
+    expect(result).toBeDefined();
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore-next-line
+    expect(result?.namespaceId).toBe('solana');
+
+    const result2 = provider.findByNamespace('evm');
+    expect(result2).toBeUndefined();
+  });
+
+  test('`before/after` is calling with correct context ', () => {
+    const connect = vi.fn();
+    const before = vi.fn(function (context) {
+      const [, setState] = context.state();
+      setState('installed', true);
+    });
+    const after = vi.fn(function (context) {
+      const [, setState] = context.state();
+      setState('installed', false);
+    });
+
+    const { evm } = namespaces;
+    const evmNamespace = evm.action('connect', connect).build();
+
+    const builder = new ProviderBuilder('garbage', { store })
+      .add('evm', evmNamespace)
+      .config('metadata', garbageWalletMetaData);
+    const provider = builder.build();
+
+    const [getState] = provider.state();
+    const result = provider.get('evm');
+
+    // Adding `after` then make it will run
+    provider.before('connect', before);
+    void result?.connect('whatever');
+
+    expect(connect).toBeCalledTimes(1);
+    expect(before).toBeCalledTimes(1);
+    expect(getState('installed')).toBe(true);
+
+    // Adding `after` then make it will run
+    provider.after('connect', after);
+    void result?.connect('whatever');
+    expect(connect).toBeCalledTimes(2);
+    expect(after).toBeCalledTimes(1);
+
+    expect(getState('installed')).toBe(false);
+  });
+});

package/src/hub/provider/provider.ts

@@ -0,0 +1,286 @@
+import type {
+  Context,
+  ExtendableInternalActions,
+  GetState,
+  RegisteredNamespaces,
+  SetState,
+  State,
+} from './types.js';
+import type { FindProxiedNamespace } from '../../builders/mod.js';
+import type { ProviderConfig, ProviderInfo, Store } from '../store/mod.js';
+import type { AnyFunction, FunctionWithContext } from '../types.js';
+
+const VERSION = '1.0';
+
+/**
+ * A `Provider` represents one wallet/integration and owns the set of namespaces
+ * that wallet exposes (e.g. `evm`, `solana`).
+ *
+ * The `TNS` generic captures exactly which namespaces this provider supports.
+ * It's normally inferred by `ProviderBuilder` from chained `.add()` calls, so
+ * `phantom.get('cosmos')` is a compile-time error if Phantom never registered
+ * `cosmos`. Construct directly only when you have a precise namespace shape
+ * to pass via `new Provider<MyNamespaces>(...)`.
+ */
+export class Provider<TNS = unknown> {
+  public readonly id: string;
+  public readonly version = VERSION;
+
+  #namespaces: RegisteredNamespaces<TNS>;
+  #initiated = false;
+  #extendInternalActions: ExtendableInternalActions = {};
+  #store: Store | undefined;
+  #configs: ProviderConfig<TNS>;
+
+  constructor(
+    id: string,
+    namespaces: RegisteredNamespaces<TNS>,
+    configs: ProviderConfig<TNS>,
+    options?: {
+      /**
+       * There are some cases we need to have a behavior like initializing a provider which will be run when we are creating an instance.
+       * These internal steps and behaviors will be useful for library user to extend the behavior by running a specific code.
+       */
+      extendInternalActions?: ExtendableInternalActions;
+      store?: Store;
+    },
+  ) {
+    this.id = id;
+    this.#configs = configs;
+    // it should be only created here, to make sure `after/before` will work properly.
+    this.#extendInternalActions = options?.extendInternalActions || {};
+    this.#namespaces = namespaces;
+
+    /**
+     * Our assumption is that the store will be optional for the provider.
+     * If a store is provided in the options, it will be initialized and set up.
+     */
+    if (options?.store) {
+      this.#store = options.store;
+      this.#setupStore();
+    }
+  }
+
+  /**
+   * This is an special callback that will be called **only once**.
+   * We don't call this in `constructor` and developer should call this manually. we only ensure it will be called once.
+   *
+   * ```ts
+   * const myInit = () => {  whatever; }   *
+   * const provider = new Provider(..., {extendInternalActions: {init: myInit} });
+   *
+   * // Will run `myInit`
+   * provider.init()
+   *
+   * // Will not run `myInit` anymore.
+   * provider.init()
+   * provider.init()
+   * ```
+   */
+  public init(): void {
+    if (this.#initiated) {
+      return;
+    }
+
+    const definedInitByUser = this.#extendInternalActions.init;
+    if (definedInitByUser) {
+      definedInitByUser(this.#context());
+    }
+
+    this.#initiated = true;
+  }
+
+  /**
+   * Getting state of a provider.
+   *
+   * @example
+   * ```ts
+   * const provider = new Provider(...);
+   * const [getState, setState] = provider.state();
+   *
+   * getState('installed');
+   * // or
+   * getState().installed;
+   * ```
+   */
+  public state(): [GetState, SetState] {
+    const store = this.#store;
+    if (!store) {
+      throw new Error(
+        `Any store detected for ${this.id}. You need to set your store using '.store' method first.`,
+      );
+    }
+
+    const setState: SetState = (name, value) => {
+      switch (name) {
+        case 'installed':
+          return store.getState().providers.updateStatus(this.id, name, value);
+        default:
+          throw new Error(
+            `Unhandled state update for provider. (provider id: ${this.id}, state name: ${name})`,
+          );
+      }
+    };
+
+    const getState: GetState = <K extends keyof State>(name?: K) => {
+      const state: State = store
+        .getState()
+        .providers.guessNamespacesState(this.id);
+
+      if (!name) {
+        return state;
+      }
+
+      switch (name) {
+        case 'installed':
+        case 'connected':
+        case 'connecting':
+          return state[name];
+        default:
+          throw new Error('Unhandled state for provider');
+      }
+    };
+
+    return [getState, setState];
+  }
+
+  /**
+   * For keeping state, we need a store. all the states will be write to/read from store.
+   *
+   * **Note: When you are setting an store for provider, it will be set for its namespaces automatically as well**
+   */
+  public store(store: Store): this {
+    if (this.#store) {
+      console.warn(
+        "You've already set an store for your Provider. Old store will be replaced by the new one.",
+      );
+    }
+    this.#store = store;
+    this.#setupStore();
+    return this;
+  }
+
+  /**
+   * Getting information about a provider which has been set on constructing Provider.
+   */
+  public info(): ProviderInfo<TNS> | undefined {
+    const store = this.#store;
+    if (!store) {
+      return this.#configs;
+    }
+    const config = store.getState().providers.list[this.id].config;
+
+    return { metadata: config.metadata };
+  }
+
+  /**
+   * A list of registered _proxied_ namespaces.
+   */
+  public getAll(): RegisteredNamespaces<TNS> {
+    return this.#namespaces;
+  }
+
+  /**
+   * Get a registered namespace in provider by its **namespace key**.
+   *
+   * Note: difference between namespace key and namespace id is the first one
+   * is the key under which the namespace is registered (the `K` in `.add(K, ns)`),
+   * and the second one is the runtime `namespaceId` (e.g. `'eip155'`) chosen
+   * when constructing the namespace itself.
+   */
+  public get<K extends keyof TNS>(
+    id: K,
+  ): FindProxiedNamespace<K, TNS> | undefined {
+    return this.#namespaces.get(id) as FindProxiedNamespace<K, TNS> | undefined;
+  }
+
+  /**
+   * Get a registered namespace by its **namespaceId** (the runtime id chosen
+   * when constructing the namespace). Returns the union of all namespaces this
+   * provider supports — caller is expected to discriminate via `namespaceId`.
+   *
+   * @example
+   * ```ts
+   * const provider = new Provider(...);
+   * provider.findByNamespace("whatever-id-i-set-for-namespace")
+   * ```
+   */
+  public findByNamespace(
+    namespaceLookingFor: string,
+  ): FindProxiedNamespace<keyof TNS, TNS> | undefined {
+    let result: FindProxiedNamespace<keyof TNS, TNS> | undefined = undefined;
+
+    this.#namespaces.forEach((namespace) => {
+      if (namespace.namespaceId === namespaceLookingFor) {
+        result = namespace;
+      }
+    });
+
+    return result;
+  }
+
+  /**
+   * Running a hook function _before_ a specific action for **all registered namespaces**.
+   */
+  public before(
+    actionName: string,
+    hookFn: FunctionWithContext<AnyFunction, Context>,
+  ): this {
+    this.#addHook('before', actionName, hookFn);
+    return this;
+  }
+
+  /**
+   * Running a hook function _after_ a specific action for **all registered namespaces**.
+   */
+  public after(
+    actionName: string,
+    hookFn: FunctionWithContext<AnyFunction, Context>,
+  ): this {
+    this.#addHook('after', actionName, hookFn);
+    return this;
+  }
+
+  #addHook(
+    hookName: 'after' | 'before',
+    actionName: string,
+    cb: FunctionWithContext<AnyFunction, Context>,
+  ): this {
+    const context = {
+      state: this.state.bind(this),
+    };
+
+    this.#namespaces.forEach((namespace) => {
+      if (hookName === 'after') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        namespace.after(actionName as any, cb, { context });
+      } else if (hookName === 'before') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        namespace.before(actionName as any, cb, { context });
+      } else {
+        throw new Error(`Your hook name is invalid: ${hookName}`);
+      }
+    });
+
+    return this;
+  }
+
+  #setupStore(): void {
+    const store = this.#store;
+    if (!store) {
+      throw new Error('For setup store, you should set `store` first.');
+    }
+    store
+      .getState()
+      .providers.addProvider(this.id, this.#configs as ProviderConfig);
+    this.#namespaces.forEach((namespace) => {
+      namespace.store(store);
+    });
+  }
+
+  #context(): Context {
+    return {
+      state: this.state.bind(this),
+    };
+  }
+}

package/src/hub/provider/types.ts

@@ -0,0 +1,37 @@
+import type { FindProxiedNamespace } from '../../builders/mod.js';
+import type { Store } from '../mod.js';
+import type { AnyFunction, FunctionWithContext } from '../types.js';
+
+export type Context = {
+  state: () => [GetState, SetState];
+};
+
+export interface State {
+  installed: boolean;
+  connected: boolean;
+  connecting: boolean;
+}
+
+export type SetState = <K extends keyof Pick<State, 'installed'>>(
+  name: K,
+  value: State[K],
+) => void;
+export type GetState = {
+  (): State;
+  <K extends keyof State>(name: K): State[K];
+};
+
+export interface ExtendableInternalActions {
+  init?: FunctionWithContext<AnyFunction, Context>;
+}
+
+/**
+ * The internal `Provider.#namespaces` map type — keys are the registered
+ * namespace ids, values are their corresponding proxied namespaces.
+ */
+export type RegisteredNamespaces<T> = Map<
+  keyof T,
+  FindProxiedNamespace<keyof T, T>
+>;
+
+export type ProviderBuilderOptions = { store?: Store };

package/src/hub/store/events.ts

@@ -0,0 +1,89 @@
+export type NamespaceDisconnectedEvent = {
+  type: 'namespace_disconnected';
+  provider: string;
+  namespace: string;
+};
+
+export type NamespaceConnectedEvent = {
+  type: 'namespace_connected';
+  provider: string;
+  namespace: string;
+  accounts: string[];
+};
+
+export type NamespaceSwitchedAccountEvent = {
+  type: 'namespace_account_switched';
+  provider: string;
+  namespace: string;
+  accounts: string[];
+  previousAccounts: string[];
+};
+
+export type NamespaceSwitchedNetworkEvent = {
+  type: 'namespace_network_switched';
+  provider: string;
+  namespace: string;
+  network: string;
+  previousNetwork: string | null;
+};
+
+export type ProviderDetectedEvent = {
+  type: 'provider_detected';
+  provider: string;
+};
+
+export type ProviderConnectingEvent = {
+  type: 'provider_connecting';
+  provider: string;
+  value: boolean;
+};
+
+export type ProviderConnectedEvent = {
+  type: 'provider_connected';
+  provider: string;
+};
+
+export type ProviderDisconnectedEvent = {
+  type: 'provider_disconnected';
+  provider: string;
+};
+
+export type Event =
+  | NamespaceDisconnectedEvent
+  | NamespaceConnectedEvent
+  | NamespaceSwitchedAccountEvent
+  | NamespaceSwitchedNetworkEvent
+  | ProviderDetectedEvent
+  | ProviderConnectingEvent
+  | ProviderConnectedEvent
+  | ProviderDisconnectedEvent;
+
+/**
+ *
+ * Keeping an array of Event and when iterates over its values, it will be removed (consume) from the array.
+ *
+ */
+export class ConsumableEvents {
+  #data: Event[] = [];
+
+  push(val: Event) {
+    this.#data.push(val);
+  }
+
+  [Symbol.iterator](): Iterator<Event> {
+    return {
+      next: (): IteratorResult<Event> => {
+        if (this.#data.length == 0) {
+          return { done: true, value: undefined };
+        }
+
+        // Typescript can not narrow the type, but we have a runtime check to ensure it will never be an empty list
+        const value = this.#data.shift()!;
+        return {
+          done: false,
+          value,
+        };
+      },
+    };
+  }
+}