bytecodec

Typed JavaScript byte utilities for base64url, UTF-8 strings, JSON, and gzip that behave the same in browsers and Node. Built to make JavaScript/TypeScript projects with lots of byte-format data a breeze to build, without having to write your own utilities or boilerplate.

Compatibility

• Runtimes: Node >= 18; Browsers: modern browsers with TextEncoder/TextDecoder + btoa/atob; Workers/Edge: runtimes with TextEncoder/TextDecoder + btoa/atob (gzip needs CompressionStream/DecompressionStream).
• Module format: ESM-only (no CJS build).
• Required globals / APIs: Node Buffer (base64/UTF-8 fallback); browser/edge TextEncoder, TextDecoder, btoa, atob; gzip in browser/edge needs CompressionStream/DecompressionStream.
• TypeScript: bundled types.

Goals

• Developer-friendly API for base64url, UTF-8, JSON, gzip, concat, and equality.
• No dependencies or bundler shims.
• ESM-only and side-effect free for tree-shaking.
• Returns copies for safety when normalizing inputs.
• Consistent behavior across Node, browsers, and edge runtimes.

Installation

npm install @z-base/bytecodec
# or
pnpm add @z-base/bytecodec
# or
yarn add @z-base/bytecodec

Usage

Bytes wrapper

import { Bytes } from '@z-base/bytecodec'
// The `Bytes` convenience class wraps the same functions as static methods.
const encoded = Bytes.toBase64UrlString(new Uint8Array([1, 2, 3]))

Base64URL

import { toBase64UrlString, fromBase64UrlString } from '@z-base/bytecodec'

const bytes = new Uint8Array([104, 101, 108, 108, 111])
const encoded = toBase64UrlString(bytes) // string of base64url chars
const decoded = fromBase64UrlString(encoded) // Uint8Array

UTF-8 strings

import { fromString, toString } from '@z-base/bytecodec'

const textBytes = fromString('caffe and rockets') // Uint8Array
const text = toString(textBytes) // "caffe and rockets"

JSON

import { fromJSON, toJSON } from '@z-base/bytecodec'

const jsonBytes = fromJSON({ ok: true, count: 3 }) // Uint8Array
const obj = toJSON(jsonBytes) // { ok: true, count: 3 }

Compression

import { toCompressed, fromCompressed } from '@z-base/bytecodec'

const compressed = await toCompressed(new Uint8Array([1, 2, 3])) // Uint8Array
const restored = await fromCompressed(compressed) // Uint8Array

Normalization

import { toUint8Array, toArrayBuffer, toBufferSource } from '@z-base/bytecodec'

const normalized = toUint8Array([1, 2, 3]) // Uint8Array
const copied = toArrayBuffer(normalized) // ArrayBuffer
const bufferSource = toBufferSource(normalized) // Uint8Array as BufferSource

Equality

import { equals } from '@z-base/bytecodec'

const isSame = equals(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])) // true | false

Concatenating

import { concat } from '@z-base/bytecodec'

const joined = concat([new Uint8Array([1, 2]), new Uint8Array([3, 4]), [5, 6]]) // Uint8Array

Runtime behavior

Node

Uses Buffer.from for base64 and TextEncoder/TextDecoder when available, with Buffer fallback; gzip uses node:zlib.

Browsers / Edge runtimes

Uses TextEncoder/TextDecoder and btoa/atob. Gzip uses CompressionStream/DecompressionStream when available.

Validation & errors

Validation failures throw BytecodecError with a code string (for example BASE64URL_INVALID_LENGTH, UTF8_DECODER_UNAVAILABLE, GZIP_COMPRESSION_UNAVAILABLE), while underlying runtime errors may bubble through.

Safety / copying semantics

Normalization helpers return copies (Uint8Array/ArrayBuffer) to avoid mutating caller-owned buffers.

Tests

Suite: unit + integration (Node), E2E (Playwright) Matrix: Chromium / Firefox / WebKit + mobile emulation (Pixel 5, iPhone 12) Coverage: c8 — 100% statements/branches/functions/lines (Node) Notes: no known skips

Benchmarks

How it was run: node benchmark/bench.js Environment: Node v22.14.0 (win32 x64) Results:

| Benchmark | Result | | ---------------- | -------------------------- | | base64 encode | 514,743 ops/s (97.1 ms) | | base64 decode | 648,276 ops/s (77.1 ms) | | utf8 encode | 1,036,895 ops/s (48.2 ms) | | utf8 decode | 2,893,954 ops/s (17.3 ms) | | json encode | 698,985 ops/s (28.6 ms) | | json decode | 791,690 ops/s (25.3 ms) | | concat 3 buffers | 617,497 ops/s (81.0 ms) | | toUint8Array | 10,149,502 ops/s (19.7 ms) | | toArrayBuffer | 620,992 ops/s (322.1 ms) | | toBufferSource | 8,297,585 ops/s (24.1 ms) | | equals same | 4,035,195 ops/s (49.6 ms) | | equals diff | 2,760,784 ops/s (72.4 ms) | | gzip compress | 10,275 ops/s (38.9 ms) | | gzip decompress | 18,615 ops/s (21.5 ms) |

Results vary by machine.

License

MIT