viem 0.4.0-main.20230418T011420 → 0.4.0-main.20230419T210450

package/src/errors/encoding.ts

@@ -81,3 +81,12 @@ export class OffsetOutOfBoundsError extends BaseError {
     )
   }
 }
+
+export class SizeOverflowError extends BaseError {
+  override name = 'SizeOverflowError'
+  constructor({ givenSize, maxSize }: { givenSize: number; maxSize: number }) {
+    super(
+      `Size cannot exceed ${maxSize} bytes. Given size: ${givenSize} bytes.`,
+    )
+  }
+}

package/src/errors/index.ts

@@ -37,6 +37,7 @@ export {
   ChainDoesNotSupportContract,
   ChainMismatchError,
   ChainNotFoundError,
+  ClientChainNotConfiguredError,
   InvalidChainIdError,
 } from './chain.js'
 
@@ -58,6 +59,7 @@ export {
   InvalidHexBooleanError,
   InvalidHexValueError,
   OffsetOutOfBoundsError,
+  SizeOverflowError,
 } from './encoding.js'
 
 export {

package/src/errors/version.ts

@@ -1 +1 @@
-export const version = '0.4.0-main.20230418T011420'
+export const version = '0.4.0-main.20230419T210450'

package/src/index.ts

@@ -182,6 +182,7 @@ export {
   CallExecutionError,
   ChainDisconnectedError,
   ChainDoesNotSupportContract,
+  ClientChainNotConfiguredError,
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
   ContractFunctionZeroDataError,

package/src/types/eip1193.ts

@@ -207,7 +207,7 @@ export type PublicRequests = {
      */
     method: 'eth_call'
     params: [
-      request: TransactionRequest,
+      request: Partial<TransactionRequest>,
       block: BlockNumber | BlockTag | BlockIdentifier,
     ]
   }): Promise<Hex>

package/src/utils/encoding/fromBytes.ts

@@ -1,8 +1,20 @@
 import { InvalidBytesBooleanError } from '../../errors/index.js'
 import type { ByteArray, Hex } from '../../types/index.js'
-import { hexToBigInt, hexToNumber } from './fromHex.js'
+import { trim } from '../data/trim.js'
+import { assertSize, hexToBigInt, hexToNumber } from './fromHex.js'
 import { bytesToHex } from './toHex.js'
 
+export type FromBytesParameters<
+  TTo extends 'string' | 'hex' | 'bigint' | 'number' | 'boolean',
+> =
+  | TTo
+  | {
+      /** Size of the bytes. */
+      size?: number
+      /** Type to convert to. */
+      to: TTo
+    }
+
 type FromBytesReturnType<TTo> = TTo extends 'string'
   ? string
   : TTo extends 'hex'
@@ -16,30 +28,106 @@ type FromBytesReturnType<TTo> = TTo extends 'string'
   : never
 
 /**
- * @description Decodes a byte array into a UTF-8 string, hex value, number, bigint or boolean.
+ * Decodes a byte array into a UTF-8 string, hex value, number, bigint or boolean.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromBytes.html
+ * - Example: https://viem.sh/docs/utilities/fromBytes.html#usage
+ *
+ * @param bytes Byte array to decode.
+ * @param toOrOpts Type to convert to or options.
+ * @returns Decoded value.
+ *
+ * @example
+ * import { fromBytes } from 'viem'
+ * const data = fromBytes(new Uint8Array([1, 164]), 'number')
+ * // 420
+ *
+ * @example
+ * import { fromBytes } from 'viem'
+ * const data = fromBytes(
+ *   new Uint8Array([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33]),
+ *   'string'
+ * )
+ * // 'Hello world'
  */
 export function fromBytes<
   TTo extends 'string' | 'hex' | 'bigint' | 'number' | 'boolean',
->(bytes: ByteArray, to: TTo): FromBytesReturnType<TTo> {
-  if (to === 'number') return bytesToNumber(bytes) as FromBytesReturnType<TTo>
-  if (to === 'bigint') return bytesToBigint(bytes) as FromBytesReturnType<TTo>
-  if (to === 'boolean') return bytesToBool(bytes) as FromBytesReturnType<TTo>
-  if (to === 'string') return bytesToString(bytes) as FromBytesReturnType<TTo>
-  return bytesToHex(bytes) as FromBytesReturnType<TTo>
+>(
+  bytes: ByteArray,
+  toOrOpts: FromBytesParameters<TTo>,
+): FromBytesReturnType<TTo> {
+  const opts = typeof toOrOpts === 'string' ? { to: toOrOpts } : toOrOpts
+  const to = opts.to
+
+  if (to === 'number')
+    return bytesToNumber(bytes, opts) as FromBytesReturnType<TTo>
+  if (to === 'bigint')
+    return bytesToBigint(bytes, opts) as FromBytesReturnType<TTo>
+  if (to === 'boolean')
+    return bytesToBool(bytes, opts) as FromBytesReturnType<TTo>
+  if (to === 'string')
+    return bytesToString(bytes, opts) as FromBytesReturnType<TTo>
+  return bytesToHex(bytes, opts) as FromBytesReturnType<TTo>
+}
+
+export type BytesToBigIntOpts = {
+  /** Whether or not the number of a signed representation. */
+  signed?: boolean
+  /** Size of the bytes. */
+  size?: number
 }
 
 /**
- * @description Decodes a byte array into a bigint.
+ * Decodes a byte array into a bigint.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromBytes.html#bytestobigint
+ *
+ * @param bytes Byte array to decode.
+ * @param opts Options.
+ * @returns BigInt value.
+ *
+ * @example
+ * import { bytesToBigint } from 'viem'
+ * const data = bytesToBigint(new Uint8Array([1, 164]))
+ * // 420n
  */
-export function bytesToBigint(bytes: ByteArray): bigint {
-  const hex = bytesToHex(bytes)
+export function bytesToBigint(
+  bytes: ByteArray,
+  opts: BytesToBigIntOpts = {},
+): bigint {
+  if (typeof opts.size !== 'undefined') assertSize(bytes, { size: opts.size })
+  const hex = bytesToHex(bytes, opts)
   return hexToBigInt(hex)
 }
 
+export type BytesToBoolOpts = {
+  /** Size of the bytes. */
+  size?: number
+}
+
 /**
- * @description Decodes a byte array into a boolean.
+ * Decodes a byte array into a boolean.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromBytes.html#bytestobool
+ *
+ * @param bytes Byte array to decode.
+ * @param opts Options.
+ * @returns Boolean value.
+ *
+ * @example
+ * import { bytesToBool } from 'viem'
+ * const data = bytesToBool(new Uint8Array([1]))
+ * // true
  */
-export function bytesToBool(bytes: ByteArray): boolean {
+export function bytesToBool(
+  bytes_: ByteArray,
+  opts: BytesToBoolOpts = {},
+): boolean {
+  let bytes = bytes_
+  if (typeof opts.size !== 'undefined') {
+    assertSize(bytes, { size: opts.size })
+    bytes = trim(bytes)
+  }
   if (bytes.length > 1 || bytes[0] > 1)
     throw new InvalidBytesBooleanError(bytes)
   return Boolean(bytes[0])
@@ -47,17 +135,58 @@ export function bytesToBool(bytes: ByteArray): boolean {
 
 export { bytesToHex }
 
+export type BytesToNumberOpts = BytesToBigIntOpts
+
 /**
- * @description Decodes a byte array into a number.
+ * Decodes a byte array into a number.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromBytes.html#bytestonumber
+ *
+ * @param bytes Byte array to decode.
+ * @param opts Options.
+ * @returns Number value.
+ *
+ * @example
+ * import { bytesToNumber } from 'viem'
+ * const data = bytesToNumber(new Uint8Array([1, 164]))
+ * // 420
  */
-export function bytesToNumber(bytes: ByteArray): number {
-  const hex = bytesToHex(bytes)
+export function bytesToNumber(
+  bytes: ByteArray,
+  opts: BytesToNumberOpts = {},
+): number {
+  if (typeof opts.size !== 'undefined') assertSize(bytes, { size: opts.size })
+  const hex = bytesToHex(bytes, opts)
   return hexToNumber(hex)
 }
 
+export type BytesToStringOpts = {
+  /** Size of the bytes. */
+  size?: number
+}
+
 /**
- * @description Decodes a byte array into a UTF-8 string.
+ * Decodes a byte array into a UTF-8 string.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromBytes.html#bytestostring
+ *
+ * @param bytes Byte array to decode.
+ * @param opts Options.
+ * @returns String value.
+ *
+ * @example
+ * import { bytesToString } from 'viem'
+ * const data = bytesToString(new Uint8Array([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33]))
+ * // 'Hello world'
  */
-export function bytesToString(bytes: ByteArray): string {
+export function bytesToString(
+  bytes_: ByteArray,
+  opts: BytesToStringOpts = {},
+): string {
+  let bytes = bytes_
+  if (typeof opts.size !== 'undefined') {
+    assertSize(bytes, { size: opts.size })
+    bytes = trim(bytes, { dir: 'right' })
+  }
   return new TextDecoder().decode(bytes)
 }

package/src/utils/encoding/fromHex.ts

@@ -1,9 +1,35 @@
-import { InvalidHexBooleanError } from '../../errors/index.js'
+import {
+  InvalidHexBooleanError,
+  SizeOverflowError,
+} from '../../errors/index.js'
 import type { ByteArray, Hex } from '../../types/index.js'
+import { size as size_ } from '../data/size.js'
 import { trim } from '../data/index.js'
 import { hexToBytes } from './toBytes.js'
 
-type FromHexReturnType<TTo> = TTo extends 'string'
+export function assertSize(
+  hexOrBytes: Hex | ByteArray,
+  { size }: { size: number },
+): void {
+  if (size_(hexOrBytes) > size)
+    throw new SizeOverflowError({
+      givenSize: size_(hexOrBytes),
+      maxSize: size,
+    })
+}
+
+export type FromHexParameters<
+  TTo extends 'string' | 'bigint' | 'number' | 'bytes' | 'boolean',
+> =
+  | TTo
+  | {
+      /** Size (in bytes) of the hex value. */
+      size?: number
+      /** Type to convert to. */
+      to: TTo
+    }
+
+export type FromHexReturnType<TTo> = TTo extends 'string'
   ? string
   : TTo extends 'bigint'
   ? bigint
@@ -16,29 +42,77 @@ type FromHexReturnType<TTo> = TTo extends 'string'
   : never
 
 /**
- * @description Decodes a hex string into a string, number, bigint, boolean, or bytes32 array.
+ * Decodes a hex string into a string, number, bigint, boolean, or byte array.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromHex.html
+ * - Example: https://viem.sh/docs/utilities/fromHex.html#usage
+ *
+ * @param hex Hex string to decode.
+ * @param toOrOpts Type to convert to or options.
+ * @returns Decoded value.
+ *
+ * @example
+ * import { fromHex } from 'viem'
+ * const data = fromHex('0x1a4', 'number')
+ * // 420
+ *
+ * @example
+ * import { fromHex } from 'viem'
+ * const data = fromHex('0x48656c6c6f20576f726c6421', 'string')
+ * // 'Hello world'
+ *
+ * @example
+ * import { fromHex } from 'viem'
+ * const data = fromHex('0x48656c6c6f20576f726c64210000000000000000000000000000000000000000', {
+ *   size: 32,
+ *   to: 'string'
+ * })
+ * // 'Hello world'
  */
 export function fromHex<
   TTo extends 'string' | 'bigint' | 'number' | 'bytes' | 'boolean',
->(hex: Hex, to: TTo): FromHexReturnType<TTo> {
-  if (to === 'number') return hexToNumber(hex) as FromHexReturnType<TTo>
-  if (to === 'bigint') return hexToBigInt(hex) as FromHexReturnType<TTo>
-  if (to === 'string') return hexToString(hex) as FromHexReturnType<TTo>
-  if (to === 'boolean') return hexToBool(hex) as FromHexReturnType<TTo>
-  return hexToBytes(hex) as FromHexReturnType<TTo>
+>(hex: Hex, toOrOpts: FromHexParameters<TTo>): FromHexReturnType<TTo> {
+  const opts = typeof toOrOpts === 'string' ? { to: toOrOpts } : toOrOpts
+  const to = opts.to
+
+  if (to === 'number') return hexToNumber(hex, opts) as FromHexReturnType<TTo>
+  if (to === 'bigint') return hexToBigInt(hex, opts) as FromHexReturnType<TTo>
+  if (to === 'string') return hexToString(hex, opts) as FromHexReturnType<TTo>
+  if (to === 'boolean') return hexToBool(hex, opts) as FromHexReturnType<TTo>
+  return hexToBytes(hex, opts) as FromHexReturnType<TTo>
 }
 
 export type HexToBigIntOpts = {
-  // Whether or not the number of a signed representation.
+  /** Whether or not the number of a signed representation. */
   signed?: boolean
+  /** Size (in bytes) of the hex value. */
+  size?: number
 }
 
 /**
- * @description Decodes a hex string into a bigint.
+ * Decodes a hex value into a bigint.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromHex.html#hextobigint
+ *
+ * @param hex Hex value to decode.
+ * @param opts Options.
+ * @returns BigInt value.
+ *
+ * @example
+ * import { hexToBigInt } from 'viem'
+ * const data = hexToBigInt('0x1a4', { signed: true })
+ * // 420n
+ *
+ * @example
+ * import { hexToBigInt } from 'viem'
+ * const data = hexToBigInt('0x00000000000000000000000000000000000000000000000000000000000001a4', { size: 32 })
+ * // 420n
  */
 export function hexToBigInt(hex: Hex, opts: HexToBigIntOpts = {}): bigint {
   const { signed } = opts
 
+  if (opts.size) assertSize(hex, { size: opts.size })
+
   const value = BigInt(hex)
   if (!signed) return value
 
@@ -49,28 +123,97 @@ export function hexToBigInt(hex: Hex, opts: HexToBigIntOpts = {}): bigint {
   return value - BigInt(`0x${'f'.padStart(size * 2, 'f')}`) - 1n
 }
 
+export type HexToBoolOpts = {
+  /** Size (in bytes) of the hex value. */
+  size?: number
+}
+
 /**
- * @description Decodes a hex string into a boolean.
+ * Decodes a hex value into a boolean.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromHex.html#hextobool
+ *
+ * @param hex Hex value to decode.
+ * @param opts Options.
+ * @returns Boolean value.
+ *
+ * @example
+ * import { hexToBool } from 'viem'
+ * const data = hexToBool('0x1')
+ * // true
+ *
+ * @example
+ * import { hexToBool } from 'viem'
+ * const data = hexToBool('0x0000000000000000000000000000000000000000000000000000000000000001', { size: 32 })
+ * // true
  */
-export function hexToBool(hex: Hex): boolean {
+export function hexToBool(hex_: Hex, opts: HexToBoolOpts = {}): boolean {
+  let hex = hex_
+  if (opts.size) {
+    assertSize(hex, { size: opts.size })
+    hex = trim(hex)
+  }
   if (trim(hex) === '0x0') return false
   if (trim(hex) === '0x1') return true
   throw new InvalidHexBooleanError(hex)
 }
 
-type NumberToHexOpts = HexToBigIntOpts
+export type HexToNumberOpts = HexToBigIntOpts
 
 /**
- * @description Decodes a hex string into a number.
+ * Decodes a hex string into a number.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromHex.html#hextonumber
+ *
+ * @param hex Hex value to decode.
+ * @param opts Options.
+ * @returns Number value.
+ *
+ * @example
+ * import { hexToNumber } from 'viem'
+ * const data = hexToNumber('0x1a4')
+ * // 420
+ *
+ * @example
+ * import { hexToNumber } from 'viem'
+ * const data = hexToBigInt('0x00000000000000000000000000000000000000000000000000000000000001a4', { size: 32 })
+ * // 420
  */
-export function hexToNumber(hex: Hex, opts: NumberToHexOpts = {}): number {
+export function hexToNumber(hex: Hex, opts: HexToNumberOpts = {}): number {
   return Number(hexToBigInt(hex, opts))
 }
 
+export type HexToStringOpts = {
+  /** Size (in bytes) of the hex value. */
+  size?: number
+}
+
 /**
- * @description Decodes a hex string into a UTF-8 string.
+ * Decodes a hex value into a UTF-8 string.
+ *
+ * - Docs: https://viem.sh/docs/utilities/fromHex.html#hextostring
+ *
+ * @param hex Hex value to decode.
+ * @param opts Options.
+ * @returns String value.
+ *
+ * @example
+ * import { hexToString } from 'viem'
+ * const data = hexToString('0x48656c6c6f20576f726c6421')
+ * // 'Hello world!'
+ *
+ * @example
+ * import { hexToString } from 'viem'
+ * const data = hexToString('0x48656c6c6f20576f726c64210000000000000000000000000000000000000000', {
+ *  size: 32,
+ * })
+ * // 'Hello world'
  */
-export function hexToString(hex: Hex): string {
-  const bytes = hexToBytes(hex)
+export function hexToString(hex: Hex, opts: HexToStringOpts = {}): string {
+  let bytes = hexToBytes(hex)
+  if (opts.size) {
+    assertSize(bytes, { size: opts.size })
+    bytes = trim(bytes, { dir: 'right' })
+  }
   return new TextDecoder().decode(bytes)
 }