@exodus/bytes 1.9.0 → 1.11.0

package/utf8.js

@@ -27,16 +27,21 @@ function deLoose(str, loose, res) {
 
   // Recheck if the string was encoded correctly
   let start = 0
-  const last = res.length - 2
-  // Search for EFBFBD
-  while (start < last) {
+  const last = res.length - 3
+  // Search for EFBFBD (3-byte sequence)
+  while (start <= last) {
     const pos = res.indexOf(0xef, start)
-    if (pos === -1) break
+    if (pos === -1 || pos > last) break
     start = pos + 1
     if (res[pos + 1] === 0xbf && res[pos + 2] === 0xbd) {
       // Found a replacement char in output, need to recheck if we encoded the input correctly
-      if (str !== decode(res)) throw new TypeError(E_STRICT_UNICODE)
-      return res
+      if (!nativeDecoder && str.length < 1e7) {
+        // This is ~2x faster than decode in Hermes
+        try {
+          if (encodeURI(str) !== null) return res // guard against optimizing out
+        } catch {}
+      } else if (str === decode(res)) return res
+      throw new TypeError(E_STRICT_UNICODE)
     }
   }
 

package/utf8.node.js

@@ -9,7 +9,7 @@ if (Buffer.TYPED_ARRAY_SUPPORT) throw new Error('Unexpected Buffer polyfill')
 let decoderFatal
 const decoderLoose = new TextDecoder('utf-8', { ignoreBOM: true })
 const { isWellFormed } = String.prototype
-const isDeno = Boolean(globalThis.Deno)
+const isDeno = !!globalThis.Deno
 
 try {
   decoderFatal = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true })

package/whatwg.d.ts

@@ -0,0 +1,48 @@
+/**
+ * WHATWG helpers
+ *
+ * ```js
+ * import '@exodus/bytes/encoding.js' // For full legacy multi-byte encodings support
+ * import { percentEncodeAfterEncoding } from '@exodus/bytes/whatwg.js'
+ * ```
+ *
+ * @module @exodus/bytes/whatwg.js
+ */
+
+/**
+ * Implements [percent-encode after encoding](https://url.spec.whatwg.org/#string-percent-encode-after-encoding)
+ * per WHATWG URL specification.
+ *
+ * > [!IMPORTANT]
+ * > You must import `@exodus/bytes/encoding.js` for this API to accept legacy multi-byte encodings.
+ *
+ * Encodings `utf16-le`, `utf16-be`, and `replacement` are not accepted.
+ *
+ * [C0 control percent-encode set](https://url.spec.whatwg.org/#c0-control-percent-encode-set) is
+ * always percent-encoded.
+ *
+ * `percentEncodeSet` is an addition to that, and must be a string of unique increasing codepoints
+ * in range 0x20 - 0x7e, e.g. `' "#<>'`.
+ *
+ * This method accepts [DOMStrings](https://webidl.spec.whatwg.org/#idl-DOMString) and converts them
+ * to [USVStrings](https://webidl.spec.whatwg.org/#idl-USVString).
+ * This is different from e.g. `encodeURI` and `encodeURIComponent` which throw on surrogates:
+ * ```js
+ * > percentEncodeAfterEncoding('utf8', '\ud800', ' "#$%&+,/:;<=>?@[\\]^`{|}') // component
+ * '%EF%BF%BD'
+ * > encodeURIComponent('\ud800')
+ * Uncaught URIError: URI malformed
+ * ```
+ *
+ * @param encoding - The encoding label per WHATWG Encoding spec
+ * @param input - Input scalar-value string to encode
+ * @param percentEncodeSet - A string of ASCII chars to escape in addition to C0 control percent-encode set
+ * @param spaceAsPlus - Whether to encode space as `'+'` instead of `'%20'` or `' '` (default: false)
+ * @returns The percent-encoded string
+ */
+export function percentEncodeAfterEncoding(
+  encoding: string,
+  input: string,
+  percentEncodeSet: string,
+  spaceAsPlus?: boolean
+): string;

package/whatwg.js

@@ -0,0 +1,76 @@
+import { utf8fromStringLoose } from '@exodus/bytes/utf8.js'
+import { createSinglebyteEncoder } from '@exodus/bytes/single-byte.js'
+import { isMultibyte, getMultibyteEncoder } from './fallback/encoding.js'
+import { normalizeEncoding, E_ENCODING } from './fallback/encoding.api.js'
+import { percentEncoder } from './fallback/percent.js'
+import { encodeMap } from './fallback/single-byte.js'
+import { E_STRING } from './fallback/_utils.js'
+
+// https://url.spec.whatwg.org/#string-percent-encode-after-encoding
+// Codepoints below 0x20, 0x7F specifically, and above 0x7F (non-ASCII) are always encoded
+// > A C0 control is a code point in the range U+0000 NULL to U+001F INFORMATION SEPARATOR ONE, inclusive.
+// > The C0 control percent-encode set are the C0 controls and all code points greater than U+007E (~).
+export function percentEncodeAfterEncoding(encoding, input, percentEncodeSet, spaceAsPlus = false) {
+  const enc = normalizeEncoding(encoding)
+  // Ref: https://encoding.spec.whatwg.org/#get-an-encoder
+  if (!enc || enc === 'replacement' || enc === 'utf-16le' || enc === 'utf-16be') {
+    throw new RangeError(E_ENCODING)
+  }
+
+  const percent = percentEncoder(percentEncodeSet, spaceAsPlus)
+  if (enc === 'utf-8') return percent(utf8fromStringLoose(input))
+
+  const multi = isMultibyte(enc)
+  const encoder = multi ? getMultibyteEncoder() : createSinglebyteEncoder
+  const fatal = encoder(enc)
+  try {
+    return percent(fatal(input))
+  } catch {}
+
+  let res = ''
+  let last = 0
+  if (multi) {
+    const rep = enc === 'gb18030' ? percent(fatal('\uFFFD')) : `%26%23${0xff_fd}%3B` // only gb18030 can encode it
+    const escaping = encoder(enc, (cp, u, i) => {
+      res += percent(u, last, i)
+      res += cp >= 0xd8_00 && cp < 0xe0_00 ? rep : `%26%23${cp}%3B` // &#cp;
+      last = i
+      return 0 // no bytes emitted
+    })
+
+    const u = escaping(input) // has side effects on res
+    res += percent(u, last)
+  } else {
+    if (typeof input !== 'string') throw new TypeError(E_STRING) // all other paths have their own validation
+    const m = encodeMap(enc)
+    const len = input.length
+    const u = new Uint8Array(len)
+    for (let i = 0; i < len; i++) {
+      const x = input.charCodeAt(i)
+      const b = m[x]
+      if (!b && x) {
+        let cp = x
+        const i0 = i
+        if (x >= 0xd8_00 && x < 0xe0_00) {
+          cp = 0xff_fd
+          if (x < 0xdc_00 && i + 1 < len) {
+            const x1 = input.charCodeAt(i + 1)
+            if (x1 >= 0xdc_00 && x1 < 0xe0_00) {
+              cp = 0x1_00_00 + ((x1 & 0x3_ff) | ((x & 0x3_ff) << 10))
+              i++
+            }
+          }
+        }
+
+        res += `${percent(u, last, i0)}%26%23${cp}%3B` // &#cp;
+        last = i + 1 // skip current
+      } else {
+        u[i] = b
+      }
+    }
+
+    res += percent(u, last)
+  }
+
+  return res
+}

package/wif.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Wallet Import Format (WIF) encoding and decoding.
+ *
+ * ```js
+ * import { fromWifString, toWifString } from '@exodus/bytes/wif.js'
+ * import { fromWifStringSync, toWifStringSync } from '@exodus/bytes/wif.js'
+ * ```
+ *
+ * On non-Node.js, requires peer dependency [@noble/hashes](https://www.npmjs.com/package/@noble/hashes) to be installed.
+ *
+ * @module @exodus/bytes/wif.js
+ */
+
+/// <reference types="node" />
+
+import type { Uint8ArrayBuffer } from './array.js';
+
+/**
+ * WIF (Wallet Import Format) data structure
+ */
+export interface Wif {
+  /** Network version byte */
+  version: number;
+  /** 32-byte private key */
+  privateKey: Uint8ArrayBuffer;
+  /** Whether the key is compressed */
+  compressed: boolean;
+}
+
+/**
+ * Decode a WIF string to WIF data
+ *
+ * Returns a promise that resolves to an object with `{ version, privateKey, compressed }`.
+ *
+ * The optional `version` parameter validates the version byte.
+ *
+ * Throws if the WIF string is invalid or version doesn't match.
+ *
+ * @param string - The WIF encoded string
+ * @param version - Optional expected version byte to validate against
+ * @returns The decoded WIF data
+ * @throws Error if the WIF string is invalid or version doesn't match
+ */
+export function fromWifString(string: string, version?: number): Promise<Wif>;
+
+/**
+ * Decode a WIF string to WIF data (synchronous)
+ *
+ * Returns an object with `{ version, privateKey, compressed }`.
+ *
+ * The optional `version` parameter validates the version byte.
+ *
+ * Throws if the WIF string is invalid or version doesn't match.
+ *
+ * @param string - The WIF encoded string
+ * @param version - Optional expected version byte to validate against
+ * @returns The decoded WIF data
+ * @throws Error if the WIF string is invalid or version doesn't match
+ */
+export function fromWifStringSync(string: string, version?: number): Wif;
+
+/**
+ * Encode WIF data to a WIF string
+ *
+ * @param wif - The WIF data to encode
+ * @returns The WIF encoded string
+ */
+export function toWifString(wif: Wif): Promise<string>;
+
+/**
+ * Encode WIF data to a WIF string (synchronous)
+ *
+ * @param wif - The WIF data to encode
+ * @returns The WIF encoded string
+ */
+export function toWifStringSync(wif: Wif): string;

package/wif.js

@@ -6,6 +6,7 @@ import { assertUint8 } from './assert.js'
 
 function from(arr, expectedVersion) {
   assertUint8(arr)
+  if (arr.length !== 33 && arr.length !== 34) throw new Error('Invalid WIF length')
   const version = arr[0]
   if (expectedVersion !== undefined && version !== expectedVersion) {
     throw new Error('Invalid network version')
@@ -14,7 +15,6 @@ function from(arr, expectedVersion) {
   // Makes a copy, regardless of input being a Buffer or a Uint8Array (unlike .slice)
   const privateKey = Uint8Array.from(arr.subarray(1, 33))
   if (arr.length === 33) return { version, privateKey, compressed: false }
-  if (arr.length !== 34) throw new Error('Invalid WIF length')
   if (arr[33] !== 1) throw new Error('Invalid compression flag')
   return { version, privateKey, compressed: true }
 }
@@ -22,7 +22,6 @@ function from(arr, expectedVersion) {
 function to({ version: v, privateKey, compressed }) {
   if (!Number.isSafeInteger(v) || v < 0 || v > 0xff) throw new Error('Missing or invalid version')
   assertUint8(privateKey, { length: 32, name: 'privateKey' })
-  if (privateKey.length !== 32) throw new TypeError('Invalid privateKey length')
   const out = new Uint8Array(compressed ? 34 : 33)
   out[0] = v
   out.set(privateKey, 1)