bufferbase 2.0.0 → 3.0.0

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);
+  }
+}

package/src/codec-radix.ts

@@ -0,0 +1,206 @@
+import { Buffer } from 'node:buffer';
+import type { BufferLike, DecodeOptions, RadixSpec } from './types.js';
+import { BaseCodec, toBuffer } from './codec-base.js';
+import {
+  BufferSizeError,
+  CheckSymbolError,
+  InvalidCharacterError,
+  InvalidCodecError,
+  InvalidLengthError,
+} from './errors.js';
+
+/**
+ * Reads the buffer as one big integer and rewrites it in base
+ * `alphabet.length`.
+ *
+ * This is the Base58 family of encodings. It accepts any alphabet and any
+ * input length, but it is not RFC 4648: the output length is not a fixed
+ * function of the input length, so it cannot be streamed, and encoding is
+ * O(n²) in the input size.
+ *
+ * Leading zero bytes carry no value in an integer, so they are recorded
+ * separately as leading `alphabet[0]` characters.
+ *
+ * @example
+ * ```typescript
+ * import { RadixCodec } from 'bufferbase';
+ *
+ * const binary = new RadixCodec({ alphabet: '01', algorithm: 'radix' });
+ * binary.encode(Uint8Array.of(5)); // '101'
+ * ```
+ */
+export class RadixCodec extends BaseCodec {
+  readonly algorithm = 'radix' as const;
+
+  /** Alphabet plus the extra check symbols, or `null` when unchecked. */
+  private readonly checkChars: string | null;
+
+  /** Value of every character a check symbol may be written as. */
+  private readonly checkValues: ReadonlyMap<string, number>;
+
+  constructor(spec: RadixSpec) {
+    super(spec);
+
+    const extra = spec.checkSymbols;
+    if (extra === undefined || extra === '') {
+      this.checkChars = null;
+      this.checkValues = new Map();
+      return;
+    }
+    const combined = spec.alphabet + extra;
+    if (new Set(combined).size !== combined.length) {
+      throw new InvalidCodecError('checkSymbols repeat a character of the alphabet');
+    }
+
+    // The symbol is matched by value, so that a case-insensitive codec accepts
+    // it in either case just as it does the rest of the string.
+    const values = new Map<string, number>();
+    for (let i = 0; i < combined.length; i++) {
+      const char = combined[i];
+      values.set(char, i);
+      if (spec.caseInsensitive === true) {
+        values.set(char.toLowerCase(), i);
+        values.set(char.toUpperCase(), i);
+      }
+    }
+    this.checkChars = combined;
+    this.checkValues = values;
+  }
+
+  encode(input: BufferLike): string {
+    const buffer = toBuffer(input);
+    const base = this.chars.length;
+    const digits: number[] = [];
+
+    for (const byte of buffer) {
+      let carry = byte;
+      for (let i = 0; i < digits.length; i++) {
+        carry += digits[i] * 256;
+        digits[i] = carry % base;
+        carry = Math.floor(carry / base);
+      }
+      while (carry > 0) {
+        digits.push(carry % base);
+        carry = Math.floor(carry / base);
+      }
+    }
+
+    for (let i = 0; i < buffer.length && buffer[i] === 0; i++) {
+      digits.push(0);
+    }
+
+    let out = '';
+    for (let i = digits.length - 1; i >= 0; i--) {
+      out += this.chars[digits[i]];
+    }
+    if (this.checkChars !== null) {
+      out += this.checkChars[this.remainderOf(buffer, this.checkChars.length)];
+    }
+    return out;
+  }
+
+  decode(encoded: string, options?: DecodeOptions): Buffer {
+    const bytes = this.read(this.strip(encoded));
+
+    const size = options?.size;
+    if (size === undefined) {
+      return Buffer.from(bytes);
+    }
+    if (bytes.length > size) {
+      throw new BufferSizeError(bytes.length, size);
+    }
+    const padded = Buffer.alloc(size);
+    Buffer.from(bytes).copy(padded, size - bytes.length);
+    return padded;
+  }
+
+  validate(input: string): boolean {
+    const stripped = this.strip(input);
+    if (this.checkChars === null) {
+      // Every string over the alphabet decodes, so the characters settle it.
+      for (let i = 0; i < stripped.length; i++) {
+        if (this.valueAt(stripped, i) < 0) {
+          return false;
+        }
+      }
+      return true;
+    }
+    try {
+      this.read(stripped);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Decodes the body, verifying the check symbol when the codec carries one.
+   *
+   * Everything `decode` can reject other than `DecodeOptions.size` is checked
+   * here, so `validate` and `decode` always agree.
+   */
+  private read(input: string): number[] {
+    let body = input;
+
+    if (this.checkChars !== null) {
+      if (body.length === 0) {
+        throw new InvalidLengthError(0, 'a checked encoding always carries a check symbol');
+      }
+      const found = body.slice(-1);
+      body = body.slice(0, -1);
+      const bytes = this.toBytes(body);
+      const expected = this.remainderOf(bytes, this.checkChars.length);
+      if (this.checkValues.get(found) !== expected) {
+        throw new CheckSymbolError(found, this.checkChars[expected]);
+      }
+      return bytes;
+    }
+    return this.toBytes(input);
+  }
+
+  /** Rewrites the digits of `body` as bytes, most significant first. */
+  private toBytes(body: string): number[] {
+    const base = this.chars.length;
+    const bytes: number[] = [];
+    let leadingZeros = 0;
+    let stillLeading = true;
+
+    for (let at = 0; at < body.length; at++) {
+      const value = this.valueAt(body, at);
+      if (value < 0) {
+        throw new InvalidCharacterError(body[at]);
+      }
+      if (stillLeading && value === 0) {
+        leadingZeros++;
+        continue;
+      }
+      stillLeading = false;
+
+      let carry = value;
+      for (let i = 0; i < bytes.length; i++) {
+        carry += bytes[i] * base;
+        bytes[i] = carry % 256;
+        carry = Math.floor(carry / 256);
+      }
+      while (carry > 0) {
+        bytes.push(carry % 256);
+        carry = Math.floor(carry / 256);
+      }
+    }
+
+    for (let i = 0; i < leadingZeros; i++) {
+      bytes.push(0);
+    }
+    bytes.reverse();
+    return bytes;
+  }
+
+  /** The value the bytes denote, modulo `divisor`. */
+  private remainderOf(bytes: Iterable<number>, divisor: number): number {
+    let remainder = 0;
+    for (const byte of bytes) {
+      remainder = (remainder * 256 + byte) % divisor;
+    }
+    return remainder;
+  }
+}

package/src/codec.test.ts

@@ -23,12 +23,17 @@ describe('Function API', () => {
   });
 
   test('encode/decode with custom character set', () => {
+    const spec = { alphabet: Chars.Base58, algorithm: 'radix' } as const;
     const buffer = Buffer.from('Test', 'utf8');
-    const encoded = encode(buffer, Chars.Base58);
-    const decoded = decode(encoded, Chars.Base58);
+    const encoded = encode(buffer, spec);
+    const decoded = decode(encoded, spec);
     expect(decoded.toString('utf8')).toBe('Test');
   });
 
+  test('a bare alphabet is no longer accepted as a base', () => {
+    expect(() => encode(Buffer.from('Test'), Chars.Base58 as never)).toThrow(UnknownBaseError);
+  });
+
   test('convert between bases', () => {
     const buffer = Buffer.from('Hello', 'utf8');
     const base58Encoded = encode(buffer, 'base58');
@@ -183,17 +188,20 @@ describe('All character sets', () => {
     'base58',
     'base64',
     'base64url',
+    'base32hex',
     'ascii85',
-    'base85',
     'z85',
   ] as const;
 
+  // 12 bytes, so that z85 (whole 4-byte blocks only) is covered by the loop.
+  const payload = 'Hello, World';
+
   for (const base of baseNames) {
     test(`${base} encode/decode round-trip`, () => {
-      const buffer = Buffer.from('Hello, World!', 'utf8');
+      const buffer = Buffer.from(payload, 'utf8');
       const encoded = encode(buffer, base);
       const decoded = decode(encoded, base);
-      expect(decoded.toString('utf8')).toBe('Hello, World!');
+      expect(decoded.toString('utf8')).toBe(payload);
     });
   }
 });
@@ -258,13 +266,13 @@ describe('Uint8Array support', () => {
   });
 
   test('encode Uint8Array across all base encodings', () => {
-    const uint8Array = new Uint8Array([1, 2, 3, 4, 5]);
-    const buffer = Buffer.from([1, 2, 3, 4, 5]);
+    const uint8Array = new Uint8Array([1, 2, 3, 4]);
+    const buffer = Buffer.from([1, 2, 3, 4]);
 
     const baseNames = [
-      'decimal', 'base16', 'hex', 'base32', 'base32crockford',
+      'decimal', 'base16', 'hex', 'base32', 'base32hex', 'base32crockford',
       'base36', 'base52', 'base58', 'base64', 'base64url',
-      'ascii85', 'base85', 'z85',
+      'ascii85', 'z85',
     ] as const;
 
     for (const base of baseNames) {