@exodus/bytes 1.6.0 → 1.7.0

package/README.md

@@ -31,6 +31,7 @@ See [Performance](./Performance.md) for more info
 
 ```js
 import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding.js'
+import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding.js' // Requires Streams
 ```
 
 Less than half the bundle size of [text-encoding](https://npmjs.com/text-encoding), [whatwg-encoding](https://npmjs.com/whatwg-encoding) or [iconv-lite](https://npmjs.com/iconv-lite) (gzipped or not).\
@@ -77,6 +78,7 @@ _These are only provided as a compatibility layer, prefer hardened APIs instead
 If you don't need support for legacy multi-byte encodings, you can use the lite import:
 ```js
 import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-lite.js'
+import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-lite.js' // Requires Streams
 ```
 
 This reduces the bundle size 10x:\
@@ -121,8 +123,8 @@ import { utf16fromStringLoose, utf16toStringLoose } from '@exodus/bytes/utf16.js
 ### `@exodus/bytes/single-byte.js`
 
 ```js
-import { createSinglebyteDecoder } from '@exodus/bytes/single-byte.js'
-import { windows1252toString } from '@exodus/bytes/single-byte.js'
+import { createSinglebyteDecoder, createSinglebyteEncoder } from '@exodus/bytes/single-byte.js'
+import { windows1252toString, windows1252fromString } from '@exodus/bytes/single-byte.js'
 ```
 
 Decode the legacy single-byte encodings according to the [Encoding standard](https://encoding.spec.whatwg.org/)
@@ -137,10 +139,19 @@ Supports all single-byte encodings listed in the standard:
 
 ##### `createSinglebyteDecoder(encoding, loose = false)`
 
-Create a decoder for a supported one-byte `encoding`, given it's lowercased name `encoding`.
+Create a decoder for a supported one-byte `encoding`, given its lowercased name `encoding`.
 
 Returns a function `decode(arr)` that decodes bytes to a string.
 
+##### `createSinglebyteEncoder(encoding, { mode = 'fatal' })`
+
+Create an encoder for a supported one-byte `encoding`, given its lowercased name `encoding`.
+
+Returns a function `encode(string)` that encodes a string to bytes.
+
+In `'fatal'` mode (default), will throw on non well-formed strings or any codepoints which could
+not be encoded in the target encoding.
+
 ##### `windows1252toString(arr)`
 
 Decode `windows-1252` bytes to a string.
@@ -154,6 +165,19 @@ Same as:
 const windows1252toString = createSinglebyteDecoder('windows-1252')
 ```
 
+##### `windows1252fromString(string)`
+
+Encode a string to `windows-1252` bytes.
+
+Also supports `ascii` and `latin-1` as those are strict subsets of `windows-1252`.
+
+Will throw on non well-formed strings or any codepoints which could not be encoded in `windows-1252`.
+
+Same as:
+```js
+const windows1252fromString = createSinglebyteEncoder('windows-1252', { mode: 'fatal' })
+```
+
 ### `@exodus/bytes/multi-byte.js`
 
 ```js
@@ -171,7 +195,7 @@ Supports all legacy multi-byte encodings listed in the standard:
 
 ##### `createMultibyteDecoder(encoding, loose = false)`
 
-Create a decoder for a supported legacy multi-byte `encoding`, given it's lowercased name `encoding`.
+Create a decoder for a supported legacy multi-byte `encoding`, given its lowercased name `encoding`.
 
 Returns a function `decode(arr, stream = false)` that decodes bytes to a string.
 
@@ -284,6 +308,7 @@ On non-Node.js, requires peer dependency [@exodus/crypto](https://www.npmjs.com/
 
 ```js
 import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding.js'
+import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding.js' // Requires Streams
 
 // Hooks for standards
 import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from '@exodus/bytes/encoding.js'
@@ -291,7 +316,9 @@ import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from
 
 Implements the [Encoding standard](https://encoding.spec.whatwg.org/):
 [TextDecoder](https://encoding.spec.whatwg.org/#interface-textdecoder),
-[TextEncoder](https://encoding.spec.whatwg.org/#interface-textdecoder),
+[TextEncoder](https://encoding.spec.whatwg.org/#interface-textencoder),
+[TextDecoderStream](https://encoding.spec.whatwg.org/#interface-textdecoderstream),
+[TextEncoderStream](https://encoding.spec.whatwg.org/#interface-textencoderstream),
 some [hooks](https://encoding.spec.whatwg.org/#specification-hooks) (see below).
 
 #### `new TextDecoder(label = 'utf-8', { fatal = false, ignoreBOM = false })`
@@ -300,7 +327,21 @@ some [hooks](https://encoding.spec.whatwg.org/#specification-hooks) (see below).
 
 #### `new TextEncoder()`
 
-[TextEncoder](https://encoding.spec.whatwg.org/#interface-textdecoder) implementation/polyfill.
+[TextEncoder](https://encoding.spec.whatwg.org/#interface-textencoder) implementation/polyfill.
+
+#### `new TextDecoderStream(label = 'utf-8', { fatal = false, ignoreBOM = false })`
+
+[TextDecoderStream](https://encoding.spec.whatwg.org/#interface-textdecoderstream) implementation/polyfill.
+
+Requires [Streams](https://streams.spec.whatwg.org/) to be either supported by the platform or
+[polyfilled](https://npmjs.com/package/web-streams-polyfill).
+
+#### `new TextEncoderStream()`
+
+[TextEncoderStream](https://encoding.spec.whatwg.org/#interface-textencoderstream) implementation/polyfill.
+
+Requires [Streams](https://streams.spec.whatwg.org/) to be either supported by the platform or
+[polyfilled](https://npmjs.com/package/web-streams-polyfill).
 
 #### `labelToName(label)`
 
@@ -370,6 +411,7 @@ new TextDecoder(getBOMEncoding(input) ?? fallbackEncoding).decode(input)
 
 ```js
 import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-lite.js'
+import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-lite.js' // Requires Streams
 
 // Hooks for standards
 import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from '@exodus/bytes/encoding-lite.js'
@@ -393,7 +435,9 @@ To avoid inconsistencies, the exported classes and methods are exactly the same
 > lite = require('@exodus/bytes/encoding-lite.js')
 [Module: null prototype] {
   TextDecoder: [class TextDecoder],
+  TextDecoderStream: [class TextDecoderStream],
   TextEncoder: [class TextEncoder],
+  TextEncoderStream: [class TextEncoderStream],
   getBOMEncoding: [Function: getBOMEncoding],
   labelToName: [Function: labelToName],
   legacyHookDecode: [Function: legacyHookDecode],
@@ -406,7 +450,9 @@ Error: Legacy multi-byte encodings are disabled in /encoding-lite.js, use /encod
 > full = require('@exodus/bytes/encoding.js')
 [Module: null prototype] {
   TextDecoder: [class TextDecoder],
+  TextDecoderStream: [class TextDecoderStream],
   TextEncoder: [class TextEncoder],
+  TextEncoderStream: [class TextEncoderStream],
   getBOMEncoding: [Function: getBOMEncoding],
   labelToName: [Function: labelToName],
   legacyHookDecode: [Function: legacyHookDecode],

package/bech32.js

@@ -179,6 +179,9 @@ function assertDecodeArgs(str, limit) {
   if (typeof limit !== 'number' || str.length < 8 || !(str.length <= limit)) throw new Error(E_SIZE)
 }
 
+// this is instant on 8-bit strings
+const NON_LATIN = /[^\x00-\xFF]/ // eslint-disable-line no-control-regex
+
 function fromBech32enc(str, limit, encoding) {
   assertDecodeArgs(str, limit)
   const lower = str.toLowerCase()
@@ -195,6 +198,7 @@ function fromBech32enc(str, limit, encoding) {
   if (wordsLength < 0) throw new Error(E_SIZE)
   const bytesLength = (wordsLength * 5) >> 3
   const slice = str.slice(split + 1)
+  if (!nativeEncoder && NON_LATIN.test(slice)) throw new SyntaxError(E_CHARACTER) // otherwise can't use encodeLatin1
   const c = nativeEncoder ? encodeAscii(slice, E_CHARACTER) : encodeLatin1(slice) // suboptimal, but only affects non-Hermes barebones
   const bytes = new Uint8Array(bytesLength)
 

package/encoding-lite.js

@@ -1,6 +1,8 @@
 export {
   TextDecoder,
   TextEncoder,
+  TextDecoderStream,
+  TextEncoderStream,
   normalizeEncoding,
   getBOMEncoding,
   labelToName,

package/encoding.js

@@ -6,6 +6,8 @@ setMultibyteDecoder(createMultibyteDecoder)
 export {
   TextDecoder,
   TextEncoder,
+  TextDecoderStream,
+  TextEncoderStream,
   normalizeEncoding,
   getBOMEncoding,
   labelToName,

package/fallback/_utils.js

@@ -5,14 +5,8 @@ export const isHermes = Boolean(globalThis.HermesInternal)
 export const isDeno = Boolean(globalThis.Deno)
 export const isLE = new Uint8Array(Uint16Array.of(258).buffer)[0] === 2
 
-let isNative = (x) => {
-  if (!x) return false
-  if (haveNativeBuffer) return true // we consider Node.js TextDecoder/TextEncoder native
-  const s = `${x}`
-  // See https://github.com/facebook/hermes/pull/1855#issuecomment-3659386410
-  return s.includes('[native code]') || s.includes(`[bytecode]`) // Static Hermes has [bytecode] for contrib, which includes TextEncoder/TextDecoder
-}
-
+// We consider Node.js TextDecoder/TextEncoder native
+let isNative = (x) => x && (haveNativeBuffer || `${x}`.includes('[native code]'))
 if (!haveNativeBuffer && isNative(() => {})) isNative = () => false // e.g. XS, we don't want false positives
 
 export const nativeEncoder = isNative(TextEncoder) ? new TextEncoder() : null

package/fallback/encoding.js

@@ -68,7 +68,16 @@ function isAnyUint8Array(x) {
 const fromSource = (x) => {
   if (x instanceof Uint8Array) return x
   if (ArrayBuffer.isView(x)) return new Uint8Array(x.buffer, x.byteOffset, x.byteLength)
-  if (isAnyArrayBuffer(x)) return new Uint8Array(x)
+  if (isAnyArrayBuffer(x)) {
+    if ('detached' in x) return x.detached === true ? new Uint8Array() : new Uint8Array(x)
+    // Old engines without .detached, try-catch
+    try {
+      return new Uint8Array(x)
+    } catch {
+      return new Uint8Array()
+    }
+  }
+
   throw new TypeError('Argument must be a SharedArrayBuffer, ArrayBuffer or ArrayBufferView')
 }
 
@@ -259,6 +268,79 @@ export class TextEncoder {
   }
 }
 
+const E_NO_STREAMS = 'TransformStream global not present in the environment'
+
+// https://encoding.spec.whatwg.org/#interface-textdecoderstream
+export class TextDecoderStream {
+  constructor(encoding = 'utf-8', options = {}) {
+    if (!globalThis.TransformStream) throw new Error(E_NO_STREAMS)
+    const decoder = new TextDecoder(encoding, options)
+    const transform = new TransformStream({
+      transform: (chunk, controller) => {
+        const value = decoder.decode(fromSource(chunk), { stream: true })
+        if (value) controller.enqueue(value)
+      },
+      flush: (controller) => {
+        // https://streams.spec.whatwg.org/#dom-transformer-flush
+        const value = decoder.decode()
+        if (value) controller.enqueue(value)
+        // No need to call .terminate() (Node.js is wrong)
+      },
+    })
+
+    define(this, 'encoding', decoder.encoding)
+    define(this, 'fatal', decoder.fatal)
+    define(this, 'ignoreBOM', decoder.ignoreBOM)
+    define(this, 'readable', transform.readable)
+    define(this, 'writable', transform.writable)
+  }
+
+  get [Symbol.toStringTag]() {
+    return 'TextDecoderStream'
+  }
+}
+
+// https://encoding.spec.whatwg.org/#interface-textencoderstream
+// Only UTF-8 per spec
+export class TextEncoderStream {
+  constructor() {
+    if (!globalThis.TransformStream) throw new Error(E_NO_STREAMS)
+    let lead
+    const transform = new TransformStream({
+      // https://encoding.spec.whatwg.org/#encode-and-enqueue-a-chunk
+      // Not identical in code, but reuses loose mode to have identical behavior
+      transform: (chunk, controller) => {
+        let s = String(chunk) // DOMString, might contain unpaired surrogates
+        if (s.length === 0) return
+        if (lead) {
+          s = lead + s
+          lead = null
+        }
+
+        const last = s.charCodeAt(s.length - 1) // Can't come from previous lead due to length check
+        if ((last & 0xfc_00) === 0xd8_00) {
+          lead = s[s.length - 1]
+          s = s.slice(0, -1)
+        }
+
+        if (s) controller.enqueue(utf8fromStringLoose(s))
+      },
+      // https://encoding.spec.whatwg.org/#encode-and-flush
+      flush: (controller) => {
+        if (lead) controller.enqueue(Uint8Array.of(0xef, 0xbf, 0xbd))
+      },
+    })
+
+    define(this, 'encoding', 'utf-8')
+    define(this, 'readable', transform.readable)
+    define(this, 'writable', transform.writable)
+  }
+
+  get [Symbol.toStringTag]() {
+    return 'TextEncoderStream'
+  }
+}
+
 // Warning: unlike whatwg-encoding, returns lowercased labels
 // Those are case-insensitive and that's how TextDecoder encoding getter normalizes them
 export function getBOMEncoding(input) {

package/fallback/latin1.js

@@ -109,6 +109,7 @@ export const encodeCharcodes = isHermes
 
 /* eslint-enable @exodus/mutable/no-param-reassign-prop-only */
 
+// Warning: can be used only on checked strings, converts strings to 8-bit
 export const encodeLatin1 = (str) => encodeCharcodes(str, new Uint8Array(str.length))
 
 // Expects nativeEncoder to be present

package/fallback/multi-byte.js

@@ -474,6 +474,7 @@ const mappers = {
 export const isAsciiSuperset = (enc) => enc !== 'iso-2022-jp' // all others are ASCII supersets and can use fast path
 
 export function multibyteDecoder(enc, loose = false) {
+  if (typeof loose !== 'boolean') throw new TypeError('loose option should be boolean')
   if (!Object.hasOwn(mappers, enc)) throw new RangeError('Unsupported encoding')
 
   // Input is assumed to be typechecked already

package/fallback/single-byte.js

@@ -23,6 +23,7 @@ function getEncoding(encoding) {
 
 const mappers = new Map()
 const decoders = new Map()
+const encmaps = new Map()
 
 // Used only on Node.js, no reason to optimize for anything else
 // E.g. avoiding .from and filling zero-initialized arr manually is faster on Hermes, but we avoid this codepath on Hermes completely
@@ -31,7 +32,7 @@ export function encodingMapper(encoding) {
   if (cached) return cached
 
   const codes = getEncoding(encoding)
-  const incomplete = codes.includes(0xff_fd)
+  const incomplete = codes.includes(r)
   let map
   const mapper = (arr, start = 0) => {
     if (!map) {
@@ -66,7 +67,7 @@ export function encodingDecoder(encoding) {
 
   let strings
   const codes = getEncoding(encoding)
-  const incomplete = codes.includes(0xff_fd)
+  const incomplete = codes.includes(r)
   const decoder = (arr, loose = false) => {
     if (!strings) {
       const allCodes = Array.from({ length: 128 }, (_, i) => i).concat(codes)
@@ -85,3 +86,21 @@ export function encodingDecoder(encoding) {
   decoders.set(encoding, decoder)
   return decoder
 }
+
+export function encodeMap(encoding) {
+  const cached = encmaps.get(encoding)
+  if (cached) return cached
+
+  const codes = getEncoding(encoding)
+  let max = 128
+  while (codes.length < 128) codes.push(128 + codes.length)
+  for (const code of codes) if (code > max && code !== r) max = code
+  const map = new Uint8Array(max + 1) // < 10 KiB for all except macintosh, 63 KiB for macintosh
+  for (let i = 0; i < 128; i++) {
+    map[i] = i
+    if (codes[i] !== r) map[codes[i]] = 128 + i
+  }
+
+  encmaps.set(encoding, map)
+  return map
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/bytes",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Various operations on Uint8Array data",
   "scripts": {
     "lint": "eslint .",
@@ -145,6 +145,7 @@
     "@exodus/prettier": "^1.0.0",
     "@exodus/test": "^1.0.0-rc.109",
     "@noble/hashes": "^2.0.1",
+    "@petamoriken/float16": "^3.9.3",
     "@scure/base": "^1.2.6",
     "@stablelib/base64": "^2.0.1",
     "@stablelib/hex": "^2.0.1",
@@ -172,6 +173,7 @@
     "typescript": "^5.9.3",
     "uint8array-tools": "^0.0.9",
     "utf8": "^3.0.0",
+    "web-streams-polyfill": "^4.2.0",
     "whatwg-encoding": "^3.1.1",
     "wif": "^5.0.0"
   },

package/single-byte.js

@@ -1,6 +1,7 @@
 import { assertUint8 } from './assert.js'
-import { canDecoders } from './fallback/_utils.js'
-import { assertEncoding, encodingDecoder } from './fallback/single-byte.js'
+import { canDecoders, nativeEncoder } from './fallback/_utils.js'
+import { encodeAscii } from './fallback/latin1.js'
+import { assertEncoding, encodingDecoder, encodeMap, E_STRICT } from './fallback/single-byte.js'
 
 const { TextDecoder } = globalThis
 
@@ -34,6 +35,7 @@ function shouldUseNative(enc) {
 }
 
 export function createSinglebyteDecoder(encoding, loose = false) {
+  if (typeof loose !== 'boolean') throw new TypeError('loose option should be boolean')
   assertEncoding(encoding)
 
   if (canDecoders && shouldUseNative(encoding)) {
@@ -56,4 +58,45 @@ export function createSinglebyteDecoder(encoding, loose = false) {
   }
 }
 
+const NON_LATIN = /[^\x00-\xFF]/ // eslint-disable-line no-control-regex
+
+function encode(s, m) {
+  const len = s.length
+  const x = new Uint8Array(len)
+  for (let i = 0; i < len; i++) {
+    const x0 = s.charCodeAt(i)
+    const c0 = m[x0]
+    if (!c0 && x0) return null
+    x[i] = c0
+  }
+
+  return x
+}
+
+export function createSinglebyteEncoder(encoding, { mode = 'fatal' } = {}) {
+  // TODO: replacement, truncate (replacement will need varying length)
+  if (mode !== 'fatal') throw new Error('Unsupported mode')
+  const m = encodeMap(encoding) // asserts
+
+  // No single-byte encoder produces surrogate pairs, so any surrogate is invalid
+  // This needs special treatment only to decide how many replacement chars to output, one or two
+  // Not much use in running isWellFormed, most likely cause of error is unmapped chars, not surrogate pairs
+  return (s) => {
+    if (typeof s !== 'string') throw new TypeError('Input is not a string')
+
+    // Instead of an ASCII regex check, encode optimistically - this is faster
+    // Check for 8-bit string with a regex though, this is instant on 8-bit strings so doesn't hurt the ASCII fast path
+    if (nativeEncoder && !NON_LATIN.test(s)) {
+      try {
+        return encodeAscii(s, E_STRICT)
+      } catch {}
+    }
+
+    const res = encode(s, m)
+    if (!res) throw new TypeError(E_STRICT)
+    return res
+  }
+}
+
 export const windows1252toString = createSinglebyteDecoder('windows-1252')
+export const windows1252fromString = createSinglebyteEncoder('windows-1252')

package/single-byte.node.js

@@ -2,7 +2,7 @@ import { assertUint8 } from './assert.js'
 import { isAscii } from 'node:buffer'
 import { isDeno, isLE, toBuf } from './fallback/_utils.js'
 import { asciiPrefix } from './fallback/latin1.js'
-import { encodingMapper, encodingDecoder, E_STRICT } from './fallback/single-byte.js'
+import { encodingMapper, encodingDecoder, encodeMap, E_STRICT } from './fallback/single-byte.js'
 
 function latin1Prefix(arr, start) {
   let p = start | 0
@@ -22,6 +22,7 @@ function latin1Prefix(arr, start) {
 }
 
 export function createSinglebyteDecoder(encoding, loose = false) {
+  if (typeof loose !== 'boolean') throw new TypeError('loose option should be boolean')
   const latin1path = encoding === 'windows-1252'
   if (isDeno) {
     const jsDecoder = encodingDecoder(encoding) // asserts
@@ -57,4 +58,51 @@ export function createSinglebyteDecoder(encoding, loose = false) {
   }
 }
 
+const NON_LATIN = /[^\x00-\xFF]/ // eslint-disable-line no-control-regex
+
+export function createSinglebyteEncoder(encoding, { mode = 'fatal' } = {}) {
+  // TODO: replacement, truncate (replacement will need varying length)
+  if (mode !== 'fatal') throw new Error('Unsupported mode')
+  const m = encodeMap(encoding) // asserts
+
+  return (s) => {
+    if (typeof s !== 'string') throw new TypeError('Input is not a string')
+
+    // Instead of an ASCII regex check, encode optimistically - this is faster
+    // Check for 8-bit string with a regex though, this is instant on 8-bit strings so doesn't hurt the ASCII fast path
+    if (!NON_LATIN.test(s)) {
+      const b = Buffer.from(s, 'utf8') // ascii/latin1 coerces, we need to check
+      if (b.length === s.length) return new Uint8Array(b.buffer, b.byteOffset, b.byteLength)
+    }
+
+    const len = s.length
+    let i = 0
+    const b = Buffer.from(s, 'utf-16le') // aligned
+    if (!isLE) b.swap16()
+    const x = new Uint16Array(b.buffer, b.byteOffset, b.byteLength / 2)
+    for (const len3 = len - 3; i < len3; i += 4) {
+      const x0 = x[i], x1 = x[i + 1], x2 = x[i + 2], x3 = x[i + 3] // prettier-ignore
+      const c0 = m[x0], c1 = m[x1], c2 = m[x2], c3 = m[x3] // prettier-ignore
+      if (!(c0 && c1 && c2 && c3) && ((!c0 && x0) || (!c1 && x1) || (!c2 && x2) || (!c3 && x3))) {
+        throw new TypeError(E_STRICT)
+      }
+
+      x[i] = c0
+      x[i + 1] = c1
+      x[i + 2] = c2
+      x[i + 3] = c3
+    }
+
+    for (; i < len; i++) {
+      const x0 = x[i]
+      const c0 = m[x0]
+      if (!c0 && x0) throw new TypeError(E_STRICT)
+      x[i] = c0
+    }
+
+    return new Uint8Array(x)
+  }
+}
+
 export const windows1252toString = createSinglebyteDecoder('windows-1252')
+export const windows1252fromString = createSinglebyteEncoder('windows-1252')