shelving/util/bytes.js

Toolkit for using data in JavaScript.

import { RequiredError } from "../error/RequiredError.js";
/** Is an unknown value a set of bytes? */
export function isBytes(value) {
    return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
}
/** Assert that an unknown value is a `Uint8Array` byte sequence. */
export function assertBytes(value, min = 0, max = Number.POSITIVE_INFINITY, caller = assertBytes) {
    if (!isBytes(value) || value.length < min || value.length > max)
        throw new RequiredError(`Value must be byte sequence${min > 0 || max < Number.POSITIVE_INFINITY ? ` with length between ${min} and ${max}` : ""}`, { received: value, caller });
}
/**
 * Convert an unknown value to a `Uint8Array<ArrayBuffer>` byte sequence, or `undefined` if the value cannot be converted.
 *
 * - `Uint8Array` values are returned as-is (if backed by an `ArrayBuffer`) or copied to a new `Uint8Array` (if not).
 * - `ArrayBuffer` instances are converted to `Uint8Array`
 * - Strings are encoded as UTF-8 characters in a `Uint8Array`
 * - Everything else returns `undefined`
 */
export function getBytes(value) {
    if (isBytes(value))
        return value;
    if (value instanceof ArrayBuffer)
        return new Uint8Array(value);
    if (typeof value === "string")
        return new TextEncoder().encode(value);
    return undefined;
}
/**
 * Convert a possible set of bytes to a `Uint8Array` byte sequence, or throw `RequiredError` if the value cannot be converted.
 */
export function requireBytes(value, min = 0, max = Number.POSITIVE_INFINITY, caller = requireBytes) {
    const bytes = getBytes(value);
    assertBytes(bytes, min, max, caller);
    return bytes;
}