ox 0.1.0 → 0.1.2

package/core/RpcRequest.ts

@@ -0,0 +1,192 @@
+import type { Errors } from '../index.js'
+import type * as RpcSchema from './RpcSchema.js'
+import type * as RpcSchema_internal from './internal/rpcSchema.js'
+import type { Compute } from './internal/types.js'
+
+/** A JSON-RPC request object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#request_object). */
+export type RpcRequest<schema extends RpcSchema.Generic = RpcSchema.Generic> =
+  Compute<
+    schema extends any
+      ? schema['Request'] & {
+          id: number
+          jsonrpc: '2.0'
+          /** @deprecated internal */
+          _returnType: schema['ReturnType']
+        }
+      : never
+  >
+
+/** JSON-RPC request store type. */
+export type Store<schema extends RpcSchema.Generic = RpcSchema.Default> =
+  Compute<{
+    prepare: <methodName extends RpcSchema.MethodNameGeneric>(
+      parameters: Compute<
+        RpcSchema_internal.ExtractRequestOpaque<schema, methodName>
+      >,
+    ) => Compute<RpcRequest<RpcSchema.ExtractItem<schema, methodName>>>
+    readonly id: number
+  }>
+
+/**
+ * Creates a JSON-RPC request store to build requests with an incrementing `id`.
+ *
+ * Returns a type-safe `prepare` function to build a JSON-RPC request object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#request_object).
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcRequest } from 'ox'
+ *
+ * const store = RpcRequest.createStore()
+ *
+ * const request_1 = store.prepare({
+ *   method: 'eth_blockNumber',
+ * })
+ * // @log: { id: 0, jsonrpc: '2.0', method: 'eth_blockNumber' }
+ *
+ * const request_2 = store.prepare({
+ *   method: 'eth_call',
+ *   params: [
+ *     {
+ *       to: '0x0000000000000000000000000000000000000000',
+ *       data: '0xdeadbeef',
+ *     },
+ *   ],
+ * })
+ * // @log: { id: 1, jsonrpc: '2.0', method: 'eth_call', params: [{ to: '0x0000000000000000000000000000000000000000', data: '0xdeadbeef' }] }
+ * ```
+ *
+ * @example
+ * ### Type-safe Custom Schemas
+ *
+ * It is possible to define your own type-safe schema by using the {@link ox#RpcSchema.From} type.
+ *
+ * ```ts twoslash
+ * import { RpcSchema, RpcRequest } from 'ox'
+ *
+ * type Schema = RpcSchema.From<{ // [!code focus]
+ *   Request: { // [!code focus]
+ *     method: 'eth_foobar' // [!code focus]
+ *     params: [number] // [!code focus]
+ *   } // [!code focus]
+ *   ReturnType: string // [!code focus]
+ * } | { // [!code focus]
+ *   Request: { // [!code focus]
+ *     method: 'eth_foobaz' // [!code focus]
+ *     params: [string] // [!code focus]
+ *   } // [!code focus]
+ *   ReturnType: string // [!code focus]
+ * }> // [!code focus]
+ *
+ * const store = RpcRequest.createStore<Schema>() // [!code focus]
+ *
+ * const request = store.prepare({
+ *   method: 'eth_foobar', // [!code focus]
+ *   // ^?
+ *   params: [42],
+ * })
+ * ```
+ *
+ * @param options - Request store options.
+ * @returns The request store
+ */
+export function createStore<
+  schema extends RpcSchema.Generic = RpcSchema.Default,
+>(options: createStore.Options = {}): createStore.ReturnType<schema> {
+  let id = options.id ?? 0
+  return {
+    prepare(options) {
+      return from({
+        id: id++,
+        ...options,
+      } as never) as never
+    },
+    get id() {
+      return id
+    },
+  }
+}
+
+export declare namespace createStore {
+  type Options = {
+    /** The initial request ID. */
+    id?: number
+  }
+
+  type ReturnType<schema extends RpcSchema.Generic = RpcSchema.Default> =
+    Store<schema>
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+createStore.parseError = (error: unknown) =>
+  /* v8 ignore next */
+  error as createStore.ErrorType
+
+/**
+ * A type-safe interface to build a JSON-RPC request object as per the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#request_object).
+ *
+ * :::warning
+ *
+ * You will likely want to use {@link ox#RpcRequest.(createStore:function)} instead as it will also manage `id`s and uses this function internally.
+ *
+ * :::
+ *
+ * @example
+ * ```ts twoslash
+ * import { RpcRequest, RpcResponse } from 'ox'
+ *
+ * // 1. Build a request object.
+ * const request = RpcRequest.from({ // [!code focus]
+ *   id: 0, // [!code focus]
+ *   method: 'eth_estimateGas', // [!code focus]
+ *   params: [ // [!code focus]
+ *     { // [!code focus]
+ *       from: '0xd2135CfB216b74109775236E36d4b433F1DF507B', // [!code focus]
+ *       to: '0x0D44f617435088c947F00B31160f64b074e412B4', // [!code focus]
+ *       value: '0x69420', // [!code focus]
+ *     }, // [!code focus]
+ *   ], // [!code focus]
+ * }) // [!code focus]
+ *
+ * // 2. Send the JSON-RPC request via HTTP.
+ * const gas = await fetch('https://1.rpc.thirdweb.com', {
+ *   body: JSON.stringify(request),
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *   },
+ *   method: 'POST',
+ * })
+ *  .then((response) => response.json())
+ *  // 3. Parse the JSON-RPC response into a type-safe result.
+ *  .then((response) => RpcResponse.parse(response, { request }))
+ * ```
+ *
+ * @param options - JSON-RPC request options.
+ * @returns The fully-formed JSON-RPC request object.
+ */
+export function from<methodName extends RpcSchema.MethodNameGeneric>(
+  options: from.Options<methodName>,
+): from.ReturnType<methodName> {
+  return {
+    ...options,
+    jsonrpc: '2.0',
+  } as never
+}
+
+export declare namespace from {
+  type Options<methodName extends RpcSchema.MethodNameGeneric> = Compute<
+    RpcSchema_internal.ExtractRequestOpaque<RpcSchema.Default, methodName> & {
+      id: number
+    }
+  >
+
+  type ReturnType<methodName extends RpcSchema.MethodNameGeneric> = Compute<
+    RpcRequest<RpcSchema.ExtractItem<RpcSchema.Default, methodName>>
+  >
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+from.parseError = (error: unknown) =>
+  /* v8 ignore next */
+  error as from.ErrorType

package/core/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/core/internal/ens.ts

@@ -0,0 +1,64 @@
+import { Bytes } from '../../index.js'
+import * as Ens from '../Ens.js'
+import type * as Errors from '../Errors.js'
+import * as Hex from '../Hex.js'
+
+/**
+ * @internal
+ * Encodes a [DNS packet](https://docs.ens.domains/resolution/names#dns) into a ByteArray containing a UDP payload.
+ */
+export function packetToBytes(packet: string): Bytes.Bytes {
+  // strip leading and trailing `.`
+  const value = packet.replace(/^\.|\.$/gm, '')
+  if (value.length === 0) return new Uint8Array(1)
+
+  const bytes = new Uint8Array(Bytes.fromString(value).byteLength + 2)
+
+  let offset = 0
+  const list = value.split('.')
+  for (let i = 0; i < list.length; i++) {
+    let encoded = Bytes.fromString(list[i]!)
+    // if the length is > 255, make the encoded label value a labelhash
+    // this is compatible with the universal resolver
+    if (encoded.byteLength > 255)
+      encoded = Bytes.fromString(wrapLabelhash(Ens.labelhash(list[i]!)))
+    bytes[offset] = encoded.length
+    bytes.set(encoded, offset + 1)
+    offset += encoded.length + 1
+  }
+
+  if (bytes.byteLength !== offset + 1) return bytes.slice(0, offset + 1)
+
+  return bytes
+}
+
+export declare namespace packetToBytes {
+  type ErrorType =
+    | wrapLabelhash.ErrorType
+    | Ens.labelhash.ErrorType
+    | Bytes.fromString.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/** @internal */
+export function wrapLabelhash(hash: Hex.Hex): `[${string}]` {
+  return `[${hash.slice(2)}]`
+}
+
+export declare namespace wrapLabelhash {
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/** @internal */
+export function unwrapLabelhash(label: string): Hex.Hex | null {
+  if (label.length !== 66) return null
+  if (label.indexOf('[') !== 0) return null
+  if (label.indexOf(']') !== 65) return null
+  const hash = `0x${label.slice(1, 65)}`
+  if (!Hex.validate(hash, { strict: true })) return null
+  return hash
+}
+
+export declare namespace unwrapLabelhash {
+  type ErrorType = Hex.validate.ErrorType | Errors.GlobalErrorType
+}

package/core/internal/rpcSchema.ts

@@ -0,0 +1,20 @@
+import type { Generic, MethodNameGeneric } from '../RpcSchema.js'
+import type { Compute, IsNarrowable } from './types.js'
+
+/** @internal */
+export type ExtractRequestOpaque<
+  schema extends Generic,
+  methodName extends MethodNameGeneric<schema> = MethodNameGeneric<schema>,
+> = Compute<
+  Omit<
+    {
+      method: methodName | schema['Request']['method']
+      params?: unknown
+    } & (methodName extends schema['Request']['method']
+      ? IsNarrowable<schema, Generic> extends true
+        ? Extract<schema, { Request: { method: methodName } }>['Request']
+        : {}
+      : {}),
+    ''
+  >
+>

package/core/version.ts

@@ -0,0 +1,2 @@
+/** @internal */
+export const version = '0.1.1'