@exodus/bytes 1.9.0 → 1.11.0

package/hex.d.ts

@@ -1,21 +1,35 @@
+/**
+ * Implements Base16 from [RFC4648](https://datatracker.ietf.org/doc/html/rfc4648)
+ * (no differences from [RFC3548](https://datatracker.ietf.org/doc/html/rfc4648)).
+ *
+ * ```js
+ * import { fromHex, toHex } from '@exodus/bytes/hex.js'
+ * ```
+ *
+ * @module @exodus/bytes/hex.js
+ */
+
 /// <reference types="node" />
 
 import type { OutputFormat, Uint8ArrayBuffer } from './array.js';
 
 /**
- * Encodes a Uint8Array to a lowercase hex string
+ * Encode a `Uint8Array` to a lowercase hex string
+ *
  * @param arr - The input bytes
  * @returns The hex encoded string
  */
-export function toHex(arr: Uint8ArrayBuffer): string;
+export function toHex(arr: Uint8Array): string;
 
 /**
- * Decodes a hex string to bytes
- * Unlike Buffer.from(), throws on invalid input
- * @param str - The hex encoded string (case-insensitive)
+ * Decode a hex string to bytes
+ *
+ * Unlike `Buffer.from()`, throws on invalid input
+ *
+ * @param string - The hex encoded string (case-insensitive)
  * @param format - Output format (default: 'uint8')
  * @returns The decoded bytes
  */
-export function fromHex(str: string, format?: 'uint8'): Uint8ArrayBuffer;
-export function fromHex(str: string, format: 'buffer'): Buffer;
-export function fromHex(str: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
+export function fromHex(string: string, format?: 'uint8'): Uint8ArrayBuffer;
+export function fromHex(string: string, format: 'buffer'): Buffer;
+export function fromHex(string: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;

package/index.d.ts

@@ -40,4 +40,4 @@
  * import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from '@exodus/bytes/encoding-browser.js'
  * ```
  */
-declare module "@exodus/bytes" {}
+declare module '@exodus/bytes' {}

package/multi-byte.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Decode / encode the legacy multi-byte encodings according to the
+ * [Encoding standard](https://encoding.spec.whatwg.org/)
+ * ([§10](https://encoding.spec.whatwg.org/#legacy-multi-byte-chinese-(simplified)-encodings),
+ * [§11](https://encoding.spec.whatwg.org/#legacy-multi-byte-chinese-(traditional)-encodings),
+ * [§12](https://encoding.spec.whatwg.org/#legacy-multi-byte-japanese-encodings),
+ * [§13](https://encoding.spec.whatwg.org/#legacy-multi-byte-korean-encodings)).
+ *
+ * ```js
+ * import { createMultibyteDecoder, createMultibyteEncoder } from '@exodus/bytes/multi-byte.js'
+ * ```
+ *
+ * > [!WARNING]
+ * > This is a lower-level API for legacy multi-byte encodings.
+ * >
+ * > For a safe WHATWG Encoding-compatible API, see `@exodus/bytes/encoding.js` import (and variants of it).
+ * >
+ * > Be sure to know what you are doing and check documentation when directly using encodings from this file.
+ *
+ * Supports all legacy multi-byte encodings listed in the WHATWG Encoding standard:
+ * `gbk`, `gb18030`, `big5`, `euc-jp`, `iso-2022-jp`, `shift_jis`, `euc-kr`.
+ *
+ * @module @exodus/bytes/multi-byte.js
+ */
+
+/// <reference types="node" />
+
+import type { Uint8ArrayBuffer } from './array.js';
+
+/**
+ * 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.
+ *
+ * The returned function will maintain internal state while `stream = true` is used, allowing it to
+ * handle incomplete multi-byte sequences across multiple calls.
+ * State is reset when `stream = false` or when the function is called without the `stream` parameter.
+ *
+ * @param encoding - The encoding name (e.g., 'gbk', 'gb18030', 'big5', 'euc-jp', 'iso-2022-jp', 'shift_jis', 'euc-kr')
+ * @param loose - If true, replaces unmapped bytes with replacement character instead of throwing (default: false)
+ * @returns A function that decodes bytes to string, with optional streaming support
+ */
+export function createMultibyteDecoder(
+  encoding: string,
+  loose?: boolean
+): (arr: Uint8Array, stream?: boolean) => string;
+
+/**
+ * Create an encoder for a supported legacy multi-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.
+ *
+ * @param encoding - The encoding name (e.g., 'gbk', 'gb18030', 'big5', 'euc-jp', 'iso-2022-jp', 'shift_jis', 'euc-kr')
+ * @param options - Encoding options
+ * @param options.mode - Encoding mode (default: 'fatal'). Currently, only 'fatal' mode is supported.
+ * @returns A function that encodes string to bytes
+ */
+export function createMultibyteEncoder(
+  encoding: string,
+  options?: { mode?: 'fatal' }
+): (string: string) => Uint8ArrayBuffer;

package/package.json

@@ -1,16 +1,33 @@
 {
   "name": "@exodus/bytes",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Various operations on Uint8Array data",
+  "keywords": [
+    "encoding",
+    "uint8array",
+    "textdecoder",
+    "textencoder",
+    "utf8",
+    "utf16",
+    "hex",
+    "base64",
+    "base32",
+    "base58",
+    "base58check",
+    "bech32",
+    "bech32m",
+    "wif"
+  ],
   "scripts": {
     "lint": "eslint .",
+    "typedoc": "typedoc && mkdir -p doc/assets && cp -r theme/styles doc/assets/",
     "test:javascriptcore": "npm run test:jsc --",
     "test:v8": "exodus-test --engine=v8: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:xs": "exodus-test --engine=xs:bundle",
+    "test:xs": "EXODUS_TEST_IGNORE='tests/whatwg.browser.test.js' exodus-test --engine=xs:bundle",
     "test:engine262": "exodus-test --engine=engine262:bundle",
     "test:deno": "exodus-test --engine=deno:pure",
     "test:bun": "exodus-test --engine=bun:pure",
@@ -38,7 +55,7 @@
   "bugs": {
     "url": "https://github.com/ExodusOSS/bytes/issues"
   },
-  "homepage": "https://github.com/ExodusOSS/bytes#readme",
+  "homepage": "https://github.com/ExodusOSS/bytes",
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
   },
@@ -54,6 +71,7 @@
     "/fallback/encoding.util.js",
     "/fallback/hex.js",
     "/fallback/latin1.js",
+    "/fallback/percent.js",
     "/fallback/multi-byte.encodings.cjs",
     "/fallback/multi-byte.encodings.json",
     "/fallback/multi-byte.js",
@@ -66,13 +84,18 @@
     "/array.d.ts",
     "/assert.js",
     "/base32.js",
+    "/base32.d.ts",
     "/base58.js",
+    "/base58.d.ts",
     "/base58check.js",
+    "/base58check.d.ts",
     "/base58check.node.js",
     "/base64.js",
     "/base64.d.ts",
     "/bech32.js",
+    "/bech32.d.ts",
     "/bigint.js",
+    "/bigint.d.ts",
     "/encoding-browser.js",
     "/encoding-browser.browser.js",
     "/encoding-browser.native.js",
@@ -87,15 +110,21 @@
     "/index.js",
     "/index.d.ts",
     "/multi-byte.js",
+    "/multi-byte.d.ts",
     "/multi-byte.node.js",
     "/single-byte.js",
+    "/single-byte.d.ts",
     "/single-byte.node.js",
     "/utf16.js",
+    "/utf16.d.ts",
     "/utf16.node.js",
     "/utf8.js",
     "/utf8.d.ts",
     "/utf8.node.js",
-    "/wif.js"
+    "/whatwg.js",
+    "/whatwg.d.ts",
+    "/wif.js",
+    "/wif.d.ts"
   ],
   "main": "index.js",
   "module": "index.js",
@@ -109,9 +138,16 @@
       "types": "./array.d.ts",
       "default": "./array.js"
     },
-    "./base32.js": "./base32.js",
-    "./base58.js": "./base58.js",
+    "./base32.js": {
+      "types": "./base32.d.ts",
+      "default": "./base32.js"
+    },
+    "./base58.js": {
+      "types": "./base58.d.ts",
+      "default": "./base58.js"
+    },
     "./base58check.js": {
+      "types": "./base58check.d.ts",
       "node": "./base58check.node.js",
       "default": "./base58check.js"
     },
@@ -119,18 +155,26 @@
       "types": "./base64.d.ts",
       "default": "./base64.js"
     },
-    "./bech32.js": "./bech32.js",
-    "./bigint.js": "./bigint.js",
+    "./bech32.js": {
+      "types": "./bech32.d.ts",
+      "default": "./bech32.js"
+    },
+    "./bigint.js": {
+      "types": "./bigint.d.ts",
+      "default": "./bigint.js"
+    },
     "./hex.js": {
       "types": "./hex.d.ts",
       "node": "./hex.node.js",
       "default": "./hex.js"
     },
     "./multi-byte.js": {
+      "types": "./multi-byte.d.ts",
       "node": "./multi-byte.node.js",
       "default": "./multi-byte.js"
     },
     "./single-byte.js": {
+      "types": "./single-byte.d.ts",
       "node": "./single-byte.node.js",
       "default": "./single-byte.js"
     },
@@ -150,6 +194,7 @@
       "default": "./encoding-browser.js"
     },
     "./utf16.js": {
+      "types": "./utf16.d.ts",
       "node": "./utf16.node.js",
       "default": "./utf16.js"
     },
@@ -158,7 +203,14 @@
       "node": "./utf8.node.js",
       "default": "./utf8.js"
     },
-    "./wif.js": "./wif.js"
+    "./whatwg.js": {
+      "types": "./whatwg.d.ts",
+      "default": "./whatwg.js"
+    },
+    "./wif.js": {
+      "types": "./wif.d.ts",
+      "default": "./wif.js"
+    }
   },
   "react-native": {
     "./encoding-browser.js": "./encoding-browser.native.js"
@@ -177,6 +229,7 @@
     "@exodus/eslint-config": "^5.24.0",
     "@exodus/prettier": "^1.0.0",
     "@exodus/test": "^1.0.0-rc.109",
+    "@hexagon/base64": "^2.0.4",
     "@noble/hashes": "^2.0.1",
     "@oslojs/encoding": "^1.1.0",
     "@petamoriken/float16": "^3.9.3",
@@ -207,6 +260,7 @@
     "jsvu": "^3.0.3",
     "punycode": "^2.3.1",
     "text-encoding": "^0.7.0",
+    "typedoc": "^0.28.16",
     "typescript": "^5.9.3",
     "uint8array-tools": "^0.0.9",
     "utf8": "^3.0.0",

package/single-byte.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Decode / encode the legacy single-byte encodings according to the
+ * [Encoding standard](https://encoding.spec.whatwg.org/)
+ * ([§9](https://encoding.spec.whatwg.org/#legacy-single-byte-encodings),
+ * [§14.5](https://encoding.spec.whatwg.org/#x-user-defined)),
+ * and [unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859) `iso-8859-*` mappings.
+ *
+ * ```js
+ * import { createSinglebyteDecoder, createSinglebyteEncoder } from '@exodus/bytes/single-byte.js'
+ * import { windows1252toString, windows1252fromString } from '@exodus/bytes/single-byte.js'
+ * import { latin1toString, latin1fromString } from '@exodus/bytes/single-byte.js'
+ * ```
+ *
+ * > [!WARNING]
+ * > This is a lower-level API for single-byte encodings.
+ * > It might not match what you expect, as it supports both WHATWG and unicode.org encodings under
+ * > different names, with the main intended usecase for the latter being either non-web or legacy contexts.
+ * >
+ * > For a safe WHATWG Encoding-compatible API, see `@exodus/bytes/encoding.js` import (and variants of it).
+ * >
+ * > Be sure to know what you are doing and check documentation when directly using encodings from this file.
+ *
+ * Supports all single-byte encodings listed in the WHATWG Encoding standard:
+ * `ibm866`, `iso-8859-2`, `iso-8859-3`, `iso-8859-4`, `iso-8859-5`, `iso-8859-6`, `iso-8859-7`, `iso-8859-8`,
+ * `iso-8859-8-i`, `iso-8859-10`, `iso-8859-13`, `iso-8859-14`, `iso-8859-15`, `iso-8859-16`, `koi8-r`, `koi8-u`,
+ * `macintosh`, `windows-874`, `windows-1250`, `windows-1251`, `windows-1252`, `windows-1253`, `windows-1254`,
+ * `windows-1255`, `windows-1256`, `windows-1257`, `windows-1258`, `x-mac-cyrillic` and `x-user-defined`.
+ *
+ * Also supports `iso-8859-1`, `iso-8859-9`, `iso-8859-11` as defined at
+ * [unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859)
+ * (and all other `iso-8859-*` encodings there as they match WHATWG).
+ *
+ * > [!NOTE]
+ * > While all `iso-8859-*` encodings supported by the [WHATWG Encoding standard](https://encoding.spec.whatwg.org/) match
+ * > [unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859), the WHATWG Encoding spec doesn't support
+ * > `iso-8859-1`, `iso-8859-9`, `iso-8859-11`, and instead maps them as labels to `windows-1252`, `windows-1254`, `windows-874`.\
+ * > `createSinglebyteDecoder()` (unlike `TextDecoder` or `legacyHookDecode()`) does not do such mapping,
+ * > so its results will differ from `TextDecoder` for those encoding names.
+ *
+ * ```js
+ * > new TextDecoder('iso-8859-1').encoding
+ * 'windows-1252'
+ * > new TextDecoder('iso-8859-9').encoding
+ * 'windows-1254'
+ * > new TextDecoder('iso-8859-11').encoding
+ * 'windows-874'
+ * > new TextDecoder('iso-8859-9').decode(Uint8Array.of(0x80, 0x81, 0xd0))
+ * '€\x81Ğ' // this is actually decoded according to windows-1254 per TextDecoder spec
+ * > createSinglebyteDecoder('iso-8859-9')(Uint8Array.of(0x80, 0x81, 0xd0))
+ * '\x80\x81Ğ' // this is iso-8859-9 as defined at https://unicode.org/Public/MAPPINGS/ISO8859/8859-9.txt
+ * ```
+ *
+ * All WHATWG Encoding spec [`windows-*` encodings](https://encoding.spec.whatwg.org/#windows-874) are supersets of
+ * corresponding [unicode.org encodings](https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/), meaning that
+ * they encode/decode all the old valid (non-replacement) strings / byte sequences identically, but can also support
+ * a wider range of inputs.
+ *
+ * @module @exodus/bytes/single-byte.js
+ */
+
+/// <reference types="node" />
+
+import type { Uint8ArrayBuffer } from './array.js';
+
+/**
+ * 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.
+ *
+ * @param encoding - The encoding name (e.g., 'iso-8859-1', 'windows-1252')
+ * @param loose - If true, replaces unmapped bytes with replacement character instead of throwing (default: false)
+ * @returns A function that decodes bytes to string
+ */
+export function createSinglebyteDecoder(
+  encoding: string,
+  loose?: boolean
+): (arr: Uint8Array) => string;
+
+/**
+ * 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.
+ *
+ * @param encoding - The encoding name (e.g., 'iso-8859-1', 'windows-1252')
+ * @param options - Encoding options
+ * @param options.mode - Encoding mode (default: 'fatal'). Currently, only 'fatal' mode is supported.
+ * @returns A function that encodes string to bytes
+ */
+export function createSinglebyteEncoder(
+  encoding: string,
+  options?: { mode?: 'fatal' }
+): (string: string) => Uint8ArrayBuffer;
+
+/**
+ * Decode `iso-8859-1` bytes to a string.
+ *
+ * There is no loose variant for this encoding, all bytes can be decoded.
+ *
+ * Same as:
+ * ```js
+ * const latin1toString = createSinglebyteDecoder('iso-8859-1')
+ * ```
+ *
+ * > [!NOTE]
+ * > This is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as those
+ * > alias to `new TextDecoder('windows-1252')`.
+ *
+ * @param arr - The bytes to decode
+ * @returns The decoded string
+ */
+export function latin1toString(arr: Uint8Array): string;
+
+/**
+ * Encode a string to `iso-8859-1` bytes.
+ *
+ * Throws on non well-formed strings or any codepoints which could not be encoded in `iso-8859-1`.
+ *
+ * Same as:
+ * ```js
+ * const latin1fromString = createSinglebyteEncoder('iso-8859-1', { mode: 'fatal' })
+ * ```
+ *
+ * @param string - The string to encode
+ * @returns The encoded bytes
+ */
+export function latin1fromString(string: string): Uint8ArrayBuffer;
+
+/**
+ * Decode `windows-1252` bytes to a string.
+ *
+ * There is no loose variant for this encoding, all bytes can be decoded.
+ *
+ * Same as:
+ * ```js
+ * const windows1252toString = createSinglebyteDecoder('windows-1252')
+ * ```
+ *
+ * @param arr - The bytes to decode
+ * @returns The decoded string
+ */
+export function windows1252toString(arr: Uint8Array): string;
+
+/**
+ * Encode a string to `windows-1252` bytes.
+ *
+ * Throws 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' })
+ * ```
+ *
+ * @param string - The string to encode
+ * @returns The encoded bytes
+ */
+export function windows1252fromString(string: string): Uint8ArrayBuffer;

package/utf16.d.ts

@@ -0,0 +1,92 @@
+/**
+ * UTF-16 encoding/decoding
+ *
+ * ```js
+ * import { utf16fromString, utf16toString } from '@exodus/bytes/utf16.js'
+ *
+ * // loose
+ * import { utf16fromStringLoose, utf16toStringLoose } from '@exodus/bytes/utf16.js'
+ * ```
+ *
+ * _These methods by design encode/decode BOM (codepoint `U+FEFF` Byte Order Mark) as-is._\
+ * _If you need BOM handling or detection, use `@exodus/bytes/encoding.js`_
+ *
+ * @module @exodus/bytes/utf16.js
+ */
+
+/// <reference types="node" />
+
+import type { Uint8ArrayBuffer, Uint16ArrayBuffer } from './array.js';
+
+/**
+ * Output format for UTF-16 encoding
+ */
+export type Utf16Format = 'uint16' | 'uint8-le' | 'uint8-be';
+
+/**
+ * Encode a string to UTF-16 bytes (strict mode)
+ *
+ * Throws on invalid Unicode (unpaired surrogates)
+ *
+ * @param string - The string to encode
+ * @param format - Output format (default: 'uint16')
+ * @returns The encoded bytes
+ */
+export function utf16fromString(string: string, format?: 'uint16'): Uint16ArrayBuffer;
+export function utf16fromString(string: string, format: 'uint8-le'): Uint8ArrayBuffer;
+export function utf16fromString(string: string, format: 'uint8-be'): Uint8ArrayBuffer;
+export function utf16fromString(string: string, format?: Utf16Format): Uint16ArrayBuffer | Uint8ArrayBuffer;
+
+/**
+ * Encode a string to UTF-16 bytes (loose mode)
+ *
+ * Replaces invalid Unicode (unpaired surrogates) with replacement codepoints `U+FFFD`
+ * per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
+ *
+ * _Such replacement is a non-injective function, is irreversible and causes collisions.\
+ * Prefer using strict throwing methods for cryptography applications._
+ *
+ * @param string - The string to encode
+ * @param format - Output format (default: 'uint16')
+ * @returns The encoded bytes
+ */
+export function utf16fromStringLoose(string: string, format?: 'uint16'): Uint16ArrayBuffer;
+export function utf16fromStringLoose(string: string, format: 'uint8-le'): Uint8ArrayBuffer;
+export function utf16fromStringLoose(string: string, format: 'uint8-be'): Uint8ArrayBuffer;
+export function utf16fromStringLoose(string: string, format?: Utf16Format): Uint16ArrayBuffer | Uint8ArrayBuffer;
+
+/**
+ * Decode UTF-16 bytes to a string (strict mode)
+ *
+ * Throws on invalid UTF-16 byte sequences
+ *
+ * Throws on non-even byte length.
+ *
+ * @param arr - The bytes to decode
+ * @param format - Input format (default: 'uint16')
+ * @returns The decoded string
+ */
+export function utf16toString(arr: Uint16Array, format?: 'uint16'): string;
+export function utf16toString(arr: Uint8Array, format: 'uint8-le'): string;
+export function utf16toString(arr: Uint8Array, format: 'uint8-be'): string;
+export function utf16toString(arr: Uint16Array | Uint8Array, format?: Utf16Format): string;
+
+/**
+ * Decode UTF-16 bytes to a string (loose mode)
+ *
+ * Replaces invalid UTF-16 byte sequences with replacement codepoints `U+FFFD`
+ * per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
+ *
+ * _Such replacement is a non-injective function, is irreversible and causes collisions.\
+ * Prefer using strict throwing methods for cryptography applications._
+ *
+ * Throws on non-even byte length.
+ *
+ * @param arr - The bytes to decode
+ * @param format - Input format (default: 'uint16')
+ * @returns The decoded string
+ */
+export function utf16toStringLoose(arr: Uint16Array, format?: 'uint16'): string;
+export function utf16toStringLoose(arr: Uint8Array, format: 'uint8-le'): string;
+export function utf16toStringLoose(arr: Uint8Array, format: 'uint8-be'): string;
+export function utf16toStringLoose(arr: Uint16Array | Uint8Array, format?: Utf16Format): string;

package/utf16.js

@@ -8,7 +8,7 @@ const decoderLooseLE = canDecoders ? new TextDecoder('utf-16le', { ignoreBOM })
 const decoderFatalBE = canDecoders ? new TextDecoder('utf-16be', { ignoreBOM, fatal: true }) : null
 const decoderLooseBE = canDecoders ? new TextDecoder('utf-16be', { ignoreBOM }) : null
 const decoderFatal16 = isLE ? decoderFatalLE : decoderFatalBE
-const decoderLoose16 = isLE ? decoderLooseLE : decoderFatalBE
+const decoderLoose16 = isLE ? decoderLooseLE : decoderLooseBE
 const { isWellFormed, toWellFormed } = String.prototype
 
 const { E_STRICT, E_STRICT_UNICODE } = js

package/utf8.d.ts

@@ -1,42 +1,96 @@
+/**
+ * UTF-8 encoding/decoding
+ *
+ * ```js
+ * import { utf8fromString, utf8toString } from '@exodus/bytes/utf8.js'
+ *
+ * // loose
+ * import { utf8fromStringLoose, utf8toStringLoose } from '@exodus/bytes/utf8.js'
+ * ```
+ *
+ * _These methods by design encode/decode BOM (codepoint `U+FEFF` Byte Order Mark) as-is._\
+ * _If you need BOM handling or detection, use `@exodus/bytes/encoding.js`_
+ *
+ * @module @exodus/bytes/utf8.js
+ */
+
 /// <reference types="node" />
 
 import type { OutputFormat, Uint8ArrayBuffer } from './array.js';
 
 /**
- * Encodes a string to UTF-8 bytes (strict mode)
+ * Encode a string to UTF-8 bytes (strict mode)
+ *
  * Throws on invalid Unicode (unpaired surrogates)
- * @param str - The string to encode
+ *
+ * This is similar to the following snippet (but works on all engines):
+ * ```js
+ * // Strict encode, requiring Unicode codepoints to be valid
+ * if (typeof string !== 'string' || !string.isWellFormed()) throw new TypeError()
+ * return new TextEncoder().encode(string)
+ * ```
+ *
+ * @param string - The string to encode
  * @param format - Output format (default: 'uint8')
  * @returns The encoded bytes
  */
-export function utf8fromString(str: string, format?: 'uint8'): Uint8ArrayBuffer;
-export function utf8fromString(str: string, format: 'buffer'): Buffer;
-export function utf8fromString(str: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
+export function utf8fromString(string: string, format?: 'uint8'): Uint8ArrayBuffer;
+export function utf8fromString(string: string, format: 'buffer'): Buffer;
+export function utf8fromString(string: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
 
 /**
- * Encodes a string to UTF-8 bytes (loose mode)
- * Replaces invalid Unicode with replacement character
- * @param str - The string to encode
+ * Encode a string to UTF-8 bytes (loose mode)
+ *
+ * Replaces invalid Unicode (unpaired surrogates) with replacement codepoints `U+FFFD`
+ * per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
+ *
+ * _Such replacement is a non-injective function, is irreversable and causes collisions.\
+ * Prefer using strict throwing methods for cryptography applications._
+ *
+ * This is similar to the following snippet (but works on all engines):
+ * ```js
+ * // Loose encode, replacing invalid Unicode codepoints with U+FFFD
+ * if (typeof string !== 'string') throw new TypeError()
+ * return new TextEncoder().encode(string)
+ * ```
+ *
+ * @param string - The string to encode
  * @param format - Output format (default: 'uint8')
  * @returns The encoded bytes
  */
-export function utf8fromStringLoose(str: string, format?: 'uint8'): Uint8ArrayBuffer;
-export function utf8fromStringLoose(str: string, format: 'buffer'): Buffer;
-export function utf8fromStringLoose(str: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
+export function utf8fromStringLoose(string: string, format?: 'uint8'): Uint8ArrayBuffer;
+export function utf8fromStringLoose(string: string, format: 'buffer'): Buffer;
+export function utf8fromStringLoose(
+  string: string,
+  format?: OutputFormat
+): Uint8ArrayBuffer | Buffer;
 
 /**
- * Decodes UTF-8 bytes to a string (strict mode)
- * Throws on invalid UTF-8 sequences
+ * Decode UTF-8 bytes to a string (strict mode)
+ *
+ * Throws on invalid UTF-8 byte sequences
+ *
+ * This is similar to `new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(arr)`,
+ * but works on all engines.
+ *
  * @param arr - The bytes to decode
  * @returns The decoded string
  */
-export function utf8toString(arr: Uint8ArrayBuffer): string;
+export function utf8toString(arr: Uint8Array): string;
 
 /**
- * Decodes UTF-8 bytes to a string (loose mode)
- * Replaces invalid sequences with replacement character
+ * Decode UTF-8 bytes to a string (loose mode)
+ *
+ * Replaces invalid UTF-8 byte sequences with replacement codepoints `U+FFFD`
+ * per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
+ *
+ * _Such replacement is a non-injective function, is irreversable and causes collisions.\
+ * Prefer using strict throwing methods for cryptography applications._
+ *
+ * This is similar to `new TextDecoder('utf-8', { ignoreBOM: true }).decode(arr)`,
+ * but works on all engines.
+ *
  * @param arr - The bytes to decode
  * @returns The decoded string
  */
-export function utf8toStringLoose(arr: Uint8ArrayBuffer): string;
-
+export function utf8toStringLoose(arr: Uint8Array): string;