bufferbase 1.3.0 → 3.0.0

package/src/bufferbase.test.ts

@@ -1,53 +1,49 @@
 import { Chars, BufferEncoder } from './bufferbase.js';
 import { Buffer } from 'node:buffer';
-import test from 'node:test'; // ①
-import assert from 'node:assert';
+import { describe, test, expect } from 'bun:test';
 
-test('BufferEncoder', async (t) => {
-  await t.test(
-    'encodes and decodes a string correctly with base58chars',
-    () => {
-      const encoder = new BufferEncoder(Chars.Base58);
-      const buffer = Buffer.from('Hello, World!', 'utf8');
+describe('BufferEncoder', () => {
+  test('encodes and decodes a string correctly with base58chars', () => {
+    const encoder = new BufferEncoder(Chars.Base58);
+    const buffer = Buffer.from('Hello, World!', 'utf8');
 
-      const encoded = encoder.encode(buffer);
-      const decoded = encoder.decode(encoded);
+    const encoded = encoder.encode(buffer);
+    const decoded = encoder.decode(encoded);
 
-      assert.strictEqual(decoded.toString('utf8'), 'Hello, World!');
-    }
-  );
+    expect(decoded.toString('utf8')).toBe('Hello, World!');
+  });
 
-  await t.test('handles empty buffer correctly', () => {
+  test('handles empty buffer correctly', () => {
     const encoder = new BufferEncoder(Chars.Base58);
     const buffer = Buffer.alloc(0);
 
     const encoded = encoder.encode(buffer);
     const decoded = encoder.decode(encoded);
 
-    assert.strictEqual(decoded.toString('utf8'), '');
+    expect(decoded.toString('utf8')).toBe('');
   });
 
-  await t.test('handles long buffer correctly', () => {
+  test('handles long buffer correctly', () => {
     const encoder = new BufferEncoder(Chars.Base58);
     const buffer = Buffer.from('Hello, World!'.repeat(100), 'utf8');
 
     const encoded = encoder.encode(buffer);
     const decoded = encoder.decode(encoded);
 
-    assert.strictEqual(decoded.toString('utf8'), 'Hello, World!'.repeat(100));
+    expect(decoded.toString('utf8')).toBe('Hello, World!'.repeat(100));
   });
 
-  await t.test('handles bufferSize argument correctly', () => {
+  test('handles bufferSize argument correctly', () => {
     const encoder = new BufferEncoder(Chars.Base58);
     const buffer = Buffer.alloc(0);
 
     const encoded = encoder.encode(buffer);
     const decoded = encoder.decode(encoded, 4);
 
-    assert.strictEqual(decoded.toString('hex'), '00000000');
+    expect(decoded.toString('hex')).toBe('00000000');
   });
 
-  await t.test('encode and decode various chars correctly', () => {
+  test('encode and decode various chars correctly', () => {
     for (const charTable of Object.values(Chars)) {
       const encoder = new BufferEncoder(charTable);
       const buffer = Buffer.from('Hello, World!', 'utf8');
@@ -55,11 +51,11 @@ test('BufferEncoder', async (t) => {
       const encoded = encoder.encode(buffer);
       const decoded = encoder.decode(encoded);
 
-      assert.strictEqual(decoded.toString('utf8'), 'Hello, World!');
+      expect(decoded.toString('utf8')).toBe('Hello, World!');
     }
   });
 
-  await t.test('handles binary powers from 1 to 63 correctly', () => {
+  test('handles binary powers from 1 to 63 correctly', () => {
     const encoder = new BufferEncoder(Chars.Base58);
     for (let i = 0; i < 64; i++) {
       const buffer = Buffer.alloc(8);
@@ -68,14 +64,35 @@ test('BufferEncoder', async (t) => {
       const encoded = encoder.encode(buffer);
       const decoded = encoder.decode(encoded, 8);
       const result = decoded.readBigInt64BE();
-      console.log(encoded, result);
-      assert.strictEqual(result, num);
+      expect(result).toBe(num);
     }
   });
-  await t.test('throws error on invalid characters in decode', () => {
-    assert.throws(() => {
+
+  test('throws error on invalid characters in decode', () => {
+    expect(() => {
       const encoder = new BufferEncoder(Chars.Base58);
       encoder.decode('InvalidString!');
-    }, new Error('Invalid character found'));
+    }).toThrow(/Invalid character found/);
+  });
+
+  test('encodes Uint8Array correctly', () => {
+    const encoder = new BufferEncoder(Chars.Base58);
+    const uint8Array = new Uint8Array([72, 101, 108, 108, 111]); // 'Hello'
+    const buffer = Buffer.from('Hello', 'utf8');
+
+    const encodedFromUint8 = encoder.encode(uint8Array);
+    const encodedFromBuffer = encoder.encode(buffer);
+
+    expect(encodedFromUint8).toBe(encodedFromBuffer);
+  });
+
+  test('encodes Uint8Array with leading zeros correctly', () => {
+    const encoder = new BufferEncoder(Chars.Base58);
+    const uint8Array = new Uint8Array([0, 0, 1, 2, 3]);
+
+    const encoded = encoder.encode(uint8Array);
+    const decoded = encoder.decode(encoded);
+
+    expect(Array.from(decoded)).toEqual([0, 0, 1, 2, 3]);
   });
 });

package/src/bufferbase.ts

@@ -1,150 +1,65 @@
 /**
- * A collection of common bases.
+ * @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.
  */
-export const Chars = {
-  Decimal: '0123456789',
-  Base16: '0123456789ABCDEF',
-  Base32: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567',
-  Base32Crockford: '0123456789ABCDEFGHJKMNPQRSTVWXYZ',
-  Base36: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ',
-  Base52: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
-  Base58: '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz',
-  Base64_STD:
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/',
-  Base64_URL_SAFE:
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_',
-  Base64_XML_NMTOKEN:
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._',
-  Base64_XML_NAME:
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_:',
-  Ascii85:
-    '!"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstu',
-  Base85:
-    '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!#$%&()*+-;<=>?@^_`{|}~',
-  Z85: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#',
-};
 
-export class InvalidCharacterError extends Error {
-  message = 'Invalid character found';
-}
+import type { Buffer } from 'node:buffer';
+import type { BufferLike } from './types.js';
+import { RadixCodec } from './codec-radix.js';
 
-export class BufferSizeError extends Error {
-  message = 'Buffer size exceeds specified size';
-}
+/** @deprecated Import `Chars` from the package root. */
+export { Chars } from './bases.js';
 
-/**
- * Encodes and decodes buffers to and from a base.
- */
+/** @deprecated Import these from the package root. */
+export { BufferSizeError, InvalidCharacterError } from './errors.js';
+
+/** @deprecated Use `createCodec(alphabet)`. */
 export class BufferEncoder {
-  constructor(private baseChars: string) {}
+  private readonly codec: RadixCodec;
 
-  /**
-   * Encodes a buffer to a string.
-   */
-  encode(buffer: Buffer): string {
-    let result = [];
-    for (const byte of buffer) {
-      let carry = byte;
-      for (let j = 0; j < result.length; j++) {
-        carry += result[j] * 256;
-        result[j] = carry % this.baseChars.length;
-        carry = Math.floor(carry / this.baseChars.length);
-      }
-      while (carry > 0) {
-        result.push(carry % this.baseChars.length);
-        carry = Math.floor(carry / this.baseChars.length);
-      }
-    }
-    for (const byte of buffer) {
-      if (byte === 0) {
-        result.push(0);
-      } else {
-        break;
-      }
-    }
-    return result
-      .reverse()
-      .map((index) => this.baseChars[index])
-      .join('');
+  constructor(baseChars: string) {
+    this.codec = new RadixCodec({ alphabet: baseChars, algorithm: 'radix' });
+  }
+
+  encode(buffer: BufferLike): string {
+    return this.codec.encode(buffer);
   }
 
-  /**
-   * Decodes a string to a buffer.
-   */
   decode(encoded: string, bufferSize?: number): Buffer {
-    let result = Buffer.alloc(0);
-    for (const char of encoded) {
-      const value = this.baseChars.indexOf(char);
-      if (value === -1) throw new InvalidCharacterError();
-      let carry = value;
-      let tempResult = Buffer.alloc(result.length);
-      let i;
-      for (i = 0; i < result.length; i++) {
-        carry += result[i] * this.baseChars.length;
-        tempResult[i] = carry % 256;
-        carry = Math.floor(carry / 256);
-      }
-      while (carry > 0) {
-        tempResult = Buffer.concat([tempResult, Buffer.from([carry % 256])]);
-        carry = Math.floor(carry / 256);
-      }
-      result = tempResult;
-    }
-    // buffer size
-    if (bufferSize && result.length < bufferSize) {
-      result = Buffer.concat([
-        result,
-        Buffer.from(Array(bufferSize - result.length).fill(0)),
-      ]);
-    }
-    if (bufferSize && result.length > bufferSize) {
-      throw new BufferSizeError();
-    }
-    result.reverse();
-    return result;
+    return this.codec.decode(encoded, bufferSize === undefined ? undefined : { size: bufferSize });
   }
 }
 
-/**
- * Creates a converter function that can convert between two bases.
- */
+/** @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);
     this.encoder = new BufferEncoder(outputBase);
   }
 
-  /**
-   * Converts a string from the input base to the output base.
-   */
   convert(input: string): string {
     return this.encoder.encode(this.decoder.decode(input));
   }
 }
 
+/** @deprecated Use `validate()` or `codec.validate()`. */
 export class Validator {
-  decorder: BufferEncoder;
+  private readonly codec: RadixCodec;
 
   constructor(inputBase: string) {
-    this.decorder = new BufferEncoder(inputBase);
+    this.codec = new RadixCodec({ alphabet: inputBase, algorithm: 'radix' });
   }
 
   validate(input: string): boolean {
-    try {
-      this.decorder.decode(input);
-      return true;
-    } catch (e) {
-      if (e instanceof InvalidCharacterError) {
-        return false;
-      }
-      throw e;
-    }
+    return this.codec.validate(input);
   }
 }
-
-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));
+  }
+}