ox 0.13.1 → 0.14.0

package/core/Base32.ts

@@ -0,0 +1,134 @@
+import * as Bytes from './Bytes.js'
+import * as Errors from './Errors.js'
+import * as Hex from './Hex.js'
+
+/** Bech32 base32 alphabet (BIP-173). */
+const alphabet = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
+const alphabetMap = /*#__PURE__*/ (() => {
+  const map: Record<string, number> = {}
+  for (let i = 0; i < alphabet.length; i++) map[alphabet[i]!] = i
+  return map
+})()
+
+/**
+ * Encodes a {@link ox#Bytes.Bytes} value to a Base32-encoded string (using the BIP-173 bech32 alphabet).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Base32, Bytes } from 'ox'
+ *
+ * const value = Base32.fromBytes(new Uint8Array([0x00, 0xff, 0x00]))
+ * ```
+ *
+ * @param value - The byte array to encode.
+ * @returns The Base32 encoded string.
+ */
+export function fromBytes(value: Bytes.Bytes): string {
+  let bits = 0
+  let acc = 0
+  let result = ''
+  for (const byte of value) {
+    acc = (acc << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      bits -= 5
+      result += alphabet[(acc >>> bits) & 0x1f]
+    }
+  }
+  if (bits > 0) result += alphabet[(acc << (5 - bits)) & 0x1f]
+  return result
+}
+
+export declare namespace fromBytes {
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Encodes a {@link ox#Hex.Hex} value to a Base32-encoded string (using the BIP-173 bech32 alphabet).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Base32 } from 'ox'
+ *
+ * const value = Base32.fromHex('0x00ff00')
+ * ```
+ *
+ * @param value - The hex value to encode.
+ * @returns The Base32 encoded string.
+ */
+export function fromHex(value: Hex.Hex): string {
+  return fromBytes(Bytes.fromHex(value))
+}
+
+export declare namespace fromHex {
+  type ErrorType = fromBytes.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Decodes a Base32-encoded string (using the BIP-173 bech32 alphabet) to {@link ox#Bytes.Bytes}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Base32 } from 'ox'
+ *
+ * const value = Base32.toBytes('qqsa0')
+ * ```
+ *
+ * @param value - The Base32 encoded string.
+ * @returns The decoded byte array.
+ */
+export function toBytes(value: string): Bytes.Bytes {
+  const values: number[] = []
+  for (const char of value) {
+    const v = alphabetMap[char]
+    if (v === undefined) throw new InvalidCharacterError({ character: char })
+    values.push(v)
+  }
+
+  let bits = 0
+  let acc = 0
+  const bytes: number[] = []
+  for (const v of values) {
+    acc = (acc << 5) | v
+    bits += 5
+    if (bits >= 8) {
+      bits -= 8
+      bytes.push((acc >>> bits) & 0xff)
+    }
+  }
+  return new Uint8Array(bytes)
+}
+
+export declare namespace toBytes {
+  type ErrorType = InvalidCharacterError | Errors.GlobalErrorType
+}
+
+/**
+ * Decodes a Base32-encoded string (using the BIP-173 bech32 alphabet) to {@link ox#Hex.Hex}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Base32 } from 'ox'
+ *
+ * const value = Base32.toHex('qqsa0')
+ * ```
+ *
+ * @param value - The Base32 encoded string.
+ * @returns The decoded hex string.
+ */
+export function toHex(value: string): Hex.Hex {
+  return Hex.fromBytes(toBytes(value))
+}
+
+export declare namespace toHex {
+  type ErrorType = toBytes.ErrorType | Errors.GlobalErrorType
+}
+
+/** Thrown when a Base32 string contains an invalid character. */
+export class InvalidCharacterError extends Errors.BaseError {
+  override readonly name = 'Base32.InvalidCharacterError'
+
+  constructor({ character }: { character: string }) {
+    super(`Invalid bech32 base32 character: "${character}".`)
+  }
+}

package/core/Bech32m.ts

@@ -0,0 +1,263 @@
+import type * as Errors from './Errors.js'
+import { BaseError } from './Errors.js'
+
+/**
+ * Encodes data bytes with a human-readable part (HRP) into a bech32m string (BIP-350).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Bech32m } from 'ox'
+ *
+ * const encoded = Bech32m.encode('tempo', new Uint8Array(20))
+ * // @log: 'tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwa7xtm'
+ * ```
+ *
+ * @param hrp - The human-readable part (e.g. `"tempo"`, `"tempoz"`).
+ * @param data - The data bytes to encode.
+ * @returns The bech32m-encoded string.
+ */
+export function encode(
+  hrp: string,
+  data: Uint8Array,
+  options: encode.Options = {},
+): string {
+  const { limit = 90 } = options
+
+  hrp = hrp.toLowerCase()
+
+  if (hrp.length === 0) throw new InvalidHrpError()
+  for (let i = 0; i < hrp.length; i++) {
+    const c = hrp.charCodeAt(i)
+    if (c < 33 || c > 126) throw new InvalidHrpError()
+  }
+
+  const data5 = convertBits(data, 8, 5, true)
+
+  if (hrp.length + 1 + data5.length + 6 > limit)
+    throw new ExceedsLengthError({ limit })
+
+  const checksum = createChecksum(hrp, data5)
+  let result = hrp + '1'
+  for (const d of data5.concat(checksum)) result += alphabet[d]
+  return result
+}
+
+export declare namespace encode {
+  type Options = {
+    /** Maximum length of the encoded string. @default 90 */
+    limit?: number | undefined
+  }
+
+  type ErrorType = InvalidHrpError | ExceedsLengthError | Errors.GlobalErrorType
+}
+
+/**
+ * Decodes a bech32m string (BIP-350) into a human-readable part and data bytes.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Bech32m } from 'ox'
+ *
+ * const { hrp, data } = Bech32m.decode('tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwa7xtm')
+ * // @log: { hrp: 'tempo', data: Uint8Array(20) }
+ * ```
+ *
+ * @param str - The bech32m-encoded string to decode.
+ * @returns The decoded HRP and data bytes.
+ */
+export function decode(
+  str: string,
+  options: decode.Options = {},
+): decode.ReturnType {
+  const { limit = 90 } = options
+
+  if (str.length > limit) throw new ExceedsLengthError({ limit })
+
+  if (str !== str.toLowerCase() && str !== str.toUpperCase())
+    throw new MixedCaseError()
+
+  const lower = str.toLowerCase()
+  const pos = lower.lastIndexOf('1')
+  if (pos === -1) throw new NoSeparatorError()
+  if (pos === 0) throw new InvalidHrpError()
+  if (pos + 7 > lower.length) throw new InvalidChecksumError()
+
+  const hrp = lower.slice(0, pos)
+  for (let i = 0; i < hrp.length; i++) {
+    const c = hrp.charCodeAt(i)
+    if (c < 33 || c > 126) throw new InvalidHrpError()
+  }
+
+  const dataChars = lower.slice(pos + 1)
+
+  const data5: number[] = []
+  for (const c of dataChars) {
+    const v = alphabetMap[c]
+    if (v === undefined) throw new InvalidCharacterError({ character: c })
+    data5.push(v)
+  }
+
+  if (!verifyChecksum(hrp, data5)) throw new InvalidChecksumError()
+
+  const data8 = convertBits(data5.slice(0, -6), 5, 8, false)
+  return { hrp, data: new Uint8Array(data8) }
+}
+
+export declare namespace decode {
+  type Options = {
+    /** Maximum length of the encoded string. @default 90 */
+    limit?: number | undefined
+  }
+
+  type ReturnType = {
+    /** The human-readable part. */
+    hrp: string
+    /** The decoded data bytes. */
+    data: Uint8Array
+  }
+
+  type ErrorType =
+    | NoSeparatorError
+    | InvalidChecksumError
+    | InvalidCharacterError
+    | InvalidPaddingError
+    | MixedCaseError
+    | InvalidHrpError
+    | ExceedsLengthError
+    | Errors.GlobalErrorType
+}
+
+/** Thrown when a bech32m string has no separator. */
+export class NoSeparatorError extends BaseError {
+  override readonly name = 'Bech32m.NoSeparatorError'
+  constructor() {
+    super('Bech32m string has no separator.')
+  }
+}
+
+/** Thrown when a bech32m string has an invalid checksum. */
+export class InvalidChecksumError extends BaseError {
+  override readonly name = 'Bech32m.InvalidChecksumError'
+  constructor() {
+    super('Invalid bech32m checksum.')
+  }
+}
+
+/** Thrown when a bech32m string contains an invalid character. */
+export class InvalidCharacterError extends BaseError {
+  override readonly name = 'Bech32m.InvalidCharacterError'
+  constructor({ character }: { character: string }) {
+    super(`Invalid bech32m character: "${character}".`)
+  }
+}
+
+/** Thrown when the padding bits are invalid during base32 conversion. */
+export class InvalidPaddingError extends BaseError {
+  override readonly name = 'Bech32m.InvalidPaddingError'
+  constructor() {
+    super('Invalid padding in bech32m data.')
+  }
+}
+
+/** Thrown when a bech32m string contains mixed case. */
+export class MixedCaseError extends BaseError {
+  override readonly name = 'Bech32m.MixedCaseError'
+  constructor() {
+    super('Bech32m string must not contain mixed case.')
+  }
+}
+
+/** Thrown when the HRP is invalid (empty or contains non-ASCII characters). */
+export class InvalidHrpError extends BaseError {
+  override readonly name = 'Bech32m.InvalidHrpError'
+  constructor() {
+    super(
+      'Invalid bech32m human-readable part (HRP). Must be 1+ characters in ASCII range 33-126.',
+    )
+  }
+}
+
+/** Thrown when the encoded string exceeds the length limit. */
+export class ExceedsLengthError extends BaseError {
+  override readonly name = 'Bech32m.ExceedsLengthError'
+  constructor({ limit }: { limit: number }) {
+    super(`Bech32m string exceeds length limit of ${limit}.`)
+  }
+}
+
+/** @internal */
+const alphabet = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
+
+/** @internal */
+const alphabetMap = /*#__PURE__*/ (() => {
+  const map: Record<string, number> = {}
+  for (let i = 0; i < alphabet.length; i++) map[alphabet[i]!] = i
+  return map
+})()
+
+/** @internal */
+const BECH32M_CONST = 0x2bc830a3
+
+/** @internal */
+const GEN = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3]
+
+/** @internal */
+function polymod(values: number[]): number {
+  let chk = 1
+  for (const v of values) {
+    const b = chk >> 25
+    chk = ((chk & 0x1ffffff) << 5) ^ v
+    for (let i = 0; i < 5; i++) if ((b >> i) & 1) chk ^= GEN[i]!
+  }
+  return chk
+}
+
+/** @internal */
+function hrpExpand(hrp: string): number[] {
+  const ret: number[] = []
+  for (let i = 0; i < hrp.length; i++) ret.push(hrp.charCodeAt(i) >> 5)
+  ret.push(0)
+  for (let i = 0; i < hrp.length; i++) ret.push(hrp.charCodeAt(i) & 31)
+  return ret
+}
+
+/** @internal */
+function createChecksum(hrp: string, data: number[]): number[] {
+  const values = hrpExpand(hrp).concat(data).concat([0, 0, 0, 0, 0, 0])
+  const mod = polymod(values) ^ BECH32M_CONST
+  const ret: number[] = []
+  for (let i = 0; i < 6; i++) ret.push((mod >> (5 * (5 - i))) & 31)
+  return ret
+}
+
+/** @internal */
+function verifyChecksum(hrp: string, data: number[]): boolean {
+  return polymod(hrpExpand(hrp).concat(data)) === BECH32M_CONST
+}
+
+/** @internal */
+function convertBits(
+  data: Iterable<number>,
+  fromBits: number,
+  toBits: number,
+  pad: boolean,
+): number[] {
+  let acc = 0
+  let bits = 0
+  const maxv = (1 << toBits) - 1
+  const ret: number[] = []
+  for (const value of data) {
+    acc = (acc << fromBits) | value
+    bits += fromBits
+    while (bits >= toBits) {
+      bits -= toBits
+      ret.push((acc >> bits) & maxv)
+    }
+  }
+  if (pad) {
+    if (bits > 0) ret.push((acc << (toBits - bits)) & maxv)
+  } else if (bits >= fromBits || (acc << (toBits - bits)) & maxv) {
+    throw new InvalidPaddingError()
+  }
+  return ret
+}

package/core/CompactSize.ts

@@ -0,0 +1,169 @@
+import * as Bytes from './Bytes.js'
+import * as Errors from './Errors.js'
+import * as Hex from './Hex.js'
+
+/**
+ * Encodes an integer using Bitcoin's CompactSize variable-length encoding.
+ *
+ * | Range | Encoding | Bytes |
+ * |---|---|---|
+ * | 0–252 | Direct value | 1 |
+ * | 253–65,535 | `0xFD` + 2 bytes LE | 3 |
+ * | 65,536–4,294,967,295 | `0xFE` + 4 bytes LE | 5 |
+ * | \> 4,294,967,295 | `0xFF` + 8 bytes LE | 9 |
+ *
+ * @example
+ * ```ts twoslash
+ * import { CompactSize } from 'ox'
+ *
+ * const bytes = CompactSize.toBytes(252)
+ * // Uint8Array [252]
+ *
+ * const bytes2 = CompactSize.toBytes(253)
+ * // Uint8Array [253, 253, 0]
+ * ```
+ *
+ * @param value - The integer to encode.
+ * @returns The CompactSize-encoded bytes.
+ */
+export function toBytes(value: bigint | number): Bytes.Bytes {
+  const n = BigInt(value)
+  if (n < 0n) throw new NegativeValueError({ value: n })
+  if (n <= 252n) return new Uint8Array([Number(n)])
+  if (n <= 0xffffn) {
+    const buf = new Uint8Array(3)
+    buf[0] = 0xfd
+    const view = new DataView(buf.buffer)
+    view.setUint16(1, Number(n), true)
+    return buf
+  }
+  if (n <= 0xffffffffn) {
+    const buf = new Uint8Array(5)
+    buf[0] = 0xfe
+    const view = new DataView(buf.buffer)
+    view.setUint32(1, Number(n), true)
+    return buf
+  }
+  const buf = new Uint8Array(9)
+  buf[0] = 0xff
+  const view = new DataView(buf.buffer)
+  view.setBigUint64(1, n, true)
+  return buf
+}
+
+export declare namespace toBytes {
+  type ErrorType = NegativeValueError | Errors.GlobalErrorType
+}
+
+/**
+ * Encodes an integer using Bitcoin's CompactSize variable-length encoding and returns it as {@link ox#Hex.Hex}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { CompactSize } from 'ox'
+ *
+ * const hex = CompactSize.toHex(252)
+ * // '0xfc'
+ * ```
+ *
+ * @param value - The integer to encode.
+ * @returns The CompactSize-encoded hex string.
+ */
+export function toHex(value: bigint | number): Hex.Hex {
+  return Hex.fromBytes(toBytes(value))
+}
+
+export declare namespace toHex {
+  type ErrorType = toBytes.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Decodes a CompactSize-encoded value from {@link ox#Bytes.Bytes}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { CompactSize } from 'ox'
+ *
+ * const result = CompactSize.fromBytes(new Uint8Array([0xfd, 0x00, 0x01]))
+ * // { value: 256, size: 3 }
+ * ```
+ *
+ * @param data - The bytes to decode from.
+ * @returns The decoded value and number of bytes consumed.
+ */
+export function fromBytes(data: Bytes.Bytes): fromBytes.ReturnType {
+  if (data.length === 0)
+    throw new InsufficientBytesError({ expected: 1, actual: 0 })
+  const first = data[0]!
+  if (first < 0xfd) return { value: BigInt(first), size: 1 }
+  const view = new DataView(data.buffer, data.byteOffset)
+  if (first === 0xfd) {
+    if (data.length < 3)
+      throw new InsufficientBytesError({ expected: 3, actual: data.length })
+    return { value: BigInt(view.getUint16(1, true)), size: 3 }
+  }
+  if (first === 0xfe) {
+    if (data.length < 5)
+      throw new InsufficientBytesError({ expected: 5, actual: data.length })
+    return { value: BigInt(view.getUint32(1, true)), size: 5 }
+  }
+  if (data.length < 9)
+    throw new InsufficientBytesError({ expected: 9, actual: data.length })
+  return {
+    value: view.getBigUint64(1, true),
+    size: 9,
+  }
+}
+
+export declare namespace fromBytes {
+  type ReturnType = {
+    /** The decoded integer value. */
+    value: bigint
+    /** The number of bytes consumed. */
+    size: number
+  }
+
+  type ErrorType = InsufficientBytesError | Errors.GlobalErrorType
+}
+
+/**
+ * Decodes a CompactSize-encoded value from {@link ox#Hex.Hex}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { CompactSize } from 'ox'
+ *
+ * const result = CompactSize.fromHex('0xfd0001')
+ * // { value: 256, size: 3 }
+ * ```
+ *
+ * @param data - The hex string to decode from.
+ * @returns The decoded value and number of bytes consumed.
+ */
+export function fromHex(data: Hex.Hex): fromBytes.ReturnType {
+  return fromBytes(Bytes.fromHex(data))
+}
+
+export declare namespace fromHex {
+  type ErrorType = fromBytes.ErrorType | Errors.GlobalErrorType
+}
+
+/** Thrown when a CompactSize value is negative. */
+export class NegativeValueError extends Errors.BaseError {
+  override readonly name = 'CompactSize.NegativeValueError'
+
+  constructor({ value }: { value: bigint }) {
+    super(`CompactSize value must be non-negative, got ${value}.`)
+  }
+}
+
+/** Thrown when there are insufficient bytes to decode a CompactSize value. */
+export class InsufficientBytesError extends Errors.BaseError {
+  override readonly name = 'CompactSize.InsufficientBytesError'
+
+  constructor({ expected, actual }: { expected: number; actual: number }) {
+    super(
+      `Insufficient bytes for CompactSize decoding. Expected at least ${expected}, got ${actual}.`,
+    )
+  }
+}

package/index.ts

@@ -838,6 +838,30 @@ export * as AesGcm from './core/AesGcm.js'
  */
 export * as Authorization from './core/Authorization.js'
 
+/**
+ * Utility functions for working with Base32 values using the [BIP-173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki) bech32 alphabet.
+ *
+ * @example
+ * ### Encoding to Base32
+ *
+ * ```ts twoslash
+ * import { Base32 } from 'ox'
+ *
+ * const value = Base32.fromHex('0x00ff00')
+ * ```
+ *
+ * @example
+ * ### Decoding Base32
+ *
+ * ```ts twoslash
+ * import { Base32 } from 'ox'
+ *
+ * const value = Base32.toBytes('qrlsq')
+ * ```
+ *
+ * @category Data
+ */
+export * as Base32 from './core/Base32.js'
 /**
  * Utility functions for working with [Base58](https://digitalbazaar.github.io/base58-spec/) values.
  *
@@ -892,7 +916,6 @@ export * as Authorization from './core/Authorization.js'
  * @category Data
  */
 export * as Base58 from './core/Base58.js'
-
 /**
  * Utility functions for working with [RFC-4648](https://datatracker.ietf.org/doc/html/rfc4648) Base64.
  *
@@ -946,6 +969,30 @@ export * as Base58 from './core/Base58.js'
  * @category Data
  */
 export * as Base64 from './core/Base64.js'
+/**
+ * Utility functions for [BIP-350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) bech32m encoding and decoding.
+ *
+ * @example
+ * ### Encoding
+ *
+ * ```ts twoslash
+ * import { Bech32m } from 'ox'
+ *
+ * const encoded = Bech32m.encode('tempo', new Uint8Array(20))
+ * ```
+ *
+ * @example
+ * ### Decoding
+ *
+ * ```ts twoslash
+ * import { Bech32m } from 'ox'
+ *
+ * const { hrp, data } = Bech32m.decode('tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq7w9gdx')
+ * ```
+ *
+ * @category Data
+ */
+export * as Bech32m from './core/Bech32m.js'
 
 /**
  * Utility functions for working with [EIP-7864](https://eips.ethereum.org/EIPS/eip-7864) Binary State Trees.
@@ -1330,6 +1377,32 @@ export * as Caches from './core/Caches.js'
  * @category Data
  */
 export * as Cbor from './core/Cbor.js'
+
+/**
+ * Utility functions for [Bitcoin's CompactSize](https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer) variable-length integer encoding.
+ *
+ * @example
+ * ### Encoding
+ *
+ * ```ts twoslash
+ * import { CompactSize } from 'ox'
+ *
+ * const bytes = CompactSize.toBytes(65535)
+ * ```
+ *
+ * @example
+ * ### Decoding
+ *
+ * ```ts twoslash
+ * import { CompactSize } from 'ox'
+ *
+ * const { value, size } = CompactSize.fromBytes(new Uint8Array([0xfd, 0xff, 0xff]))
+ * ```
+ *
+ * @category Data
+ */
+export * as CompactSize from './core/CompactSize.js'
+
 /**
  * Utility functions for computing Contract Addresses.
  *