@wagmi/core 1.4.1 → 2.0.0

package/src/createConfig.ts

@@ -0,0 +1,382 @@
+import {
+  type Address,
+  type Chain,
+  type Client,
+  type ClientConfig as viem_ClientConfig,
+  type Transport,
+  createClient,
+} from 'viem'
+import { persist, subscribeWithSelector } from 'zustand/middleware'
+import { createStore } from 'zustand/vanilla'
+
+import {
+  type ConnectorEventMap,
+  type CreateConnectorFn,
+} from './createConnector.js'
+import { Emitter, type EventData, createEmitter } from './createEmitter.js'
+import { type Storage, createStorage, noopStorage } from './createStorage.js'
+import { ChainNotConfiguredError } from './errors/config.js'
+import type { Evaluate, ExactPartial, LooseOmit, OneOf } from './types/utils.js'
+import { uid } from './utils/uid.js'
+
+export type CreateConfigParameters<
+  chains extends readonly [Chain, ...Chain[]] = readonly [Chain, ...Chain[]],
+  transports extends Record<chains[number]['id'], Transport> = Record<
+    chains[number]['id'],
+    Transport
+  >,
+> = Evaluate<
+  {
+    chains: chains
+    connectors?: CreateConnectorFn[] | undefined
+    reconnectOnMount?: boolean | undefined
+    storage?: Storage | null | undefined
+    syncConnectedChain?: boolean | undefined
+  } & OneOf<
+    | ({ transports: transports } & {
+        [key in keyof ClientConfig]?:
+          | ClientConfig[key]
+          | { [_ in chains[number]['id']]?: ClientConfig[key] | undefined }
+          | undefined
+      })
+    | {
+        client(parameters: { chain: chains[number] }): Client<
+          transports[chains[number]['id']],
+          chains[number]
+        >
+      }
+  > &
+    OneOf<
+      | {
+          /** @deprecated Use `reconnectOnMount` instead */
+          autoConnect?: boolean | undefined
+        }
+      | { reconnectOnMount?: boolean | undefined }
+    >
+>
+
+export type Config<
+  chains extends readonly [Chain, ...Chain[]] = readonly [Chain, ...Chain[]],
+  transports extends Record<chains[number]['id'], Transport> = Record<
+    chains[number]['id'],
+    Transport
+  >,
+> = {
+  readonly chains: chains
+  readonly connectors: readonly Connector[]
+  readonly state: State<chains>
+  readonly storage: Storage | null
+
+  getClient<chainId extends chains[number]['id']>(parameters?: {
+    chainId?: chainId | chains[number]['id'] | undefined
+  }): Client<transports[chainId], Extract<chains[number], { id: chainId }>>
+  setState<tchains extends readonly [Chain, ...Chain[]] = chains>(
+    value: State<tchains> | ((state: State<tchains>) => State<tchains>),
+  ): void
+  subscribe<state>(
+    selector: (state: State<chains>) => state,
+    listener: (selectedState: state, previousSelectedState: state) => void,
+    options?:
+      | {
+          equalityFn?: ((a: state, b: state) => boolean) | undefined
+          fireImmediately?: boolean | undefined
+        }
+      | undefined,
+  ): () => void
+
+  _internal: {
+    readonly reconnectOnMount: boolean
+    readonly syncConnectedChain: boolean
+    readonly transports: transports
+
+    change(data: EventData<ConnectorEventMap, 'change'>): void
+    connect(data: EventData<ConnectorEventMap, 'connect'>): void
+    disconnect(data: EventData<ConnectorEventMap, 'disconnect'>): void
+    setup(connectorFn: CreateConnectorFn): Connector
+  }
+}
+
+export function createConfig<
+  const chains extends readonly [Chain, ...Chain[]],
+  transports extends Record<chains[number]['id'], Transport>,
+>(
+  parameters: CreateConfigParameters<chains, transports>,
+): Config<chains, transports> {
+  const {
+    autoConnect,
+    chains,
+    reconnectOnMount = autoConnect ?? true,
+    storage = createStorage({
+      storage:
+        typeof window !== 'undefined' && window.localStorage
+          ? window.localStorage
+          : noopStorage,
+    }),
+    syncConnectedChain = true,
+    ...rest
+  } = parameters
+
+  /////////////////////////////////////////////////////////////////////////////////////////////////
+  // Set up connectors, clients, etc.
+  /////////////////////////////////////////////////////////////////////////////////////////////////
+
+  const connectors = (rest.connectors ?? []).map(setup)
+  function setup(connectorFn: CreateConnectorFn) {
+    // Set up emitter with uid and add to connector so they are "linked" together.
+    const emitter = createEmitter<ConnectorEventMap>(uid())
+    const connector = {
+      ...connectorFn({ emitter, chains, storage }),
+      emitter,
+      uid: emitter.uid,
+    }
+
+    // Start listening for `connect` events if `reconnectOnMount` is switched on.
+    // This allows connectors to "connect" themselves without user interaction (e.g. MetaMask's "Manually connect to current site")
+    if (reconnectOnMount) emitter.on('connect', connect)
+    connector.setup?.()
+
+    return connector
+  }
+
+  const clients = new Map<number, Client<Transport, chains[number]>>()
+  function getClient<chainId extends chains[number]['id']>(
+    config: { chainId?: chainId | chains[number]['id'] | undefined } = {},
+  ): Client<Transport, Extract<chains[number], { id: chainId }>> {
+    const chainId = config.chainId ?? store.getState().chainId
+    const chain = chains.find((x) => x.id === chainId)
+
+    // If the target chain is not configured, use the client of the current chain.
+    // TODO: should we error instead? idk. figure out later.
+    type Return = Client<Transport, Extract<chains[number], { id: chainId }>>
+    {
+      const client = clients.get(store.getState().chainId)
+      if (client && !chain) return client as Return
+      else if (!chain) throw new ChainNotConfiguredError()
+    }
+
+    // If a memoized client exists for a chain id, use that.
+    {
+      const client = clients.get(chainId)
+      if (client) return client as Return
+    }
+
+    let client
+    if (rest.client) client = rest.client({ chain })
+    else {
+      const chainId = chain.id as chains[number]['id']
+      // Grab all properties off `rest` and resolve for use in `createClient`
+      const properties: Partial<viem_ClientConfig> = {}
+      const entries = Object.entries(rest) as [keyof typeof rest, any][]
+      for (const [key, value] of entries) {
+        if (key === 'client' || key === 'connectors' || key === 'transports')
+          continue
+        else {
+          if (typeof value === 'object') properties[key] = value[chainId]
+          else properties[key] = value
+        }
+      }
+      client = createClient({
+        ...properties,
+        chain,
+        batch: properties.batch ?? { multicall: true },
+        transport: rest.transports[chainId],
+      })
+    }
+
+    clients.set(chainId, client)
+    return client as Return
+  }
+
+  /////////////////////////////////////////////////////////////////////////////////////////////////
+  // Create store
+  /////////////////////////////////////////////////////////////////////////////////////////////////
+
+  const initialState: State = {
+    chainId: chains[0].id,
+    connections: new Map(),
+    current: undefined,
+    status: 'disconnected',
+  }
+
+  const store = createStore(
+    subscribeWithSelector(
+      // only use persist middleware if storage exists
+      storage
+        ? persist(() => initialState, {
+            name: 'store',
+            partialize(state) {
+              return {
+                chainId: state.chainId,
+                connections: state.connections,
+                current: state.current,
+                status: state.status,
+              } satisfies PartializedState
+            },
+            skipHydration: !reconnectOnMount,
+            storage: storage as Storage<Record<string, unknown>>,
+            version: 1,
+          })
+        : () => initialState,
+    ),
+  )
+
+  /////////////////////////////////////////////////////////////////////////////////////////////////
+  // Subscribe to changes
+  /////////////////////////////////////////////////////////////////////////////////////////////////
+
+  // Update default chain when connector chain changes
+  if (syncConnectedChain)
+    store.subscribe(
+      ({ connections, current }) =>
+        current ? connections.get(current)?.chainId : undefined,
+      (chainId) => {
+        // If chain is not configured, then don't switch over to it.
+        const isChainConfigured = chains.some((x) => x.id === chainId)
+        if (!isChainConfigured) return
+
+        return store.setState((x) => ({
+          ...x,
+          chainId: chainId ?? x.chainId,
+        }))
+      },
+    )
+
+  /////////////////////////////////////////////////////////////////////////////////////////////////
+  // Emitter listeners
+  /////////////////////////////////////////////////////////////////////////////////////////////////
+
+  function change(data: EventData<ConnectorEventMap, 'change'>) {
+    store.setState((x) => {
+      const connection = x.connections.get(data.uid)!
+      return {
+        ...x,
+        connections: new Map(x.connections).set(data.uid, {
+          accounts:
+            (data.accounts as readonly [Address, ...Address[]]) ??
+            connection.accounts,
+          chainId: data.chainId ?? connection.chainId,
+          connector: connection.connector,
+        }),
+      }
+    })
+  }
+  function connect(data: EventData<ConnectorEventMap, 'connect'>) {
+    // Disable handling if reconnecting
+    if (store.getState().status === 'reconnecting') return
+
+    store.setState((x) => {
+      const connector = connectors.find((x) => x.uid === data.uid)
+      if (!connector) return x
+      return {
+        ...x,
+        connections: new Map(x.connections).set(data.uid, {
+          accounts: data.accounts as readonly [Address, ...Address[]],
+          chainId: data.chainId,
+          connector: connector,
+        }),
+        current: data.uid,
+        status: 'connected',
+      }
+    })
+  }
+  function disconnect(data: EventData<ConnectorEventMap, 'disconnect'>) {
+    store.setState((x) => {
+      const connection = x.connections.get(data.uid)
+      if (connection) {
+        connection.connector.emitter.off('change', change)
+        connection.connector.emitter.off('disconnect', disconnect)
+        connection.connector.emitter.on('connect', connect)
+      }
+
+      x.connections.delete(data.uid)
+
+      if (x.connections.size === 0)
+        return {
+          ...x,
+          connections: new Map(),
+          current: undefined,
+          status: 'disconnected',
+        }
+
+      const nextConnection = x.connections.values().next().value as Connection
+      return {
+        ...x,
+        connections: new Map(x.connections),
+        current: nextConnection.connector.uid,
+      }
+    })
+  }
+
+  return {
+    chains: chains as chains,
+    connectors,
+    get state() {
+      return store.getState() as unknown as State<chains>
+    },
+    storage,
+
+    getClient,
+    setState(value) {
+      let newState: State
+      if (typeof value === 'function') newState = value(store.getState() as any)
+      else newState = value
+
+      // Reset state if it got set to something not matching the base state
+      if (typeof newState !== 'object') newState = initialState
+      const isCorrupt = Object.keys(initialState).some((x) => !(x in newState))
+      if (isCorrupt) newState = initialState
+
+      store.setState(newState, true)
+    },
+    subscribe(selector, listener, options) {
+      return store.subscribe(
+        selector as unknown as (state: State) => any,
+        listener,
+        options,
+      )
+    },
+
+    _internal: {
+      reconnectOnMount,
+      syncConnectedChain,
+      transports: rest.transports as transports,
+      change,
+      connect,
+      disconnect,
+      setup,
+    },
+  }
+}
+
+/////////////////////////////////////////////////////////////////////////////////////////////////
+// Types
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+export type State<
+  chains extends readonly [Chain, ...Chain[]] = readonly [Chain, ...Chain[]],
+> = {
+  chainId: chains[number]['id']
+  connections: Map<string, Connection>
+  current: string | undefined
+  status: 'connected' | 'connecting' | 'disconnected' | 'reconnecting'
+}
+
+export type PartializedState = Evaluate<
+  ExactPartial<Pick<State, 'chainId' | 'connections' | 'current' | 'status'>>
+>
+
+export type Connection = {
+  accounts: readonly [Address, ...Address[]]
+  chainId: number
+  connector: Connector
+}
+
+export type Connector = ReturnType<CreateConnectorFn> & {
+  emitter: Emitter<ConnectorEventMap>
+  uid: string
+}
+
+type ClientConfig = LooseOmit<
+  viem_ClientConfig,
+  'account' | 'chain' | 'key' | 'name' | 'transport' | 'type'
+>

package/src/createConnector.ts

@@ -0,0 +1,78 @@
+import {
+  type Address,
+  type Chain,
+  type Client,
+  type ProviderConnectInfo,
+  type ProviderMessage,
+} from 'viem'
+
+import { Emitter } from './createEmitter.js'
+import { type Storage } from './createStorage.js'
+import { type Evaluate } from './types/utils.js'
+
+export type ConnectorEventMap = {
+  change: {
+    accounts?: readonly Address[] | undefined
+    chainId?: number | undefined
+  }
+  connect: { accounts: readonly Address[]; chainId: number }
+  disconnect: never
+  error: { error: Error }
+  message: { type: string; data?: unknown | undefined }
+}
+
+export type CreateConnectorFn<
+  provider = unknown,
+  properties extends Record<string, unknown> = {},
+  storageItem extends Record<string, unknown> = {},
+> = (config: {
+  chains: readonly [Chain, ...Chain[]]
+  emitter: Emitter<ConnectorEventMap>
+  storage?: Evaluate<Storage<storageItem>> | null | undefined
+}) => Evaluate<
+  {
+    readonly id: string
+    readonly name: string
+
+    setup?(): Promise<void>
+    connect(
+      parameters?: { chainId?: number | undefined } | undefined,
+    ): Promise<{
+      accounts: readonly Address[]
+      chainId: number
+    }>
+    disconnect(): Promise<void>
+    getAccounts(): Promise<readonly Address[]>
+    getChainId(): Promise<number>
+    getProvider(
+      parameters?:
+        | {
+            chainId?: number | undefined
+          }
+        | undefined,
+    ): Promise<provider>
+    getClient?(
+      parameters?:
+        | {
+            chainId?: number | undefined
+          }
+        | undefined,
+    ): Promise<Client>
+    isAuthorized(): Promise<boolean>
+    switchChain?(parameters: { chainId: number }): Promise<Chain>
+
+    onAccountsChanged(accounts: string[]): void
+    onChainChanged(chainId: string): void
+    onConnect?(connectInfo: ProviderConnectInfo): void
+    onDisconnect(error?: Error | undefined): void
+    onMessage?(message: ProviderMessage): void
+  } & properties
+>
+
+export function createConnector<
+  provider,
+  properties extends Record<string, unknown> = {},
+  storageItem extends Record<string, unknown> = {},
+>(fn: CreateConnectorFn<provider, properties, storageItem>) {
+  return fn
+}

package/src/createEmitter.ts

@@ -0,0 +1,68 @@
+import { EventEmitter } from 'eventemitter3'
+
+type EventMap = Record<string, object | never>
+type EventKey<eventMap extends EventMap> = string & keyof eventMap
+type EventFn<parameters extends unknown[] = any[]> = (
+  ...parameters: parameters
+) => void
+export type EventData<
+  eventMap extends EventMap,
+  eventName extends keyof eventMap,
+> = (eventMap[eventName] extends [never] ? unknown : eventMap[eventName]) & {
+  uid: string
+}
+
+export class Emitter<eventMap extends EventMap> {
+  #emitter = new EventEmitter()
+
+  constructor(public uid: string) {}
+
+  on<key extends EventKey<eventMap>>(
+    eventName: key,
+    fn: EventFn<
+      eventMap[key] extends [never]
+        ? [{ uid: string }]
+        : [data: eventMap[key] & { uid: string }]
+    >,
+  ) {
+    this.#emitter.on(eventName, fn as EventFn)
+  }
+
+  once<key extends EventKey<eventMap>>(
+    eventName: key,
+    fn: EventFn<
+      eventMap[key] extends [never]
+        ? [{ uid: string }]
+        : [data: eventMap[key] & { uid: string }]
+    >,
+  ) {
+    this.#emitter.once(eventName, fn as EventFn)
+  }
+
+  off<key extends EventKey<eventMap>>(
+    eventName: key,
+    fn: EventFn<
+      eventMap[key] extends [never]
+        ? [{ uid: string }]
+        : [data: eventMap[key] & { uid: string }]
+    >,
+  ) {
+    this.#emitter.off(eventName, fn as EventFn)
+  }
+
+  emit<key extends EventKey<eventMap>>(
+    eventName: key,
+    ...params: eventMap[key] extends [never] ? [] : [data: eventMap[key]]
+  ) {
+    const data = params[0]
+    this.#emitter.emit(eventName, { uid: this.uid, ...data })
+  }
+
+  listenerCount<key extends EventKey<eventMap>>(eventName: key) {
+    return this.#emitter.listenerCount(eventName)
+  }
+}
+
+export function createEmitter<eventMap extends EventMap>(uid: string) {
+  return new Emitter<eventMap>(uid)
+}

package/src/createStorage.ts

@@ -0,0 +1,89 @@
+import { type PartializedState } from './createConfig.js'
+import type { Evaluate } from './types/utils.js'
+import { deserialize as deserialize_ } from './utils/deserialize.js'
+import { serialize as serialize_ } from './utils/serialize.js'
+
+// key-values for loose autocomplete and typing
+export type StorageItemMap = {
+  recentConnectorId: string
+  state: PartializedState
+}
+
+export type Storage<
+  itemMap extends Record<string, unknown> = {},
+  ///
+  storageItemMap extends StorageItemMap = StorageItemMap & itemMap,
+> = {
+  getItem<
+    key extends keyof storageItemMap,
+    value extends storageItemMap[key],
+    defaultValue extends value | null | undefined,
+  >(
+    key: key,
+    defaultValue?: defaultValue | undefined,
+  ):
+    | (defaultValue extends null ? value | null : value)
+    | Promise<defaultValue extends null ? value | null : value>
+  setItem<
+    key extends keyof storageItemMap,
+    value extends storageItemMap[key] | null,
+  >(key: key, value: value): void | Promise<void>
+  removeItem(key: keyof storageItemMap): void | Promise<void>
+}
+
+type BaseStorage = {
+  getItem(
+    key: string,
+  ): string | null | undefined | Promise<string | null | undefined>
+  setItem(key: string, value: string): void | Promise<void>
+  removeItem(key: string): void | Promise<void>
+}
+
+export type CreateStorageParameters = {
+  deserialize?: (<T>(value: string) => T) | undefined
+  key?: string | undefined
+  serialize?: (<T>(value: T) => string) | undefined
+  storage: Evaluate<BaseStorage>
+}
+
+export function createStorage<
+  itemMap extends Record<string, unknown> = {},
+  storageItemMap extends StorageItemMap = StorageItemMap & itemMap,
+>(parameters: CreateStorageParameters): Evaluate<Storage<storageItemMap>> {
+  const {
+    deserialize = deserialize_,
+    key: prefix = 'wagmi',
+    serialize = serialize_,
+    storage,
+  } = parameters
+
+  function unwrap<type>(value: type): type | Promise<type> {
+    if (value instanceof Promise)
+      return value.then((x) => x).catch(() => undefined)
+    return value
+  }
+
+  return {
+    ...storage,
+    async getItem(key, defaultValue) {
+      const value = storage.getItem(`${prefix}.${key as string}`)
+      const unwrapped = await unwrap(value)
+      if (unwrapped) return deserialize(unwrapped) ?? null
+      return (defaultValue ?? null) as any
+    },
+    async setItem(key, value) {
+      const storageKey = `${prefix}.${key as string}`
+      if (value === null) await unwrap(storage.removeItem(storageKey))
+      else await unwrap(storage.setItem(storageKey, serialize(value)))
+    },
+    async removeItem(key) {
+      await unwrap(storage.removeItem(`${prefix}.${key as string}`))
+    },
+  }
+}
+
+export const noopStorage = {
+  getItem: () => null,
+  setItem: () => {},
+  removeItem: () => {},
+} satisfies BaseStorage

package/src/errors/base.ts

@@ -0,0 +1,71 @@
+import type { Evaluate, OneOf } from '../types/utils.js'
+import { getVersion } from '../utils/getVersion.js'
+
+type BaseErrorOptions = Evaluate<
+  {
+    docsPath?: string
+    docsSlug?: string
+    metaMessages?: string[]
+  } & OneOf<{ details?: string } | { cause: BaseError | Error }>
+>
+
+export class BaseError extends Error {
+  details: string
+  docsPath?: string | undefined
+  metaMessages?: string[] | undefined
+  shortMessage: string
+
+  override name = 'WagmiCoreError'
+  get docsBaseUrl() {
+    return 'https://alpha.wagmi.sh/core'
+  }
+  get version() {
+    return getVersion()
+  }
+
+  constructor(shortMessage: string, options: BaseErrorOptions = {}) {
+    super()
+
+    const details =
+      options.cause instanceof BaseError
+        ? options.cause.details
+        : options.cause?.message
+        ? options.cause.message
+        : options.details!
+    const docsPath =
+      options.cause instanceof BaseError
+        ? options.cause.docsPath || options.docsPath
+        : options.docsPath
+
+    this.message = [
+      shortMessage || 'An error occurred.',
+      '',
+      ...(options.metaMessages ? [...options.metaMessages, ''] : []),
+      ...(docsPath
+        ? [
+            `Docs: ${this.docsBaseUrl}${docsPath}.html${
+              options.docsSlug ? `#${options.docsSlug}` : ''
+            }`,
+          ]
+        : []),
+      ...(details ? [`Details: ${details}`] : []),
+      `Version: ${this.version}`,
+    ].join('\n')
+
+    if (options.cause) this.cause = options.cause
+    this.details = details
+    this.docsPath = docsPath
+    this.metaMessages = options.metaMessages
+    this.shortMessage = shortMessage
+  }
+
+  walk(fn?: (err: unknown) => boolean) {
+    return this.#walk(this, fn)
+  }
+
+  #walk(err: unknown, fn?: (err: unknown) => boolean): unknown {
+    if (fn?.(err)) return err
+    if ((err as Error).cause) return this.#walk((err as Error).cause, fn)
+    return err
+  }
+}