bufferbase 1.3.0 → 3.0.0

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

@@ -0,0 +1,328 @@
+import { Buffer } from 'node:buffer';
+import { describe, test, expect } from 'bun:test';
+
+import {
+  encode,
+  decode,
+  convert,
+  validate,
+  createCodec,
+  Codecs,
+  Chars,
+  InvalidCharacterError,
+  BufferSizeError,
+  UnknownBaseError,
+} from './index.js';
+
+describe('Function API', () => {
+  test('encode/decode round-trip with base name', () => {
+    const buffer = Buffer.from('Hello, World!', 'utf8');
+    const encoded = encode(buffer, 'base58');
+    const decoded = decode(encoded, 'base58');
+    expect(decoded.toString('utf8')).toBe('Hello, World!');
+  });
+
+  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, 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');
+    const converted = convert(base58Encoded, 'base58', 'base64url');
+    const expected = encode(buffer, 'base64url');
+    expect(converted).toBe(expected);
+  });
+
+  test('validate returns true for valid input', () => {
+    expect(validate('9Ajdvz', 'base58')).toBe(true);
+  });
+
+  test('validate returns false for invalid input', () => {
+    expect(validate('0Ajdvz', 'base58')).toBe(false);
+  });
+
+  test('decode with size option pads buffer', () => {
+    const buffer = Buffer.from([1, 2, 3]);
+    const encoded = encode(buffer, 'base58');
+    const decoded = decode(encoded, 'base58', { size: 8 });
+    expect(decoded.length).toBe(8);
+    expect(decoded).toEqual(Buffer.from([0, 0, 0, 0, 0, 1, 2, 3]));
+  });
+
+  test('decode with size option throws on overflow', () => {
+    const buffer = Buffer.from([1, 2, 3, 4, 5]);
+    const encoded = encode(buffer, 'base58');
+    expect(() => {
+      decode(encoded, 'base58', { size: 3 });
+    }).toThrow(BufferSizeError);
+  });
+
+  test('throws UnknownBaseError for invalid base name', () => {
+    expect(() => {
+      encode(Buffer.from('test'), 'invalid');
+    }).toThrow(UnknownBaseError);
+  });
+});
+
+describe('Codecs object', () => {
+  test('Codecs.base58.encode/decode round-trip', () => {
+    const buffer = Buffer.from('Hello, World!', 'utf8');
+    const encoded = Codecs.base58.encode(buffer);
+    const decoded = Codecs.base58.decode(encoded);
+    expect(decoded.toString('utf8')).toBe('Hello, World!');
+  });
+
+  test('Codecs.base64url.encode/decode round-trip', () => {
+    const buffer = Buffer.from('Hello, World!', 'utf8');
+    const encoded = Codecs.base64url.encode(buffer);
+    const decoded = Codecs.base64url.decode(encoded);
+    expect(decoded.toString('utf8')).toBe('Hello, World!');
+  });
+
+  test('Codecs.base58.convertTo', () => {
+    const buffer = Buffer.from('Test', 'utf8');
+    const base58Encoded = Codecs.base58.encode(buffer);
+    const converted = Codecs.base58.convertTo(Codecs.base64url, base58Encoded);
+    expect(converted).toBe(Codecs.base64url.encode(buffer));
+  });
+
+  test('Codecs.base58.validate', () => {
+    expect(Codecs.base58.validate('123abc')).toBe(true);
+    expect(Codecs.base58.validate('0abc')).toBe(false);
+  });
+});
+
+describe('createCodec', () => {
+  test('creates custom codec', () => {
+    const binary = createCodec('01');
+    const buffer = Buffer.from([5]);
+    const encoded = binary.encode(buffer);
+    expect(encoded).toBe('101');
+    const decoded = binary.decode(encoded);
+    expect(decoded).toEqual(Buffer.from([5]));
+  });
+});
+
+describe('Edge cases', () => {
+  test('empty buffer', () => {
+    const buffer = Buffer.alloc(0);
+    const encoded = encode(buffer, 'base58');
+    expect(encoded).toBe('');
+    const decoded = decode(encoded, 'base58');
+    expect(decoded.length).toBe(0);
+  });
+
+  test('empty string with size option', () => {
+    const decoded = decode('', 'base58', { size: 4 });
+    expect(decoded).toEqual(Buffer.from([0, 0, 0, 0]));
+  });
+
+  test('leading zero bytes preserved', () => {
+    const buffer = Buffer.from([0, 0, 1, 2, 3]);
+    const encoded = encode(buffer, 'base58');
+    const decoded = decode(encoded, 'base58');
+    expect(decoded).toEqual(buffer);
+  });
+
+  test('multiple leading zeros', () => {
+    const buffer = Buffer.from([0, 0, 0, 0, 255]);
+    const encoded = encode(buffer, 'base58');
+    const decoded = decode(encoded, 'base58');
+    expect(decoded).toEqual(buffer);
+  });
+
+  test('all zeros', () => {
+    const buffer = Buffer.from([0, 0, 0]);
+    const encoded = encode(buffer, 'base58');
+    const decoded = decode(encoded, 'base58');
+    expect(decoded).toEqual(buffer);
+  });
+
+  test('single byte values', () => {
+    for (let i = 0; i < 256; i++) {
+      const buffer = Buffer.from([i]);
+      const encoded = encode(buffer, 'base58');
+      const decoded = decode(encoded, 'base58');
+      expect(decoded).toEqual(buffer);
+    }
+  });
+
+  test('long buffer', () => {
+    const buffer = Buffer.from('Hello, World!'.repeat(100), 'utf8');
+    const encoded = encode(buffer, 'base58');
+    const decoded = decode(encoded, 'base58');
+    expect(decoded.toString('utf8')).toBe('Hello, World!'.repeat(100));
+  });
+
+  test('binary powers from 0 to 63', () => {
+    for (let i = 0; i < 64; i++) {
+      const buffer = Buffer.alloc(8);
+      const num = BigInt(2) ** BigInt(i) - BigInt(1);
+      buffer.writeBigInt64BE(num);
+      const encoded = encode(buffer, 'base58');
+      const decoded = decode(encoded, 'base58', { size: 8 });
+      const result = decoded.readBigInt64BE();
+      expect(result).toBe(num);
+    }
+  });
+});
+
+describe('All character sets', () => {
+  const baseNames = [
+    'decimal',
+    'base16',
+    'hex',
+    'base32',
+    'base32crockford',
+    'base36',
+    'base52',
+    'base58',
+    'base64',
+    'base64url',
+    'base32hex',
+    'ascii85',
+    '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(payload, 'utf8');
+      const encoded = encode(buffer, base);
+      const decoded = decode(encoded, base);
+      expect(decoded.toString('utf8')).toBe(payload);
+    });
+  }
+});
+
+describe('Error handling', () => {
+  test('InvalidCharacterError on decode', () => {
+    expect(() => {
+      decode('Invalid!String', 'base58');
+    }).toThrow(InvalidCharacterError);
+  });
+
+  test('InvalidCharacterError includes character', () => {
+    try {
+      decode('abc!def', 'base58');
+      expect(true).toBe(false);
+    } catch (e) {
+      expect(e).toBeInstanceOf(InvalidCharacterError);
+      expect((e as Error).message).toContain('!');
+    }
+  });
+});
+
+describe('Uint8Array support', () => {
+  test('encode Uint8Array with function API', () => {
+    const uint8Array = new Uint8Array([72, 101, 108, 108, 111]); // 'Hello'
+    const buffer = Buffer.from('Hello', 'utf8');
+
+    const encodedFromUint8 = encode(uint8Array, 'base58');
+    const encodedFromBuffer = encode(buffer, 'base58');
+
+    expect(encodedFromUint8).toBe(encodedFromBuffer);
+  });
+
+  test('encode Uint8Array with Codecs object', () => {
+    const uint8Array = new Uint8Array([72, 101, 108, 108, 111]); // 'Hello'
+    const buffer = Buffer.from('Hello', 'utf8');
+
+    const encodedFromUint8 = Codecs.base58.encode(uint8Array);
+    const encodedFromBuffer = Codecs.base58.encode(buffer);
+
+    expect(encodedFromUint8).toBe(encodedFromBuffer);
+  });
+
+  test('encode empty Uint8Array', () => {
+    const uint8Array = new Uint8Array(0);
+    const encoded = encode(uint8Array, 'base58');
+    expect(encoded).toBe('');
+  });
+
+  test('encode Uint8Array with leading zeros', () => {
+    const uint8Array = new Uint8Array([0, 0, 1, 2, 3]);
+    const encoded = encode(uint8Array, 'base58');
+    const decoded = decode(encoded, 'base58');
+    expect(Array.from(decoded)).toEqual([0, 0, 1, 2, 3]);
+  });
+
+  test('encode Uint8Array all zeros', () => {
+    const uint8Array = new Uint8Array([0, 0, 0]);
+    const encoded = encode(uint8Array, 'base58');
+    const decoded = decode(encoded, 'base58');
+    expect(Array.from(decoded)).toEqual([0, 0, 0]);
+  });
+
+  test('encode Uint8Array across all base encodings', () => {
+    const uint8Array = new Uint8Array([1, 2, 3, 4]);
+    const buffer = Buffer.from([1, 2, 3, 4]);
+
+    const baseNames = [
+      'decimal', 'base16', 'hex', 'base32', 'base32hex', 'base32crockford',
+      'base36', 'base52', 'base58', 'base64', 'base64url',
+      'ascii85', 'z85',
+    ] as const;
+
+    for (const base of baseNames) {
+      const encodedFromUint8 = encode(uint8Array, base);
+      const encodedFromBuffer = encode(buffer, base);
+      expect(encodedFromUint8).toBe(encodedFromBuffer);
+    }
+  });
+
+  test('custom codec with Uint8Array', () => {
+    const binary = createCodec('01');
+    const uint8Array = new Uint8Array([5]);
+    const encoded = binary.encode(uint8Array);
+    expect(encoded).toBe('101');
+  });
+});
+
+describe('Backward compatibility', () => {
+  test('BufferEncoder works', async () => {
+    const { BufferEncoder, Chars } = await import('./bufferbase.js');
+    const encoder = new BufferEncoder(Chars.Base58);
+    const buffer = Buffer.from('Hello', 'utf8');
+    const encoded = encoder.encode(buffer);
+    const decoded = encoder.decode(encoded);
+    expect(decoded.toString('utf8')).toBe('Hello');
+  });
+
+  test('BufferEncoder with bufferSize', async () => {
+    const { BufferEncoder, Chars } = await import('./bufferbase.js');
+    const encoder = new BufferEncoder(Chars.Base58);
+    const buffer = Buffer.alloc(0);
+    const encoded = encoder.encode(buffer);
+    const decoded = encoder.decode(encoded, 4);
+    expect(decoded.toString('hex')).toBe('00000000');
+  });
+
+  test('Converter works', async () => {
+    const { BufferEncoder, Converter, Chars } = await import('./bufferbase.js');
+    const converter = new Converter(Chars.Base58, Chars.Base64);
+    const buffer = Buffer.from('Test', 'utf8');
+    const base58Encoded = new BufferEncoder(Chars.Base58).encode(buffer);
+    const converted = converter.convert(base58Encoded);
+    const expected = new BufferEncoder(Chars.Base64).encode(buffer);
+    expect(converted).toBe(expected);
+  });
+
+  test('Validator works', async () => {
+    const { Validator, Chars } = await import('./bufferbase.js');
+    const validator = new Validator(Chars.Base58);
+    expect(validator.validate('123abc')).toBe(true);
+    expect(validator.validate('0abc')).toBe(false);
+  });
+});

package/src/codec.ts

@@ -0,0 +1,67 @@
+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';
+
+/**
+ * Builds the codec described by a spec.
+ *
+ * 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 { createCodec } from 'bufferbase';
+ *
+ * const binary = createCodec('01');
+ * binary.encode(Uint8Array.of(5)); // '101'
+ *
+ * const paddedHex = createCodec({ alphabet: '0123456789abcdef', algorithm: 'block' });
+ * paddedHex.encode(Uint8Array.of(0, 1)); // '0001'
+ * ```
+ */
+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);
+  }
+}
+
+const cache = new WeakMap<CodecSpec, ICodec>();
+
+/**
+ * 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';
+
+/**
+ * @deprecated Use `createCodec({ alphabet, algorithm: 'radix' })`, or
+ * `createCodec(alphabet)` for the same thing.
+ */
+export class Codec extends RadixCodec {
+  constructor(chars: string) {
+    super({ alphabet: chars, algorithm: 'radix' });
+  }
+}

package/src/codecs.ts

@@ -0,0 +1,24 @@
+import type { ICodec } from './types.js';
+import { Bases, type BaseName } from './bases.js';
+import { getCodec } from './codec.js';
+
+/**
+ * A ready-made codec for every name in `Bases`.
+ *
+ * @example
+ * ```typescript
+ * import { Codecs } from 'bufferbase';
+ *
+ * Codecs.base58.encode(Buffer.from('Hello'));      // '9Ajdvzr'
+ * Codecs.base64.encode(Buffer.from('fo'));         // 'Zm8='
+ * Codecs.base58.convertTo(Codecs.base64url, '9Ajdvzr');
+ * ```
+ */
+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.
+ */
+export type CodecName = BaseName;