@exodus/bytes 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Exodus Movement
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# bytes
+
+Data structures handling

package/array.js

@@ -0,0 +1,17 @@
+import { assertTypedArray } from './assert.js'
+
+const { Buffer } = globalThis // Buffer is optional
+
+export function fromTypedArray(arr, format) {
+  assertTypedArray(arr)
+  switch (format) {
+    case 'uint8':
+      if (arr.constructor === Uint8Array) return arr // fast path
+      return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength)
+    case 'buffer':
+      if (arr.constructor === Buffer && Buffer.isBuffer(arr)) return arr
+      return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength)
+  }
+
+  throw new TypeError('Unexpected format')
+}

package/assert.js

@@ -0,0 +1,22 @@
+export function assert(x, msg) {
+  if (!x) throw new Error(msg || 'Assertion failed')
+}
+
+export function assertEmptyRest(rest) {
+  if (Object.keys(rest).length > 0) throw new TypeError('Unexpected extra options')
+}
+
+// eslint-disable-next-line sonarjs/no-nested-template-literals
+const makeMessage = (name, extra) => `Expected${name ? ` ${name} to be` : ''} an Uint8Array${extra}`
+
+const TypedArray = Object.getPrototypeOf(Uint8Array)
+
+export function assertTypedArray(arr) {
+  assert(arr instanceof TypedArray, 'Expected a TypedArray instance')
+}
+
+export function assertUint8(arr, { name, length, ...rest } = {}) {
+  assertEmptyRest(rest)
+  if (arr instanceof Uint8Array && (length === undefined || arr.length === length)) return
+  throw new TypeError(makeMessage(name, length === undefined ? '' : ` of size ${Number(length)}`))
+}

package/base64.js

@@ -0,0 +1,204 @@
+import { assert, assertUint8 } from './assert.js'
+import { fromTypedArray } from './array.js'
+
+// See https://datatracker.ietf.org/doc/html/rfc4648
+
+// base64:    A-Za-z0-9+/ and =
+// base64url: A-Za-z0-9_-
+
+const { Buffer, atob } = globalThis // Buffer is optional, only used when native
+const haveNativeBuffer = Buffer && !Buffer.TYPED_ARRAY_SUPPORT
+const { toBase64: web64 } = Uint8Array.prototype // Modern engines have this
+
+export function toBase64(x) {
+  assertUint8(x)
+  if (web64 && x.toBase64 === web64) return x.toBase64() // Modern
+  if (!haveNativeBuffer) return toBase64js(x, BASE64, true) // Fallback
+  if (x.constructor === Buffer && Buffer.isBuffer(x)) return x.toString('base64') // Older Node.js
+  return Buffer.from(x.buffer, x.byteOffset, x.byteLength).toString('base64') // Older Node.js
+}
+
+// NOTE: base64url omits padding
+export function toBase64url(x) {
+  assertUint8(x)
+  if (web64 && x.toBase64 === web64) return x.toBase64({ alphabet: 'base64url', omitPadding: true }) // Modern
+  if (!haveNativeBuffer) return toBase64js(x, BASE64URL, false) // Fallback
+  if (x.constructor === Buffer && Buffer.isBuffer(x)) return x.toString('base64url') // Older Node.js
+  return Buffer.from(x.buffer, x.byteOffset, x.byteLength).toString('base64url') // Older Node.js
+}
+
+// Unlike Buffer.from(), throws on invalid input (non-base64 symbols and incomplete chunks)
+// Unlike Buffer.from() and Uint8Array.fromBase64(), does not allow spaces
+// NOTE: Always operates in strict mode for last chunk
+
+// Accepts both padded and non-padded variants, only strict base64
+export function fromBase64(str, format = 'uint8') {
+  if (typeof str !== 'string') throw new TypeError('Input is not a string')
+
+  // These checks should be needed only for Buffer path, not Uint8Array.fromBase64 path, but JSC lacks proper checks
+  assert(str.length % 4 !== 1, 'Invalid base64 length') // JSC misses this in fromBase64
+  if (str.endsWith('=')) {
+    assert(str.length % 4 === 0, 'Invalid padded length') // JSC misses this too
+    assert(str[str.length - 3] !== '=', 'Excessive padding') // no more than two = at the end
+  }
+
+  return fromTypedArray(fromBase64common(str, false), format)
+}
+
+// Accepts both only non-padded strict base64url
+export function fromBase64url(str, format = 'uint8') {
+  if (typeof str !== 'string') throw new TypeError('Input is not a string')
+
+  // These checks should be needed only for Buffer path, not Uint8Array.fromBase64 path, but JSC lacks proper checks
+  assert(str.length % 4 !== 1, 'Invalid base64 length') // JSC misses this in fromBase64
+  assert(!str.endsWith('='), 'Did not expect padding in base64url input') // inclusion is checked separately
+
+  return fromTypedArray(fromBase64common(str, true), format)
+}
+
+let fromBase64common
+if (Uint8Array.fromBase64) {
+  // NOTICE: this is actually slower than our JS impl in older JavaScriptCore and (slightly) in SpiderMonkey, but faster on V8 and new JavaScriptCore
+  fromBase64common = (str, isBase64url) => {
+    const alphabet = isBase64url ? 'base64url' : 'base64'
+    assert(!/\s/u.test(str), `Invalid character in ${alphabet} input`) // all other chars are checked natively
+    const padded = str.length % 4 > 0 ? `${str}${'='.repeat(4 - (str.length % 4))}` : str
+    return Uint8Array.fromBase64(padded, { alphabet, lastChunkHandling: 'strict' })
+  }
+} else {
+  fromBase64common = (str, isBase64url) => {
+    if (isBase64url) {
+      assert(!/[^0-9a-z_-]/iu.test(str), 'Invalid character in base64url input')
+    } else {
+      assert(!/[^0-9a-z=+/]/iu.test(str), 'Invalid character in base64 input')
+    }
+
+    let arr
+    if (!haveNativeBuffer && atob) {
+      // atob is faster than manual parsing on Hermes
+      const raw = atob(isBase64url ? str.replaceAll('-', '+').replaceAll('_', '/') : str)
+      arr = new Uint8Array(raw.length)
+      for (let i = 0; i < raw.length; i++) arr[i] = raw.charCodeAt(i)
+    } else {
+      // base64url is already checked to have no padding via a regex above
+      if (!isBase64url) {
+        const at = str.indexOf('=')
+        if (at >= 0) assert(!/[^=]/iu.test(str.slice(at)), 'Invalid padding')
+      }
+
+      arr = haveNativeBuffer ? Buffer.from(str, 'base64') : fromBase64js(str)
+    }
+
+    if (arr.length % 3 !== 0) {
+      // Check last chunk to be strict if it was incomplete
+      const expected = toBase64(arr.subarray(-(arr.length % 3)))
+      const end = str.length % 4 === 0 ? str.slice(-4) : str.slice(-(str.length % 4)).padEnd(4, '=')
+      const actual = isBase64url ? end.replaceAll('-', '+').replaceAll('_', '/') : end
+      if (expected !== actual) throw new Error('Invalid last chunk')
+    }
+
+    return arr
+  }
+}
+
+const BASE64 = [...'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/']
+const BASE64URL = [...'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_']
+
+const BASE64_PAIRS = []
+const BASE64URL_PAIRS = []
+
+// We construct output by concatenating chars, this seems to be fine enough on modern JS engines
+function toBase64js(arr, alphabet, padding) {
+  assertUint8(arr)
+  const fullChunks = Math.floor(arr.length / 3)
+  const fullChunksBytes = fullChunks * 3
+  let o = ''
+  let i = 0
+
+  const pairs = alphabet === BASE64URL ? BASE64URL_PAIRS : BASE64_PAIRS
+  if (pairs.length === 0) {
+    for (let i = 0; i < 64; i++) {
+      for (let j = 0; j < 64; j++) pairs.push(`${alphabet[i]}${alphabet[j]}`)
+    }
+  }
+
+  // Fast path for complete blocks
+  // This whole loop can be commented out, the algorithm won't change, it's just an optimization of the next loop
+  for (; i < fullChunksBytes; i += 3) {
+    const a = arr[i]
+    const b = arr[i + 1]
+    const c = arr[i + 2]
+    o += pairs[(a << 4) | (b >> 4)] + pairs[((b & 0x0f) << 8) | c]
+  }
+
+  // If we have something left, process it with a full algo
+  let carry = 0
+  let shift = 2 // First byte needs to be shifted by 2 to get 6 bits
+  const length = arr.length
+  for (; i < length; i++) {
+    const x = arr[i]
+    o += alphabet[carry | (x >> shift)] // shift >= 2, so this fits
+    if (shift === 6) {
+      shift = 0
+      o += alphabet[x & 0x3f]
+    }
+
+    carry = (x << (6 - shift)) & 0x3f
+    shift += 2 // Each byte prints 6 bits and leaves 2 bits
+  }
+
+  if (shift !== 2) o += alphabet[carry] // shift 2 means we have no carry left
+  if (padding) o += ['', '==', '='][length - fullChunksBytes]
+
+  return o
+}
+
+// Assumes no chars after =, checked
+let fromBase64jsMap
+
+function fromBase64js(str) {
+  const map = fromBase64jsMap || new Array(256)
+  if (!fromBase64jsMap) {
+    fromBase64jsMap = map
+    BASE64.forEach((c, i) => (map[c.charCodeAt(0)] = i))
+    map['-'.charCodeAt(0)] = map['+'.charCodeAt(0)] // for base64url
+    map['_'.charCodeAt(0)] = map['/'.charCodeAt(0)] // for base64url
+  }
+
+  let inputLength = str.length
+  while (str[inputLength - 1] === '=') inputLength--
+
+  const arr = new Uint8Array(Math.floor((inputLength * 3) / 4))
+  const tailLength = inputLength % 4
+  const mainLength = inputLength - tailLength // multiples of 4
+
+  let at = 0
+  let i = 0
+  let tmp
+
+  while (i < mainLength) {
+    tmp =
+      (map[str.charCodeAt(i)] << 18) |
+      (map[str.charCodeAt(i + 1)] << 12) |
+      (map[str.charCodeAt(i + 2)] << 6) |
+      map[str.charCodeAt(i + 3)]
+    arr[at++] = tmp >> 16
+    arr[at++] = (tmp >> 8) & 0xff
+    arr[at++] = tmp & 0xff
+    i += 4
+  }
+
+  if (tailLength === 3) {
+    tmp =
+      (map[str.charCodeAt(i)] << 10) |
+      (map[str.charCodeAt(i + 1)] << 4) |
+      (map[str.charCodeAt(i + 2)] >> 2)
+    arr[at++] = (tmp >> 8) & 0xff
+    arr[at++] = tmp & 0xff
+  } else if (tailLength === 2) {
+    tmp = (map[str.charCodeAt(i)] << 2) | (map[str.charCodeAt(i + 1)] >> 4)
+    arr[at++] = tmp & 0xff
+  }
+
+  return arr
+}

package/hex.js

@@ -0,0 +1,78 @@
+import { assertTypedArray, assert } from './assert.js'
+import { fromTypedArray } from './array.js'
+
+const { Buffer } = globalThis // Buffer is optional, only used when native
+const haveNativeBuffer = Buffer && !Buffer.TYPED_ARRAY_SUPPORT
+const { toHex: webHex } = Uint8Array.prototype // Modern engines have this
+
+let hexArray
+let dehexArray
+
+export function toHex(arr) {
+  assertTypedArray(arr)
+  if (!(arr instanceof Uint8Array)) arr = new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength)
+  if (webHex && arr.toHex === webHex) return arr.toHex()
+  if (haveNativeBuffer) {
+    if (arr.constructor === Buffer && Buffer.isBuffer(arr)) return arr.toString('hex')
+    return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength).toString('hex')
+  }
+
+  if (!hexArray) hexArray = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, '0'))
+  const length = arr.length // this helps Hermes
+
+  if (length > 3000) {
+    // Limit concatenation to avoid excessive GC
+    // Thresholds checked on Hermes
+    const concat = []
+    for (let i = 0; i < length; ) {
+      const step = i + 500
+      const end = step > length ? length : step
+      let chunk = ''
+      for (; i < end; i++) chunk += hexArray[arr[i]]
+      concat.push(chunk)
+    }
+
+    const res = concat.join('')
+    concat.length = 0
+    return res
+  }
+
+  let out = ''
+  for (let i = 0; i < length; i++) out += hexArray[arr[i]]
+  return out
+}
+
+// Unlike Buffer.from(), throws on invalid input
+let fromHex
+if (Uint8Array.fromHex) {
+  fromHex = (str, format = 'uint8') => fromTypedArray(Uint8Array.fromHex(str), format)
+} else {
+  fromHex = (str, format = 'uint8') => {
+    if (typeof str !== 'string') throw new TypeError('Input is not a string')
+    assert(str.length % 2 === 0, 'Input is not a hex string')
+
+    // We don't use native Buffer impl, as rechecking input make it slower than pure js
+    // This path is used only on older engines though
+
+    if (!dehexArray) {
+      dehexArray = new Array(103) // f is 102
+      for (let i = 0; i < 16; i++) {
+        const s = i.toString(16)
+        dehexArray[s.charCodeAt(0)] = dehexArray[s.toUpperCase().charCodeAt(0)] = i
+      }
+    }
+
+    const arr = new Uint8Array(str.length / 2)
+    let j = 0
+    const length = arr.length // this helps Hermes
+    for (let i = 0; i < length; i++) {
+      const a = dehexArray[str.charCodeAt(j++)] * 16 + dehexArray[str.charCodeAt(j++)]
+      if (!a && Number.isNaN(a)) throw new Error('Input is not a hex string')
+      arr[i] = a
+    }
+
+    return fromTypedArray(arr, format)
+  }
+}
+
+export { fromHex }

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@exodus/bytes",
+  "version": "1.0.0-rc.0",
+  "description": "Various operations on Uint8Array data",
+  "scripts": {
+    "lint": "eslint .",
+    "test:v8": "npm run test:d8 --",
+    "test:javascriptcore": "npm run test:jsc --",
+    "test:d8": "exodus-test --engine=d8:bundle",
+    "test:jsc": "exodus-test --engine=jsc:bundle",
+    "test:spidermonkey": "exodus-test --engine=spidermonkey:bundle",
+    "test:hermes": "exodus-test --engine=hermes:bundle",
+    "test:quickjs": "exodus-test --engine=quickjs:bundle",
+    "test:electron:bundle": "exodus-test --engine=electron:bundle",
+    "test:electron:as-node": "exodus-test --engine=electron-as-node:test",
+    "test:chrome:puppeteer": "exodus-test --engine=chrome:puppeteer",
+    "test:chromium:playwright": "exodus-test --engine=chromium:playwright",
+    "test:webkit:playwright": "exodus-test --engine=webkit:playwright",
+    "test:firefox:puppeteer": "exodus-test --engine=firefox:puppeteer",
+    "test:firefox:playwright": "exodus-test --engine=firefox:playwright",
+    "test": "exodus-test",
+    "jsvu": "jsvu",
+    "playwright": "exodus-test --playwright",
+    "benchmark": "exodus-test --concurrency=1 benchmarks/*.bench.js",
+    "coverage": "exodus-test --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExodusMovement/bytes.git"
+  },
+  "author": "Exodus Movement, Inc.",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ExodusMovement/bytes/issues"
+  },
+  "homepage": "https://github.com/ExodusMovement/bytes#readme",
+  "engines": {
+    "node": "^20.19.0 || >=22.13.0"
+  },
+  "type": "module",
+  "files": [
+    "/assert.js",
+    "/base64.js",
+    "/array.js",
+    "/hex.js"
+  ],
+  "exports": {
+    "./base64.js": "./base64.js",
+    "./array.js": "./array.js",
+    "./hex.js": "./hex.js"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@exodus/eslint-config": "^5.24.0",
+    "@exodus/prettier": "^1.0.0",
+    "@exodus/test": "^1.0.0-rc.105",
+    "@scure/base": "^1.2.6",
+    "@types/node": "^24.0.10",
+    "base-x": "^5.0.1",
+    "base32.js": "^0.1.0",
+    "base64-js": "^1.5.1",
+    "buffer": "^6.0.3",
+    "electron": "36.5.0",
+    "eslint": "^8.44.0",
+    "jsvu": "^3.0.0"
+  },
+  "prettier": "@exodus/prettier",
+  "packageManager": "pnpm@10.12.1+sha256.889bac470ec93ccc3764488a19d6ba8f9c648ad5e50a9a6e4be3768a5de387a3"
+}