bufferbase 1.3.0 → 2.0.0

package/src/codec.ts

@@ -0,0 +1,266 @@
+import { Buffer } from 'node:buffer';
+import type { ICodec, DecodeOptions, BufferLike } from './types.js';
+import { InvalidCharacterError, BufferSizeError } from './errors.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.
+ *
+ * Use pre-defined codecs from `Codecs` for common encodings,
+ * or create custom codecs with `createCodec()`.
+ *
+ * @example
+ * ```typescript
+ * import { Codec, Codecs, createCodec } from 'bufferbase';
+ *
+ * // Use pre-defined codec
+ * const encoded = Codecs.base58.encode(Buffer.from('Hello'));
+ *
+ * // Create custom codec
+ * const binary = createCodec('01');
+ * const bits = binary.encode(Buffer.from([5])); // '101'
+ * ```
+ */
+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);
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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);
+  }
+}
+
+/**
+ * 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'
+ * ```
+ */
+export function createCodec(chars: string): Codec {
+  return new Codec(chars);
+}

package/src/codecs.ts

@@ -0,0 +1,118 @@
+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);
+
+/**
+ * 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.
+ *
+ * @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
+ * ```
+ *
+ * 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;
+
+/**
+ * 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;

package/src/errors.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 {
+  /**
+   * @param char - The invalid character that was encountered (optional)
+   */
+  constructor(char?: string) {
+    const message = char ? `Invalid character found: '${char}'` : 'Invalid character found';
+    super(message);
+    this.name = 'InvalidCharacterError';
+  }
+}
+
+/**
+ * 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"
+ *   }
+ * }
+ * ```
+ */
+export class BufferSizeError extends Error {
+  /**
+   * @param actual - The actual decoded buffer size
+   * @param expected - The expected (specified) buffer size
+   */
+  constructor(actual: number, expected: number) {
+    super(`Buffer size ${actual} exceeds 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}'`);
+    this.name = 'UnknownBaseError';
+  }
+}

package/src/example.ts

@@ -1,28 +1,17 @@
-import { Chars, BufferEncoder, Converter, Validator } from './bufferbase.js';
+import { Buffer } from 'node:buffer';
+import { encode, decode, convert, validate, Codecs } from './index.js';
 
 // Example buffer
 const bytes = Buffer.from('Hello, World!', 'utf8');
 
-// Encoding buffer to Base32
-const encoder = new BufferEncoder(Chars.Base32Crockford);
-const base32encoded = encoder.encode(bytes);
-
-// Converting Base32 to Base58
-const converter_32to58 = new Converter(Chars.Base32Crockford, Chars.Base58);
-const base58encoded = converter_32to58.convert(base32encoded);
-
-// Converting Base32 to Base58
-const converter_58to64 = new Converter(Chars.Base58, Chars.Base64_URL_SAFE);
-const base64encoded = converter_58to64.convert(base58encoded);
-
-// Validating Base64
-const validatorB64 = new Validator(Chars.Base64_URL_SAFE);
-const isValidAsBase64 = validatorB64.validate(base64encoded);
-
-// Decoding Base64
-const decoder = new BufferEncoder(Chars.Base64_URL_SAFE);
-const decoded = decoder.decode(base64encoded);
+// 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');
 
+console.log('=== Function API ===');
 console.table({
   bytes: bytes.toString('utf8'),
   base32encoded,
@@ -31,13 +20,14 @@ console.table({
   isValidAsBase64,
   decoded: decoded.toString('utf8'),
 });
-// ┌─────────────────┬─────────────────────────┐
-// │ (index)         │ Values                  │
-// ├─────────────────┼─────────────────────────┤
-// │ bytes           │ 'Hello, World!'         │
-// │ base32encoded   │ '4GSBCDHQJR82QDXS6RS11' │
-// │ base58encoded   │ '72k1xXWG59fYdzSNoA'    │
-// │ base64encoded   │ 'BIZWxsbywgV29ybGQh'    │
-// │ isValidAsBase64 │ true                    │
-// │ decoded         │ 'Hello, World!'         │
-// └─────────────────┴─────────────────────────┘
+
+// Using Codecs object
+console.log('\n=== Codecs API ===');
+const encoded = Codecs.base58.encode(bytes);
+const converted = Codecs.base58.convertTo(Codecs.base64url, encoded);
+console.table({
+  original: bytes.toString('utf8'),
+  base58: encoded,
+  base64url: converted,
+  valid: Codecs.base64url.validate(converted),
+});

package/src/functions.ts

@@ -0,0 +1,93 @@
+import type { BaseName, DecodeOptions, BufferLike } from './types.js';
+import { Codec } from './codec.js';
+import { resolveChars } from './bases.js';
+
+// Cache for codec instances
+const codecCache = new Map<string, Codec>();
+
+/**
+ * Gets or creates a codec for the specified base.
+ */
+function getCodec(base: BaseName | string): Codec {
+  const chars = resolveChars(base);
+  let codec = codecCache.get(chars);
+  if (!codec) {
+    codec = new Codec(chars);
+    codecCache.set(chars, codec);
+  }
+  return codec;
+}
+
+/**
+ * Encodes a buffer to a base-encoded string.
+ *
+ * @param buffer - Buffer or Uint8Array to encode
+ * @param base - Base name (e.g., 'base58') or custom character set
+ * @returns Encoded string
+ *
+ * @example
+ * ```typescript
+ * // Node.js Buffer
+ * const encoded = encode(Buffer.from('Hello'), 'base58');
+ *
+ * // Browser Uint8Array
+ * const encoded = encode(new Uint8Array([72, 101, 108, 108, 111]), 'base58');
+ * ```
+ */
+export function encode(buffer: BufferLike, base: BaseName | string): string {
+  return getCodec(base).encode(buffer);
+}
+
+/**
+ * Decodes a base-encoded string to a buffer.
+ *
+ * @param encoded - String to decode
+ * @param base - Base name (e.g., 'base58') or custom character set
+ * @param options - Decode options (e.g., { size: 32 })
+ * @returns Decoded buffer
+ *
+ * @example
+ * ```typescript
+ * const buffer = decode('9Ajdvz', 'base58');
+ * const fixedSize = decode('9Ajdvz', 'base58', { size: 32 });
+ * ```
+ */
+export function decode(encoded: string, base: BaseName | string, options?: DecodeOptions): Buffer {
+  return getCodec(base).decode(encoded, options);
+}
+
+/**
+ * Converts a string from one base to another.
+ *
+ * @param input - String to convert
+ * @param from - Source base name or character set
+ * @param to - Target base name or character set
+ * @returns Converted string
+ *
+ * @example
+ * ```typescript
+ * const base64 = convert('9Ajdvz', 'base58', 'base64url');
+ * ```
+ */
+export function convert(input: string, from: BaseName | string, to: BaseName | string): string {
+  const fromCodec = getCodec(from);
+  const toCodec = getCodec(to);
+  return fromCodec.convertTo(toCodec, input);
+}
+
+/**
+ * Validates if a string contains only valid characters for the specified base.
+ *
+ * @param input - String to validate
+ * @param base - Base name or character set
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * validate('9Ajdvz', 'base58'); // true
+ * validate('0Ajdvz', 'base58'); // false ('0' is not in base58)
+ * ```
+ */
+export function validate(input: string, base: BaseName | string): boolean {
+  return getCodec(base).validate(input);
+}

package/src/index.ts

@@ -1,8 +1,21 @@
-export {
-  Chars,
-  BufferEncoder,
-  Converter,
-  InvalidCharacterError,
-  Validator,
-  validate,
-} from './bufferbase.js';
+// Types
+export type { BaseName, DecodeOptions, ICodec, BufferLike } from './types.js';
+export type { CodecName } from './codecs.js';
+
+// Errors
+export { InvalidCharacterError, BufferSizeError, UnknownBaseError } from './errors.js';
+
+// Codec class and factory
+export { Codec, createCodec } from './codec.js';
+
+// Character sets and utilities
+export { Chars, resolveChars, isBaseName } from './bases.js';
+
+// Simple function API
+export { encode, decode, convert, validate } from './functions.js';
+
+// Pre-defined codecs (namespaced)
+export { Codecs } from './codecs.js';
+
+// Deprecated exports for backward compatibility
+export { BufferEncoder, Converter, Validator } from './bufferbase.js';