@hub3js/core 0.59.0 → 0.59.1-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hub3js/core",
-  "version": "0.59.0",
+  "version": "0.59.1-next.0",
   "license": "MIT",
   "type": "module",
   "source": "./src/mod.ts",
@@ -11,64 +11,26 @@
       "types": "./dist/mod.d.ts",
       "default": "./dist/mod.js"
     },
-    "./legacy": {
-      "types": "./dist/legacy/mod.d.ts",
-      "default": "./dist/legacy/mod.js"
-    },
-    "./utils": {
-      "types": "./dist/utils/mod.d.ts",
-      "default": "./dist/utils/mod.js"
-    },
     "./store": {
       "types": "./dist/hub/store/mod.d.ts",
       "default": "./dist/hub/store/mod.js"
     },
-    "./namespaces/common": {
-      "types": "./dist/namespaces/common/mod.d.ts",
-      "default": "./dist/namespaces/common/mod.js"
-    },
-    "./namespaces/cosmos": {
-      "types": "./dist/namespaces/cosmos/mod.d.ts",
-      "default": "./dist/namespaces/cosmos/mod.js"
-    },
-    "./namespaces/evm": {
-      "types": "./dist/namespaces/evm/mod.d.ts",
-      "default": "./dist/namespaces/evm/mod.js"
-    },
-    "./namespaces/solana": {
-      "types": "./dist/namespaces/solana/mod.d.ts",
-      "default": "./dist/namespaces/solana/mod.js"
-    },
-    "./namespaces/starknet": {
-      "types": "./dist/namespaces/starknet/mod.d.ts",
-      "default": "./dist/namespaces/starknet/mod.js"
-    },
-    "./namespaces/sui": {
-      "types": "./dist/namespaces/sui/mod.d.ts",
-      "default": "./dist/namespaces/sui/mod.js"
-    },
-    "./namespaces/utxo": {
-      "types": "./dist/namespaces/utxo/mod.d.ts",
-      "default": "./dist/namespaces/utxo/mod.js"
-    },
-    "./namespaces/tron": {
-      "types": "./dist/namespaces/tron/mod.d.ts",
-      "default": "./dist/namespaces/tron/mod.js"
+    "./utils": {
+      "types": "./dist/utils/mod.d.ts",
+      "default": "./dist/utils/mod.js"
     },
-    "./namespaces/xrpl": {
-      "types": "./dist/namespaces/xrpl/mod.d.ts",
-      "default": "./dist/namespaces/xrpl/mod.js"
+    "./test-utils": {
+      "types": "./dist/test-utils/mod.d.ts",
+      "default": "./dist/test-utils/mod.js"
     }
   },
   "files": [
     "dist",
     "src",
-    "legacy",
-    "namespaces",
     "store"
   ],
   "scripts": {
-    "build": "yarn run rangutopia library build --inputs src/mod.ts,src/utils/mod.ts,src/legacy/mod.ts,src/hub/store/mod.ts,src/namespaces/evm/mod.ts,src/namespaces/solana/mod.ts,src/namespaces/cosmos/mod.ts,src/namespaces/utxo/mod.ts,src/namespaces/sui/mod.ts,src/namespaces/tron/mod.ts,src/namespaces/starknet/mod.ts,src/namespaces/xrpl/mod.ts,src/namespaces/common/mod.ts",
+    "build": "yarn run rangutopia library build --inputs src/mod.ts,src/hub/store/mod.ts,src/utils/mod.ts,src/test-utils/mod.ts",
     "ts-check": "tsc --declaration --emitDeclarationOnly -p tsconfig.json",
     "clean": "rimraf dist",
     "format": "prettier --write '{.,src}/**/*.{ts,tsx}'",
@@ -76,24 +38,11 @@
     "test": "vitest",
     "coverage": "vitest run --coverage"
   },
-  "peerDependencies": {
-    "@mysten/wallet-standard": "^0.13.26",
-    "@types/react": "^17.0.0 || ^18.0.0",
-    "react": "^17.0.0 || ^18.0.0",
-    "react-dom": "^17.0.0 || ^18.0.0",
-    "xrpl": "^4.2.0"
-  },
   "dependencies": {
-    "@chain-registry/types": "2.0.110",
-    "caip": "^1.1.1",
     "immer": "^10.0.4",
-    "rango-types": "^0.1.98",
+    "rango-types": "^0.5.0",
     "zustand": "^4.5.2"
   },
-  "devDependencies": {
-    "@mysten/wallet-standard": "^0.13.26",
-    "xrpl": "^4.2.0"
-  },
   "publishConfig": {
     "access": "public"
   }

package/src/builders/action.test.ts

@@ -0,0 +1,225 @@
+import type { Context } from '../hub/namespaces/mod.js';
+import type { FunctionWithContext } from '../hub/types.js';
+
+import { describe, expect, test, vi } from 'vitest';
+
+import { garbageWalletMetaData } from '../test-utils/fixtures.js';
+
+import { ActionBuilder } from './action.js';
+import { NamespaceBuilder } from './namespace.js';
+import { ProviderBuilder } from './provider.js';
+
+interface TestEvmActions {
+  connect: (chain: string) => Promise<{ accounts: string[]; network: string }>;
+  disconnect: () => void;
+}
+
+interface TestSolanaActions {
+  connect: () => Promise<string[]>;
+}
+
+describe('Provider built from multiple namespaces', () => {
+  const walletName = 'garbage-wallet';
+
+  test('connect runs the right action on each registered namespace', async () => {
+    const spyOnEvmConnect = vi.fn();
+    const evmConnect: FunctionWithContext<
+      TestEvmActions['connect'],
+      Context
+    > = async () => {
+      spyOnEvmConnect();
+      return {
+        accounts: ['eip155:0x1:0x000000000000000000000000000000000000dead'],
+        network: 'eth',
+      };
+    };
+
+    const spyOnSolanaConnect = vi.fn();
+    const solanaConnect: FunctionWithContext<
+      TestSolanaActions['connect'],
+      Context
+    > = async () => {
+      spyOnSolanaConnect();
+      return ['solana:mainnet:1nc1nerator11111111111111111111111111111111'];
+    };
+
+    const evmNamespace = new NamespaceBuilder<TestEvmActions>('evm', walletName)
+      .action('connect', evmConnect)
+      .build();
+    const solanaNamespace = new NamespaceBuilder<TestSolanaActions>(
+      'solana',
+      walletName,
+    )
+      .action('connect', solanaConnect)
+      .build();
+
+    const wallet = new ProviderBuilder(walletName)
+      .add('evm', evmNamespace)
+      .add('solana', solanaNamespace)
+      .config('metadata', garbageWalletMetaData)
+      .build();
+
+    const evmResult = await wallet.get('evm')?.connect('0x1');
+    const solanaResult = await wallet.get('solana')?.connect();
+
+    expect(evmResult?.accounts).toStrictEqual([
+      'eip155:0x1:0x000000000000000000000000000000000000dead',
+    ]);
+    expect(solanaResult).toStrictEqual([
+      'solana:mainnet:1nc1nerator11111111111111111111111111111111',
+    ]);
+    expect(spyOnEvmConnect).toBeCalledTimes(1);
+    expect(spyOnSolanaConnect).toBeCalledTimes(1);
+  });
+});
+
+describe('ActionBuilder integration with namespace', () => {
+  const walletName = 'garbage-wallet';
+
+  test('and-then transforms the action result; after hook runs', async () => {
+    const spyOnConnect = vi.fn();
+    const evmConnect: FunctionWithContext<
+      TestEvmActions['connect'],
+      Context
+    > = async () => {
+      spyOnConnect();
+      return {
+        accounts: [
+          '0x000000000000000000000000000000000000dead',
+          '0x0000000000000000000000000000000000000000',
+        ],
+        network: 'eth',
+      };
+    };
+
+    const andConnect = vi.fn(
+      (_context, result: { network: string; accounts: string[] }) => ({
+        network: result.network,
+        accounts: result.accounts.map((account) => `eip155:0x1:${account}`),
+      }),
+    );
+
+    const evmDisconnect = vi.fn();
+    const afterDisconnect = vi.fn();
+
+    const connectAction = new ActionBuilder<TestEvmActions, 'connect'>(
+      'connect',
+    )
+      .action(evmConnect)
+      .and(andConnect)
+      .build();
+
+    const disconnectAction = new ActionBuilder<TestEvmActions, 'disconnect'>(
+      'disconnect',
+    )
+      .action(evmDisconnect)
+      .after(afterDisconnect)
+      .build();
+
+    const evmNamespace = new NamespaceBuilder<TestEvmActions>('evm', walletName)
+      .action(connectAction)
+      .action(disconnectAction)
+      .build();
+
+    const wallet = new ProviderBuilder(walletName)
+      .add('evm', evmNamespace)
+      .config('metadata', garbageWalletMetaData)
+      .build();
+
+    const evmResult = await wallet.get('evm')?.connect('0x1');
+
+    expect(evmResult?.accounts).toStrictEqual([
+      'eip155:0x1:0x000000000000000000000000000000000000dead',
+      'eip155:0x1:0x0000000000000000000000000000000000000000',
+    ]);
+
+    await wallet.get('evm')?.connect('0x1');
+    wallet.get('evm')?.disconnect();
+
+    expect(spyOnConnect).toBeCalledTimes(2);
+    expect(andConnect).toBeCalledTimes(2);
+    expect(evmDisconnect).toBeCalledTimes(1);
+    expect(afterDisconnect).toBeCalledTimes(1);
+  });
+
+  test('and runs on success; or runs on throw; throw without or propagates', async () => {
+    const spyOnSuccessAndAction = vi.fn((_ctx, value) => value);
+    const spyOnThrowAndAction = vi.fn();
+    const spyOnThrowAndActionWithOr = vi.fn();
+    const spyOnSuccessOrAction = vi.fn();
+    const spyOnThrowOrAction = vi.fn();
+
+    interface GarbageActions {
+      successfulAction: () => string;
+      throwErrorAction: () => void;
+      throwErrorActionWithOr: () => void;
+    }
+
+    const successfulAction = new ActionBuilder<
+      GarbageActions,
+      'successfulAction'
+    >('successfulAction')
+      .action(() => 'yay!')
+      .and(spyOnSuccessAndAction)
+      .or(spyOnSuccessOrAction)
+      .build();
+
+    const throwErrorAction = new ActionBuilder<
+      GarbageActions,
+      'throwErrorAction'
+    >('throwErrorAction')
+      .action(() => {
+        throw new Error('whatever');
+      })
+      .and(spyOnThrowAndAction)
+      .build();
+
+    const throwErrorActionWithOr = new ActionBuilder<
+      GarbageActions,
+      'throwErrorActionWithOr'
+    >('throwErrorActionWithOr')
+      .action(() => {
+        throw new Error('whatever');
+      })
+      .and(spyOnThrowAndActionWithOr)
+      .or(spyOnThrowOrAction)
+      .build();
+
+    const namespace = new NamespaceBuilder<GarbageActions>('evm', walletName)
+      .action(successfulAction)
+      .action(throwErrorAction)
+      .action(throwErrorActionWithOr)
+      .build();
+
+    namespace.successfulAction();
+    expect(spyOnSuccessAndAction).toBeCalledTimes(1);
+    expect(spyOnSuccessAndAction).toHaveLastReturnedWith('yay!');
+    expect(spyOnSuccessOrAction).toBeCalledTimes(0);
+
+    expect(() => namespace.throwErrorAction()).toThrowError();
+    expect(spyOnThrowAndAction).toBeCalledTimes(0);
+
+    namespace.throwErrorActionWithOr();
+    expect(spyOnThrowAndActionWithOr).toBeCalledTimes(0);
+    expect(spyOnThrowOrAction).toBeCalledTimes(1);
+  });
+
+  test("'action-name' in namespace returns true for registered actions", () => {
+    interface GarbageActions {
+      garbageAction: () => string;
+    }
+
+    const garbageAction = new ActionBuilder<GarbageActions, 'garbageAction'>(
+      'garbageAction',
+    )
+      .action(() => 'yay!')
+      .build();
+
+    const namespace = new NamespaceBuilder<GarbageActions>('evm', walletName)
+      .action(garbageAction)
+      .build();
+
+    expect('garbageAction' in namespace).toBe(true);
+    expect('init' in namespace).toBe(true);
+  });
+});

package/src/builders/action.ts

@@ -1,5 +1,5 @@
 import type { Actions, Context, Operators } from '../hub/namespaces/types.js';
-import type { AnyFunction, FunctionWithContext } from '../types/actions.js';
+import type { AnyFunction, FunctionWithContext } from '../hub/types.js';
 
 export interface ActionByBuilder<T, Context> {
   actionName: keyof T;

package/src/builders/namespace.ts

@@ -2,7 +2,7 @@ import type { ActionByBuilder } from './action.js';
 import type { ProxiedNamespace } from './types.js';
 import type { Actions, ActionsMap, Context } from '../hub/namespaces/mod.js';
 import type { NamespaceConfig } from '../hub/store/mod.js';
-import type { FunctionWithContext } from '../types/actions.js';
+import type { FunctionWithContext } from '../hub/types.js';
 
 import { Namespace } from '../hub/mod.js';
 

package/src/builders/provider.ts

@@ -1,18 +1,42 @@
-import type { FindProxiedNamespace } from './types.js';
+import type { ProxiedNamespace } from './types.js';
+import type { Actions } from '../hub/namespaces/mod.js';
 import type {
-  CommonNamespaces,
   ExtendableInternalActions,
   ProviderBuilderOptions,
+  RegisteredNamespaces,
 } from '../hub/provider/mod.js';
 import type { ProviderConfig } from '../hub/store/mod.js';
 
 import { Provider } from '../hub/provider/mod.js';
 
-export class ProviderBuilder {
+/**
+ * Fluent builder for `Provider`. Each `.add(key, namespace)` call accumulates
+ * the registered namespace map into the `TNS` generic, so the resulting
+ * `Provider<TNS>` knows exactly which namespaces it owns.
+ *
+ * @example
+ * ```ts
+ * const phantom = new ProviderBuilder('phantom')
+ *   .config('metadata', meta)
+ *   .add('evm', evmNamespace)        // adds { evm: EvmActions }
+ *   .add('solana', solanaNamespace)  // adds { solana: SolanaActions }
+ *   .build();
+ * // Provider<{ evm: EvmActions; solana: SolanaActions }>
+ * ```
+ * `{}` is intentional: identity element under intersection so the first
+ * `.add(K, T)` produces `{} & Record<K, T> = Record<K, T>` and subsequent calls
+ * accumulate cleanly. Not the unsafe "any non-nullish" usage the rule targets.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export class ProviderBuilder<TNS = {}> {
   #id: string;
-  #namespaces = new Map();
+  /*
+   * Internal storage is opaque — types are recovered when `build()` produces
+   * the `Provider<TNS>`.
+   */
+  #namespaces = new Map<string, unknown>();
   #methods: ExtendableInternalActions = {};
-  #configs: Partial<ProviderConfig> = {};
+  #configs: Partial<ProviderConfig<TNS>> = {};
   #options: Partial<ProviderBuilderOptions>;
 
   constructor(id: string, options?: ProviderBuilderOptions) {
@@ -20,42 +44,58 @@ export class ProviderBuilder {
     this.#options = options || {};
   }
 
-  public add<K extends keyof CommonNamespaces>(
+  /**
+   * Register a namespace under `id`. Captures both the key and the namespace's
+   * action interface into the builder's `TNS` so subsequent operations are
+   * statically typed against the accumulated set.
+   */
+  public add<const K extends string, T extends Actions<T>>(
     id: K,
-    namespace: FindProxiedNamespace<K, CommonNamespaces>,
-  ) {
+    namespace: ProxiedNamespace<T>,
+  ): ProviderBuilder<TNS & Record<K, T>> {
     if (this.#options.store) {
       namespace.store(this.#options.store);
     }
     this.#namespaces.set(id, namespace);
-    return this;
+    return this as unknown as ProviderBuilder<TNS & Record<K, T>>;
   }
 
-  public config<K extends keyof ProviderConfig>(
+  public config<K extends keyof ProviderConfig<TNS>>(
     name: K,
-    value: ProviderConfig[K],
-  ) {
+    value: ProviderConfig<TNS>[K],
+  ): this {
     this.#configs[name] = value;
     return this;
   }
 
-  public init(cb: Exclude<ExtendableInternalActions['init'], undefined>) {
+  public init(cb: Exclude<ExtendableInternalActions['init'], undefined>): this {
     this.#methods.init = cb;
     return this;
   }
 
-  public build(): Provider {
+  public build(): Provider<TNS> {
     if (this.#isConfigsValid(this.#configs)) {
-      return new Provider(this.#id, this.#namespaces, this.#configs, {
-        extendInternalActions: this.#methods,
-        store: this.#options.store,
-      });
+      return new Provider<TNS>(
+        this.#id,
+        /*
+         * The runtime map is keyed by `string`; we re-view it through the
+         * builder's accumulated `TNS` for the typed `Provider` API.
+         */
+        this.#namespaces as unknown as RegisteredNamespaces<TNS>,
+        this.#configs,
+        {
+          extendInternalActions: this.#methods,
+          store: this.#options.store,
+        },
+      );
     }
 
     throw new Error('You need to set all required configs.');
   }
 
-  #isConfigsValid(config: Partial<ProviderConfig>): config is ProviderConfig {
+  #isConfigsValid(
+    config: Partial<ProviderConfig<TNS>>,
+  ): config is ProviderConfig<TNS> {
     return !!config.metadata;
   }
 }

package/src/builders/types.ts

@@ -16,11 +16,13 @@ export type ProxiedNamespace<T extends Actions<T>> = T &
   NamespacePublicValues;
 
 /**
- * This is useful when you gave a list of namespaces and want to map a key to corresponding namespace.
+ * Map a key into the corresponding proxied namespace inside a namespace set.
  *
- * e.g:
- * Type List = { evm: EvmActions, solana: SolanaActions};
- * FindProxiedNamespace<"solana", List>
+ * @example
+ * ```ts
+ * type List = { evm: EvmActions; solana: SolanaActions };
+ * FindProxiedNamespace<'solana', List>;   // ProxiedNamespace<SolanaActions>
+ * ```
  */
 export type FindProxiedNamespace<K extends keyof T, T> =
   T[K] extends Actions<T[K]> ? ProxiedNamespace<T[K]> : never;

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);
+  });
+});