ox 0.0.1 → 0.1.0

package/RpcResponse.ts

@@ -0,0 +1,389 @@
+import type { Errors, RpcRequest } from './index.js'
+import type {
+  Compute,
+  IsNarrowable,
+  OneOf,
+  UnionPartialBy,
+} from './internal/types.js'
+
+/** A JSON-RPC response object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#request_object). */
+export type RpcResponse<
+  result = unknown,
+  error extends ErrorObject = ErrorObject,
+> = Compute<
+  {
+    id: number
+    jsonrpc: '2.0'
+  } & OneOf<{ result: result } | { error: error }>
+>
+
+/** JSON-RPC error object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#error_object). */
+export type ErrorObject = {
+  code: number
+  message: string
+  data?: unknown | undefined
+}
+
+/**
+ * A type-safe interface to instantiate a JSON-RPC response object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#response_object).
+ *
+ * @example
+ * ### Instantiating a Response Object
+ *
+ * ```ts twoslash
+ * import { RpcResponse } from 'ox'
+ *
+ * const response = RpcResponse.from({
+ *   id: 0,
+ *   jsonrpc: '2.0',
+ *   result: '0x69420',
+ * })
+ * ```
+ *
+ * @example
+ * ### Type-safe Instantiation
+ *
+ * If you have a JSON-RPC request object, you can use it to strongly-type the response. If a `request` is provided,
+ * then the `id` and `jsonrpc` properties will be overridden with the values from the request.
+ *
+ * ```ts twoslash
+ * import { RpcRequest, RpcResponse } from 'ox'
+ *
+ * const request = RpcRequest.from({ id: 0, method: 'eth_blockNumber' })
+ *
+ * const response = RpcResponse.from(
+ *   { result: '0x69420' },
+ *   { request },
+ * )
+ * ```
+ *
+ * @param response - Opaque JSON-RPC response object.
+ * @param options - Parsing options.
+ * @returns Typed JSON-RPC result, or response object (if `raw` is `true`).
+ */
+export function from<
+  request extends RpcRequest.RpcRequest | undefined = undefined,
+  const response =
+    | (request extends RpcRequest.RpcRequest
+        ? request['_returnType']
+        : RpcResponse)
+    | unknown,
+>(
+  response: from.Response<request, response>,
+  options?: from.Options<request>,
+): Compute<from.ReturnType<response>>
+// eslint-disable-next-line jsdoc/require-jsdoc
+export function from(response: RpcResponse, options: any = {}): RpcResponse {
+  const { request } = options
+  return {
+    ...response,
+    id: response.id ?? request?.id,
+    jsonrpc: response.jsonrpc ?? request.jsonrpc,
+  }
+}
+
+export declare namespace from {
+  type Response<
+    request extends RpcRequest.RpcRequest | undefined = undefined,
+    response = unknown,
+  > = response &
+    (request extends RpcRequest.RpcRequest
+      ? UnionPartialBy<RpcResponse<request['_returnType']>, 'id' | 'jsonrpc'>
+      : RpcResponse)
+
+  type Options<
+    request extends RpcRequest.RpcRequest | undefined =
+      | RpcRequest.RpcRequest
+      | undefined,
+  > = {
+    request?: request | RpcRequest.RpcRequest | undefined
+  }
+
+  type ReturnType<response> = IsNarrowable<response, RpcResponse> extends true
+    ? RpcResponse
+    : response & Readonly<{ id: number; jsonrpc: '2.0' }>
+}
+
+/**
+ * A type-safe interface to parse a JSON-RPC response object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#response_object), and extract the result.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcRequest, RpcResponse } from 'ox'
+ *
+ * // 1. Create a request store.
+ * const store = RpcRequest.createStore()
+ *
+ * // 2. Get a request object.
+ * const request = store.prepare({
+ *   method: 'eth_getBlockByNumber',
+ *   params: ['0x1', false],
+ * })
+ *
+ * // 3. Send the JSON-RPC request via HTTP.
+ * const block = await fetch('https://1.rpc.thirdweb.com', {
+ *   body: JSON.stringify(request),
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *   },
+ *   method: 'POST',
+ * })
+ *  .then((response) => response.json())
+ *  // 4. Parse the JSON-RPC response into a type-safe result. // [!code focus]
+ *  .then((response) => RpcResponse.parse(response, { request })) // [!code focus]
+ *
+ * block // [!code focus]
+ * // ^?
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ *
+ * :::tip
+ *
+ * If you don't need the return type, you can omit the options entirely.
+ *
+ * ```ts twoslash
+ * // @noErrors
+ * import { RpcResponse } from 'ox'
+ *
+ * const block = await fetch('https://1.rpc.thirdweb.com', {})
+ *  .then((response) => response.json())
+ *  .then((response) => RpcResponse.parse(response, { request })) // [!code --]
+ *  .then(RpcResponse.parse) // [!code ++]
+ * ```
+ * :::
+ *
+ * @example
+ * ### Raw Mode
+ *
+ * If `raw` is `true`, the response will be returned as an object with `result` and `error` properties instead of returning the `result` directly and throwing errors.
+ *
+ * ```ts twoslash
+ * import { RpcRequest, RpcResponse } from 'ox'
+ *
+ * const store = RpcRequest.createStore()
+ *
+ * const request = store.prepare({
+ *   method: 'eth_blockNumber',
+ * })
+ *
+ * const response = RpcResponse.parse({}, {
+ *   request,
+ *   raw: true, // [!code hl]
+ * })
+ *
+ * response.result
+ * //       ^?
+ *
+ *
+ * response.error
+ * //       ^?
+ *
+ *
+ * ```
+ *
+ * @param response - Opaque JSON-RPC response object.
+ * @param options - Parsing options.
+ * @returns Typed JSON-RPC result, or response object (if `raw` is `true`).
+ */
+export function parse<
+  const response extends RpcResponse | unknown,
+  returnType,
+  raw extends boolean = false,
+>(
+  response: response,
+  options: parse.Options<returnType, raw> = {},
+): parse.ReturnType<
+  unknown extends response
+    ? returnType
+    : response extends RpcResponse
+      ? response extends { result: infer result }
+        ? result
+        : never
+      : returnType,
+  raw
+> {
+  const { raw = false } = options
+  const response_ = response as RpcResponse
+  if (raw) return response as never
+  if (response_.error) {
+    const { code } = response_.error
+    const JsonRpcError = (() => {
+      if (code === InternalError.code) return InternalError
+      if (code === InvalidInputError.code) return InvalidInputError
+      if (code === InvalidParamsError.code) return InvalidParamsError
+      if (code === InvalidRequestError.code) return InvalidRequestError
+      if (code === LimitExceededError.code) return LimitExceededError
+      if (code === MethodNotFoundError.code) return MethodNotFoundError
+      if (code === MethodNotSupportedError.code) return MethodNotSupportedError
+      if (code === ParseError.code) return ParseError
+      if (code === ResourceNotFoundError.code) return ResourceNotFoundError
+      if (code === ResourceUnavailableError.code)
+        return ResourceUnavailableError
+      if (code === TransactionRejectedError.code)
+        return TransactionRejectedError
+      if (code === VersionNotSupportedError.code)
+        return VersionNotSupportedError
+      return BaseError
+    })()
+    throw new JsonRpcError(response_.error)
+  }
+  return response_.result as never
+}
+
+export declare namespace parse {
+  type Options<returnType, raw extends boolean = false> = {
+    /**
+     * JSON-RPC Method that was used to make the request. Used for typing the response.
+     */
+    request?:
+      | {
+          _returnType: returnType
+        }
+      | RpcRequest.RpcRequest
+      | undefined
+    /**
+     * Enables raw mode – responses will return an object with `result` and `error` properties instead of returning the `result` directly and throwing errors.
+     *
+     * - `true`: a JSON-RPC response object will be returned with `result` and `error` properties.
+     * - `false`: the JSON-RPC response object's `result` property will be returned directly, and JSON-RPC Errors will be thrown.
+     *
+     * @default false
+     */
+    raw?: raw | boolean | undefined
+  }
+
+  type ReturnType<returnType, raw extends boolean = false> = Compute<
+    raw extends true ? RpcResponse<returnType> : returnType
+  >
+
+  type ErrorType =
+    | ParseError
+    | InvalidInputError
+    | ResourceNotFoundError
+    | ResourceUnavailableError
+    | TransactionRejectedError
+    | MethodNotSupportedError
+    | LimitExceededError
+    | VersionNotSupportedError
+    | InvalidRequestError
+    | MethodNotFoundError
+    | InvalidParamsError
+    | InternalError
+    | BaseErrorType
+    | Errors.GlobalErrorType
+}
+
+parse.parseError = (error: unknown) =>
+  /* v8 ignore next */
+  error as parse.ErrorType
+
+export type BaseErrorType = BaseError & { name: 'BaseError' }
+
+/** Thrown when a JSON-RPC error has occurred. */
+export class BaseError extends Error {
+  override name = 'RpcResponse.BaseError'
+
+  readonly code: number
+  readonly data?: unknown | undefined
+
+  constructor(errorObject: ErrorObject) {
+    const { code, message, data } = errorObject
+    super(message)
+    this.code = code
+    this.data = data
+  }
+}
+
+/** Thrown when the input to a JSON-RPC method is invalid. */
+export class InvalidInputError extends BaseError {
+  static readonly code = -32000
+  override readonly code = -32000
+  override readonly name = 'RpcResponse.InvalidInputError'
+}
+
+/** Thrown when a JSON-RPC resource is not found. */
+export class ResourceNotFoundError extends BaseError {
+  static readonly code = -32001
+  override readonly code = -32001
+  override readonly name = 'RpcResponse.ResourceNotFoundError'
+}
+
+/** Thrown when a JSON-RPC resource is unavailable. */
+export class ResourceUnavailableError extends BaseError {
+  static readonly code = -32002
+  override readonly code = -32002
+  override readonly name = 'RpcResponse.ResourceUnavailableError'
+}
+
+/** Thrown when a JSON-RPC transaction is rejected. */
+export class TransactionRejectedError extends BaseError {
+  static readonly code = -32003
+  override readonly code = -32003
+  override readonly name = 'RpcResponse.TransactionRejectedError'
+}
+
+/** Thrown when a JSON-RPC method is not supported. */
+export class MethodNotSupportedError extends BaseError {
+  static readonly code = -32004
+  override readonly code = -32004
+  override readonly name = 'RpcResponse.MethodNotSupportedError'
+}
+
+/** Thrown when a rate-limit is exceeded. */
+export class LimitExceededError extends BaseError {
+  static readonly code = -32005
+  override readonly code = -32005
+  override readonly name = 'RpcResponse.LimitExceededError'
+}
+
+/** Thrown when a JSON-RPC version is not supported. */
+export class VersionNotSupportedError extends BaseError {
+  static readonly code = -32006
+  override readonly code = -32006
+  override readonly name = 'RpcResponse.VersionNotSupportedError'
+}
+
+/** Thrown when a JSON-RPC request is invalid. */
+export class InvalidRequestError extends BaseError {
+  static readonly code = -32600
+  override readonly code = -32600
+  override readonly name = 'RpcResponse.InvalidRequestError'
+}
+
+/** Thrown when a JSON-RPC method is not found. */
+export class MethodNotFoundError extends BaseError {
+  static readonly code = -32601
+  override readonly code = -32601
+  override readonly name = 'RpcResponse.MethodNotFoundError'
+}
+
+/** Thrown when the parameters to a JSON-RPC method are invalid. */
+export class InvalidParamsError extends BaseError {
+  static readonly code = -32602
+  override readonly code = -32602
+  override readonly name = 'RpcResponse.InvalidParamsError'
+}
+
+/** Thrown when an internal JSON-RPC error has occurred. */
+export class InternalError extends BaseError {
+  static readonly code = -32603
+  override readonly code = -32603
+  override readonly name = 'RpcResponse.InternalErrorError'
+}
+
+/** Thrown when a JSON-RPC response is invalid. */
+export class ParseError extends BaseError {
+  static readonly code = -32700
+  override readonly code = -32700
+  override readonly name = 'RpcResponse.ParseError'
+}

package/RpcSchema/package.json

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

package/RpcSchema.ts

@@ -0,0 +1,273 @@
+import type { ResolvedRegister } from './internal/register.js'
+import type { Compute, IsNarrowable } from './internal/types.js'
+
+export type { Eth } from './internal/rpcSchemas/eth.js'
+export type { Wallet } from './internal/rpcSchemas/wallet.js'
+
+/**
+ * Instantiates a statically typed Schema. This is a runtime-noop function, and is purposed
+ * to be used as a type-level tag to be used with {@link ox#Provider.(from:function)} or
+ * {@link ox#RpcTransport.(fromHttp:function)}.
+ *
+ * @example
+ * ### Using with `Provider.from`
+ *
+ * ```ts twoslash
+ * // @noErrors
+ * import 'ox/window'
+ * import { Provider, RpcSchema } from 'ox'
+ *
+ * const schema = RpcSchema.from<
+ *   | RpcSchema.Default
+ *   | {
+ *       Request: {
+ *         method: 'abe_foo',
+ *         params: [id: number],
+ *       }
+ *       ReturnType: string
+ *     }
+ *   | {
+ *       Request: {
+ *         method: 'abe_bar',
+ *         params: [id: string],
+ *       }
+ *       ReturnType: string
+ *     }
+ * >()
+ *
+ * const provider = Provider.from(window.ethereum, { schema })
+ *
+ * const blockNumber = await provider.request({ method: 'e' })
+ * //                                                    ^|
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export function from<schema extends Generic>(): schema {
+  return null as never
+}
+
+/**
+ * Extracts a schema item from a {@link ox#RpcSchema.Generic} or {@link ox#RpcSchema.MethodNameGeneric}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema } from 'ox'
+ *
+ * type Item = RpcSchema.ExtractItem<RpcSchema.Eth, 'eth_getBlockByNumber'>
+ * //   ^?
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export type ExtractItem<
+  schema extends Generic,
+  methodName extends MethodNameGeneric<schema> = MethodNameGeneric<schema>,
+> = Compute<{
+  Request: ExtractRequest<schema, methodName>
+  ReturnType: ExtractReturnType<schema, methodName>
+}>
+
+/**
+ * Extracts request from a {@link ox#RpcSchema.Generic} or {@link ox#RpcSchema.MethodNameGeneric}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema } from 'ox'
+ *
+ * type Request = RpcSchema.ExtractRequest<RpcSchema.Eth, 'eth_getBlockByNumber'>
+ * //   ^?
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export type ExtractRequest<
+  schema extends Generic,
+  methodName extends MethodNameGeneric<schema> = MethodNameGeneric<schema>,
+> = Extract<schema['Request'], { method: methodName }>
+
+/**
+ * Type-safe union of all JSON-RPC Method Names.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema } from 'ox'
+ *
+ * type MethodName = RpcSchema.ExtractMethodName<RpcSchema.Default>
+ * //   ^?
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export type ExtractMethodName<schema extends Generic> =
+  schema['Request']['method']
+
+/**
+ * Extracts parameters from a {@link ox#RpcSchema.Generic} or {@link ox#RpcSchema.MethodNameGeneric}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema } from 'ox'
+ *
+ * type Eth_GetBlockByNumber = RpcSchema.ExtractParams<RpcSchema.Eth, 'eth_getBlockByNumber'>
+ * //   ^?
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export type ExtractParams<
+  schema extends Generic,
+  methodName extends MethodNameGeneric<schema> = MethodNameGeneric<schema>,
+> = ExtractRequest<schema, methodName>['params']
+
+/**
+ * Extracts return type from a {@link ox#RpcSchema.Generic} or {@link ox#RpcSchema.MethodNameGeneric}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema } from 'ox'
+ *
+ * type ReturnType = RpcSchema.ExtractReturnType<RpcSchema.Eth, 'eth_getBlockByNumber'>
+ * //   ^?
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export type ExtractReturnType<
+  schema extends Generic,
+  methodName extends MethodNameGeneric<schema> = MethodNameGeneric<schema>,
+> = methodName extends schema['Request']['method']
+  ? IsNarrowable<schema, Generic> extends true
+    ? Extract<schema, { Request: { method: methodName } }>['ReturnType']
+    : unknown
+  : unknown
+
+/**
+ * Type to define a custom type-safe JSON-RPC Schema.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema, RpcRequest } from 'ox'
+ *
+ * type Schema = RpcSchema.From<{
+ *   Request: {
+ *     method: 'eth_foobar',
+ *     params: [id: number],
+ *   }
+ *   ReturnType: string
+ * }>
+ * ```
+ */
+export type From<schema extends Generic> = schema
+
+/**
+ * Generic type to define a JSON-RPC Method.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema } from 'ox'
+ *
+ * type Schema = RpcSchema.Generic
+ * //   ^?
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export type Generic<name extends string = string, params = unknown> = {
+  Request: {
+    method: name
+    params?: params | undefined
+  }
+  ReturnType?: unknown
+}
+
+/**
+ * Type-safe union of all JSON-RPC Methods.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema } from 'ox'
+ *
+ * type Schema = RpcSchema.Default
+ * //   ^?
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export type Default = ResolvedRegister['RpcSchema']
+
+/**
+ * Generic type to define a JSON-RPC Method Name.
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcSchema } from 'ox'
+ *
+ * type Name = RpcSchema.MethodNameGeneric
+ * //   ^?
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
+export type MethodNameGeneric<schema extends Generic = Generic> =
+  | schema['Request']['method']
+  | (string & {})

package/RpcTransport/package.json

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