bufferbase 2.0.0 → 3.0.0

package/src/bufferbase.ts

@@ -1,46 +1,45 @@
 /**
- * @deprecated Use the new API instead:
- * - `encode(buffer, 'base58')` or `base58.encode(buffer)`
- * - `decode(encoded, 'base58')` or `base58.decode(encoded)`
- * - `convert(input, 'base58', 'base64')` or `base58.convertTo(base64, input)`
- * - `validate(input, 'base58')` or `base58.validate(input)`
+ * @deprecated Use the current API instead:
+ * - `encode(buffer, 'base58')` or `Codecs.base58.encode(buffer)`
+ * - `decode(encoded, 'base58')` or `Codecs.base58.decode(encoded)`
+ * - `convert(input, 'base58', 'base64')` or `Codecs.base58.convertTo(...)`
+ * - `validate(input, 'base58')` or `Codecs.base58.validate(input)`
+ *
+ * These classes take a bare alphabet, which always meant a radix conversion,
+ * so they keep behaving exactly as they did.
  */
 
-import { Buffer } from 'node:buffer';
-import { Codec } from './codec.js';
-import { InvalidCharacterError, BufferSizeError } from './errors.js';
+import type { Buffer } from 'node:buffer';
+import type { BufferLike } from './types.js';
+import { RadixCodec } from './codec-radix.js';
 
-// Re-export Chars for backward compatibility
+/** @deprecated Import `Chars` from the package root. */
 export { Chars } from './bases.js';
 
-// Re-export errors
-export { InvalidCharacterError, BufferSizeError };
+/** @deprecated Import these from the package root. */
+export { BufferSizeError, InvalidCharacterError } from './errors.js';
 
-/**
- * @deprecated Use `Codec` or `createCodec()` instead.
- */
+/** @deprecated Use `createCodec(alphabet)`. */
 export class BufferEncoder {
-  private codec: Codec;
+  private readonly codec: RadixCodec;
 
-  constructor(private baseChars: string) {
-    this.codec = new Codec(baseChars);
+  constructor(baseChars: string) {
+    this.codec = new RadixCodec({ alphabet: baseChars, algorithm: 'radix' });
   }
 
-  encode(buffer: Buffer): string {
+  encode(buffer: BufferLike): string {
     return this.codec.encode(buffer);
   }
 
   decode(encoded: string, bufferSize?: number): Buffer {
-    return this.codec.decode(encoded, bufferSize !== undefined ? { size: bufferSize } : undefined);
+    return this.codec.decode(encoded, bufferSize === undefined ? undefined : { size: bufferSize });
   }
 }
 
-/**
- * @deprecated Use `convert()` function or `codec.convertTo()` instead.
- */
+/** @deprecated Use `convert()` or `codec.convertTo()`. */
 export class Converter {
-  decoder: BufferEncoder;
-  encoder: BufferEncoder;
+  readonly decoder: BufferEncoder;
+  readonly encoder: BufferEncoder;
 
   constructor(inputBase: string, outputBase: string) {
     this.decoder = new BufferEncoder(inputBase);
@@ -52,24 +51,15 @@ export class Converter {
   }
 }
 
-/**
- * @deprecated Use `validate()` function or `codec.validate()` instead.
- */
+/** @deprecated Use `validate()` or `codec.validate()`. */
 export class Validator {
-  private codec: Codec;
+  private readonly codec: RadixCodec;
 
   constructor(inputBase: string) {
-    this.codec = new Codec(inputBase);
+    this.codec = new RadixCodec({ alphabet: inputBase, algorithm: 'radix' });
   }
 
   validate(input: string): boolean {
     return this.codec.validate(input);
   }
 }
-
-/**
- * @deprecated Use `validate()` from the main module instead.
- */
-export const validate = (input: string, base: string): boolean => {
-  return new Validator(base).validate(input);
-};

package/src/codec-base.ts

@@ -0,0 +1,181 @@
+import { Buffer } from 'node:buffer';
+import type { Algorithm, BufferLike, CodecSpec, DecodeOptions, ICodec } from './types.js';
+import { InvalidCodecError } from './errors.js';
+
+/** Returns one byte per character, or `null` if the alphabet needs more. */
+function singleByteCodes(alphabet: string): Uint8Array | null {
+  const codes = new Uint8Array(alphabet.length);
+  for (let i = 0; i < alphabet.length; i++) {
+    const code = alphabet.charCodeAt(i);
+    if (code > 0xff) {
+      return null;
+    }
+    codes[i] = code;
+  }
+  return codes;
+}
+
+/** Indexes the decodable characters by code unit, or `null` if any needs more than a byte. */
+function codeTable(charToIndex: ReadonlyMap<string, number>): Int16Array | null {
+  const table = new Int16Array(256).fill(-1);
+  for (const [char, value] of charToIndex) {
+    const code = char.charCodeAt(0);
+    if (char.length !== 1 || code > 0xff) {
+      return null;
+    }
+    table[code] = value;
+  }
+  return table;
+}
+
+/** Converts a `BufferLike` to a `Buffer` without copying when possible. */
+export function toBuffer(input: BufferLike): Buffer {
+  return Buffer.isBuffer(input) ? input : Buffer.from(input.buffer, input.byteOffset, input.length);
+}
+
+/**
+ * Shared alphabet handling for the three codec implementations.
+ *
+ * Subclasses provide the mapping between bytes and characters; this class owns
+ * the alphabet, the character lookup, optional case folding, and `convertTo`.
+ */
+export abstract class BaseCodec implements ICodec {
+  /** Character set used for encoding. */
+  readonly chars: string;
+
+  /** The algorithm this codec applies to `chars`. */
+  abstract readonly algorithm: Algorithm;
+
+  /** Whether non-canonical input is rejected. */
+  protected readonly strict: boolean;
+
+  private readonly charToIndex: Map<string, number>;
+
+  /** Characters dropped from the input before decoding. */
+  private readonly ignored: ReadonlySet<string>;
+
+  /**
+   * The alphabet as one byte per character, or `null` when some character does
+   * not fit in a byte.
+   *
+   * Assembling output as bytes and decoding it once is several times faster
+   * than concatenating characters, and every alphabet in practical use is
+   * single-byte.
+   */
+  protected readonly codes: Uint8Array | null;
+
+  /**
+   * The value of every decodable character, indexed by code unit, or `-1`.
+   * `null` when some character does not fit in a byte.
+   *
+   * Reading a character by index and looking it up here avoids allocating a
+   * string and hashing it for every character of the input.
+   */
+  private readonly valueByCode: Int16Array | null;
+
+  protected constructor(spec: CodecSpec) {
+    const { alphabet, strict = true, caseInsensitive = false, aliases, ignore } = spec;
+
+    if (alphabet.length < 2) {
+      throw new InvalidCodecError(`alphabet needs at least 2 characters, got ${alphabet.length}`);
+    }
+    if (new Set(alphabet).size !== alphabet.length) {
+      throw new InvalidCodecError('alphabet contains duplicate characters');
+    }
+    if ([...alphabet].some((char) => char.length !== 1)) {
+      throw new InvalidCodecError('every alphabet character must be a single code unit');
+    }
+    if (caseInsensitive && new Set(alphabet.toLowerCase()).size !== alphabet.length) {
+      throw new InvalidCodecError(
+        'caseInsensitive needs an alphabet that does not contain both cases of a letter',
+      );
+    }
+
+    this.chars = alphabet;
+    this.strict = strict;
+    this.charToIndex = new Map();
+
+    const accept = (char: string, value: number): void => {
+      this.charToIndex.set(char, value);
+      if (caseInsensitive) {
+        this.charToIndex.set(char.toLowerCase(), value);
+        this.charToIndex.set(char.toUpperCase(), value);
+      }
+    };
+
+    for (let i = 0; i < alphabet.length; i++) {
+      accept(alphabet[i], i);
+    }
+
+    for (const [from, to] of Object.entries(aliases ?? {})) {
+      if (from.length !== 1) {
+        throw new InvalidCodecError(`alias '${from}' must be a single character`);
+      }
+      const value = this.charToIndex.get(to);
+      if (value === undefined) {
+        throw new InvalidCodecError(`alias '${from}' points at '${to}', which is not in the alphabet`);
+      }
+      if (alphabet.includes(from)) {
+        throw new InvalidCodecError(`alias '${from}' is already in the alphabet`);
+      }
+      accept(from, value);
+    }
+
+    this.codes = singleByteCodes(alphabet);
+    this.valueByCode = codeTable(this.charToIndex);
+    this.ignored = new Set(ignore ?? '');
+    for (const char of this.ignored) {
+      if (this.charToIndex.has(char)) {
+        throw new InvalidCodecError(`ignored character '${char}' is also decodable`);
+      }
+    }
+  }
+
+  /** Reads the first `length` bytes of `written` back as text. */
+  protected textFrom(written: Uint8Array, length: number): string {
+    return Buffer.from(written.buffer, written.byteOffset, length).toString('latin1');
+  }
+
+  /** Drops the characters this codec ignores, such as readability hyphens. */
+  protected strip(input: string): string {
+    if (this.ignored.size === 0) {
+      return input;
+    }
+    let out = '';
+    for (let i = 0; i < input.length; i++) {
+      const char = input[i];
+      if (!this.ignored.has(char)) {
+        out += char;
+      }
+    }
+    return out;
+  }
+
+  /** Returns the value of a character, or `undefined` if it is not in the alphabet. */
+  protected valueOf(char: string): number | undefined {
+    return this.charToIndex.get(char);
+  }
+
+  /**
+   * Returns the value of the character at `index`, or `-1` if it is not
+   * decodable. This is the hot path of every decoder.
+   */
+  protected valueAt(input: string, index: number): number {
+    const table = this.valueByCode;
+    if (table === null) {
+      const value = this.charToIndex.get(input[index]);
+      return value === undefined ? -1 : value;
+    }
+    const code = input.charCodeAt(index);
+    return code > 0xff ? -1 : table[code];
+  }
+
+  abstract encode(buffer: BufferLike): string;
+  abstract decode(encoded: string, options?: DecodeOptions): Buffer;
+  abstract validate(input: string): boolean;
+
+  /** Decodes with this codec, then re-encodes with `target`. */
+  convertTo(target: ICodec, input: string): string {
+    return target.encode(this.decode(input));
+  }
+}

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