bufferbase 1.3.0 → 3.0.0

package/src/codec-block.ts

@@ -0,0 +1,258 @@
+import { Buffer } from 'node:buffer';
+import type { BlockSpec, BufferLike, DecodeOptions } from './types.js';
+import { BaseCodec, toBuffer } from './codec-base.js';
+import {
+  BufferSizeError,
+  InvalidCharacterError,
+  InvalidCodecError,
+  InvalidLengthError,
+  NonCanonicalError,
+} from './errors.js';
+
+const RFC_BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const RFC_BASE64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const HEX_LOWER = '0123456789abcdef';
+const HEX_UPPER = '0123456789ABCDEF';
+
+/** A Node encoding that produces exactly what this codec would, and whether it needs upper-casing. */
+type NativeEncoder = { readonly encoding: 'base64' | 'base64url' | 'hex'; readonly upper: boolean };
+
+/**
+ * Finds the Node encoding equivalent to a spec, if there is one.
+ *
+ * Node's encoders are 100-250x faster than the loop below and always emit
+ * canonical output, so an exact match is handed off. Decoding is never handed
+ * off: Node's decoders are lenient, and rejecting non-canonical input is the
+ * point of this codec.
+ */
+function nativeEncoderFor(alphabet: string, pad: string | false): NativeEncoder | null {
+  if (alphabet === RFC_BASE64 && pad === '=') {
+    return { encoding: 'base64', upper: false };
+  }
+  if (alphabet === RFC_BASE64URL && pad === false) {
+    return { encoding: 'base64url', upper: false };
+  }
+  if (pad === false && (alphabet === HEX_LOWER || alphabet === HEX_UPPER)) {
+    return { encoding: 'hex', upper: alphabet === HEX_UPPER };
+  }
+  return null;
+}
+
+const gcd = (a: number, b: number): number => (b === 0 ? a : gcd(b, a % b));
+
+/**
+ * Regroups the bit stream into fixed-width chunks, as specified by RFC 4648.
+ *
+ * Each character carries `log2(alphabet.length)` bits, so the alphabet must
+ * hold 2, 4, 8, 16, 32, or 64 characters. Unlike a radix conversion the output
+ * length is a fixed function of the input length, which is what makes Base64
+ * and Base32 splittable and streamable.
+ *
+ * A trailing partial block leaves spare bits in the final character. RFC 4648
+ * §3.5 requires those bits to be zero for the encoding to be canonical; input
+ * that sets them is rejected unless the spec passes `strict: false`.
+ *
+ * @example
+ * ```typescript
+ * import { Codecs } from 'bufferbase';
+ *
+ * Codecs.base64.encode(Buffer.from('fo')); // 'Zm8='
+ * Codecs.base64.validate('Zm9=');          // false — spare bits are not zero
+ * ```
+ */
+export class BlockCodec extends BaseCodec {
+  readonly algorithm = 'block' as const;
+
+  /** Bits carried by one character. */
+  private readonly bitsPerChar: number;
+  /** Characters in a whole block. */
+  private readonly charsPerBlock: number;
+  private readonly padChar: string | false;
+  private readonly native: NativeEncoder | null;
+
+  constructor(spec: BlockSpec) {
+    super(spec);
+
+    const bits = Math.log2(spec.alphabet.length);
+    if (!Number.isInteger(bits)) {
+      throw new InvalidCodecError(
+        `'block' needs an alphabet of 2, 4, 8, 16, 32, or 64 characters, got ${spec.alphabet.length}`,
+      );
+    }
+
+    const pad = spec.pad ?? '=';
+    if (pad !== false) {
+      if (pad.length !== 1) {
+        throw new InvalidCodecError(`pad must be a single character, got '${pad}'`);
+      }
+      if (this.valueOf(pad) !== undefined) {
+        throw new InvalidCodecError(`pad character '${pad}' is part of the alphabet`);
+      }
+    }
+
+    this.bitsPerChar = bits;
+    this.charsPerBlock = 8 / gcd(8, bits);
+    this.padChar = pad;
+    this.native = nativeEncoderFor(spec.alphabet, pad);
+  }
+
+  encode(input: BufferLike): string {
+    const buffer = toBuffer(input);
+    if (this.native !== null) {
+      const encoded = buffer.toString(this.native.encoding);
+      return this.native.upper ? encoded.toUpperCase() : encoded;
+    }
+
+    const bits = this.bitsPerChar;
+    const mask = this.chars.length - 1;
+    const codes = this.codes;
+    if (codes === null) {
+      return this.encodeAsText(buffer);
+    }
+
+    const dataChars = Math.ceil((buffer.length * 8) / bits);
+    const total =
+      this.padChar === false
+        ? dataChars
+        : Math.ceil(dataChars / this.charsPerBlock) * this.charsPerBlock;
+    const written = new Uint8Array(total);
+    let at = 0;
+    let acc = 0;
+    let held = 0;
+
+    for (let i = 0; i < buffer.length; i++) {
+      acc = ((acc << 8) | buffer[i]) & 0xffff;
+      held += 8;
+      while (held >= bits) {
+        held -= bits;
+        written[at++] = codes[(acc >>> held) & mask];
+      }
+    }
+    if (held > 0) {
+      written[at++] = codes[(acc << (bits - held)) & mask];
+    }
+    if (this.padChar !== false) {
+      const padCode = this.padChar.charCodeAt(0);
+      while (at < total) {
+        written[at++] = padCode;
+      }
+    }
+    return this.textFrom(written, at);
+  }
+
+  /** The character-by-character path, for an alphabet that is not single-byte. */
+  private encodeAsText(buffer: Uint8Array): string {
+    const bits = this.bitsPerChar;
+    const mask = this.chars.length - 1;
+    let out = '';
+    let acc = 0;
+    let held = 0;
+
+    for (const byte of buffer) {
+      acc = ((acc << 8) | byte) & 0xffff;
+      held += 8;
+      while (held >= bits) {
+        held -= bits;
+        out += this.chars[(acc >>> held) & mask];
+      }
+    }
+    if (held > 0) {
+      out += this.chars[(acc << (bits - held)) & mask];
+    }
+    if (this.padChar !== false) {
+      while (out.length % this.charsPerBlock !== 0) {
+        out += this.padChar;
+      }
+    }
+    return out;
+  }
+
+  decode(encoded: string, options?: DecodeOptions): Buffer {
+    const data = this.checkStructure(this.strip(encoded));
+    const bits = this.bitsPerChar;
+    const bytes = Buffer.alloc(Math.floor((data.length * bits) / 8));
+    let at = 0;
+    let acc = 0;
+    let held = 0;
+
+    for (let i = 0; i < data.length; i++) {
+      const value = this.valueAt(data, i);
+      if (value < 0) {
+        throw new InvalidCharacterError(data[i]);
+      }
+      acc = ((acc << bits) | value) & 0xffff;
+      held += bits;
+      if (held >= 8) {
+        held -= 8;
+        bytes[at++] = (acc >>> held) & 0xff;
+      }
+    }
+
+    const size = options?.size;
+    if (size !== undefined && bytes.length !== size) {
+      throw new BufferSizeError(bytes.length, size);
+    }
+    return bytes;
+  }
+
+  validate(input: string): boolean {
+    try {
+      this.checkStructure(this.strip(input));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Strips and checks the padding, then verifies that what remains can be the
+   * encoding of some byte sequence. Returns the data characters.
+   *
+   * Everything `decode` can reject other than `DecodeOptions.size` is checked
+   * here, so `validate` and `decode` always agree.
+   */
+  private checkStructure(input: string): string {
+    let data = input;
+
+    if (this.padChar !== false) {
+      let dataLength = input.length;
+      while (dataLength > 0 && input[dataLength - 1] === this.padChar) {
+        dataLength--;
+      }
+      data = input.slice(0, dataLength);
+      if (input.length % this.charsPerBlock !== 0) {
+        throw new InvalidLengthError(
+          input.length,
+          `padded input must be a multiple of ${this.charsPerBlock} characters`,
+        );
+      }
+      if (input.length - dataLength >= this.charsPerBlock) {
+        throw new InvalidLengthError(input.length, 'too many padding characters');
+      }
+    }
+
+    const bits = this.bitsPerChar;
+    const spare = (data.length * bits) % 8;
+    if (spare >= bits) {
+      throw new InvalidLengthError(
+        data.length,
+        `${data.length} characters carry ${data.length * bits} bits, which is not a whole number of bytes`,
+      );
+    }
+
+    let last = -1;
+    for (let i = 0; i < data.length; i++) {
+      last = this.valueAt(data, i);
+      if (last < 0) {
+        throw new InvalidCharacterError(data[i]);
+      }
+    }
+
+    if (this.strict && spare > 0 && last >= 0 && (last & ((1 << spare) - 1)) !== 0) {
+      throw new NonCanonicalError(
+        `the final character carries ${spare} spare bits that must be zero`,
+      );
+    }
+    return data;
+  }
+}

package/src/codec-block85.ts

@@ -0,0 +1,315 @@
+import { Buffer } from 'node:buffer';
+import type { Block85Spec, BufferLike, DecodeOptions } from './types.js';
+import { BaseCodec, toBuffer } from './codec-base.js';
+import {
+  BufferSizeError,
+  InvalidCharacterError,
+  InvalidCodecError,
+  InvalidLengthError,
+  NonCanonicalError,
+  ValueRangeError,
+} from './errors.js';
+
+const BYTES_PER_BLOCK = 4;
+const CHARS_PER_BLOCK = 5;
+const BLOCK_LIMIT = 0x1_00_00_00_00;
+const ZERO_CHAR = 'z';
+const ZERO_CODE = ZERO_CHAR.charCodeAt(0);
+const SPACE_CHAR = 'y';
+const SPACE_CODE = SPACE_CHAR.charCodeAt(0);
+const SPACE_BLOCK = 0x20202020;
+const OPEN = '<~';
+const CLOSE = '~>';
+
+/**
+ * Converts each 4-byte block to 5 characters, the Ascii85 and Z85 family.
+ *
+ * 85^5 is the smallest power of 85 above 2^32, so five characters are enough
+ * for four bytes and the expansion is 25% instead of Base64's 33%.
+ *
+ * Several mutually incompatible encodings share this algorithm and alphabet,
+ * differing only in the shortcuts and framing they add. They are options here
+ * rather than separate codecs: the btoa form is `zeroShortcut` plus
+ * `spaceShortcut`, and the Adobe form is `zeroShortcut` plus `delimiters`. The
+ * default, `zeroShortcut` alone, matches Python's `base64.a85encode`.
+ *
+ * @example
+ * ```typescript
+ * import { Codecs } from 'bufferbase';
+ *
+ * Codecs.ascii85.encode(Buffer.from('Man ')); // '9jqo^'
+ * Codecs.ascii85.encode(Buffer.alloc(4));     // 'z'
+ * ```
+ */
+export class Block85Codec extends BaseCodec {
+  readonly algorithm = 'block85' as const;
+
+  private readonly zeroShortcut: boolean;
+  private readonly spaceShortcut: boolean;
+  private readonly delimiters: boolean;
+  private readonly requireFullBlocks: boolean;
+
+  constructor(spec: Block85Spec) {
+    super(spec);
+
+    if (spec.alphabet.length !== 85) {
+      throw new InvalidCodecError(
+        `'block85' needs an alphabet of exactly 85 characters, got ${spec.alphabet.length}`,
+      );
+    }
+    for (const [enabled, char] of [
+      [spec.zeroShortcut, ZERO_CHAR],
+      [spec.spaceShortcut, SPACE_CHAR],
+    ] as const) {
+      if (enabled === true && this.valueOf(char) !== undefined) {
+        throw new InvalidCodecError(`shortcut character '${char}' is part of the alphabet`);
+      }
+    }
+
+    this.zeroShortcut = spec.zeroShortcut ?? false;
+    this.spaceShortcut = spec.spaceShortcut ?? false;
+    this.delimiters = spec.delimiters ?? false;
+    this.requireFullBlocks = spec.requireFullBlocks ?? false;
+  }
+
+  encode(input: BufferLike): string {
+    const buffer = toBuffer(input);
+    if (this.requireFullBlocks && buffer.length % BYTES_PER_BLOCK !== 0) {
+      throw new InvalidLengthError(
+        buffer.length,
+        `this codec encodes whole ${BYTES_PER_BLOCK}-byte blocks only`,
+      );
+    }
+
+    const codes = this.codes;
+    if (codes === null) {
+      return this.encodeAsText(buffer);
+    }
+
+    const blocks = Math.ceil(buffer.length / BYTES_PER_BLOCK);
+    const written = new Uint8Array(blocks * CHARS_PER_BLOCK + OPEN.length + CLOSE.length);
+    let at = 0;
+    if (this.delimiters) {
+      at += this.writeAscii(written, at, OPEN);
+    }
+
+    // Whole blocks, with the five divisions unrolled. Dividing a float by 85
+    // and truncating with `>>> 0` is several times quicker than `%` paired
+    // with `Math.floor`, because every quotient here still fits in 32 bits.
+    const whole = buffer.length - (buffer.length % BYTES_PER_BLOCK);
+    for (let from = 0; from < whole; from += BYTES_PER_BLOCK) {
+      const value = buffer.readUInt32BE(from);
+      if (this.zeroShortcut && value === 0) {
+        written[at++] = ZERO_CODE;
+        continue;
+      }
+      if (this.spaceShortcut && value === SPACE_BLOCK) {
+        written[at++] = SPACE_CODE;
+        continue;
+      }
+      const q1 = (value / 85) >>> 0;
+      const q2 = (q1 / 85) >>> 0;
+      const q3 = (q2 / 85) >>> 0;
+      const q4 = (q3 / 85) >>> 0;
+      written[at] = codes[q4];
+      written[at + 1] = codes[q3 - q4 * 85];
+      written[at + 2] = codes[q2 - q3 * 85];
+      written[at + 3] = codes[q1 - q2 * 85];
+      written[at + 4] = codes[value - q1 * 85];
+      at += CHARS_PER_BLOCK;
+    }
+
+    // The trailing partial block, encoded as `size + 1` characters.
+    if (whole < buffer.length) {
+      const size = buffer.length - whole;
+      let value = 0;
+      for (let i = 0; i < BYTES_PER_BLOCK; i++) {
+        value = value * 256 + (whole + i < buffer.length ? buffer[whole + i] : 0);
+      }
+      const digits = new Uint8Array(CHARS_PER_BLOCK);
+      for (let i = CHARS_PER_BLOCK - 1; i >= 0; i--) {
+        const quotient = (value / 85) >>> 0;
+        digits[i] = codes[value - quotient * 85];
+        value = quotient;
+      }
+      for (let i = 0; i <= size; i++) {
+        written[at++] = digits[i];
+      }
+    }
+    if (this.delimiters) {
+      at += this.writeAscii(written, at, CLOSE);
+    }
+    return this.textFrom(written, at);
+  }
+
+  decode(encoded: string, options?: DecodeOptions): Buffer {
+    const bytes = this.readBytes(this.undelimit(this.strip(encoded)));
+    const size = options?.size;
+    if (size !== undefined && bytes.length !== size) {
+      throw new BufferSizeError(bytes.length, size);
+    }
+    return Buffer.from(bytes);
+  }
+
+  validate(input: string): boolean {
+    try {
+      this.readBytes(this.undelimit(this.strip(input)));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Writes an ASCII marker, returning how many bytes it took. */
+  private writeAscii(into: Uint8Array, at: number, text: string): number {
+    for (let i = 0; i < text.length; i++) {
+      into[at + i] = text.charCodeAt(i);
+    }
+    return text.length;
+  }
+
+  /** The character-by-character path, for an alphabet that is not single-byte. */
+  private encodeAsText(buffer: Uint8Array): string {
+    let out = '';
+    for (let at = 0; at < buffer.length; at += BYTES_PER_BLOCK) {
+      const size = Math.min(BYTES_PER_BLOCK, buffer.length - at);
+      let value = 0;
+      for (let i = 0; i < BYTES_PER_BLOCK; i++) {
+        value = value * 256 + (at + i < buffer.length ? buffer[at + i] : 0);
+      }
+      if (size === BYTES_PER_BLOCK && this.zeroShortcut && value === 0) {
+        out += ZERO_CHAR;
+      } else if (size === BYTES_PER_BLOCK && this.spaceShortcut && value === SPACE_BLOCK) {
+        out += SPACE_CHAR;
+      } else {
+        out += this.digitsOf(value).slice(0, size === BYTES_PER_BLOCK ? CHARS_PER_BLOCK : size + 1);
+      }
+    }
+    return this.delimiters ? OPEN + out + CLOSE : out;
+  }
+
+  /** Renders a block value as its five characters, most significant first. */
+  private digitsOf(value: number): string {
+    let rest = value;
+    const digits: string[] = [];
+    for (let i = 0; i < CHARS_PER_BLOCK; i++) {
+      digits.unshift(this.chars[rest % 85]);
+      rest = Math.floor(rest / 85);
+    }
+    return digits.join('');
+  }
+
+  /** Removes the framing, rejecting input that is missing or misplacing it. */
+  private undelimit(input: string): string {
+    if (!this.delimiters) {
+      return input;
+    }
+    if (!input.startsWith(OPEN) || !input.endsWith(CLOSE) || input.length < OPEN.length + CLOSE.length) {
+      throw new InvalidCharacterError();
+    }
+    return input.slice(OPEN.length, input.length - CLOSE.length);
+  }
+
+  /**
+   * Decodes the body. Everything `decode` can reject other than
+   * `DecodeOptions.size` is checked here, so `validate` and `decode` agree.
+   */
+  private readBytes(body: string): number[] {
+    const bytes: number[] = [];
+    let held = 0;
+    let value = 0;
+    let groupAt = 0;
+
+    for (let i = 0; i < body.length; i++) {
+      if (held === 0) {
+        const code = body.charCodeAt(i);
+        if (this.zeroShortcut && code === ZERO_CODE) {
+          bytes.push(0, 0, 0, 0);
+          continue;
+        }
+        if (this.spaceShortcut && code === SPACE_CODE) {
+          bytes.push(0x20, 0x20, 0x20, 0x20);
+          continue;
+        }
+        groupAt = i;
+      }
+      const digit = this.valueAt(body, i);
+      if (digit < 0) {
+        throw new InvalidCharacterError(body[i]);
+      }
+      value = value * 85 + digit;
+      held++;
+      if (held === CHARS_PER_BLOCK) {
+        if (value >= BLOCK_LIMIT) {
+          throw new ValueRangeError(body.slice(groupAt, i + 1));
+        }
+        bytes.push(
+          (value / 0x1000000) & 0xff,
+          (value / 0x10000) & 0xff,
+          (value / 0x100) & 0xff,
+          value & 0xff,
+        );
+        held = 0;
+        value = 0;
+      }
+    }
+
+    if (held > 0) {
+      this.readPartial(body.slice(groupAt), bytes);
+    }
+    return bytes;
+  }
+
+  /**
+   * Decodes a trailing group of 2..4 characters into 1..3 bytes.
+   *
+   * The group is padded to a whole block with the highest digit so that the
+   * missing low-order bytes cannot round the value down, then the bytes the
+   * group actually carries are kept.
+   */
+  private readPartial(group: string, bytes: number[]): void {
+    if (this.requireFullBlocks) {
+      throw new InvalidLengthError(
+        group.length,
+        `this codec decodes whole ${CHARS_PER_BLOCK}-character blocks only`,
+      );
+    }
+    if (group.length < 2) {
+      throw new InvalidLengthError(
+        group.length,
+        `a trailing group needs at least 2 characters to carry a byte`,
+      );
+    }
+
+    const padded = group.padEnd(CHARS_PER_BLOCK, this.chars[84]);
+    let value = 0;
+    for (let i = 0; i < CHARS_PER_BLOCK; i++) {
+      const digit = this.valueAt(padded, i);
+      if (digit < 0) {
+        throw new InvalidCharacterError(padded[i]);
+      }
+      value = value * 85 + digit;
+    }
+    if (value >= BLOCK_LIMIT) {
+      throw new ValueRangeError(group);
+    }
+
+    const carried = group.length - 1;
+    const block: number[] = [];
+    for (let shift = 24; shift >= 0; shift -= 8) {
+      block.push((value / 2 ** shift) & 0xff);
+    }
+    const kept = block.slice(0, carried);
+
+    if (this.strict) {
+      let padded = 0;
+      for (let i = 0; i < BYTES_PER_BLOCK; i++) {
+        padded = padded * 256 + (i < carried ? kept[i] : 0);
+      }
+      if (this.digitsOf(padded).slice(0, group.length) !== group) {
+        throw new NonCanonicalError(`'${group}' is not the shortest encoding of its bytes`);
+      }
+    }
+    bytes.push(...kept);
+  }
+}