bufferbase 2.0.0 → 3.0.0

package/src/codec.ts

@@ -1,266 +1,67 @@
-import { Buffer } from 'node:buffer';
-import type { ICodec, DecodeOptions, BufferLike } from './types.js';
-import { InvalidCharacterError, BufferSizeError } from './errors.js';
+import type { CodecSpec, ICodec } from './types.js';
+import { RadixCodec } from './codec-radix.js';
+import { BlockCodec } from './codec-block.js';
+import { Block85Codec } from './codec-block85.js';
 
 /**
- * Converts a BufferLike (Buffer or Uint8Array) to a Buffer.
- * @internal
- */
-function toBuffer(input: BufferLike): Buffer {
-  if (Buffer.isBuffer(input)) {
-    return input;
-  }
-  return Buffer.from(input);
-}
-
-/**
- * Codec for encoding and decoding buffers to/from a specific base.
+ * Builds the codec described by a spec.
  *
- * Use pre-defined codecs from `Codecs` for common encodings,
- * or create custom codecs with `createCodec()`.
+ * A bare string is read as a custom alphabet for a radix conversion, which is
+ * the only algorithm that works with an alphabet of any length.
  *
  * @example
  * ```typescript
- * import { Codec, Codecs, createCodec } from 'bufferbase';
- *
- * // Use pre-defined codec
- * const encoded = Codecs.base58.encode(Buffer.from('Hello'));
+ * import { createCodec } from 'bufferbase';
  *
- * // Create custom codec
  * const binary = createCodec('01');
- * const bits = binary.encode(Buffer.from([5])); // '101'
+ * binary.encode(Uint8Array.of(5)); // '101'
+ *
+ * const paddedHex = createCodec({ alphabet: '0123456789abcdef', algorithm: 'block' });
+ * paddedHex.encode(Uint8Array.of(0, 1)); // '0001'
  * ```
  */
-export class Codec implements ICodec {
-  /** Character set used for encoding. */
-  readonly chars: string;
-
-  /** @internal */
-  private readonly charToIndex: Map<string, number>;
-
-  /**
-   * Creates a new codec with the specified character set.
-   * @param chars - The character set to use for encoding/decoding
-   */
-  constructor(chars: string) {
-    this.chars = chars;
-    this.charToIndex = new Map();
-    for (let i = 0; i < chars.length; i++) {
-      this.charToIndex.set(chars[i], i);
-    }
-  }
-
-  /**
-   * Encodes a buffer to a base-encoded string.
-   *
-   * Leading zero bytes in the buffer are preserved as the first character
-   * of the encoding alphabet (e.g., '1' for Base58).
-   *
-   * @param input - The buffer or Uint8Array to encode
-   * @returns Base-encoded string
-   *
-   * @example
-   * ```typescript
-   * const codec = Codecs.base58;
-   * codec.encode(Buffer.from('Hello')); // '9Ajdvzr'
-   * codec.encode(new Uint8Array([0, 0, 1])); // '112' (preserves leading zeros)
-   * ```
-   */
-  encode(input: BufferLike): string {
-    const buffer = toBuffer(input);
-    if (buffer.length === 0) {
-      return '';
-    }
-
-    const base = this.chars.length;
-    const result: number[] = [];
-
-    // Count leading zeros
-    let leadingZeros = 0;
-    for (const byte of buffer) {
-      if (byte === 0) {
-        leadingZeros++;
-      } else {
-        break;
-      }
-    }
-
-    // Convert to base
-    for (const byte of buffer) {
-      let carry = byte;
-      for (let j = 0; j < result.length; j++) {
-        carry += result[j] * 256;
-        result[j] = carry % base;
-        carry = Math.floor(carry / base);
-      }
-      while (carry > 0) {
-        result.push(carry % base);
-        carry = Math.floor(carry / base);
-      }
-    }
-
-    // Add leading zeros
-    for (let i = 0; i < leadingZeros; i++) {
-      result.push(0);
-    }
-
-    // Reverse and convert to string
-    return result
-      .reverse()
-      .map((index) => this.chars[index])
-      .join('');
-  }
-
-  /**
-   * Decodes a base-encoded string to a buffer.
-   *
-   * Leading characters that represent zero (first char of alphabet)
-   * are converted to leading zero bytes in the result.
-   *
-   * @param encoded - The string to decode
-   * @param options - Decode options
-   * @returns Decoded buffer
-   * @throws {InvalidCharacterError} If the string contains invalid characters
-   * @throws {BufferSizeError} If the result exceeds the specified size
-   *
-   * @example
-   * ```typescript
-   * const codec = Codecs.base58;
-   * codec.decode('9Ajdvzr'); // Buffer('Hello')
-   * codec.decode('9Ajdvzr', { size: 32 }); // Pads to 32 bytes
-   * ```
-   */
-  decode(encoded: string, options?: DecodeOptions): Buffer {
-    if (encoded.length === 0) {
-      if (options?.size !== undefined && options.size > 0) {
-        return Buffer.alloc(options.size);
-      }
-      return Buffer.alloc(0);
-    }
-
-    const base = this.chars.length;
-    const zeroChar = this.chars[0];
-
-    // Count leading zeros in encoded string
-    let leadingZeros = 0;
-    for (const char of encoded) {
-      if (char === zeroChar) {
-        leadingZeros++;
-      } else {
-        break;
-      }
-    }
-
-    // Convert from base
-    const result: number[] = [];
-    for (const char of encoded) {
-      const value = this.charToIndex.get(char);
-      if (value === undefined) {
-        throw new InvalidCharacterError(char);
-      }
-
-      let carry = value;
-      for (let i = 0; i < result.length; i++) {
-        carry += result[i] * base;
-        result[i] = carry % 256;
-        carry = Math.floor(carry / 256);
-      }
-      while (carry > 0) {
-        result.push(carry % 256);
-        carry = Math.floor(carry / 256);
-      }
-    }
-
-    // Add leading zeros
-    for (let i = 0; i < leadingZeros; i++) {
-      result.push(0);
-    }
-
-    result.reverse();
-
-    // Handle size option
-    const size = options?.size;
-    if (size !== undefined) {
-      if (result.length > size) {
-        throw new BufferSizeError(result.length, size);
-      }
-      if (result.length < size) {
-        // Pad with leading zeros
-        const padded = new Array(size - result.length).fill(0).concat(result);
-        return Buffer.from(padded);
-      }
-    }
-
-    return Buffer.from(result);
+export function createCodec(spec: CodecSpec | string): ICodec {
+  const resolved: CodecSpec =
+    typeof spec === 'string' ? { alphabet: spec, algorithm: 'radix' } : spec;
+
+  switch (resolved.algorithm) {
+    case 'radix':
+      return new RadixCodec(resolved);
+    case 'block':
+      return new BlockCodec(resolved);
+    case 'block85':
+      return new Block85Codec(resolved);
   }
+}
 
-  /**
-   * Validates if a string contains only valid characters for this base.
-   *
-   * This is a fast check that doesn't perform full decoding.
-   *
-   * @param input - The string to validate
-   * @returns `true` if all characters are valid, `false` otherwise
-   *
-   * @example
-   * ```typescript
-   * Codecs.base58.validate('9Ajdvzr'); // true
-   * Codecs.base58.validate('0invalid'); // false ('0' not in Base58)
-   * ```
-   */
-  validate(input: string): boolean {
-    for (const char of input) {
-      if (!this.charToIndex.has(char)) {
-        return false;
-      }
-    }
-    return true;
-  }
+const cache = new WeakMap<CodecSpec, ICodec>();
 
-  /**
-   * Converts a string from this base to another base.
-   *
-   * Internally decodes to a buffer, then encodes with the target codec.
-   *
-   * @param target - Target codec to convert to
-   * @param input - The string to convert
-   * @returns String in the target base encoding
-   * @throws {InvalidCharacterError} If the input contains invalid characters
-   *
-   * @example
-   * ```typescript
-   * const base58str = '9Ajdvzr';
-   * const base64str = Codecs.base58.convertTo(Codecs.base64url, base58str);
-   * ```
-   */
-  convertTo(target: ICodec, input: string): string {
-    const buffer = this.decode(input);
-    return target.encode(buffer);
+/**
+ * Returns the codec for a spec, building it once per spec object.
+ *
+ * Named bases always resolve to the same spec object, so they are built once
+ * for the lifetime of the process.
+ */
+export function getCodec(spec: CodecSpec): ICodec {
+  const cached = cache.get(spec);
+  if (cached !== undefined) {
+    return cached;
   }
+  const codec = createCodec(spec);
+  cache.set(spec, codec);
+  return codec;
 }
 
+export { RadixCodec } from './codec-radix.js';
+export { BlockCodec } from './codec-block.js';
+export { Block85Codec } from './codec-block85.js';
+
 /**
- * Creates a new codec with the specified character set.
- *
- * Use this to create codecs for custom base encodings.
- * The base is determined by the length of the character set.
- *
- * @param chars - The character set to use for encoding/decoding
- * @returns A new Codec instance
- *
- * @example
- * ```typescript
- * import { createCodec } from 'bufferbase';
- *
- * // Binary codec (base 2)
- * const binary = createCodec('01');
- * binary.encode(Buffer.from([5])); // '101'
- *
- * // Octal codec (base 8)
- * const octal = createCodec('01234567');
- * octal.encode(Buffer.from([255])); // '377'
- * ```
+ * @deprecated Use `createCodec({ alphabet, algorithm: 'radix' })`, or
+ * `createCodec(alphabet)` for the same thing.
  */
-export function createCodec(chars: string): Codec {
-  return new Codec(chars);
+export class Codec extends RadixCodec {
+  constructor(chars: string) {
+    super({ alphabet: chars, algorithm: 'radix' });
+  }
 }

package/src/codecs.ts

@@ -1,118 +1,24 @@
-import { Codec } from './codec.js';
-import { Chars } from './bases.js';
-
-/** Decimal (base 10) codec: 0-9 */
-const decimal = new Codec(Chars.Decimal);
-
-/** Hexadecimal (base 16) codec: 0-9A-F */
-const base16 = new Codec(Chars.Base16);
-
-/** Alias for base16 */
-const hex = base16;
-
-/** RFC 4648 Base32 codec: A-Z2-7 */
-const base32 = new Codec(Chars.Base32);
-
-/** Crockford's Base32 codec: 0-9A-HJKMNP-TV-Z (no I, L, O, U) */
-const base32crockford = new Codec(Chars.Base32Crockford);
-
-/** Base36 codec: 0-9A-Z */
-const base36 = new Codec(Chars.Base36);
-
-/** Base52 codec: A-Za-z (letters only) */
-const base52 = new Codec(Chars.Base52);
-
-/** Bitcoin Base58 codec: 1-9A-HJ-NP-Za-km-z (no 0, O, I, l) */
-const base58 = new Codec(Chars.Base58);
-
-/** Standard Base64 codec: A-Za-z0-9+/ */
-const base64 = new Codec(Chars.Base64);
-
-/** URL-safe Base64 codec: A-Za-z0-9-_ */
-const base64url = new Codec(Chars.Base64Url);
-
-/** XML token Base64 codec: A-Za-z0-9._ */
-const base64xml = new Codec(Chars.Base64Xml);
-
-/** XML name Base64 codec: A-Za-z0-9_: */
-const base64xmlname = new Codec(Chars.Base64XmlName);
-
-/** ASCII85 codec */
-const ascii85 = new Codec(Chars.Ascii85);
-
-/** Base85 codec */
-const base85 = new Codec(Chars.Base85);
-
-/** ZeroMQ Z85 codec */
-const z85 = new Codec(Chars.Z85);
+import type { ICodec } from './types.js';
+import { Bases, type BaseName } from './bases.js';
+import { getCodec } from './codec.js';
 
 /**
- * Pre-defined codec instances for common base encodings.
- *
- * Use these for encoding/decoding without creating codec instances manually.
- * Each codec provides `encode()`, `decode()`, `validate()`, and `convertTo()` methods.
+ * A ready-made codec for every name in `Bases`.
  *
  * @example
  * ```typescript
  * import { Codecs } from 'bufferbase';
  *
- * // Encode to Base58
- * const encoded = Codecs.base58.encode(Buffer.from('Hello'));
- *
- * // Decode from Base58
- * const decoded = Codecs.base58.decode(encoded);
- *
- * // Convert between bases
- * const base64 = Codecs.base58.convertTo(Codecs.base64url, encoded);
- *
- * // Validate
- * Codecs.base58.validate(encoded); // true
+ * Codecs.base58.encode(Buffer.from('Hello'));      // '9Ajdvzr'
+ * Codecs.base64.encode(Buffer.from('fo'));         // 'Zm8='
+ * Codecs.base58.convertTo(Codecs.base64url, '9Ajdvzr');
  * ```
- *
- * Available codecs:
- * - `decimal` - Base 10 (0-9)
- * - `base16` / `hex` - Hexadecimal (0-9A-F)
- * - `base32` - RFC 4648 Base32 (A-Z2-7)
- * - `base32crockford` - Crockford's Base32
- * - `base36` - Alphanumeric (0-9A-Z)
- * - `base52` - Letters only (A-Za-z)
- * - `base58` - Bitcoin alphabet
- * - `base64` - Standard Base64
- * - `base64url` - URL-safe Base64
- * - `base64xml` - XML token Base64
- * - `base64xmlname` - XML name Base64
- * - `ascii85` - ASCII85 encoding
- * - `base85` - Base85 encoding
- * - `z85` - ZeroMQ Z85 encoding
  */
-export const Codecs = {
-  decimal,
-  base16,
-  hex,
-  base32,
-  base32crockford,
-  base36,
-  base52,
-  base58,
-  base64,
-  base64url,
-  base64xml,
-  base64xmlname,
-  ascii85,
-  base85,
-  z85,
-} as const;
+export const Codecs = Object.fromEntries(
+  Object.entries(Bases).map(([name, spec]) => [name, getCodec(spec)]),
+) as Record<BaseName, ICodec>;
 
 /**
  * Type representing valid codec names in the `Codecs` object.
- *
- * @example
- * ```typescript
- * import { Codecs, CodecName } from 'bufferbase';
- *
- * function getCodec(name: CodecName) {
- *   return Codecs[name];
- * }
- * ```
  */
-export type CodecName = keyof typeof Codecs;
+export type CodecName = BaseName;

package/src/errors.ts

@@ -1,18 +1,5 @@
 /**
  * Error thrown when an invalid character is encountered during decoding.
- *
- * @example
- * ```typescript
- * import { decode, InvalidCharacterError } from 'bufferbase';
- *
- * try {
- *   decode('invalid!', 'base58');
- * } catch (e) {
- *   if (e instanceof InvalidCharacterError) {
- *     console.log(e.message); // "Invalid character found: '!'"
- *   }
- * }
- * ```
  */
 export class InvalidCharacterError extends Error {
   /**
@@ -26,24 +13,8 @@ export class InvalidCharacterError extends Error {
 }
 
 /**
- * Error thrown when decoded buffer size exceeds the specified size.
- *
- * This error is thrown when using the `size` option in decode operations
- * and the decoded data is larger than the specified size.
- *
- * @example
- * ```typescript
- * import { decode, BufferSizeError } from 'bufferbase';
- *
- * try {
- *   // Trying to decode into a buffer too small
- *   decode('72k1xXWG59fYdzSNoA', 'base58', { size: 2 });
- * } catch (e) {
- *   if (e instanceof BufferSizeError) {
- *     console.log(e.message); // "Buffer size 13 exceeds specified size 2"
- *   }
- * }
- * ```
+ * Error thrown when the decoded buffer does not have the size requested
+ * through `DecodeOptions.size`.
  */
 export class BufferSizeError extends Error {
   /**
@@ -51,37 +22,106 @@ export class BufferSizeError extends Error {
    * @param expected - The expected (specified) buffer size
    */
   constructor(actual: number, expected: number) {
-    super(`Buffer size ${actual} exceeds specified size ${expected}`);
+    super(`Buffer size ${actual} does not match specified size ${expected}`);
     this.name = 'BufferSizeError';
   }
 }
 
 /**
  * Error thrown when an unknown base name is provided.
- *
- * This error is thrown when using the function API with an invalid base name
- * that is neither a known encoding name nor a valid custom character set
- * (character sets must be longer than 15 characters).
- *
- * @example
- * ```typescript
- * import { encode, UnknownBaseError } from 'bufferbase';
- *
- * try {
- *   encode(Buffer.from('test'), 'invalidbase');
- * } catch (e) {
- *   if (e instanceof UnknownBaseError) {
- *     console.log(e.message); // "Unknown base encoding: 'invalidbase'"
- *   }
- * }
- * ```
  */
 export class UnknownBaseError extends Error {
   /**
    * @param name - The unknown base name that was provided
    */
   constructor(name: string) {
-    super(`Unknown base encoding: '${name}'`);
+    super(
+      `Unknown base encoding: '${name}'. ` +
+        'Pass a CodecSpec such as { alphabet, algorithm: \'radix\' } to use a custom alphabet.',
+    );
     this.name = 'UnknownBaseError';
   }
 }
+
+/**
+ * Error thrown when a string cannot be the encoding of any byte sequence
+ * because of its length.
+ *
+ * A Base64 string of 5 characters, for example, describes 30 bits: too many
+ * for 3 bytes and too few for 4.
+ */
+export class InvalidLengthError extends Error {
+  /**
+   * @param length - The length that cannot occur
+   * @param detail - What the length should have been
+   */
+  constructor(length: number, detail: string) {
+    super(`Invalid encoded length ${length}: ${detail}`);
+    this.name = 'InvalidLengthError';
+  }
+}
+
+/**
+ * Error thrown when input is well-formed but is not the canonical encoding of
+ * the bytes it decodes to (RFC 4648 §3.5).
+ *
+ * Accepting such input makes decoding non-injective: `'Zm8='` and `'Zm9='`
+ * would both decode to `'fo'`. Pass `strict: false` in the codec spec to allow
+ * it.
+ */
+export class NonCanonicalError extends Error {
+  /**
+   * @param detail - What made the input non-canonical
+   */
+  constructor(detail: string) {
+    super(`Non-canonical encoding: ${detail}`);
+    this.name = 'NonCanonicalError';
+  }
+}
+
+/**
+ * Error thrown when a codec spec cannot be realised, such as a `'block'`
+ * algorithm with an alphabet whose length is not a power of two.
+ */
+export class InvalidCodecError extends Error {
+  /**
+   * @param detail - Why the spec is unusable
+   */
+  constructor(detail: string) {
+    super(`Invalid codec: ${detail}`);
+    this.name = 'InvalidCodecError';
+  }
+}
+
+/**
+ * Error thrown when a group of characters denotes a number too large for the
+ * bytes it is supposed to encode.
+ *
+ * In an Ascii85 group, five characters must denote a value below 2^32; `'s8W-!'`
+ * does not, so it encodes nothing. Unlike `NonCanonicalError` this is never
+ * allowed, because there is no byte sequence to decode to.
+ */
+export class ValueRangeError extends Error {
+  /**
+   * @param group - The group of characters that is out of range
+   */
+  constructor(group: string) {
+    super(`Encoded group '${group}' exceeds the maximum value for its block`);
+    this.name = 'ValueRangeError';
+  }
+}
+
+/**
+ * Error thrown when a trailing check symbol does not match the value it
+ * follows, which means the string was mistyped or corrupted.
+ */
+export class CheckSymbolError extends Error {
+  /**
+   * @param found - The check symbol present in the input
+   * @param expected - The check symbol the value calls for
+   */
+  constructor(found: string, expected: string) {
+    super(`Check symbol '${found}' does not match the expected '${expected}'`);
+    this.name = 'CheckSymbolError';
+  }
+}

package/src/example.ts

@@ -1,33 +1,58 @@
 import { Buffer } from 'node:buffer';
-import { encode, decode, convert, validate, Codecs } from './index.js';
+import { encode, decode, convert, validate, createCodec, Chars, Codecs } from './index.js';
 
-// Example buffer
 const bytes = Buffer.from('Hello, World!', 'utf8');
 
-// Using simple function API
-const base32encoded = encode(bytes, 'base32crockford');
-const base58encoded = convert(base32encoded, 'base32crockford', 'base58');
-const base64encoded = convert(base58encoded, 'base58', 'base64url');
-const isValidAsBase64 = validate(base64encoded, 'base64url');
-const decoded = decode(base64encoded, 'base64url');
+// The same bytes under each algorithm.
+console.log('=== Algorithms ===');
+console.table({
+  'block   base64': encode(bytes, 'base64'),
+  'block   base32': encode(bytes, 'base32'),
+  'block85 ascii85': encode(bytes, 'ascii85'),
+  'radix   base58': encode(bytes, 'base58'),
+  'radix   base32crockford': encode(bytes, 'base32crockford'),
+});
 
-console.log('=== Function API ===');
+// Converting goes through the bytes, so any pair works.
+console.log('\n=== Function API ===');
+const base58 = encode(bytes, 'base58');
+const base64url = convert(base58, 'base58', 'base64url');
 console.table({
   bytes: bytes.toString('utf8'),
-  base32encoded,
-  base58encoded,
-  base64encoded,
-  isValidAsBase64,
-  decoded: decoded.toString('utf8'),
+  base58,
+  base64url,
+  valid: validate(base64url, 'base64url'),
+  decoded: decode(base64url, 'base64url').toString('utf8'),
+});
+
+// validate() agrees with decode(): it checks length, padding and canonicality.
+console.log('\n=== Rejected input ===');
+console.table({
+  "'Zm8=' (canonical)": validate('Zm8=', 'base64'),
+  "'Zm9=' (spare bits set)": validate('Zm9=', 'base64'),
+  "'Zm9vd' (5 characters)": validate('Zm9vd', 'base64'),
 });
 
-// Using Codecs object
-console.log('\n=== Codecs API ===');
-const encoded = Codecs.base58.encode(bytes);
-const converted = Codecs.base58.convertTo(Codecs.base64url, encoded);
+// Crockford's Base32 reads what a person is likely to have written down.
+console.log('\n=== Crockford ===');
+const crockford = encode(bytes, 'base32crockfordcheck');
+console.table({
+  encoded: crockford,
+  'as typed': decode(`${crockford.slice(0, 4)}-${crockford.slice(4)}`.toLowerCase(), 'base32crockfordcheck').toString('utf8'),
+  'one character changed': validate(`${crockford.slice(0, -2)}Z${crockford.slice(-1)}`, 'base32crockfordcheck'),
+});
+
+// Codecs, and a custom alphabet.
+console.log('\n=== Codecs and custom alphabets ===');
+const binary = createCodec('01');
+const adobe = createCodec({
+  alphabet: Chars.Ascii85,
+  algorithm: 'block85',
+  zeroShortcut: true,
+  delimiters: true,
+});
 console.table({
-  original: bytes.toString('utf8'),
-  base58: encoded,
-  base64url: converted,
-  valid: Codecs.base64url.validate(converted),
+  'Codecs.base58': Codecs.base58.encode(bytes),
+  'binary of [5]': binary.encode(Uint8Array.of(5)),
+  'adobe ascii85': adobe.encode(bytes),
 });