@hub3js/std 0.0.1-next.0

package/src/hooks/changeAccountSubscriber.test.ts

@@ -0,0 +1,172 @@
+import type { AutoImplementedActionsByRecommended } from '../types/namespace.js';
+import type { Actions } from '@hub3js/core';
+
+import { createStore, Namespace } from '@hub3js/core';
+import { waitFor } from '@testing-library/dom';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { ChangeAccountSubscriberBuilder } from './changeAccountSubscriber.js';
+
+interface TestNamespaceActions {
+  disconnect: () => void;
+}
+
+describe('check changeAccountSubscriber', () => {
+  const garbageProvider = { name: 'garbage provider' };
+
+  const garbageFormatter = async (
+    _instance: typeof garbageProvider,
+    accounts: string[],
+  ) => accounts.map((account) => `Formatted: ${account}`);
+
+  const garbageAddEventListener = (
+    _instance: typeof garbageProvider,
+    callback: (event: string[]) => void,
+  ) => {
+    callback(['0']);
+  };
+
+  const garbageRemoveEventListener = (
+    _: typeof garbageProvider,
+    __: (event: string[]) => void,
+  ) => {};
+
+  let builder: ChangeAccountSubscriberBuilder<
+    string[],
+    typeof garbageProvider,
+    Actions<AutoImplementedActionsByRecommended>
+  >;
+
+  const setupNamespace = () => {
+    const actions = new Map();
+    const disconnectAction = vi.fn();
+    actions.set('disconnect', disconnectAction);
+
+    const store = createStore();
+    const ns = new Namespace<TestNamespaceActions>('evm', 'garbage provider', {
+      actions,
+      store,
+    });
+
+    const context = { action: ns.run.bind(ns), state: ns.state.bind(ns) };
+
+    return { ns, context, disconnectAction };
+  };
+
+  beforeEach(() => {
+    builder = new ChangeAccountSubscriberBuilder();
+  });
+
+  test('throws error if required operators are not set', () => {
+    expect(() => builder.build()).toThrow(
+      `Required "getInstance" operation has not been set for "changeAccountSubscriber"`,
+    );
+
+    builder.getInstance(() => garbageProvider);
+    expect(() => builder.build()).toThrow(
+      `Required "format" operation has not been set for "changeAccountSubscriber"`,
+    );
+
+    builder.format(garbageFormatter);
+    expect(() => builder.build()).toThrow(
+      `Required "addEventListener" operation has not been set for "changeAccountSubscriber"`,
+    );
+
+    builder.addEventListener(garbageAddEventListener);
+    expect(() => builder.build()).toThrow(
+      `Required "removeEventListener" operation has not been set for "changeAccountSubscriber"`,
+    );
+
+    builder.removeEventListener(garbageRemoveEventListener);
+
+    // should not throw now
+    builder.build();
+  });
+
+  test('calls addEventListener and formats accounts correctly', async () => {
+    const { context } = setupNamespace();
+    const spiedAddEventListener = vi.fn(garbageAddEventListener);
+
+    builder
+      .getInstance(() => garbageProvider)
+      .format(garbageFormatter)
+      .addEventListener(spiedAddEventListener)
+      .removeEventListener(garbageRemoveEventListener);
+
+    const [subscriber] = builder.build();
+
+    expect(spiedAddEventListener).toHaveBeenCalledTimes(0);
+    subscriber(context);
+    expect(spiedAddEventListener).toHaveBeenCalledTimes(1);
+
+    const [getState] = context.state();
+    await waitFor(() => {
+      expect(getState('accounts')?.[0]).toBe('Formatted: 0');
+    });
+  });
+
+  test('wont update accounts if preventDefault called', async () => {
+    const { context } = setupNamespace();
+    const spiedAddEventListener = vi.fn(garbageAddEventListener);
+    const [getState, setState] = context.state();
+    setState('accounts', ['Initial State']);
+    builder
+      .getInstance(() => garbageProvider)
+      .format(garbageFormatter)
+      .addEventListener(spiedAddEventListener)
+      .onSwitchAccount((event) => {
+        event.preventDefault();
+      })
+      .removeEventListener(garbageRemoveEventListener);
+
+    const [subscriber] = builder.build();
+
+    subscriber(context);
+    await waitFor(() => {
+      expect(getState('accounts')?.[0]).toBe('Initial State');
+    });
+  });
+
+  test('calls removeEventListener', () => {
+    const { context } = setupNamespace();
+    const spiedRemoveEventListener = vi.fn(garbageRemoveEventListener);
+
+    builder
+      .getInstance(() => garbageProvider)
+      .format(garbageFormatter)
+      .addEventListener(garbageAddEventListener)
+      .removeEventListener(spiedRemoveEventListener);
+
+    const [, clearSubscriber] = builder.build();
+
+    expect(spiedRemoveEventListener).toHaveBeenCalledTimes(0);
+    clearSubscriber(context);
+    expect(spiedRemoveEventListener).toHaveBeenCalledTimes(1);
+  });
+
+  test('calls addEventListener returned function', () => {
+    const { context } = setupNamespace();
+    const unsubscribe = vi.fn();
+
+    const addEventListenerWithReturn = (
+      _: typeof garbageProvider,
+      __: (event: string[]) => void,
+    ) => {
+      return unsubscribe;
+    };
+
+    builder
+      .getInstance(() => garbageProvider)
+      .format(garbageFormatter)
+      .addEventListener(addEventListenerWithReturn)
+      .removeEventListener(garbageRemoveEventListener);
+
+    const [subscriber, clearSubscriber] = builder.build();
+
+    subscriber(context);
+    expect(unsubscribe).toHaveBeenCalledTimes(0);
+
+    clearSubscriber(context);
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/changeAccountSubscriber.ts

@@ -0,0 +1,239 @@
+import type { AutoImplementedActionsByRecommended } from '../types/namespace.js';
+import type {
+  Actions,
+  Context,
+  Subscriber,
+  SubscriberCleanUp,
+} from '@hub3js/core';
+
+type OnSwitchAccountEvent<EventType> = {
+  payload: EventType;
+  preventDefault: () => void;
+};
+
+export class ChangeAccountSubscriberBuilder<
+  EventType,
+  ProviderAPI,
+  ActionsType extends Actions<ActionsType> &
+    Actions<AutoImplementedActionsByRecommended>,
+> {
+  #getInstance: (() => ProviderAPI) | null = null;
+  #format:
+    | ((instance: ProviderAPI, event: EventType) => Promise<string[]>)
+    | null = null;
+  #onSwitchAccount:
+    | ((
+        event: OnSwitchAccountEvent<EventType>,
+        context: Context<ActionsType>,
+      ) => void)
+    | null = null;
+
+  #addEventListener:
+    | ((
+        instance: ProviderAPI,
+        callback: (event: EventType) => void,
+      ) => (() => void) | void)
+    | null = null;
+  #removeEventListener:
+    | ((instance: ProviderAPI, callback: (event: EventType) => void) => void)
+    | null = null;
+
+  /**
+   * Sets the function that provides the provider API instance.
+   *
+   * @param operator - Function that returns the provider API instance
+   * @returns The builder instance for method chaining
+   * @example
+   * ```typescript
+   * builder.getInstance(() => window.ethereum)
+   * ```
+   */
+  public getInstance(operator: () => ProviderAPI) {
+    this.#getInstance = operator;
+    return this;
+  }
+
+  /**
+   * Sets the formatter function that converts provider events to account strings.
+   *
+   * @param operator - Function that takes a provider instance and event, returns array of account strings
+   * @returns The builder instance for method chaining
+   * @example
+   * ```typescript
+   * builder.format(async (instance, event) => event.accounts || [])
+   * ```
+   */
+  public format(
+    operator: (instance: ProviderAPI, event: EventType) => Promise<string[]>,
+  ) {
+    this.#format = operator;
+    return this;
+  }
+
+  /**
+   * Set a handler that runs whenever a **switch-account** event occurs.
+   *
+   * The provided operator is called with:
+   * - `event`: An object containing:
+   *    - `payload`: The event payload associated with the account switch.
+   *    - `preventDefault`: A function that prevents the default switch-account
+   *       behavior (e.g., updating the active accounts list).
+   * - `context`: The execution context of the current flow or action.
+   *
+   * Calling `event.preventDefault()` inside the handler cancels the built-in
+   * account switching logic.
+   *
+   * @param operator - A function invoked on each switch-account event.
+   *   It receives `(event, context)` and can call `event.preventDefault()` to
+   *   stop the default behavior.
+   *
+   * @returns The builder instance for method chaining.
+   *
+   * @example
+   * ```ts
+   * builder.onSwitchAccount((event, context) => {
+   *   if (!event.payload.userConfirmed) {
+   *     event.preventDefault(); // cancel default account switch
+   *   }
+   *
+   *   console.log("Switching account:", event.payload.accountId);
+   * });
+   * ```
+   */
+  public onSwitchAccount(
+    operator: (
+      event: OnSwitchAccountEvent<EventType>,
+      context: Context<ActionsType>,
+    ) => void,
+  ) {
+    this.#onSwitchAccount = operator;
+    return this;
+  }
+
+  /**
+   * Sets the event listener attachment function.
+   *
+   * @param operator - Function that attaches an event listener and optionally returns a cleanup function
+   * @returns The builder instance for method chaining
+   * @example
+   * ```typescript
+   * builder.addEventListener((instance, callback) => {
+   *   return instance.on('accountsChanged', callback);
+   * })
+   * ```
+   */
+  public addEventListener(
+    operator: (
+      instance: ProviderAPI,
+      callback: (event: EventType) => void,
+    ) => (() => void) | void,
+  ) {
+    this.#addEventListener = operator;
+    return this;
+  }
+
+  /**
+   * Sets the event listener removal function.
+   *
+   * @param operator - Function that removes an event listener from the provider
+   * @returns The builder instance for method chaining
+   * @example
+   * ```typescript
+   * builder.removeEventListener((instance, callback) => instance.off('accountsChanged', callback))
+   * ```
+   */
+  public removeEventListener(
+    operator: (
+      instance: ProviderAPI,
+      callback: (event: EventType) => void,
+    ) => void,
+  ) {
+    this.#removeEventListener = operator;
+    return this;
+  }
+
+  public build(): [Subscriber<ActionsType>, SubscriberCleanUp<ActionsType>] {
+    if (this.#getInstance === null) {
+      throw new Error(this.#getErrorMessage('getInstance'));
+    }
+    if (this.#format === null) {
+      throw new Error(this.#getErrorMessage('format'));
+    }
+    if (this.#addEventListener === null) {
+      throw new Error(this.#getErrorMessage('addEventListener'));
+    }
+    if (this.#removeEventListener === null) {
+      throw new Error(this.#getErrorMessage('removeEventListener'));
+    }
+
+    /*
+     * Capture current operator state at build time to ensure immutability.
+     *
+     * This creates a snapshot of all operators, preventing the built subscriber
+     * from being affected by subsequent changes to the builder instance.
+     * Each call to build() gets its own isolated set of operators, allowing
+     * the builder to be reused for creating multiple independent subscribers.
+     */
+    const getInstance = this.#getInstance;
+    const format = this.#format;
+    const addEventListener = this.#addEventListener;
+    const removeEventListener = this.#removeEventListener;
+    const onSwitchAccount = this.#onSwitchAccount;
+
+    let subscriber: (event: EventType) => void;
+    let unsubscribe: (() => void) | void;
+    return [
+      async (context) => {
+        const [, setState] = context.state();
+        const instance = getInstance();
+
+        if (!instance) {
+          throw new Error(
+            'Trying to subscribe to your wallet, but seems its instance is not available.',
+          );
+        }
+        subscriber = async (event) => {
+          let shouldProceedWithDefault = true;
+          onSwitchAccount?.(
+            {
+              payload: event,
+              preventDefault: () => {
+                shouldProceedWithDefault = false;
+              },
+            },
+            context,
+          );
+          if (!shouldProceedWithDefault) {
+            return;
+          }
+          setState('accounts', await format(instance, event));
+        };
+        unsubscribe = addEventListener(instance, subscriber);
+      },
+      (_, err) => {
+        /*
+         * Call the cleanup function if addEventListener returned one.
+         * This handles providers that return an unsubscribe function from
+         * their event listeners.
+         */
+        if (unsubscribe && typeof unsubscribe === 'function') {
+          unsubscribe();
+        }
+        const instance = getInstance();
+
+        /*
+         * Always call removeEventListener as well to handle the on/off pattern.
+         * This ensures cleanup works regardless of which pattern the provider uses.
+         */
+        removeEventListener(instance, subscriber);
+
+        // subscriber can be passed to `or`; rethrow to chain into next `or`.
+        return err;
+      },
+    ];
+  }
+
+  #getErrorMessage(operatorName: string) {
+    return `Required "${operatorName}" operation has not been set for "changeAccountSubscriber"`;
+  }
+}

package/src/hooks/mod.ts

@@ -0,0 +1 @@
+export { ChangeAccountSubscriberBuilder } from './changeAccountSubscriber.js';

package/src/operators/after.ts

@@ -0,0 +1,8 @@
+import type { Context } from '@hub3js/core';
+
+export function intoConnectionFinished(context: Context) {
+  const [, setState] = context.state();
+  setState('connecting', false);
+}
+
+export const recommended = [['connect', intoConnectionFinished] as const];

package/src/operators/and.ts

@@ -0,0 +1,39 @@
+import type { Accounts, AccountsWithActiveChain } from '../types/accounts.js';
+import type { Context } from '@hub3js/core';
+
+import { isValidCaipAddress } from '../utils/caip.js';
+
+export function connectAndUpdateStateForSingleNetwork(
+  context: Context,
+  accounts: Accounts,
+) {
+  if (!accounts.every(isValidCaipAddress)) {
+    throw new Error(
+      `Your provider should format account addresses in CAIP-10 format. Your provided accounts: ${accounts}`,
+    );
+  }
+
+  const [, setState] = context.state();
+  setState('accounts', accounts);
+  setState('connected', true);
+  return accounts;
+}
+
+export function connectAndUpdateStateForMultiNetworks(
+  context: Context,
+  accounts: AccountsWithActiveChain,
+) {
+  if (!accounts.accounts.every(isValidCaipAddress)) {
+    throw new Error(
+      `Your provider should format account addresses in CAIP-10 format. Your provided accounts: ${accounts.accounts}`,
+    );
+  }
+
+  const [, setState] = context.state();
+  setState('accounts', accounts.accounts);
+  setState('network', accounts.network);
+  setState('connected', true);
+  return accounts;
+}
+
+export const recommended = [];

package/src/operators/before.ts

@@ -0,0 +1,12 @@
+import type { Context } from '@hub3js/core';
+
+export function intoConnecting(context: Context) {
+  const [, setState] = context.state();
+  setState('connecting', true);
+}
+
+/**
+ * Recommended `before` hooks every namespace should wire up. Tuple shape
+ * matches what `NamespaceBuilder.before(...)` expects.
+ */
+export const recommended = [['connect', intoConnecting] as const];

package/src/operators/mod.ts

@@ -0,0 +1,11 @@
+export { intoConnecting, recommended as beforeRecommended } from './before.js';
+export {
+  intoConnectionFinished,
+  recommended as afterRecommended,
+} from './after.js';
+export {
+  connectAndUpdateStateForMultiNetworks,
+  connectAndUpdateStateForSingleNetwork,
+  recommended as andRecommended,
+} from './and.js';
+export { standardizeAndThrowError } from './or.js';

package/src/operators/or.ts

@@ -0,0 +1,19 @@
+import type { Context } from '@hub3js/core';
+
+import { parseErrorAndThrowStandardizeError } from '../utils/error.js';
+
+/**
+ * Standardizes an unknown error into an `Error` object and throws it. If the
+ * input is already an `Error`, it's thrown directly. Otherwise a new `Error`
+ * is created with the input's message or string representation.
+ *
+ * The actual standardization lives in `parseErrorAndThrowStandardizeError`,
+ * which can be called independently outside an action context.
+ *
+ * @param _context - The action context (unused).
+ * @param e - The unknown error object.
+ * @throws {Error} - The standardized `Error` object.
+ */
+export function standardizeAndThrowError(_context: Context, e: unknown): never {
+  parseErrorAndThrowStandardizeError(e);
+}

package/src/types/accounts.ts

@@ -0,0 +1,13 @@
+type CaipNamespace = string;
+type CaipChainId = string;
+type CaipAccountAddress = string;
+
+export type CaipAccount =
+  `${CaipNamespace}:${CaipChainId}:${CaipAccountAddress}`;
+
+export type Accounts = CaipAccount[];
+
+export type AccountsWithActiveChain = {
+  accounts: Accounts;
+  network: string;
+};

package/src/types/mod.ts

@@ -0,0 +1,11 @@
+export type {
+  Namespace,
+  CommonActions,
+  AutoImplementedActionsByRecommended,
+} from './namespace.js';
+
+export type {
+  CaipAccount,
+  Accounts,
+  AccountsWithActiveChain,
+} from './accounts.js';

package/src/types/namespace.ts

@@ -0,0 +1,26 @@
+/*
+ * These are the supported namespace tags. The opaque `(string & {})` widening
+ * keeps the union open — downstream packages can register arbitrary names —
+ * while preserving autocomplete for the well-known ones.
+ */
+type KnownNamespace =
+  | 'EVM'
+  | 'Solana'
+  | 'Cosmos'
+  | 'UTXO'
+  | 'Starknet'
+  | 'Tron'
+  | 'Ton'
+  | 'Sui'
+  | 'XRPL'
+  | 'Stellar';
+
+export type Namespace = KnownNamespace | (string & {});
+
+export interface CommonActions {
+  init: () => void;
+}
+
+export interface AutoImplementedActionsByRecommended {
+  disconnect: () => void;
+}

package/src/utils/caip.ts

@@ -0,0 +1,10 @@
+import { AccountId } from 'caip';
+
+export function isValidCaipAddress(address: string): boolean {
+  try {
+    AccountId.parse(address);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/error.ts

@@ -0,0 +1,44 @@
+/**
+ * Standardizes an unknown error into an `Error` object and throws it.
+ * If the input is already an `Error`, it's thrown directly. Otherwise a new
+ * `Error` is created with the input's message or string representation,
+ * preserving `code` and `data` fields when present.
+ *
+ * @param e - The unknown error object.
+ * @throws {Error} - The standardized `Error` object.
+ */
+export function parseErrorAndThrowStandardizeError(e: unknown): never {
+  if (e instanceof Error) {
+    throw e;
+  }
+
+  let errorMessage: string;
+  if (
+    typeof e === 'object' &&
+    e !== null &&
+    'message' in e &&
+    typeof e.message === 'string'
+  ) {
+    errorMessage = e.message;
+  } else if (typeof e === 'string') {
+    errorMessage = e;
+  } else {
+    errorMessage = String(e);
+  }
+
+  const err = new Error(errorMessage) as Error & {
+    code?: unknown;
+    data?: unknown;
+  };
+
+  if (typeof e === 'object' && e !== null) {
+    if ('code' in e) {
+      err.code = e.code;
+    }
+    if ('data' in e) {
+      err.data = e.data;
+    }
+  }
+
+  throw err;
+}

package/src/utils/mod.ts

@@ -0,0 +1,2 @@
+export { isValidCaipAddress } from './caip.js';
+export { parseErrorAndThrowStandardizeError } from './error.js';

package/types/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@hub3js/std/types",
+  "type": "module",
+  "main": "../dist/types/mod.js",
+  "module": "../dist/types/mod.js",
+  "types": "../dist/types/mod.d.ts",
+  "sideEffects": false
+}

package/utils/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@hub3js/std/utils",
+  "type": "module",
+  "main": "../dist/utils/mod.js",
+  "module": "../dist/utils/mod.js",
+  "types": "../dist/utils/mod.d.ts",
+  "sideEffects": false
+}