feat: isomorphic encode/decode

Author: ChALkeR

README.md

@@ -344,6 +344,9 @@ const latin1toString = createSinglebyteDecoder('iso-8859-1')
 > This is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as those
 > alias to `new TextDecoder('windows-1252')`.
 
+Prefer using `isomorphicDecode()` from `@exodus/bytes/encoding.js` or `@exodus/bytes/encoding-lite.js`,
+which is identical to this but allows more input types.
+
 #### `latin1fromString(string)`
 
 Encode a string to `iso-8859-1` bytes.
@@ -355,6 +358,8 @@ Same as:
 const latin1fromString = createSinglebyteEncoder('iso-8859-1', { mode: 'fatal' })
 ```
 
+Prefer using `isomorphicEncode()` from `@exodus/bytes/encoding.js` or `@exodus/bytes/encoding-lite.js`.
+
 #### `windows1252toString(arr)`
 
 Decode `windows-1252` bytes to a string.
@@ -714,6 +719,7 @@ 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
+import { isomorphicDecode, isomorphicEncode } from '@exodus/bytes/encoding.js'
 
 // Hooks for standards
 import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from '@exodus/bytes/encoding.js'
@@ -749,6 +755,26 @@ 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).
 
+#### `isomorphicDecode(input)`
+
+Implements [isomorphic decode](https://infra.spec.whatwg.org/#isomorphic-decode).
+
+Given a `TypedArray` or an `ArrayBuffer` instance `input`, creates a string of the same length
+as input byteLength, using bytes from input as codepoints.
+
+E.g. for `Uint8Array` input, this is similar to `String.fromCodePoint(...input)`.
+
+Wider `TypedArray` inputs, e.g. `Uint16Array`, are interpreted as underlying _bytes_.
+
+#### `isomorphicEncode(str)`
+
+Implements [isomorphic encode](https://infra.spec.whatwg.org/#isomorphic-encode).
+
+Given a string, creates an `Uint8Array` of the same length with the string codepoints as byte values.
+
+Accepts only [isomorphic string](https://infra.spec.whatwg.org/#isomorphic-string) input
+and asserts that, throwing on any strings containing codepoints higher than `U+00FF`.
+
 #### `labelToName(label)`
 
 Implements [get an encoding from a string `label`](https://encoding.spec.whatwg.org/#concept-encoding-get).
@@ -822,6 +848,7 @@ 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
+import { isomorphicDecode, isomorphicEncode } from '@exodus/bytes/encoding-lite.js'
 
 // Hooks for standards
 import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from '@exodus/bytes/encoding-lite.js'
@@ -877,6 +904,8 @@ true
 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).
 
+Does not provide `isomorphicDecode` and `isomorphicEncode` exports.
+
 ```js
 import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-browser.js'
 import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-browser.js' // Requires Streams

encoding-browser.d.ts

@@ -2,6 +2,8 @@
  * 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).
  *
+ * Does not provide `isomorphicDecode` and `isomorphicEncode` exports.
+ *
  * ```js
  * import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-browser.js'
  * import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-browser.js' // Requires Streams
@@ -21,4 +23,13 @@
  * @module @exodus/bytes/encoding-browser.js
  */
 
-export * from './encoding.js'
+export {
+  TextDecoder,
+  TextEncoder,
+  TextDecoderStream,
+  TextEncoderStream,
+  normalizeEncoding,
+  getBOMEncoding,
+  labelToName,
+  legacyHookDecode,
+} from './encoding.js'

encoding-browser.js

@@ -1 +1 @@
-export * from './encoding.js'
+export * from './encoding-browser.native.js'

encoding-browser.native.js

@@ -1 +1,10 @@
-export * from './encoding.js'
+export {
+  TextDecoder,
+  TextEncoder,
+  TextDecoderStream,
+  TextEncoderStream,
+  normalizeEncoding,
+  getBOMEncoding,
+  labelToName,
+  legacyHookDecode,
+} from './encoding.js'

encoding-lite.d.ts

@@ -6,6 +6,7 @@
  * ```js
  * import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-lite.js'
  * import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-lite.js' // Requires Streams
+ * import { isomorphicDecode, isomorphicEncode } from '@exodus/bytes/encoding-lite.js'
  *
  * // Hooks for standards
  * import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from '@exodus/bytes/encoding-lite.js'

encoding-lite.js

@@ -7,4 +7,6 @@ export {
   getBOMEncoding,
   labelToName,
   legacyHookDecode,
+  isomorphicDecode,
+  isomorphicEncode,
 } from './fallback/encoding.js'

encoding.d.ts

@@ -9,6 +9,7 @@
  * ```js
  * import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding.js'
  * import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding.js' // Requires Streams
+ * import { isomorphicDecode, isomorphicEncode } from '@exodus/bytes/encoding.js'
  *
  * // Hooks for standards
  * import { getBOMEncoding, legacyHookDecode, labelToName, normalizeEncoding } from '@exodus/bytes/encoding.js'
@@ -90,6 +91,34 @@ export function legacyHookDecode(
   fallbackEncoding?: string
 ): string;
 
+/**
+ * Implements [isomorphic decode](https://infra.spec.whatwg.org/#isomorphic-decode).
+ *
+ * Given a `TypedArray` or an `ArrayBuffer` instance `input`, creates a string of the same length
+ * as input byteLength, using bytes from input as codepoints.
+ *
+ * E.g. for `Uint8Array` input, this is similar to `String.fromCodePoint(...input)`.
+ *
+ * Wider `TypedArray` inputs, e.g. `Uint16Array`, are interpreted as underlying _bytes_.
+ *
+ * @param input - The bytes to decode
+ * @returns The decoded string
+ */
+export function isomorphicDecode(input: ArrayBufferLike | ArrayBufferView): string;
+
+/**
+ * Implements [isomorphic encode](https://infra.spec.whatwg.org/#isomorphic-encode).
+ *
+ * Given a string, creates an `Uint8Array` of the same length with the string codepoints as byte values.
+ *
+ * Accepts only [isomorphic string](https://infra.spec.whatwg.org/#isomorphic-string) input
+ * and asserts that, throwing on any strings containing codepoints higher than `U+00FF`.
+ *
+ * @param input - The bytes to decode
+ * @returns An Uint8Array containing the input bytes.
+ */
+export function isomorphicEncode(str: string): Uint8Array;
+
 /**
  * Implements [get an encoding from a string `label`](https://encoding.spec.whatwg.org/#concept-encoding-get).
  *

encoding.js

@@ -13,4 +13,6 @@ export {
   getBOMEncoding,
   labelToName,
   legacyHookDecode,
+  isomorphicDecode,
+  isomorphicEncode,
 } from './fallback/encoding.js'

fallback/encoding.js

@@ -3,7 +3,11 @@
 
 import { utf16toString, utf16toStringLoose } from '@exodus/bytes/utf16.js'
 import { utf8fromStringLoose, utf8toString, utf8toStringLoose } from '@exodus/bytes/utf8.js'
-import { createSinglebyteDecoder } from '@exodus/bytes/single-byte.js'
+import {
+  createSinglebyteDecoder,
+  latin1toString,
+  latin1fromString,
+} from '@exodus/bytes/single-byte.js'
 import labels from './encoding.labels.js'
 import { fromSource, getBOMEncoding } from './encoding.api.js'
 import { unfinishedBytes, mergePrefix } from './encoding.util.js'
@@ -357,3 +361,13 @@ export function legacyHookDecode(input, fallbackEncoding = 'utf-8') {
 
   return createSinglebyteDecoder(enc, true)(u8)
 }
+
+export function isomorphicDecode(input) {
+  return latin1toString(fromSource(input))
+}
+
+export function isomorphicEncode(str) {
+  const res = latin1fromString(str)
+  // match new Uint8Array, which is non-pooled
+  return res.byteOffset === 0 && res.length === res.buffer.byteLength ? res : res.slice(0)
+}

single-byte.d.ts

@@ -108,6 +108,9 @@ export function createSinglebyteEncoder(
  * > This is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as those
  * > alias to `new TextDecoder('windows-1252')`.
  *
+ * Prefer using `isomorphicDecode()` from `@exodus/bytes/encoding.js` or `@exodus/bytes/encoding-lite.js`,
+ * which is identical to this but allows more input types.
+ *
  * @param arr - The bytes to decode
  * @returns The decoded string
  */
@@ -123,6 +126,8 @@ export function latin1toString(arr: Uint8Array): string;
  * const latin1fromString = createSinglebyteEncoder('iso-8859-1', { mode: 'fatal' })
  * ```
  *
+ * Prefer using `isomorphicEncode()` from `@exodus/bytes/encoding.js` or `@exodus/bytes/encoding-lite.js`.
+ *
  * @param string - The string to encode
  * @returns The encoded bytes
  */