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

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

@@ -0,0 +1,86 @@
+import type { Actions, Context, Operators } from '../hub/namespaces/types.js';
+import type { AnyFunction, FunctionWithContext } from '../hub/types.js';
+
+export interface ActionByBuilder<T, Context> {
+  actionName: keyof T;
+  and: Operators<T>;
+  or: Operators<T>;
+  after: Operators<T>;
+  before: Operators<T>;
+  action: FunctionWithContext<T[keyof T], Context>;
+}
+
+/*
+ * TODO:
+ * Currently, to use this builder you will write something like this:
+ * new ActionBuilder<EvmActions, 'disconnect'>('disconnect').after(....)
+ *
+ * I couldn't figure it out to be able typescript infer the constructor value as key of actions.
+ * Ideal usage:
+ * new ActionBuilder<EvmActions>('disconnect').after(....)
+ *
+ */
+export class ActionBuilder<T extends Actions<T>, K extends keyof T> {
+  readonly name: K;
+  #and: Operators<T> = new Map();
+  #or: Operators<T> = new Map();
+  #after: Operators<T> = new Map();
+  #before: Operators<T> = new Map();
+  #action: FunctionWithContext<T[keyof T], Context<T>> | undefined;
+
+  constructor(name: K) {
+    this.name = name;
+  }
+
+  public and(action: FunctionWithContext<AnyFunction, Context<T>>) {
+    if (!this.#and.has(this.name)) {
+      this.#and.set(this.name, []);
+    }
+    this.#and.get(this.name)?.push(action);
+    return this;
+  }
+
+  public or(action: FunctionWithContext<AnyFunction, Context<T>>) {
+    if (!this.#or.has(this.name)) {
+      this.#or.set(this.name, []);
+    }
+    this.#or.get(this.name)?.push(action);
+    return this;
+  }
+
+  public before(action: FunctionWithContext<AnyFunction, Context<T>>) {
+    if (!this.#before.has(this.name)) {
+      this.#before.set(this.name, []);
+    }
+    this.#before.get(this.name)?.push(action);
+    return this;
+  }
+
+  public after(action: FunctionWithContext<AnyFunction, Context<T>>) {
+    if (!this.#after.has(this.name)) {
+      this.#after.set(this.name, []);
+    }
+    this.#after.get(this.name)?.push(action);
+    return this;
+  }
+
+  public action(action: FunctionWithContext<T[keyof T], Context<T>>) {
+    this.#action = action;
+    return this;
+  }
+
+  public build(): ActionByBuilder<T, Context<T>> {
+    if (!this.#action) {
+      throw new Error('Your action builder should includes an action.');
+    }
+
+    return {
+      actionName: this.name,
+      action: this.#action,
+      before: this.#before,
+      after: this.#after,
+      and: this.#and,
+      or: this.#or,
+    };
+  }
+}

package/src/builders/mod.ts

@@ -0,0 +1,5 @@
+export type { ProxiedNamespace, FindProxiedNamespace } from './types.js';
+
+export { NamespaceBuilder } from './namespace.js';
+export { ProviderBuilder } from './provider.js';
+export { ActionBuilder } from './action.js';

package/src/builders/namespace.ts

@@ -0,0 +1,258 @@
+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 '../hub/types.js';
+
+import { Namespace } from '../hub/mod.js';
+
+/**
+ * There are Namespace's methods that should be called directly on Proxy object.
+ * The Proxy object is creating in `.build`.
+ */
+export const allowedMethods = [
+  'init',
+  'state',
+  'after',
+  'before',
+  'and_then',
+  'or_else',
+  'store',
+] as const;
+/**
+ * List of value types that are considered safe to return directly when
+ * accessing properties on a proxied `Namespace`.
+ *
+ * This is useful for allowing public values like `version` to be accessed.
+ * If a property's value is of one of these types (e.g.,`'string'`, `'number'`),
+ * it will be returned as-is.
+ *
+ * @const {Array<'string' | 'number'>} allowedPublicValues
+ */
+const allowedPublicValues = ['string', 'number'];
+
+export class NamespaceBuilder<T extends Actions<T>> {
+  #id: string;
+  #providerId: string;
+  #actions: ActionsMap<T> = new Map();
+  /*
+   * We keep a list of `ActionBuilder` outputs here to use them in separate phases.
+   * Actually, `ActionBuilder` is packing action and its hooks in one place, here we should expand them and them in appropriate places.
+   * Eventually, action will be added to `#actions` and its hooks will be added to `Namespace`.
+   */
+  #actionBuilders: ActionByBuilder<T, Context<T>>[] = [];
+  #configs: NamespaceConfig;
+
+  constructor(id: string, providerId: string) {
+    this.#id = id;
+    this.#providerId = providerId;
+    this.#configs = {};
+  }
+
+  /** There are some predefined configs that can be set for each namespace separately */
+  public config<K extends keyof NamespaceConfig>(
+    name: K,
+    value: NamespaceConfig[K],
+  ) {
+    this.#configs[name] = value;
+    return this;
+  }
+
+  /**
+   * Getting a list of actions.
+   *
+   * e.g.:
+   * ```ts
+   * .action([
+   *      ["connect", () => {}],
+   *      ["disconnect", () => {}]
+   * ])
+   * ```
+   *
+   */
+  public action<K extends keyof T>(
+    action: (readonly [K, FunctionWithContext<T[K], Context<T>>])[],
+  ): NamespaceBuilder<T>;
+
+  /**
+   *
+   * Add a single action
+   *
+   * e.g.:
+   * ```ts
+   * .action( ["connect", () => {}] )
+   * ```
+   */
+  public action<K extends keyof T>(
+    action: K,
+    actionFn: FunctionWithContext<T[K], Context<T>>,
+  ): NamespaceBuilder<T>;
+
+  public action(action: ActionByBuilder<T, Context<T>>): NamespaceBuilder<T>;
+
+  /**
+   *
+   * Actions are piece of functionality that a namespace can have, for example it can be a `connect` function
+   * or a sign function or even a function for updating namespace's internal state. Actions are flexible and can be anything.
+   *
+   * Generally, each standard namespace (e.g. evm) has an standard interface defined in `src/namespaces/`
+   * and provider (which includes namespaces) authors will implement those actions.
+   *
+   * You can call this function by a list of actions or a single action.
+   *
+   */
+  public action<K extends keyof T>(
+    action: (readonly [K, FunctionWithContext<T[K], Context<T>>])[] | K,
+    actionFn?: FunctionWithContext<T[K], Context<T>>,
+  ) {
+    // List mode
+    if (Array.isArray(action)) {
+      action.forEach(([name, actionFnForItem]) => {
+        this.#actions.set(name, actionFnForItem);
+      });
+      return this;
+    }
+
+    // Action builder mode
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    if (typeof action === 'object' && !!action?.actionName) {
+      this.#actionBuilders.push(action);
+      return this;
+    }
+
+    // Single action mode
+    if (!!actionFn) {
+      this.#actions.set(action, actionFn);
+    }
+
+    return this;
+  }
+
+  /**
+   * By calling build, an instance of Namespace will be built.
+   *
+   * Note: it's not exactly a `Namespace`, it returns a Proxy which add more convenient use like `namespace.connect()` instead of `namespace.run("connect")`
+   */
+  public build(): ProxiedNamespace<T> {
+    if (this.#isConfigsValid(this.#configs)) {
+      return this.#buildApi(this.#configs);
+    }
+
+    throw new Error(`You namespace config isn't valid.`);
+  }
+
+  // Currently, namespace doesn't has any config.
+  #isConfigsValid(_config: NamespaceConfig): boolean {
+    return true;
+  }
+
+  /*
+   * Extracting hooks and add them to `Namespace` for the action.
+   *
+   * Note: this should be called after `addActionsFromActionBuilders` to ensure the action is added first.
+   */
+  #addHooksFromActionBuilders(namespace: Namespace<T>) {
+    this.#actionBuilders.forEach((actionByBuild) => {
+      actionByBuild.after.forEach((afterHooks) => {
+        afterHooks.map((action) => {
+          namespace.after(actionByBuild.actionName, action);
+        });
+      });
+
+      actionByBuild.before.forEach((beforeHooks) => {
+        beforeHooks.map((action) => {
+          namespace.before(actionByBuild.actionName, action);
+        });
+      });
+
+      actionByBuild.and.forEach((andHooks) => {
+        andHooks.map((action) => {
+          namespace.and_then(actionByBuild.actionName, action);
+        });
+      });
+
+      actionByBuild.or.forEach((orHooks) => {
+        orHooks.map((action) => {
+          namespace.or_else(actionByBuild.actionName, action);
+        });
+      });
+    });
+  }
+
+  /**
+   * Iterate over `actionBuilders` and add them to exists `actions`.
+   * Note: Hooks will be added in a separate phase.
+   */
+  #addActionsFromActionBuilders() {
+    this.#actionBuilders.forEach((actionByBuild) => {
+      this.#actions.set(actionByBuild.actionName, actionByBuild.action);
+    });
+  }
+
+  /**
+   * Build a Proxy object to call actions in a more convenient way. e.g `.connect()` instead of `.run(connect)`
+   */
+  #buildApi(configs: NamespaceConfig): ProxiedNamespace<T> {
+    this.#addActionsFromActionBuilders();
+    const namespace = new Namespace<T>(this.#id, this.#providerId, {
+      configs,
+      actions: this.#actions,
+    });
+    this.#addHooksFromActionBuilders(namespace);
+
+    const api = new Proxy(namespace, {
+      has: (_, property) => {
+        if (typeof property !== 'string') {
+          throw new Error(
+            'You can use string as your property on Namespace instance.',
+          );
+        }
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore-next-line
+        if (allowedMethods.includes(property)) {
+          return true;
+        }
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore-next-line
+        if (allowedPublicValues.includes(typeof namespace[property])) {
+          return true;
+        }
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore-next-line
+        return namespace.has(property);
+      },
+      get: (_, property) => {
+        if (typeof property !== 'string') {
+          throw new Error(
+            'You can use string as your property on Namespace instance.',
+          );
+        }
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore-next-line
+        const targetValue = namespace[property];
+
+        if (
+          allowedMethods.includes(property as (typeof allowedMethods)[number])
+        ) {
+          return targetValue.bind(namespace);
+        }
+        /*
+         * This is useful accessing values like `version`, If we don't do this, we should whitelist
+         * All the values as well, So it can be confusing for someone that only wants to add a public value to `Namespace`
+         */
+        if (allowedPublicValues.includes(typeof targetValue)) {
+          return targetValue;
+        }
+
+        return namespace.run.bind(namespace, property as keyof T);
+      },
+      set: () => {
+        throw new Error('You can not set anything on this object.');
+      },
+    });
+
+    return api as unknown as ProxiedNamespace<T>;
+  }
+}

package/src/builders/provider.ts

@@ -0,0 +1,101 @@
+import type { ProxiedNamespace } from './types.js';
+import type { Actions } from '../hub/namespaces/mod.js';
+import type {
+  ExtendableInternalActions,
+  ProviderBuilderOptions,
+  RegisteredNamespaces,
+} from '../hub/provider/mod.js';
+import type { ProviderConfig } from '../hub/store/mod.js';
+
+import { Provider } from '../hub/provider/mod.js';
+
+/**
+ * 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;
+  /*
+   * Internal storage is opaque — types are recovered when `build()` produces
+   * the `Provider<TNS>`.
+   */
+  #namespaces = new Map<string, unknown>();
+  #methods: ExtendableInternalActions = {};
+  #configs: Partial<ProviderConfig<TNS>> = {};
+  #options: Partial<ProviderBuilderOptions>;
+
+  constructor(id: string, options?: ProviderBuilderOptions) {
+    this.#id = id;
+    this.#options = options || {};
+  }
+
+  /**
+   * 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: ProxiedNamespace<T>,
+  ): ProviderBuilder<TNS & Record<K, T>> {
+    if (this.#options.store) {
+      namespace.store(this.#options.store);
+    }
+    this.#namespaces.set(id, namespace);
+    return this as unknown as ProviderBuilder<TNS & Record<K, T>>;
+  }
+
+  public config<K extends keyof ProviderConfig<TNS>>(
+    name: K,
+    value: ProviderConfig<TNS>[K],
+  ): this {
+    this.#configs[name] = value;
+    return this;
+  }
+
+  public init(cb: Exclude<ExtendableInternalActions['init'], undefined>): this {
+    this.#methods.init = cb;
+    return this;
+  }
+
+  public build(): Provider<TNS> {
+    if (this.#isConfigsValid(this.#configs)) {
+      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<TNS>>,
+  ): config is ProviderConfig<TNS> {
+    return !!config.metadata;
+  }
+}

package/src/builders/types.ts

@@ -0,0 +1,28 @@
+import type { allowedMethods } from './namespace.js';
+import type { Actions, Namespace } from '../hub/namespaces/mod.js';
+
+// These should be matched with `/hub/namespace.ts` public values.
+type NamespacePublicValues = {
+  namespaceId: string;
+  providerId: string;
+};
+
+/**
+ * NamespaceBuilder is creating a proxy instead of return Namespace instance.
+ * The reason is improving access to actions. e.g `.connect()` instead of `.run('connect')`
+ */
+export type ProxiedNamespace<T extends Actions<T>> = T &
+  Pick<Namespace<T>, (typeof allowedMethods)[number]> &
+  NamespacePublicValues;
+
+/**
+ * Map a key into the corresponding proxied namespace inside a namespace set.
+ *
+ * @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;