@hub3js/core 0.58.2-next.0

package/src/hub/hub.ts

@@ -0,0 +1,128 @@
+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';
+
+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, Provider>();
+  #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[] = [];
+
+    // 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];
+      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: Provider) {
+    if (this.#options.store) {
+      provider.store(this.#options.store);
+    }
+    this.#providers.set(id, provider);
+    return this;
+  }
+  remove(id: string) {
+    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): Provider | undefined {
+    return this.#providers.get(providerId);
+  }
+
+  getAll() {
+    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<
+        Provider['state']
+      >;
+
+      res[result.id] = {
+        ...(getProviderState() || {}),
+        namespaces: namespaces,
+      };
+    });
+    return res;
+  }
+}

package/src/hub/mod.ts

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

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';

package/src/hub/namespaces/namespace.test.ts

@@ -0,0 +1,443 @@
+import { describe, expect, test, vi } from 'vitest';
+
+import { createStore } from '../mod.js';
+
+import { OR_ELSE_ACTION_FAILED_ERROR } from './errors.js';
+import { Namespace } from './namespace.js';
+
+interface CustomMatchers<R = unknown> {
+  toThrowErrorWithCause: (expectedError: unknown, expectedCause: unknown) => R;
+}
+
+declare module 'vitest' {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-empty-object-type
+  interface Assertion<T = any> extends CustomMatchers<T> {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface AsymmetricMatchersContaining extends CustomMatchers {}
+}
+
+interface TestNamespaceActions {
+  connect: () => void;
+  disconnect: () => void;
+}
+
+expect.extend({
+  toThrowErrorWithCause(actualFunction, expectedError, expectedCause) {
+    try {
+      actualFunction();
+    } catch (error) {
+      const isExactError = error === expectedError;
+      const hasExpectedCause =
+        error instanceof Error && error.cause === expectedCause;
+
+      if (isExactError) {
+        return {
+          pass: true,
+          message: () => `Expected function to throw the exact error.`,
+        };
+      }
+
+      if (hasExpectedCause) {
+        return {
+          pass: true,
+          message: () =>
+            `Expected function to throw an error with the exact cause.`,
+        };
+      }
+
+      return {
+        pass: false,
+        message: () =>
+          `Expected function to throw the exact error with the expected cause, but got a different error.`,
+      };
+    }
+
+    return {
+      pass: false,
+      message: () =>
+        `Expected function to throw an Error, but it did not throw.`,
+    };
+  },
+});
+
+describe('check initializing Namespace', () => {
+  const NAMESPACE = 'evm';
+  const PROVIDER_ID = 'garbage provider';
+
+  test('initialize a namespace and run an action', () => {
+    const connect = vi.fn();
+    const disconnect = vi.fn();
+    const actions = new Map();
+    actions.set('connect', connect);
+    actions.set('disconnect', disconnect);
+
+    const ns = new Namespace<TestNamespaceActions>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+    });
+
+    ns.run('connect');
+
+    expect(disconnect).toBeCalledTimes(0);
+    expect(connect).toBeCalledTimes(1);
+  });
+
+  test('init action should be called once', () => {
+    const connect = vi.fn();
+    const disconnect = vi.fn();
+    const init = vi.fn();
+    const actions = new Map();
+    actions.set('connect', connect);
+    actions.set('disconnect', disconnect);
+    actions.set('init', init);
+
+    const ns = new Namespace<TestNamespaceActions>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+    });
+
+    expect(init).toBeCalledTimes(0);
+
+    ns.run('connect');
+    ns.init();
+    ns.init();
+
+    expect(disconnect).toBeCalledTimes(0);
+    expect(connect).toBeCalledTimes(1);
+    expect(init).toBeCalledTimes(1);
+  });
+
+  test('state should be updated and actions have access to them', () => {
+    const connect = vi.fn((context) => {
+      const [, setState] = context.state();
+      setState('connected', true);
+    });
+    const init = vi.fn((context) => {
+      const [, setState] = context.state();
+      setState('connecting', true);
+    });
+    const actions = new Map();
+    actions.set('connect', connect);
+    actions.set('init', init);
+
+    const store = createStore();
+    const ns = new Namespace<TestNamespaceActions>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+      store,
+    });
+
+    ns.run('connect');
+    ns.init();
+    ns.init();
+
+    const [currentState] = ns.state();
+    expect(currentState().connected).toBe(true);
+    expect(currentState('connecting')).toBe(true);
+  });
+
+  test('has method returns true when namespace contains the specified action', () => {
+    const connectAction = vi.fn((context) => {
+      const [, setState] = context.state();
+      setState('connected', true);
+    });
+
+    const actionsMap = new Map([['connect', connectAction]]);
+
+    const store = createStore();
+    const namespace = new Namespace<TestNamespaceActions>(
+      NAMESPACE,
+      PROVIDER_ID,
+      {
+        actions: actionsMap,
+        store,
+      },
+    );
+
+    expect(namespace.has('connect')).toBe(true);
+    expect(namespace.has('disconnect')).toBe(false);
+  });
+  test("throw an error if store doesn't set", () => {
+    const ns = new Namespace<TestNamespaceActions>(NAMESPACE, PROVIDER_ID, {
+      actions: new Map(),
+    });
+
+    expect(() => ns.state()).toThrowError();
+  });
+});
+
+describe('check actions with hooks and operators', () => {
+  const NAMESPACE = 'bip122';
+  const PROVIDER_ID = 'garbage provider';
+
+  test('add actions and run them.', () => {
+    const actions = new Map();
+    actions.set('hello', () => 'hello world');
+    actions.set('bye', () => 'bye bye');
+    actions.set('chainable', () => "it's also chainable");
+    actions.set('chain2', () => "it's also chainable");
+
+    const ns = new Namespace<{
+      hello: () => string;
+      bye: () => string;
+      chainable: () => void;
+      chain2: () => void;
+    }>(NAMESPACE, PROVIDER_ID, { actions });
+
+    expect(ns.run('hello')).toBe('hello world');
+    expect(ns.run('bye')).toBe('bye bye');
+
+    expect(() => {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore-next-line
+      return ns.run('some_action_name_that_has_not_added');
+    }).toThrowError();
+  });
+
+  test('should be called before/after target action correctly even with multiple hook assigned to an action name', () => {
+    const beforeAction = vi.fn();
+    const anotherBeforeAction = vi.fn();
+    const afterAction = vi.fn();
+    const anotherAfterAction = vi.fn();
+    const connectAction = vi.fn();
+    const disconnectAction = vi.fn();
+
+    const actions = new Map();
+    actions.set('connect', connectAction);
+    actions.set('disconnect', disconnectAction);
+
+    const ns = new Namespace<TestNamespaceActions>(NAMESPACE, PROVIDER_ID, {
+      actions,
+    });
+
+    ns.run('connect');
+    expect(connectAction).toBeCalledTimes(1);
+    expect(beforeAction).toBeCalledTimes(0);
+    expect(anotherBeforeAction).toBeCalledTimes(0);
+    expect(afterAction).toBeCalledTimes(0);
+    expect(anotherAfterAction).toBeCalledTimes(0);
+
+    ns.before('connect', beforeAction);
+    ns.before('connect', anotherBeforeAction);
+    ns.run('connect');
+    expect(connectAction).toBeCalledTimes(2);
+    expect(beforeAction).toBeCalledTimes(1);
+    expect(anotherBeforeAction).toBeCalledTimes(1);
+    expect(afterAction).toBeCalledTimes(0);
+    expect(anotherAfterAction).toBeCalledTimes(0);
+
+    ns.after('connect', afterAction);
+    ns.after('connect', anotherAfterAction);
+    ns.run('connect');
+    expect(beforeAction).toBeCalledTimes(2);
+    expect(anotherBeforeAction).toBeCalledTimes(2);
+    expect(afterAction).toBeCalledTimes(1);
+    expect(anotherAfterAction).toBeCalledTimes(1);
+  });
+
+  test('should call `and_then` sequentially.', () => {
+    const andActionFirst = vi.fn((_ctx, result) => result + 1);
+    const andActionSecond = vi.fn((_ctx, result) => result + 1);
+
+    const connectAction = vi.fn(() => 0);
+    const disconnectAction = vi.fn();
+
+    const actions = new Map();
+    actions.set('connect', connectAction);
+    actions.set('disconnect', disconnectAction);
+
+    const ns = new Namespace<TestNamespaceActions>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+    });
+    ns.and_then('connect', andActionFirst);
+    ns.and_then('connect', andActionSecond);
+
+    const result = ns.run('connect');
+
+    expect(connectAction).toBeCalledTimes(1);
+    expect(andActionFirst).toBeCalledTimes(1);
+    expect(andActionSecond).toBeCalledTimes(1);
+
+    expect(result).toBe(2);
+
+    ns.run('connect');
+    expect(connectAction).toBeCalledTimes(2);
+    expect(andActionFirst).toBeCalledTimes(2);
+    expect(andActionSecond).toBeCalledTimes(2);
+  });
+
+  test("shouldn't run other `and_then` hooks if one of them fails then fallback to `or_else`.", () => {
+    const andActionFirst = vi.fn((_ctx, _result) => {
+      throw new Error('Oops!');
+    });
+    const andActionSecond = vi.fn((_ctx, result) => result + 1);
+
+    const orAction = vi.fn((_ctx, e) => e instanceof Error);
+
+    const connectAction = vi.fn(() => 0);
+    const actions = new Map();
+    actions.set('connect', connectAction);
+
+    const ns = new Namespace<{
+      connect: () => void;
+    }>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+      configs: {},
+    });
+    ns.and_then('connect', andActionFirst);
+    ns.and_then('connect', andActionSecond);
+
+    ns.or_else('connect', orAction);
+
+    const result = ns.run('connect');
+
+    expect(connectAction).toBeCalledTimes(1);
+    expect(andActionFirst).toBeCalledTimes(1);
+    expect(andActionSecond).toBeCalledTimes(0);
+    expect(orAction).toBeCalledTimes(1);
+    expect(result).toBe(true);
+  });
+
+  test('should throw error if there are no `or` to handle error', () => {
+    const andActionFirst = vi.fn((_ctx, _result) => {
+      throw new Error('Oops!');
+    });
+    const andActionSecond = vi.fn((_ctx, result) => result + 1);
+
+    const connectAction = vi.fn(() => 0);
+    const actions = new Map();
+    actions.set('connect', connectAction);
+
+    const ns = new Namespace<{
+      connect: () => void;
+    }>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+      configs: {},
+    });
+
+    ns.and_then('connect', andActionFirst);
+    ns.and_then('connect', andActionSecond);
+
+    expect(() => ns.run('connect')).toThrowError();
+  });
+
+  test('ensure `or_else` has access to error', () => {
+    const actions = new Map();
+    actions.set('connect', () => {
+      throw new Error('Oops!');
+    });
+
+    const ns = new Namespace<{
+      connect: () => void;
+    }>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+      configs: {},
+    });
+
+    ns.or_else('connect', (_ctx: unknown, err: unknown) => {
+      return err instanceof Error;
+    });
+
+    const result = ns.run('connect');
+    expect(result).toBe(true);
+  });
+
+  test('should call `or_else` sequentially.', () => {
+    const orActionFirst = vi.fn((_ctx, _err) => 1);
+    const orActionSecond = vi.fn((_ctx, _err) => _err + 1);
+
+    const connectAction = vi.fn(() => {
+      throw new Error('Oops!');
+    });
+
+    const actions = new Map();
+    actions.set('connect', connectAction);
+
+    const ns = new Namespace<{
+      connect: () => void;
+    }>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+    });
+
+    ns.or_else('connect', orActionFirst);
+    ns.or_else('connect', orActionSecond);
+
+    const result = ns.run('connect');
+
+    expect(connectAction).toBeCalledTimes(1);
+    expect(orActionFirst).toBeCalledTimes(1);
+    expect(orActionSecond).toBeCalledTimes(1);
+
+    expect(result).toBe(2);
+
+    ns.run('connect');
+    expect(connectAction).toBeCalledTimes(2);
+    expect(orActionFirst).toBeCalledTimes(2);
+    expect(orActionSecond).toBeCalledTimes(2);
+  });
+  test('throw a wrapped error if `or_else` handler fails to run.', () => {
+    const orActionFirst = vi.fn((_ctx, _err) => 1);
+    const orActionSecondError = 'This is actually a bad situation';
+    const orActionSecond = vi.fn((_ctx, _err) => {
+      // eslint-disable-next-line @typescript-eslint/only-throw-error
+      throw orActionSecondError;
+    });
+    const connectActionError = new Error('Oops!');
+
+    const connectAction = vi.fn(() => {
+      throw connectActionError;
+    });
+
+    const actions = new Map();
+    actions.set('connect', connectAction);
+
+    const ns = new Namespace<{
+      connect: () => void;
+    }>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+    });
+
+    ns.or_else('connect', orActionFirst);
+    ns.or_else('connect', orActionSecond);
+
+    expect(() => ns.run('connect')).toThrowError(
+      expect.objectContaining({
+        message: OR_ELSE_ACTION_FAILED_ERROR(
+          `connect for ${ns.namespaceId} namespace.`,
+        ),
+        cause: expect.objectContaining({
+          message: orActionSecondError,
+          cause: connectActionError,
+        }),
+      }),
+    );
+
+    expect(orActionFirst).toBeCalledTimes(1);
+    expect(connectAction).toBeCalledTimes(1);
+    expect(orActionSecond).toBeCalledTimes(1);
+  });
+
+  test('throw the exact error if `or_else` handler fails and the error is an instance of Error.', () => {
+    const orActionError = new Error('Or action error');
+    const orAction = vi.fn((_ctx, _err) => {
+      throw orActionError;
+    });
+    const connectActionError = new Error('Oops!');
+    const connectAction = vi.fn(() => {
+      throw connectActionError;
+    });
+    const actions = new Map();
+    actions.set('connect', connectAction);
+
+    const ns = new Namespace<{
+      connect: () => void;
+    }>(NAMESPACE, PROVIDER_ID, {
+      actions: actions,
+    });
+    ns.or_else('connect', orAction);
+
+    expect(() => {
+      ns.run('connect');
+    }).toThrowErrorWithCause(orActionError, connectActionError);
+
+    expect(orAction).toBeCalledTimes(1);
+    expect(connectAction).toBeCalledTimes(1);
+  });
+});