# RpcResponse

Utility types & functions for working with [JSON-RPC 2.0 Responses](https://www.jsonrpc.org/specification#response_object)

## Examples

Below are some examples demonstrating common usages of the `RpcResponse` module:

* [Instantiating an RPC Response](#instantiating-an-rpc-response)

* [Parsing an RPC Response](#parsing-an-rpc-response)

### Instantiating an RPC Response

RPC Responses can be instantiated using [`RpcResponse.from`](/api/RpcResponse/from):

```ts twoslash
import { RpcResponse } from 'ox'

const response = RpcResponse.from({
  id: 0,
  jsonrpc: '2.0',
  result: '0x69420'
})
```

:::note
Type-safe instantiation from a `request` object is also supported. 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 }
)
```
:::

### Parsing an RPC Response

RPC Responses can be parsed using [`RpcResponse.parse`](/api/RpcResponse/parse):

```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]
// ^?
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`RpcResponse.from`](/api/RpcResponse/from) | 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). |
| [`RpcResponse.parse`](/api/RpcResponse/parse) | 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. |
| [`RpcResponse.parseError`](/api/RpcResponse/parseError) | Parses an error into a RPC Error instance. |

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`RpcResponse.BaseError`](/api/RpcResponse/errors#rpcresponsebaseerror) | Thrown when a JSON-RPC error has occurred. |
| [`RpcResponse.InternalError`](/api/RpcResponse/errors#rpcresponseinternalerror) | Thrown when an internal JSON-RPC error has occurred. |
| [`RpcResponse.InvalidInputError`](/api/RpcResponse/errors#rpcresponseinvalidinputerror) | Thrown when the input to a JSON-RPC method is invalid. |
| [`RpcResponse.InvalidParamsError`](/api/RpcResponse/errors#rpcresponseinvalidparamserror) | Thrown when the parameters to a JSON-RPC method are invalid. |
| [`RpcResponse.InvalidRequestError`](/api/RpcResponse/errors#rpcresponseinvalidrequesterror) | Thrown when a JSON-RPC request is invalid. |
| [`RpcResponse.LimitExceededError`](/api/RpcResponse/errors#rpcresponselimitexceedederror) | Thrown when a rate-limit is exceeded. |
| [`RpcResponse.MethodNotFoundError`](/api/RpcResponse/errors#rpcresponsemethodnotfounderror) | Thrown when a JSON-RPC method is not found. |
| [`RpcResponse.MethodNotSupportedError`](/api/RpcResponse/errors#rpcresponsemethodnotsupportederror) | Thrown when a JSON-RPC method is not supported. |
| [`RpcResponse.ParseError`](/api/RpcResponse/errors#rpcresponseparseerror) | Thrown when a JSON-RPC response is invalid. |
| [`RpcResponse.ResourceNotFoundError`](/api/RpcResponse/errors#rpcresponseresourcenotfounderror) | Thrown when a JSON-RPC resource is not found. |
| [`RpcResponse.ResourceUnavailableError`](/api/RpcResponse/errors#rpcresponseresourceunavailableerror) | Thrown when a JSON-RPC resource is unavailable. |
| [`RpcResponse.TransactionRejectedError`](/api/RpcResponse/errors#rpcresponsetransactionrejectederror) | Thrown when a JSON-RPC transaction is rejected. |
| [`RpcResponse.VersionNotSupportedError`](/api/RpcResponse/errors#rpcresponseversionnotsupportederror) | Thrown when a JSON-RPC version is not supported. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`RpcResponse.BaseErrorType`](/api/RpcResponse/types#rpcresponsebaseerrortype) |  |
| [`RpcResponse.ErrorObject`](/api/RpcResponse/types#rpcresponseerrorobject) | JSON-RPC error object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#error_object). |
| [`RpcResponse.RpcResponse`](/api/RpcResponse/types#rpcresponserpcresponse) | A JSON-RPC response object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#request_object). |