bufferbase 1.3.0 → 2.0.0

package/src/bufferbase.ts

@@ -1,112 +1,42 @@
 /**
- * A collection of common bases.
+ * @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)`
  */
-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 { Buffer } from 'node:buffer';
+import { Codec } from './codec.js';
+import { InvalidCharacterError, BufferSizeError } from './errors.js';
 
-export class BufferSizeError extends Error {
-  message = 'Buffer size exceeds specified size';
-}
+// Re-export Chars for backward compatibility
+export { Chars } from './bases.js';
+
+// Re-export errors
+export { InvalidCharacterError, BufferSizeError };
 
 /**
- * Encodes and decodes buffers to and from a base.
+ * @deprecated Use `Codec` or `createCodec()` instead.
  */
 export class BufferEncoder {
-  constructor(private baseChars: string) {}
+  private codec: Codec;
+
+  constructor(private baseChars: string) {
+    this.codec = new Codec(baseChars);
+  }
 
-  /**
-   * 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('');
+    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 ? { size: bufferSize } : undefined);
   }
 }
 
 /**
- * Creates a converter function that can convert between two bases.
+ * @deprecated Use `convert()` function or `codec.convertTo()` instead.
  */
 export class Converter {
   decoder: BufferEncoder;
@@ -117,34 +47,29 @@ export class Converter {
     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()` function or `codec.validate()` instead.
+ */
 export class Validator {
-  decorder: BufferEncoder;
+  private codec: Codec;
 
   constructor(inputBase: string) {
-    this.decorder = new BufferEncoder(inputBase);
+    this.codec = new Codec(inputBase);
   }
 
   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);
   }
 }
 
+/**
+ * @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.test.ts

@@ -0,0 +1,320 @@
+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 buffer = Buffer.from('Test', 'utf8');
+    const encoded = encode(buffer, Chars.Base58);
+    const decoded = decode(encoded, Chars.Base58);
+    expect(decoded.toString('utf8')).toBe('Test');
+  });
+
+  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',
+    'ascii85',
+    'base85',
+    'z85',
+  ] as const;
+
+  for (const base of baseNames) {
+    test(`${base} encode/decode round-trip`, () => {
+      const buffer = Buffer.from('Hello, World!', 'utf8');
+      const encoded = encode(buffer, base);
+      const decoded = decode(encoded, base);
+      expect(decoded.toString('utf8')).toBe('Hello, World!');
+    });
+  }
+});
+
+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, 5]);
+    const buffer = Buffer.from([1, 2, 3, 4, 5]);
+
+    const baseNames = [
+      'decimal', 'base16', 'hex', 'base32', 'base32crockford',
+      'base36', 'base52', 'base58', 'base64', 'base64url',
+      'ascii85', 'base85', '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);
+  });
+});