suaveplan/openspec/archive/2026-05-02-bytes-spec-conformance/specs/bytes/spec.md

Spec: @suaveplan/bytes

Capability

Low-level byte I/O for the Suaveplan monorepo. Provides lossless conversion between Uint8Array and the three ubiquitous text representations (hex, base64, UTF-8), ergonomic Uint8Array utilities (concat, slice, equality, format auto-detection, unified conversion façade), and UUID string ↔ 16-byte binary round-trip functions.

Requirements

Requirement: Hex encoding round-trips and rejects malformed input

The package SHALL export bytesToHex(bytes: Uint8Array): string producing lowercase hex (empty array → ""), and hexToBytes(hex: string): Uint8Array accepting case-insensitive hex. hexToBytes MUST throw BytesError with code BYTES.ENCODE.INVALID_HEX on odd-length input or non-hex characters. Round-tripping arbitrary Uint8Array through bytesToHex → hexToBytes MUST be lossless.

Scenario: Round-trip preserves arbitrary bytes

• WHEN any Uint8Array is passed through bytesToHex then hexToBytes
• THEN the resulting bytes equal the input byte-for-byte

Scenario: Empty input maps to empty output

• WHEN bytesToHex(new Uint8Array(0)) is called
• THEN the result is ""

Scenario: Malformed hex is rejected with a structured error

• WHEN hexToBytes is called with odd-length input or non-hex characters
• THEN a BytesError with code BYTES.ENCODE.INVALID_HEX is thrown

Verified by: src/encoding/encoding.test.ts::"round-trips arbitrary bytes" AND src/encoding/encoding.test.ts::"bytesToHex produces lowercase hex" AND src/encoding/encoding.test.ts::"bytesToHex handles empty array" AND src/encoding/encoding.test.ts::"hexToBytes handles empty string" AND src/encoding/encoding.test.ts::"hexToBytes rejects odd-length string" AND src/encoding/encoding.test.ts::"hexToBytes rejects non-hex chars" AND src/encoding/encoding.test.ts::"hexToBytes accepts uppercase hex letters" AND src/encoding/encoding.test.ts::"hexToBytes rejects uppercase letters that are not hex" AND src/encoding/encoding.test.ts::"hex round-trip for arbitrary bytes"

Requirement: Base64 encoding round-trips and rejects malformed input

The package SHALL export bytesToBase64(bytes: Uint8Array): string (standard base64 with = padding) and base64ToBytes(base64: string): Uint8Array. base64ToBytes MUST throw BytesError with code BYTES.ENCODE.INVALID_BASE64 on syntactically invalid or malformed input. Round-tripping arbitrary Uint8Array is lossless.

Scenario: Round-trip preserves arbitrary bytes

• WHEN any Uint8Array is passed through bytesToBase64 then base64ToBytes
• THEN the resulting bytes equal the input

Scenario: Malformed base64 is rejected

• WHEN base64ToBytes is called with non-base64 characters or bad padding
• THEN a BytesError with code BYTES.ENCODE.INVALID_BASE64 is thrown

Verified by: src/encoding/encoding.test.ts::"round-trips arbitrary bytes" AND src/encoding/encoding.test.ts::"handles empty array" AND src/encoding/encoding.test.ts::"rejects invalid base64" AND src/encoding/encoding.test.ts::"rejects syntactically valid but malformed base64 (bad padding)" AND src/encoding/encoding.test.ts::"base64 round-trip for arbitrary bytes"

Requirement: UTF-8 encoding round-trips arbitrary strings

The package SHALL export bytesToUtf8(bytes: Uint8Array): string backed by TextDecoder("utf-8") and utf8ToBytes(str: string): Uint8Array backed by TextEncoder. Round-tripping multibyte and ASCII strings is lossless.

Scenario: ASCII round-trip

• WHEN any ASCII string is passed through utf8ToBytes then bytesToUtf8
• THEN the result equals the input

Scenario: Multibyte round-trip

• WHEN strings containing non-ASCII characters are round-tripped
• THEN code points are preserved

Verified by: src/encoding/encoding.test.ts::"round-trips ASCII" AND src/encoding/encoding.test.ts::"round-trips multibyte characters" AND src/encoding/encoding.test.ts::"handles empty string" AND src/encoding/encoding.test.ts::"utf8 round-trip for arbitrary strings"

Requirement: Uint8Array utility surface

The package SHALL export concatUint8Arrays(...arrays: Uint8Array[]): Uint8Array, sliceUint8Array(arr, start, end?): Uint8Array, and uint8ArraysEqual(a, b): boolean (NOT constant-time — documented). concatUint8Arrays MUST be associative under concatenation and tolerate zero arguments and empty arrays.

Scenario: Concatenation joins arrays end-to-end

• WHEN concatUint8Arrays(a, b, c) is called
• THEN the result has a.length + b.length + c.length bytes in order

Scenario: Concatenation handles edge cases

• WHEN called with no arguments, a single array, or arrays of length zero
• THEN the result is empty (or the lone non-empty array) without throwing

Scenario: Slicing returns a copy of the requested range

• WHEN sliceUint8Array(arr, start, end?) is called
• THEN the result contains bytes [start, end) (or [start, arr.length) if end is omitted)

Scenario: Equality compares length and bytes

• WHEN uint8ArraysEqual(a, b) is called
• THEN the result is true iff lengths match AND every byte at every index is equal

Verified by: src/uint8/uint8.test.ts::"concatenates multiple arrays" AND src/uint8/uint8.test.ts::"handles empty arrays" AND src/uint8/uint8.test.ts::"handles single array" AND src/uint8/uint8.test.ts::"handles no arguments" AND src/uint8/uint8.test.ts::"concatUint8Arrays associativity" AND src/uint8/uint8.test.ts::"slices correctly" AND src/uint8/uint8.test.ts::"slices from start only" AND src/uint8/uint8.test.ts::"returns empty for zero-length slice" AND src/uint8/uint8.test.ts::"returns true for equal arrays" AND src/uint8/uint8.test.ts::"returns false for different arrays" AND src/uint8/uint8.test.ts::"returns false for different lengths" AND src/uint8/uint8.test.ts::"returns true for two empty arrays"

Requirement: Format detection and validation

The package SHALL export detectInputFormat(input: BytesInput): InputFormat returning "uint8array" for Uint8Array, "hex" for even-length all-hex strings, and "utf8" otherwise; inputToUint8Array(input, format?) coercing input into bytes (auto-detecting when format is omitted); and validateInputTypeFormat(input, format) which MUST throw BytesError with code BYTES.UINT8.FORMAT_MISMATCH when the runtime type does not match the declared format.

Scenario: Heuristic detects the three input formats

• WHEN detectInputFormat is called with a Uint8Array, an even-length hex string, or any other string
• THEN the result is "uint8array", "hex", or "utf8" respectively

Scenario: Coercion respects explicit format and falls back to auto-detection

• WHEN inputToUint8Array(value, format?) is called
• THEN the value is decoded using format (or the detected format) into a Uint8Array

Scenario: Validation throws on type/format mismatch

• WHEN validateInputTypeFormat is called with a value whose runtime type does not match the declared format (e.g. string with "uint8array" format)
• THEN a BytesError with code BYTES.UINT8.FORMAT_MISMATCH is thrown

Verified by: src/uint8/uint8.test.ts::"detects Uint8Array" AND src/uint8/uint8.test.ts::"detects hex string" AND src/uint8/uint8.test.ts::"detects utf8 for general string" AND src/uint8/uint8.test.ts::"detects utf8 for non-hex even string" AND src/uint8/uint8.test.ts::"returns Uint8Array as-is" AND src/uint8/uint8.test.ts::"converts hex string to Uint8Array" AND src/uint8/uint8.test.ts::"converts utf8 string to Uint8Array" AND src/uint8/uint8.test.ts::"converts base64 string to Uint8Array" AND src/uint8/uint8.test.ts::"auto-detects format when not provided" AND src/uint8/uint8.test.ts::"throws when string given with uint8array format" AND src/uint8/uint8.test.ts::"validates Uint8Array with uint8array format" AND src/uint8/uint8.test.ts::"validates string with hex format" AND src/uint8/uint8.test.ts::"throws when Uint8Array given but string format requested" AND src/uint8/uint8.test.ts::"throws when string given but uint8array format requested"

Requirement: Unified conversion façade with OTel span

The package SHALL export formatOutput(bytes, format) returning a value in the requested representation (uint8array / hex / base64 / utf8) and convertDataFormat(input, outputFormat, inputFormat?) which MUST emit an OpenTelemetry span around the conversion. Auto-detection of inputFormat MUST kick in when omitted.

Scenario: Output formatting covers every supported format

• WHEN formatOutput(bytes, format) is called with each of "uint8array", "hex", "base64", "utf8"
• THEN the result is the corresponding representation of bytes

Scenario: Format conversion bridges any input to any output

• WHEN convertDataFormat is called with mismatched input/output formats (e.g. hex → utf8, utf8 → hex, Uint8Array → hex, hex → base64)
• THEN the conversion proceeds and the output matches the expected encoding

Scenario: Auto-detection fills in missing input format

• WHEN convertDataFormat(value, outputFormat) is called without inputFormat
• THEN the input format is detected via detectInputFormat before conversion

Verified by: src/uint8/uint8.test.ts::"returns Uint8Array for uint8array format" AND src/uint8/uint8.test.ts::"returns hex string for hex format" AND src/uint8/uint8.test.ts::"returns base64 string for base64 format" AND src/uint8/uint8.test.ts::"returns utf8 string for utf8 format" AND src/uint8/uint8.test.ts::"converts hex to utf8" AND src/uint8/uint8.test.ts::"converts utf8 to hex" AND src/uint8/uint8.test.ts::"converts Uint8Array to hex" AND src/uint8/uint8.test.ts::"converts hex to base64" AND src/uint8/uint8.test.ts::"converts Uint8Array to uint8array (identity)" AND src/uint8/uint8.test.ts::"auto-detects input format for hex strings"

Requirement: UUID round-trip and validation

The package SHALL export generateUuid(): string (UUIDv4 via crypto.randomUUID()), uuidToUint8Array(uuid: string): Uint8Array returning 16 bytes, and uint8ArrayToUuid(bytes: Uint8Array): string returning canonical lowercase. Invalid UUIDs MUST throw BytesError with code BYTES.UUID.INVALID_FORMAT; non-16-byte arrays MUST throw BYTES.UUID.INVALID_LENGTH. Round-trip is lossless including all-zero and all-f corner cases.

Scenario: Generated UUIDs are valid and unique

• WHEN generateUuid() is called multiple times
• THEN every result matches the UUIDv4 lowercase canonical shape AND no two results are equal

Scenario: Round-trip preserves the canonical form

• WHEN a UUID string is passed through uuidToUint8Array then uint8ArrayToUuid
• THEN the output equals the (lowercased) input — including the all-zero and all-f corner cases

Scenario: Invalid UUID strings are rejected

• WHEN uuidToUint8Array is called with a malformed string
• THEN a BytesError with code BYTES.UUID.INVALID_FORMAT is thrown

Scenario: Wrong-length byte arrays are rejected

• WHEN uint8ArrayToUuid is called with an array whose length is not 16 (including empty)
• THEN a BytesError with code BYTES.UUID.INVALID_LENGTH is thrown

Verified by: src/uuid/uuid.test.ts::"round-trips a known UUID" AND src/uuid/uuid.test.ts::"uuidToUint8Array produces 16 bytes" AND src/uuid/uuid.test.ts::"throws on invalid UUID" AND src/uuid/uuid.test.ts::"throws on UUID with wrong structure" AND src/uuid/uuid.test.ts::"uint8ArrayToUuid throws on non-16-byte array" AND src/uuid/uuid.test.ts::"uint8ArrayToUuid throws on empty array" AND src/uuid/uuid.test.ts::"round-trips all-zeros UUID" AND src/uuid/uuid.test.ts::"round-trips all-fs UUID" AND src/uuid/uuid.test.ts::"generates a valid UUID v4 string" AND src/uuid/uuid.test.ts::"generates unique values" AND src/uuid/uuid.test.ts::"output is lowercase" AND src/uuid/uuid.test.ts::"generated UUID can round-trip through uint8Array"

Error codes

BYTES.ENCODE.INVALID_HEX, BYTES.ENCODE.INVALID_BASE64, BYTES.ENCODE.INVALID_UTF8 (reserved), BYTES.UINT8.INVALID_INPUT, BYTES.UINT8.FORMAT_MISMATCH, BYTES.UUID.INVALID_LENGTH, BYTES.UUID.INVALID_FORMAT

Version

Published: 0.1.0 (2026-04-20). Spec heading conformance: bytes-spec-conformance (2026-04-26).