diff options
Diffstat (limited to 'vanilla/node_modules/@exodus/bytes/README.md')
| -rw-r--r-- | vanilla/node_modules/@exodus/bytes/README.md | 925 |
1 files changed, 0 insertions, 925 deletions
diff --git a/vanilla/node_modules/@exodus/bytes/README.md b/vanilla/node_modules/@exodus/bytes/README.md deleted file mode 100644 index d14b0ae..0000000 --- a/vanilla/node_modules/@exodus/bytes/README.md +++ /dev/null @@ -1,925 +0,0 @@ -# @exodus/bytes - -[](https://npmjs.org/package/@exodus/bytes) -[](https://github.com/ExodusOSS/bytes/releases) -[](https://www.npmcharts.com/compare/@exodus/bytes?minimal=true) -[](https://github.com/ExodusOSS/bytes/blob/HEAD/LICENSE) -[](https://github.com/ExodusOSS/bytes/actions/workflows/test.yml?query=branch%3Amain) - -`Uint8Array` conversion to and from `base64`, `base32`, `base58`, `hex`, `utf8`, `utf16`, `bech32` and `wif` - -And a [`TextEncoder` / `TextDecoder` polyfill](#textencoder--textdecoder-polyfill) - -See [documentation](https://exodusoss.github.io/bytes/). - -## Strict - -Performs proper input validation, ensures no garbage-in-garbage-out - -Tested in CI with [@exodus/test](https://github.com/ExodusMovement/test#exodustest) on: - -[](https://nodejs.org/api/test.html) -[](https://deno.com/) -[](https://bun.sh/) -[](http://electronjs.org/) -[](https://github.com/cloudflare/workerd)\ -[](https://www.chromium.org/Home/) -[](http://webkit.org/) -[](https://github.com/mozilla-firefox) -[](https://servo.org/)\ -[](https://hermesengine.dev) -[](https://v8.dev/docs/d8) -[](https://docs.webkit.org/Deep%20Dive/JSC/JavaScriptCore.html) -[](https://spidermonkey.dev/)\ -[](https://github.com/quickjs-ng/quickjs) -[](https://github.com/Moddable-OpenSource/moddable) -[](https://github.com/oracle/graaljs) - -## Fast - -* `10-20x` faster than `Buffer` polyfill -* `2-10x` faster than `iconv-lite` - -The above was for the js fallback - -It's up to `100x` when native impl is available \ -e.g. in `utf8fromString` on Hermes / React Native or `fromHex` in Chrome - -Also: -* `3-8x` faster than `bs58` -* `10-30x` faster than `@scure/base` (or `>100x` on Node.js <25) -* Faster in `utf8toString` / `utf8fromString` than `Buffer` or `TextDecoder` / `TextEncoder` on Node.js - -See [Performance](./Performance.md) for more info - -## TextEncoder / TextDecoder polyfill - -```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).\ -Also [much faster](#fast) than all of those. - -> [!TIP] -> See also the [lite version](#lite-version) to get this down to 10 KiB gzipped. - -Spec compliant, passing WPT and covered with extra tests.\ -Moreover, tests for this library uncovered [bugs in all major implementations](https://docs.google.com/spreadsheets/d/1pdEefRG6r9fZy61WHGz0TKSt8cO4ISWqlpBN5KntIvQ/edit).\ -Including all three major browser engines being wrong at UTF-8.\ -See [WPT pull request](https://github.com/web-platform-tests/wpt/pull/56892). - -It works correctly even in environments that have native implementations broken (that's all of them currently).\ -Runs (and passes WPT) on Node.js built without ICU. - -> [!NOTE] -> [Faster than Node.js native implementation on Node.js](https://github.com/nodejs/node/issues/61041#issuecomment-3649242024). -> -> The JS multi-byte version is as fast as native impl in Node.js and browsers, but (unlike them) returns correct results. -> -> For encodings where native version is known to be fast and correct, it is automatically used.\ -> Some single-byte encodings are faster than native in all three major browser engines. - -See [analysis table](https://docs.google.com/spreadsheets/d/1pdEefRG6r9fZy61WHGz0TKSt8cO4ISWqlpBN5KntIvQ/edit) for more info. - -### Caveat: `TextDecoder` / `TextEncoder` APIs are lossy by default per spec - -_These are only provided as a compatibility layer, prefer hardened APIs instead in new code._ - - * `TextDecoder` can (and should) be used with `{ fatal: true }` option for all purposes demanding correctness / lossless transforms - - * `TextEncoder` does not support a fatal mode per spec, it always performs replacement. - - That is not suitable for hashing, cryptography or consensus applications.\ - Otherwise there would be non-equal strings with equal signatures and hashes — the collision is caused by the lossy transform of a JS string to bytes. - Those also survive e.g. `JSON.stringify`/`JSON.parse` or being sent over network. - - Use strict APIs in new applications, see `utf8fromString` / `utf16fromString` below.\ - Those throw on non-well-formed strings by default. - -### Lite version - -Alternate exports exist that can help reduce bundle size, see comparison: - -| import | size | -| - | - | -| [@exodus/bytes/encoding-browser.js](#exodusbytesencoding-browserjs-) | <sub></sub> | -| [@exodus/bytes/encoding-lite.js](#exodusbytesencoding-litejs-) | <sub></sub> | -| [@exodus/bytes/encoding.js](#exodusbytesencodingjs-) | <sub></sub> | -| `text-encoding` | <sub></sub> | -| `iconv-lite` | <sub></sub> | -| `whatwg-encoding` | <sub></sub> | - -Libraries are advised to use single-purpose hardened `@exodus/bytes/utf8.js` / `@exodus/bytes/utf16.js` APIs for Unicode. - -Applications (including React Native apps) are advised to load either `@exodus/bytes/encoding-lite.js` or `@exodus/bytes/encoding.js` -(depending on whether legacy multi-byte support is needed) and use that as a global polyfill. - -#### `@exodus/bytes/encoding-lite.js` - -If you don't need support for legacy multi-byte encodings. - -Reduces the bundle size ~12x, while still keeping `utf-8`, `utf-16le`, `utf-16be` and all single-byte encodings specified by the spec. -The only difference is support for legacy multi-byte encodings. - -See [the list of encodings](https://encoding.spec.whatwg.org/#names-and-labels). - -This can be useful for example in React Native global TextDecoder polyfill, -if you are sure that you don't need legacy multi-byte encodings support. - -#### `@exodus/bytes/encoding-browser.js` - -Resolves to a tiny import in browser bundles, preferring native `TextDecoder` / `TextEncoder`. - -For non-browsers (Node.js, React Native), loads a full implementation. - -> [!NOTE] -> This is not the default behavior for `@exodus/bytes/encoding.js` because all major browser implementations have bugs, -> which `@exodus/bytes/encoding.js` fixes. Only use if you are ok with that. - -## API - -### @exodus/bytes/utf8.js <sub><sub> - -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`_ - -#### `utf8fromString(string, format = 'uint8')` - -Encode a string to UTF-8 bytes (strict mode) - -Throws on invalid Unicode (unpaired surrogates) - -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) -``` - -#### `utf8fromStringLoose(string, format = 'uint8')` - -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) -``` - -#### `utf8toString(arr)` - -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. - -#### `utf8toStringLoose(arr)` - -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. - -### @exodus/bytes/utf16.js <sub><sub> - -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`_ - -#### `utf16fromString(string, format = 'uint16')` - -Encode a string to UTF-16 bytes (strict mode) - -Throws on invalid Unicode (unpaired surrogates) - -#### `utf16fromStringLoose(string, format = 'uint16')` - -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._ - -#### `utf16toString(arr, format = 'uint16')` - -Decode UTF-16 bytes to a string (strict mode) - -Throws on invalid UTF-16 byte sequences - -Throws on non-even byte length. - -#### `utf16toStringLoose(arr, format = 'uint16')` - -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. - -### @exodus/bytes/single-byte.js <sub></sub> - -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. - -#### `createSinglebyteDecoder(encoding, loose = false)` - -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. - -#### `latin1toString(arr)` - -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')`. - -#### `latin1fromString(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' }) -``` - -#### `windows1252toString(arr)` - -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') -``` - -#### `windows1252fromString(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' }) -``` - -### @exodus/bytes/multi-byte.js <sub></sub> - -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`. - -#### `createMultibyteDecoder(encoding, loose = false)` - -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. - -#### `createMultibyteEncoder(encoding, { mode = 'fatal' })` - -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. - -### @exodus/bytes/bigint.js <sub></sub> - -Convert between BigInt and Uint8Array - -```js -import { fromBigInt, toBigInt } from '@exodus/bytes/bigint.js' -``` - -#### `fromBigInt(bigint, { length, format = 'uint8' })` - -Convert a BigInt to a Uint8Array or Buffer - -The output bytes are in big-endian format. - -Throws if the BigInt is negative or cannot fit into the specified length. - -#### `toBigInt(arr)` - -Convert a Uint8Array or Buffer to a BigInt - -The bytes are interpreted as a big-endian unsigned integer. - -### @exodus/bytes/hex.js <sub></sub> - -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' -``` - -#### `fromHex(string, format = 'uint8')` - -Decode a hex string to bytes - -Unlike `Buffer.from()`, throws on invalid input - -#### `toHex(arr)` - -Encode a `Uint8Array` to a lowercase hex string - -### @exodus/bytes/base64.js <sub></sub> - -Implements base64 and base64url from [RFC4648](https://datatracker.ietf.org/doc/html/rfc4648) -(no differences from [RFC3548](https://datatracker.ietf.org/doc/html/rfc4648)). - -```js -import { fromBase64, toBase64 } from '@exodus/bytes/base64.js' -import { fromBase64url, toBase64url } from '@exodus/bytes/base64.js' -import { fromBase64any } from '@exodus/bytes/base64.js' -``` - -#### `fromBase64(string, { format = 'uint8', padding = 'both' })` - -Decode a base64 string to bytes - -Operates in strict mode for last chunk, does not allow whitespace - -#### `fromBase64url(string, { format = 'uint8', padding = false })` - -Decode a base64url string to bytes - -Operates in strict mode for last chunk, does not allow whitespace - -#### `fromBase64any(string, { format = 'uint8', padding = 'both' })` - -Decode either base64 or base64url string to bytes - -Automatically detects the variant based on characters present - -#### `toBase64(arr, { padding = true })` - -Encode a `Uint8Array` to a base64 string (RFC 4648) - -#### `toBase64url(arr, { padding = false })` - -Encode a `Uint8Array` to a base64url string (RFC 4648) - -### @exodus/bytes/base32.js <sub></sub> - -Implements base32 and base32hex from [RFC4648](https://datatracker.ietf.org/doc/html/rfc4648) -(no differences from [RFC3548](https://datatracker.ietf.org/doc/html/rfc4648)). - -```js -import { fromBase32, toBase32 } from '@exodus/bytes/base32.js' -import { fromBase32hex, toBase32hex } from '@exodus/bytes/base32.js' -``` - -#### `fromBase32(string, { format = 'uint8', padding = 'both' })` - -Decode a base32 string to bytes - -Operates in strict mode for last chunk, does not allow whitespace - -#### `fromBase32hex(string, { format = 'uint8', padding = 'both' })` - -Decode a base32hex string to bytes - -Operates in strict mode for last chunk, does not allow whitespace - -#### `toBase32(arr, { padding = false })` - -Encode a `Uint8Array` to a base32 string (RFC 4648) - -#### `toBase32hex(arr, { padding = false })` - -Encode a `Uint8Array` to a base32hex string (RFC 4648) - -### @exodus/bytes/bech32.js <sub></sub> - -Implements bech32 and bech32m from -[BIP-0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#specification) -and [BIP-0350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki#specification). - -```js -import { fromBech32, toBech32 } from '@exodus/bytes/bech32.js' -import { fromBech32m, toBech32m } from '@exodus/bytes/bech32.js' -import { getPrefix } from '@exodus/bytes/bech32.js' -``` - -#### `getPrefix(string, limit = 90)` - -Extract the prefix from a bech32 or bech32m string without full validation - -This is a quick check that skips most validation. - -#### `fromBech32(string, limit = 90)` - -Decode a bech32 string to bytes - -#### `toBech32(prefix, bytes, limit = 90)` - -Encode bytes to a bech32 string - -#### `fromBech32m(string, limit = 90)` - -Decode a bech32m string to bytes - -#### `toBech32m(prefix, bytes, limit = 90)` - -Encode bytes to a bech32m string - -### @exodus/bytes/base58.js <sub></sub> - -Implements [base58](https://www.ietf.org/archive/id/draft-msporny-base58-03.txt) encoding. - -Supports both standard base58 and XRP variant alphabets. - -```js -import { fromBase58, toBase58 } from '@exodus/bytes/base58.js' -import { fromBase58xrp, toBase58xrp } from '@exodus/bytes/base58.js' -``` - -#### `fromBase58(string, format = 'uint8')` - -Decode a base58 string to bytes - -Uses the standard Bitcoin base58 alphabet - -#### `toBase58(arr)` - -Encode a `Uint8Array` to a base58 string - -Uses the standard Bitcoin base58 alphabet - -#### `fromBase58xrp(string, format = 'uint8')` - -Decode a base58 string to bytes using XRP alphabet - -Uses the XRP variant base58 alphabet - -#### `toBase58xrp(arr)` - -Encode a `Uint8Array` to a base58 string using XRP alphabet - -Uses the XRP variant base58 alphabet - -### @exodus/bytes/base58check.js <sub></sub> - -Implements [base58check](https://en.bitcoin.it/wiki/Base58Check_encoding) encoding. - -```js -import { fromBase58check, toBase58check } from '@exodus/bytes/base58check.js' -import { fromBase58checkSync, toBase58checkSync } from '@exodus/bytes/base58check.js' -import { makeBase58check } from '@exodus/bytes/base58check.js' -``` - -On non-Node.js, requires peer dependency [@noble/hashes](https://www.npmjs.com/package/@noble/hashes) to be installed. - -#### `async fromBase58check(string, format = 'uint8')` - -Decode a base58check string to bytes asynchronously - -Validates the checksum using double SHA-256 - -#### `async toBase58check(arr)` - -Encode bytes to base58check string asynchronously - -Uses double SHA-256 for checksum calculation - -#### `fromBase58checkSync(string, format = 'uint8')` - -Decode a base58check string to bytes synchronously - -Validates the checksum using double SHA-256 - -#### `toBase58checkSync(arr)` - -Encode bytes to base58check string synchronously - -Uses double SHA-256 for checksum calculation - -#### `makeBase58check(hashAlgo, hashAlgoSync)` - -Create a base58check encoder/decoder with custom hash functions - -### @exodus/bytes/wif.js <sub></sub> - -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. - -#### `async fromWifString(string[, version])` - -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. - -#### `fromWifStringSync(string[, version])` - -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. - -#### `async toWifString({ version, privateKey, compressed })` - -Encode WIF data to a WIF string - -#### `toWifStringSync({ version, privateKey, compressed })` - -Encode WIF data to a WIF string (synchronous) - -### @exodus/bytes/array.js <sub></sub> - -TypedArray utils and conversions. - -```js -import { typedView } from '@exodus/bytes/array.js' -``` - -#### `typedView(arr, format = 'uint8')` - -Create a view of a TypedArray in the specified format (`'uint8'` or `'buffer'`) - -> [!IMPORTANT] -> Does not copy data, returns a view on the same underlying buffer - -### @exodus/bytes/encoding.js <sub></sub> - -Implements the [Encoding standard](https://encoding.spec.whatwg.org/): -[TextDecoder](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). - -```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' -``` - -#### `new TextDecoder(label = 'utf-8', { fatal = false, ignoreBOM = false })` - -[TextDecoder](https://encoding.spec.whatwg.org/#interface-textdecoder) implementation/polyfill. - -Decode bytes to strings according to [WHATWG Encoding](https://encoding.spec.whatwg.org) specification. - -#### `new TextEncoder()` - -[TextEncoder](https://encoding.spec.whatwg.org/#interface-textencoder) implementation/polyfill. - -Encode strings to UTF-8 bytes according to [WHATWG Encoding](https://encoding.spec.whatwg.org) specification. - -#### `new TextDecoderStream(label = 'utf-8', { fatal = false, ignoreBOM = false })` - -[TextDecoderStream](https://encoding.spec.whatwg.org/#interface-textdecoderstream) implementation/polyfill. - -A [Streams](https://streams.spec.whatwg.org/) wrapper for `TextDecoder`. - -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. - -A [Streams](https://streams.spec.whatwg.org/) wrapper for `TextEncoder`. - -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)` - -Implements [get an encoding from a string `label`](https://encoding.spec.whatwg.org/#concept-encoding-get). - -Convert an encoding [label](https://encoding.spec.whatwg.org/#names-and-labels) to its name, -as a case-sensitive string. - -If an encoding with that label does not exist, returns `null`. - -All encoding names are also valid labels for corresponding encodings. - -#### `normalizeEncoding(label)` - -Convert an encoding [label](https://encoding.spec.whatwg.org/#names-and-labels) to its name, -as an ASCII-lowercased string. - -If an encoding with that label does not exist, returns `null`. - -This is the same as [`decoder.encoding` getter](https://encoding.spec.whatwg.org/#dom-textdecoder-encoding), -except that it: - 1. Supports [`replacement` encoding](https://encoding.spec.whatwg.org/#replacement) and its - [labels](https://encoding.spec.whatwg.org/#ref-for-replacement%E2%91%A1) - 2. Does not throw for invalid labels and instead returns `null` - -It is identical to: -```js -labelToName(label)?.toLowerCase() ?? null -``` - -All encoding names are also valid labels for corresponding encodings. - -#### `getBOMEncoding(input)` - -Implements [BOM sniff](https://encoding.spec.whatwg.org/#bom-sniff) legacy hook. - -Given a `TypedArray` or an `ArrayBuffer` instance `input`, returns either of: -- `'utf-8'`, if `input` starts with UTF-8 byte order mark. -- `'utf-16le'`, if `input` starts with UTF-16LE byte order mark. -- `'utf-16be'`, if `input` starts with UTF-16BE byte order mark. -- `null` otherwise. - -#### `legacyHookDecode(input, fallbackEncoding = 'utf-8')` - -Implements [decode](https://encoding.spec.whatwg.org/#decode) legacy hook. - -Given a `TypedArray` or an `ArrayBuffer` instance `input` and an optional `fallbackEncoding` -encoding [label](https://encoding.spec.whatwg.org/#names-and-labels), -sniffs encoding from BOM with `fallbackEncoding` fallback and then -decodes the `input` using that encoding, skipping BOM if it was present. - -Notes: - -- BOM-sniffed encoding takes precedence over `fallbackEncoding` option per spec. - Use with care. -- Always operates in non-fatal [mode](https://encoding.spec.whatwg.org/#textdecoder-error-mode), - aka replacement. It can convert different byte sequences to equal strings. - -This method is similar to the following code, except that it doesn't support encoding labels and -only expects lowercased encoding name: - -```js -new TextDecoder(getBOMEncoding(input) ?? fallbackEncoding).decode(input) -``` - -### @exodus/bytes/encoding-lite.js <sub></sub> - -The exact same exports as `@exodus/bytes/encoding.js` are also exported as -`@exodus/bytes/encoding-lite.js`, with the difference that the lite version does not load -multi-byte `TextDecoder` encodings by default to reduce bundle size ~12x. - -```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' -``` - -The only affected encodings are: `gbk`, `gb18030`, `big5`, `euc-jp`, `iso-2022-jp`, `shift_jis` -and their [labels](https://encoding.spec.whatwg.org/#names-and-labels) when used with `TextDecoder`. - -Legacy single-byte encodingds are loaded by default in both cases. - -`TextEncoder` and hooks for standards (including `labelToName` / `normalizeEncoding`) do not have any behavior -differences in the lite version and support full range if inputs. - -To avoid inconsistencies, the exported classes and methods are exactly the same objects. - -```console -> 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], - normalizeEncoding: [Function: normalizeEncoding] -} -> new lite.TextDecoder('big5').decode(Uint8Array.of(0x25)) -Uncaught: -Error: Legacy multi-byte encodings are disabled in /encoding-lite.js, use /encoding.js for full encodings range support - -> 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], - normalizeEncoding: [Function: normalizeEncoding] -} -> full.TextDecoder === lite.TextDecoder -true -> new full.TextDecoder('big5').decode(Uint8Array.of(0x25)) -'%' -> new lite.TextDecoder('big5').decode(Uint8Array.of(0x25)) -'%' -``` - -### @exodus/bytes/encoding-browser.js <sub><sub> - -Same as `@exodus/bytes/encoding.js`, but in browsers instead of polyfilling just uses whatever the -browser provides, drastically reducing the bundle size (to less than 2 KiB gzipped). - -```js -import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-browser.js' -import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-browser.js' // Requires Streams - -// Hooks for standards -import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from '@exodus/bytes/encoding-browser.js' -``` - -Under non-browser engines (Node.js, React Native, etc.) a full polyfill is used as those platforms -do not provide sufficiently complete / non-buggy `TextDecoder` APIs. - -> [!NOTE] -> Implementations in browsers [have bugs](https://docs.google.com/spreadsheets/d/1pdEefRG6r9fZy61WHGz0TKSt8cO4ISWqlpBN5KntIvQ/edit), -> but they are fixing them and the expected update window is short.\ -> If you want to circumvent browser bugs, use full `@exodus/bytes/encoding.js` import. - -### @exodus/bytes/whatwg.js <sub></sub> - -WHATWG helpers - -```js -import '@exodus/bytes/encoding.js' // For full legacy multi-byte encodings support -import { percentEncodeAfterEncoding } from '@exodus/bytes/whatwg.js' -``` - -#### `percentEncodeAfterEncoding(encoding, input, percentEncodeSet, spaceAsPlus = false)` - -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 -``` - -## Changelog - -See [GitHub Releases](https://github.com/ExodusOSS/bytes/releases) tab - -## License - -[MIT](./LICENSE) |