@hub3js/core 0.59.0 → 0.59.1-next.1

package/src/hub/hub.ts

@@ -2,6 +2,23 @@ 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[];
@@ -17,8 +34,9 @@ type RunAllResult = {
 interface HubOptions {
   store?: Store;
 }
+
 export class Hub {
-  #providers = new Map<string, Provider>();
+  #providers = new Map<string, AnyProvider>();
   #options: HubOptions;
 
   constructor(options?: HubOptions) {
@@ -37,18 +55,16 @@ export class Hub {
   runAll(action: string): RunAllResult[] {
     const output: RunAllResult[] = [];
 
-    // run action on all providers eagerConnect, disconnect
     const providers = this.#providers.values();
 
     for (const provider of providers) {
-      // Calling `action` on `Provider` if exists.
       const providerOutput: RunAllResult = {
         id: provider.id,
         provider: undefined,
         namespaces: [],
       };
 
-      const providerMethod = provider[action as keyof Provider];
+      const providerMethod = provider[action as keyof AnyProvider];
       if (typeof providerMethod === 'function') {
         // eslint-disable-next-line @typescript-eslint/ban-ts-comment
         // @ts-ignore-next-line
@@ -73,14 +89,15 @@ export class Hub {
     return output;
   }
 
-  add(id: string, provider: Provider) {
+  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) {
+
+  remove(id: string): this {
     const providerToRemove = this.#providers.get(id);
 
     if (!providerToRemove) {
@@ -93,11 +110,11 @@ export class Hub {
     return this;
   }
 
-  get(providerId: string): Provider | undefined {
+  get(providerId: string): AnyProvider | undefined {
     return this.#providers.get(providerId);
   }
 
-  getAll() {
+  getAll(): Map<string, AnyProvider> {
     return this.#providers;
   }
 
@@ -115,7 +132,7 @@ export class Hub {
       });
 
       const [getProviderState] = result.provider as ReturnType<
-        Provider['state']
+        AnyProvider['state']
       >;
 
       res[result.id] = {

package/src/hub/mod.ts

@@ -1,4 +1,5 @@
 export type {
+  Actions,
   Subscriber,
   SubscriberCleanUp,
   Context,
@@ -6,7 +7,7 @@ export type {
 export { Namespace } from './namespaces/mod.js';
 
 export { Provider } from './provider/mod.js';
-export type { CommonNamespaces, CommonNamespaceKeys } 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';

package/src/hub/namespaces/namespace.ts

@@ -8,12 +8,12 @@ import type {
   SetState,
   State,
 } from './types.js';
+import type { NamespaceConfig, Store } from '../store/mod.js';
 import type {
   AndFunction,
   AnyFunction,
   FunctionWithContext,
-} from '../../types/actions.js';
-import type { NamespaceConfig, Store } from '../store/mod.js';
+} from '../types.js';
 
 import { generateStoreId, isAsync } from '../helpers.js';
 

package/src/hub/namespaces/types.ts

@@ -1,5 +1,5 @@
-import type { AnyFunction, FunctionWithContext } from '../../types/actions.js';
 import type { NamespaceData } from '../store/mod.js';
+import type { AnyFunction, FunctionWithContext } from '../types.js';
 
 type ActionName<K> = K | Omit<K, string>;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/hub/provider/mod.ts

@@ -1,7 +1,6 @@
 export type {
   ExtendableInternalActions,
-  CommonNamespaces,
-  CommonNamespaceKeys,
+  RegisteredNamespaces,
   State,
   Context,
   ProviderBuilderOptions,

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

@@ -1,5 +1,3 @@
-import type { EvmActions } from '../../namespaces/evm/types.js';
-import type { SolanaActions } from '../../namespaces/solana/types.js';
 import type { Store } from '../store/mod.js';
 
 import { beforeEach, describe, expect, test, vi } from 'vitest';
@@ -14,10 +12,23 @@ 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<EvmActions>;
-    solana: NamespaceBuilder<SolanaActions>;
+    evm: NamespaceBuilder<TestEvmActions>;
+    solana: NamespaceBuilder<TestSolanaActions>;
   };
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let namespacesMap: Map<any, any>;
@@ -25,8 +36,11 @@ describe('check providers', () => {
 
   beforeEach(() => {
     store = createStore();
-    const evmNamespace = new NamespaceBuilder<EvmActions>('eip155', 'garbage');
-    const solanaNamespace = new NamespaceBuilder<SolanaActions>(
+    const evmNamespace = new NamespaceBuilder<TestEvmActions>(
+      'eip155',
+      'garbage',
+    );
+    const solanaNamespace = new NamespaceBuilder<TestSolanaActions>(
       'solana',
       'garbage',
     );
@@ -49,7 +63,11 @@ describe('check providers', () => {
   });
 
   test('Initialize providers correctly', () => {
-    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo);
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+    );
 
     const allNamespaces = provider.getAll();
 
@@ -57,22 +75,35 @@ describe('check providers', () => {
   });
 
   test('throw error if state() is called before store initialization', () => {
-    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo);
+    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('garbage', namespacesMap, garbageWalletInfo);
+    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('garbage', namespacesMap, garbageWalletInfo, {
-      store,
-    });
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+      {
+        store,
+      },
+    );
 
     expect(provider.info()).toMatchObject(
       store.getState().providers.list['garbage'].config,
@@ -80,9 +111,14 @@ describe('check providers', () => {
   });
 
   test('access state correctly', () => {
-    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo, {
-      store: createStore(),
-    });
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+      {
+        store: createStore(),
+      },
+    );
 
     const [getState, setState] = provider.state();
 
@@ -99,9 +135,14 @@ describe('check providers', () => {
   });
   test('update state properly', () => {
     const store = createStore();
-    const provider = new Provider('garbage', namespacesMap, garbageWalletInfo, {
-      store,
-    });
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      namespacesMap,
+      garbageWalletInfo,
+      {
+        store,
+      },
+    );
 
     const [getState, setState] = provider.state();
 
@@ -120,7 +161,11 @@ describe('check providers', () => {
     testNamespaces.set('evm', evm.build());
     testNamespaces.set('solana', solana.build());
 
-    const provider = new Provider('garbage', testNamespaces, garbageWalletInfo);
+    const provider = new Provider<TestNamespaces>(
+      'garbage',
+      testNamespaces,
+      garbageWalletInfo,
+    );
 
     const result = await provider.get('solana')?.connect();
 

package/src/hub/provider/provider.ts

@@ -1,5 +1,4 @@
 import type {
-  CommonNamespaces,
   Context,
   ExtendableInternalActions,
   GetState,
@@ -8,25 +7,35 @@ import type {
   State,
 } from './types.js';
 import type { FindProxiedNamespace } from '../../builders/mod.js';
-import type { AnyFunction, FunctionWithContext } from '../../types/actions.js';
 import type { ProviderConfig, ProviderInfo, Store } from '../store/mod.js';
+import type { AnyFunction, FunctionWithContext } from '../types.js';
 
 const VERSION = '1.0';
 
-export class Provider {
+/**
+ * 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<keyof CommonNamespaces, CommonNamespaces>;
+  #namespaces: RegisteredNamespaces<TNS>;
   #initiated = false;
   #extendInternalActions: ExtendableInternalActions = {};
   #store: Store | undefined;
-  #configs: ProviderConfig;
+  #configs: ProviderConfig<TNS>;
 
   constructor(
     id: string,
-    namespaces: RegisteredNamespaces<keyof CommonNamespaces, CommonNamespaces>,
-    configs: ProviderConfig,
+    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.
@@ -82,11 +91,7 @@ export class Provider {
   }
 
   /**
-   * Getting state of a provider
-   *
-   * **Note:**
-   *    Each namespace has it's own state as well, in Legacy we didn't have this separation and all of them was accessible through Provider itself
-   *    To be compatible with legacy, `getState` has a logic to guess the final state to produce same state as legacy.
+   * Getting state of a provider.
    *
    * @example
    * ```ts
@@ -97,7 +102,6 @@ export class Provider {
    * // or
    * getState().installed;
    * ```
-   *
    */
   public state(): [GetState, SetState] {
     const store = this.#store;
@@ -107,9 +111,6 @@ export class Provider {
       );
     }
 
-    /**
-     * State updater
-     */
     const setState: SetState = (name, value) => {
       switch (name) {
         case 'installed':
@@ -121,9 +122,6 @@ export class Provider {
       }
     };
 
-    /**
-     * State getter
-     */
     const getState: GetState = <K extends keyof State>(name?: K) => {
       const state: State = store
         .getState()
@@ -150,13 +148,6 @@ export class Provider {
    * 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**
-   *
-   * @example
-   * ```ts
-   * const myStore = createStore();
-   * const provider = new Provider(...);
-   * provider.store(myStore); // or it can be passed to Provider constructor;
-   * ```
    */
   public store(store: Store): this {
     if (this.#store) {
@@ -171,16 +162,8 @@ export class Provider {
 
   /**
    * Getting information about a provider which has been set on constructing Provider.
-   *
-   * @example
-   * ```ts
-   * const walletInfo = {name: "Garbage wallet", ...}
-   * const provider = new Provider(..., {info: walletInfo});
-   *
-   * provider.info();
-   * ```
    */
-  public info(): ProviderInfo | undefined {
+  public info(): ProviderInfo<TNS> | undefined {
     const store = this.#store;
     if (!store) {
       return this.#configs;
@@ -192,40 +175,29 @@ export class Provider {
 
   /**
    * A list of registered _proxied_ namespaces.
-   *
-   * @example
-   * ```ts
-   *  const provider = new Provider(...);
-   *  const allNamespaces = provider.getAll();
-   * ```
    */
-  public getAll(): RegisteredNamespaces<
-    keyof CommonNamespaces,
-    CommonNamespaces
-  > {
+  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 setting from a predefined list the second one can be anything and will be chosen by library's user.
-   *
-   * @param {string} id - evm, solana, cosmos, ... (CommonActions)
+   * 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 CommonNamespaces>(
+  public get<K extends keyof TNS>(
     id: K,
-  ): FindProxiedNamespace<K, CommonNamespaces> | undefined {
-    return this.#namespaces.get(id) as unknown as
-      | FindProxiedNamespace<K, CommonNamespaces>
-      | undefined;
+  ): FindProxiedNamespace<K, TNS> | undefined {
+    return this.#namespaces.get(id) as FindProxiedNamespace<K, TNS> | undefined;
   }
 
   /**
-   *
-   * Get a registered namespace by its **namespaceId**.
-   *
-   * Note: difference between namespace key and namespace id is the first one is setting from a predefined list the second one can be anything and will be chosen by library's user.
+   * 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
@@ -233,11 +205,10 @@ export class Provider {
    * provider.findByNamespace("whatever-id-i-set-for-namespace")
    * ```
    */
-  public findByNamespace<K extends keyof CommonNamespaces>(
-    namespaceLookingFor: K | string,
-  ): FindProxiedNamespace<K, CommonNamespaces> | undefined {
-    // If we didn't found any match, we will return `undefined`.
-    let result: object | undefined = undefined;
+  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) {
@@ -249,16 +220,7 @@ export class Provider {
   }
 
   /**
-   * Running a hook function _after_ a specific action for **all registered namespaces**.
-   *
-   * **Note:** the context can be set from outside as well. this is useful for Provider to set its context instead of namespace context.
-   *
-   * @example
-   * ```ts
-   *  const provider = new Provider(...);
-   *
-   *  provider.after("connect", (context) => {});
-   * ```
+   * Running a hook function _before_ a specific action for **all registered namespaces**.
    */
   public before(
     actionName: string,
@@ -269,16 +231,7 @@ export class Provider {
   }
 
   /**
-   * Running a hook function _before_ a specific action for **all registered namespaces**.
-   *
-   * **Note:** the context can be set from outside as well. this is useful for Provider to set its context instead of namespace context.
-   *
-   * @example
-   * ```ts
-   *  const provider = new Provider(...);
-   *
-   *  provider.after("connect", (context) => {});
-   * ```
+   * Running a hook function _after_ a specific action for **all registered namespaces**.
    */
   public after(
     actionName: string,
@@ -300,16 +253,12 @@ export class Provider {
     this.#namespaces.forEach((namespace) => {
       if (hookName === 'after') {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        namespace.after(actionName as any, cb, {
-          context,
-        });
+        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,
-        });
+        namespace.before(actionName as any, cb, { context });
       } else {
-        throw new Error(`You hook name is invalid: ${hookName}`);
+        throw new Error(`Your hook name is invalid: ${hookName}`);
       }
     });
 
@@ -321,9 +270,11 @@ export class Provider {
     if (!store) {
       throw new Error('For setup store, you should set `store` first.');
     }
-    store.getState().providers.addProvider(this.id, this.#configs);
-    this.#namespaces.forEach((provider) => {
-      provider.store(store);
+    store
+      .getState()
+      .providers.addProvider(this.id, this.#configs as ProviderConfig);
+    this.#namespaces.forEach((namespace) => {
+      namespace.store(store);
     });
   }
 

package/src/hub/provider/types.ts

@@ -1,25 +1,17 @@
 import type { FindProxiedNamespace } from '../../builders/mod.js';
-import type { LegacyState } from '../../legacy/mod.js';
-import type { CosmosActions } from '../../namespaces/cosmos/mod.js';
-import type { EvmActions } from '../../namespaces/evm/mod.js';
-import type { SolanaActions } from '../../namespaces/solana/mod.js';
-import type { StarknetActions } from '../../namespaces/starknet/types.js';
-import type { SuiActions } from '../../namespaces/sui/mod.js';
-import type { TronActions } from '../../namespaces/tron/types.js';
-import type { UtxoActions } from '../../namespaces/utxo/mod.js';
-import type { XRPLActions } from '../../namespaces/xrpl/mod.js';
-import type { AnyFunction, FunctionWithContext } from '../../types/actions.js';
-import type { Prettify } from '../../types/utils.js';
 import type { Store } from '../mod.js';
+import type { AnyFunction, FunctionWithContext } from '../types.js';
 
 export type Context = {
   state: () => [GetState, SetState];
 };
 
-export type State = Omit<
-  LegacyState,
-  'reachable' | 'accounts' | 'network' | 'derivationPath'
->;
+export interface State {
+  installed: boolean;
+  connected: boolean;
+  connecting: boolean;
+}
+
 export type SetState = <K extends keyof Pick<State, 'installed'>>(
   name: K,
   value: State[K],
@@ -29,26 +21,17 @@ export type GetState = {
   <K extends keyof State>(name: K): State[K];
 };
 
-export interface CommonNamespaces {
-  evm: EvmActions;
-  solana: SolanaActions;
-  cosmos: CosmosActions;
-  sui: SuiActions;
-  utxo: UtxoActions;
-  tron: TronActions;
-  starknet: StarknetActions;
-  xrpl: XRPLActions;
-}
-
-export type CommonNamespaceKeys = Prettify<keyof CommonNamespaces>;
-
 export interface ExtendableInternalActions {
   init?: FunctionWithContext<AnyFunction, Context>;
 }
 
-export type RegisteredNamespaces<K extends keyof T, T> = Map<
-  K,
-  FindProxiedNamespace<K, T>
+/**
+ * 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/mod.ts

@@ -20,6 +20,7 @@ export type {
   ProviderMetadata,
   ProviderConfig,
   ProviderInfo,
+  ProviderProperty,
 } from './providers.js';
 export type { NamespaceConfig, NamespaceData } from './namespaces.js';
 export { createStore } from './store.js';