viem 2.4.0 → 2.5.0

package/node/index.ts

@@ -0,0 +1,11 @@
+export {
+  type IpcTransport,
+  type IpcTransportConfig,
+  type IpcTransportErrorType,
+  ipc,
+} from '../clients/transports/ipc.js'
+
+export {
+  type IpcRpcClient,
+  getIpcRpcClient,
+} from '../utils/rpc/ipc.js'

package/node/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../_types/node/index.d.ts",
+  "module": "../_esm/node/index.js",
+  "main": "../_cjs/node/index.js"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "viem",
   "description": "TypeScript Interface for Ethereum",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",
@@ -52,6 +52,11 @@
       "import": "./_esm/ens/index.js",
       "default": "./_cjs/ens/index.js"
     },
+    "./node": {
+      "types": "./_types/node/index.d.ts",
+      "import": "./_esm/node/index.js",
+      "default": "./_cjs/node/index.js"
+    },
     "./op-stack": {
       "types": "./_types/chains/opStack/index.d.ts",
       "import": "./_esm/chains/opStack/index.js",
@@ -94,6 +99,9 @@
       "ens": [
         "./_types/ens/index.d.ts"
       ],
+      "node": [
+        "./_types/node/index.d.ts"
+      ],
       "op-stack": [
         "./_types/chains/opStack/index.d.ts"
       ],

package/types/rpc.ts

@@ -57,3 +57,47 @@ export type RpcTransaction<TPending extends boolean = boolean> = UnionOmit<
   >,
   'typeHex'
 >
+
+type SuccessResult<T> = {
+  method?: never
+  result: T
+  error?: never
+}
+type ErrorResult<T> = {
+  method?: never
+  result?: never
+  error: T
+}
+type Subscription<TResult, TError> = {
+  method: 'eth_subscription'
+  error?: never
+  result?: never
+  params: {
+    subscription: string
+  } & (
+    | {
+        result: TResult
+        error?: never
+      }
+    | {
+        result?: never
+        error: TError
+      }
+  )
+}
+
+export type RpcRequest = {
+  jsonrpc?: '2.0'
+  method: string
+  params?: any
+  id?: number
+}
+
+export type RpcResponse<TResult = any, TError = any> = {
+  jsonrpc: `${number}`
+  id: number
+} & (
+  | SuccessResult<TResult>
+  | ErrorResult<TError>
+  | Subscription<TResult, TError>
+)

package/utils/buildRequest.ts

@@ -57,7 +57,7 @@ import type {
 } from '../types/eip1193.js'
 import type { CreateBatchSchedulerErrorType } from './promise/createBatchScheduler.js'
 import { type WithRetryErrorType, withRetry } from './promise/withRetry.js'
-import type { GetSocketErrorType } from './rpc.js'
+import type { GetSocketRpcClientErrorType } from './rpc/socket.js'
 
 export type RequestErrorType =
   | ChainDisconnectedErrorType
@@ -67,7 +67,7 @@ export type RequestErrorType =
   | InvalidInputRpcErrorType
   | InvalidParamsRpcErrorType
   | InvalidRequestRpcErrorType
-  | GetSocketErrorType
+  | GetSocketRpcClientErrorType
   | JsonRpcVersionUnsupportedErrorType
   | LimitExceededRpcErrorType
   | MethodNotFoundRpcErrorType

package/utils/index.ts

@@ -32,13 +32,6 @@ export {
 export { arrayRegex, bytesRegex, integerRegex } from './regex.js'
 
 export {
-  type GetSocketErrorType,
-  type HttpErrorType,
-  type HttpOptions,
-  type HttpReturnType,
-  type RpcRequest,
-  type RpcResponse,
-  type Socket,
   type WebSocketAsyncErrorType,
   type WebSocketAsyncOptions,
   type WebSocketAsyncReturnType,
@@ -47,7 +40,25 @@ export {
   type WebSocketReturnType,
   getSocket,
   rpc,
-} from './rpc.js'
+} from './rpc/compat.js'
+export {
+  type HttpRpcClient,
+  type HttpRpcClientOptions,
+  type HttpRequestErrorType,
+  type HttpRequestParameters,
+  type HttpRequestReturnType,
+  getHttpRpcClient,
+} from './rpc/http.js'
+export {
+  type GetSocketRpcClientErrorType,
+  type GetSocketRpcClientParameters,
+  type GetSocketParameters,
+  type Socket,
+  type SocketRpcClient,
+  getSocketRpcClient,
+  socketClientCache,
+} from './rpc/socket.js'
+export { getWebSocketRpcClient } from './rpc/webSocket.js'
 export { type StringifyErrorType, stringify } from './stringify.js'
 export {
   type DomainSeparatorErrorType,

package/utils/rpc/compat.ts

@@ -0,0 +1,117 @@
+// TODO(v3): This file is here for backwards compatibility, and to prevent breaking changes.
+// These APIs will be removed in v3.
+
+/* c8 ignore start */
+import {
+  type TimeoutErrorType,
+  WebSocketRequestError,
+} from '../../errors/request.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { RpcResponse } from '../../types/rpc.js'
+import { type WithTimeoutErrorType } from '../promise/withTimeout.js'
+import { type HttpRequestParameters, getHttpRpcClient } from './http.js'
+import { type SocketRpcClient } from './socket.js'
+import { getWebSocketRpcClient } from './webSocket.js'
+
+export type WebSocketOptions = Parameters<
+  SocketRpcClient<WebSocket>['request']
+>[0]
+export type WebSocketReturnType = SocketRpcClient<WebSocket>
+export type WebSocketErrorType = WebSocketRequestError | ErrorType
+
+function webSocket(
+  socketClient: SocketRpcClient<WebSocket>,
+  { body, onError, onResponse }: WebSocketOptions,
+): WebSocketReturnType {
+  socketClient.request({
+    body,
+    onError,
+    onResponse,
+  })
+  return socketClient
+}
+
+export type WebSocketAsyncOptions = Parameters<
+  SocketRpcClient<WebSocket>['requestAsync']
+>[0]
+export type WebSocketAsyncReturnType = RpcResponse
+export type WebSocketAsyncErrorType =
+  | WebSocketErrorType
+  | TimeoutErrorType
+  | WithTimeoutErrorType
+  | ErrorType
+
+async function webSocketAsync(
+  socketClient: SocketRpcClient<WebSocket>,
+  { body, timeout = 10_000 }: WebSocketAsyncOptions,
+): Promise<WebSocketAsyncReturnType> {
+  return socketClient.requestAsync({
+    body,
+    timeout,
+  })
+}
+
+/**
+ * @deprecated use `getSocketClient` instead.
+ *
+ * ```diff
+ * -import { getSocket } from 'viem/utils'
+ * +import { getSocketClient } from 'viem/utils'
+ *
+ * -const socket = await getSocket(url)
+ * +const socketClient = await getSocketClient(url)
+ * +const socket = socketClient.socket
+ * ```
+ */
+export async function getSocket(url: string) {
+  const client = await getWebSocketRpcClient(url)
+  return Object.assign(client.socket, {
+    requests: client.requests,
+    subscriptions: client.subscriptions,
+  })
+}
+
+export const rpc = {
+  /**
+   * @deprecated use `getHttpRpcClient` instead.
+   *
+   * ```diff
+   * -import { rpc } from 'viem/utils'
+   * +import { getHttpRpcClient } from 'viem/utils'
+   *
+   * -rpc.http(url, params)
+   * +const httpClient = getHttpRpcClient(url)
+   * +httpClient.request(params)
+   * ```
+   */
+  http(url: string, params: HttpRequestParameters) {
+    return getHttpRpcClient(url).request(params)
+  },
+  /**
+   * @deprecated use `getWebSocketRpcClient` instead.
+   *
+   * ```diff
+   * -import { rpc } from 'viem/utils'
+   * +import { getWebSocketRpcClient } from 'viem/utils'
+   *
+   * -rpc.webSocket(url, params)
+   * +const webSocketClient = getWebSocketRpcClient(url)
+   * +webSocketClient.request(params)
+   * ```
+   */
+  webSocket,
+  /**
+   * @deprecated use `getWebSocketRpcClient` instead.
+   *
+   * ```diff
+   * -import { rpc } from 'viem/utils'
+   * +import { getWebSocketRpcClient } from 'viem/utils'
+   *
+   * -const response = await rpc.webSocketAsync(url, params)
+   * +const webSocketClient = getWebSocketRpcClient(url)
+   * +const response = await webSocketClient.requestAsync(params)
+   * ```
+   */
+  webSocketAsync,
+}
+/* c8 ignore end */

package/utils/rpc/http.ts

@@ -0,0 +1,132 @@
+import {
+  HttpRequestError,
+  type HttpRequestErrorType as HttpRequestErrorType_,
+  TimeoutError,
+  type TimeoutErrorType,
+} from '../../errors/request.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { RpcRequest, RpcResponse } from '../../types/rpc.js'
+import {
+  type WithTimeoutErrorType,
+  withTimeout,
+} from '../promise/withTimeout.js'
+import { stringify } from '../stringify.js'
+import { idCache } from './id.js'
+
+export type HttpRpcClientOptions = {
+  // Request configuration to pass to `fetch`.
+  fetchOptions?: Omit<RequestInit, 'body'>
+  // The timeout (in ms) for the request.
+  timeout?: number
+}
+
+export type HttpRequestParameters<
+  TBody extends RpcRequest | RpcRequest[] = RpcRequest,
+> = {
+  // The RPC request body.
+  body: TBody
+  // Request configuration to pass to `fetch`.
+  fetchOptions?: HttpRpcClientOptions['fetchOptions']
+  // The timeout (in ms) for the request.
+  timeout?: HttpRpcClientOptions['timeout']
+}
+
+export type HttpRequestReturnType<
+  TBody extends RpcRequest | RpcRequest[] = RpcRequest,
+> = TBody extends RpcRequest[] ? RpcResponse[] : RpcResponse
+
+export type HttpRequestErrorType =
+  | HttpRequestErrorType_
+  | TimeoutErrorType
+  | WithTimeoutErrorType
+  | ErrorType
+
+export type HttpRpcClient = {
+  request<TBody extends RpcRequest | RpcRequest[]>(
+    params: HttpRequestParameters<TBody>,
+  ): Promise<HttpRequestReturnType<TBody>>
+}
+
+export function getHttpRpcClient(
+  url: string,
+  options: HttpRpcClientOptions = {},
+): HttpRpcClient {
+  return {
+    async request(params) {
+      const {
+        body,
+        fetchOptions = {},
+        timeout = options.timeout ?? 10_000,
+      } = params
+      const {
+        headers,
+        method,
+        signal: signal_,
+      } = { ...options.fetchOptions, ...fetchOptions }
+
+      try {
+        const response = await withTimeout(
+          async ({ signal }) => {
+            const response = await fetch(url, {
+              ...fetchOptions,
+              body: Array.isArray(body)
+                ? stringify(
+                    body.map((body) => ({
+                      jsonrpc: '2.0',
+                      id: body.id ?? idCache.take(),
+                      ...body,
+                    })),
+                  )
+                : stringify({
+                    jsonrpc: '2.0',
+                    id: body.id ?? idCache.take(),
+                    ...body,
+                  }),
+              headers: {
+                ...headers,
+                'Content-Type': 'application/json',
+              },
+              method: method || 'POST',
+              signal: signal_ || (timeout > 0 ? signal : undefined),
+            })
+            return response
+          },
+          {
+            errorInstance: new TimeoutError({ body, url }),
+            timeout,
+            signal: true,
+          },
+        )
+
+        let data: any
+        if (
+          response.headers.get('Content-Type')?.startsWith('application/json')
+        ) {
+          data = await response.json()
+        } else {
+          data = await response.text()
+        }
+
+        if (!response.ok) {
+          throw new HttpRequestError({
+            body,
+            details: stringify(data.error) || response.statusText,
+            headers: response.headers,
+            status: response.status,
+            url,
+          })
+        }
+
+        return data
+      } catch (err) {
+        if (err instanceof HttpRequestError) throw err
+        if (err instanceof TimeoutError) throw err
+        throw new HttpRequestError({
+          body,
+          details: (err as Error).message,
+          url,
+        })
+      }
+    },
+  }
+}

package/utils/rpc/id.ts

@@ -0,0 +1,13 @@
+export function createIdStore() {
+  return {
+    current: 0,
+    take() {
+      return this.current++
+    },
+    reset() {
+      this.current = 0
+    },
+  }
+}
+
+export const idCache = /*#__PURE__*/ createIdStore()

package/utils/rpc/ipc.ts

@@ -0,0 +1,89 @@
+import { type Socket as NetSocket, connect } from 'node:net'
+import { WebSocketRequestError } from '../../index.js'
+import {
+  type Socket,
+  type SocketRpcClient,
+  getSocketRpcClient,
+} from './socket.js'
+
+const openingBrace = '{'.charCodeAt(0)
+const closingBrace = '}'.charCodeAt(0)
+
+export function extractMessages(buffer: Buffer): [Buffer[], Buffer] {
+  const messages: Buffer[] = []
+
+  let cursor = 0
+  let level = 0
+  for (let i = 0; i < buffer.length; i++) {
+    if (buffer[i] === openingBrace) level++
+    if (buffer[i] === closingBrace) level--
+    if (level === 0) {
+      const message = buffer.subarray(cursor, i + 1)
+      if (
+        message[0] === openingBrace &&
+        message[message.length - 1] === closingBrace
+      )
+        messages.push(message)
+      cursor = i + 1
+    }
+  }
+
+  return [messages, buffer.subarray(cursor)]
+}
+
+export type IpcRpcClient = SocketRpcClient<NetSocket>
+
+export async function getIpcRpcClient(path: string): Promise<IpcRpcClient> {
+  return getSocketRpcClient({
+    async getSocket({ onResponse }) {
+      const socket = connect(path)
+
+      function onClose() {
+        socket.off('close', onClose)
+        socket.off('message', onData)
+      }
+
+      let lastRemaining = Buffer.alloc(0)
+      function onData(buffer: Buffer) {
+        const [messages, remaining] = extractMessages(
+          Buffer.concat([lastRemaining, buffer]),
+        )
+        for (const message of messages) {
+          const response = JSON.parse(Buffer.from(message).toString())
+          onResponse(response)
+        }
+        lastRemaining = remaining
+      }
+
+      socket.on('close', onClose)
+      socket.on('data', onData)
+
+      // Wait for the socket to open.
+      await new Promise<void>((resolve, reject) => {
+        socket.on('ready', () => {
+          resolve()
+          socket.off('error', reject)
+        })
+        socket.on('error', reject)
+      })
+
+      return Object.assign(socket, {
+        close() {
+          socket.destroy()
+          socket.end()
+        },
+        request({ body }) {
+          if (socket.readyState !== 'open')
+            throw new WebSocketRequestError({
+              body,
+              url: path,
+              details: 'Socket is closed.',
+            })
+
+          return socket.write(JSON.stringify(body))
+        },
+      } as Socket<{}>)
+    },
+    url: path,
+  })
+}

package/utils/rpc/socket.ts

@@ -0,0 +1,162 @@
+import { TimeoutError } from '../../errors/request.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { RpcRequest, RpcResponse } from '../../types/rpc.js'
+import {
+  type CreateBatchSchedulerErrorType,
+  createBatchScheduler,
+} from '../promise/createBatchScheduler.js'
+import { withTimeout } from '../promise/withTimeout.js'
+import { idCache } from './id.js'
+
+type Id = string | number
+type CallbackFn = (message: any) => void
+type CallbackMap = Map<Id, CallbackFn>
+
+export type GetSocketParameters = {
+  onResponse: (data: RpcResponse) => void
+}
+
+export type Socket<socket extends {}> = socket & {
+  close(): void
+  request(params: {
+    body: RpcRequest
+  }): void
+}
+
+export type SocketRpcClient<socket extends {}> = {
+  close(): void
+  socket: Socket<socket>
+  request(params: {
+    body: RpcRequest
+    onError?: (error: Error) => void
+    onResponse: (message: RpcResponse) => void
+  }): void
+  requestAsync(params: {
+    body: RpcRequest
+    timeout?: number
+  }): Promise<RpcResponse>
+  requests: CallbackMap
+  subscriptions: CallbackMap
+  url: string
+}
+
+export type GetSocketRpcClientParameters<socket extends {}> = {
+  url: string
+  getSocket(params: GetSocketParameters): Promise<Socket<socket>>
+}
+
+export type GetSocketRpcClientErrorType =
+  | CreateBatchSchedulerErrorType
+  | ErrorType
+
+export const socketClientCache = /*#__PURE__*/ new Map<
+  string,
+  SocketRpcClient<Socket<{}>>
+>()
+
+export async function getSocketRpcClient<socket extends {}>(
+  params: GetSocketRpcClientParameters<socket>,
+): Promise<SocketRpcClient<socket>> {
+  const { getSocket, url } = params
+
+  let socketClient = socketClientCache.get(url)
+
+  // If the socket already exists, return it.
+  if (socketClient) return socketClient as {} as SocketRpcClient<socket>
+
+  const { schedule } = createBatchScheduler<
+    undefined,
+    [SocketRpcClient<socket>]
+  >({
+    id: url,
+    fn: async () => {
+      // Set up a cache for incoming "synchronous" requests.
+      const requests = new Map<Id, CallbackFn>()
+
+      // Set up a cache for subscriptions (eth_subscribe).
+      const subscriptions = new Map<Id, CallbackFn>()
+
+      // Set up socket implementation.
+      const socket = await getSocket({
+        onResponse(data) {
+          const isSubscription = data.method === 'eth_subscription'
+          const id = isSubscription ? data.params.subscription : data.id
+          const cache = isSubscription ? subscriptions : requests
+          const callback = cache.get(id)
+          if (callback) callback(data)
+          if (!isSubscription) cache.delete(id)
+        },
+      })
+
+      // Create a new socket instance.
+      socketClient = {
+        close() {
+          socket.close()
+          socketClientCache.delete(url)
+        },
+        socket,
+        request({ body, onError, onResponse }) {
+          const id = body.id ?? idCache.take()
+
+          const callback = (response: RpcResponse) => {
+            if (typeof response.id === 'number' && id !== response.id) return
+
+            // If we are subscribing to a topic, we want to set up a listener for incoming
+            // messages.
+            if (
+              body.method === 'eth_subscribe' &&
+              typeof response.result === 'string'
+            )
+              subscriptions.set(response.result, callback)
+
+            // If we are unsubscribing from a topic, we want to remove the listener.
+            if (body.method === 'eth_unsubscribe')
+              subscriptions.delete(body.params?.[0])
+
+            onResponse(response)
+
+            // TODO: delete request?
+          }
+
+          requests.set(id, callback)
+          try {
+            socket.request({
+              body: {
+                jsonrpc: '2.0',
+                id,
+                ...body,
+              },
+            })
+          } catch (error) {
+            onError?.(error as Error)
+          }
+        },
+        requestAsync({ body, timeout = 10_000 }) {
+          return withTimeout(
+            () =>
+              new Promise<RpcResponse>((onResponse, onError) =>
+                this.request({
+                  body,
+                  onError,
+                  onResponse,
+                }),
+              ),
+            {
+              errorInstance: new TimeoutError({ body, url }),
+              timeout,
+            },
+          )
+        },
+        requests,
+        subscriptions,
+        url,
+      }
+      socketClientCache.set(url, socketClient)
+
+      return [socketClient as {} as SocketRpcClient<socket>]
+    },
+  })
+
+  const [_, [socketClient_]] = await schedule()
+  return socketClient_
+}