bufferbase 1.3.0 → 3.0.0

package/src/errors.ts

@@ -0,0 +1,127 @@
+/**
+ * Error thrown when an invalid character is encountered during decoding.
+ */
+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 the decoded buffer does not have the size requested
+ * through `DecodeOptions.size`.
+ */
+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} does not match specified size ${expected}`);
+    this.name = 'BufferSizeError';
+  }
+}
+
+/**
+ * Error thrown when an unknown base name is provided.
+ */
+export class UnknownBaseError extends Error {
+  /**
+   * @param name - The unknown base name that was provided
+   */
+  constructor(name: string) {
+    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,43 +1,58 @@
-import { Chars, BufferEncoder, Converter, Validator } from './bufferbase.js';
+import { Buffer } from 'node:buffer';
+import { encode, decode, convert, validate, createCodec, Chars, 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);
+// 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'),
+});
 
-// Converting Base32 to Base58
-const converter_58to64 = new Converter(Chars.Base58, Chars.Base64_URL_SAFE);
-const base64encoded = converter_58to64.convert(base58encoded);
+// 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'),
+  base58,
+  base64url,
+  valid: validate(base64url, 'base64url'),
+  decoded: decode(base64url, 'base64url').toString('utf8'),
+});
 
-// Validating Base64
-const validatorB64 = new Validator(Chars.Base64_URL_SAFE);
-const isValidAsBase64 = validatorB64.validate(base64encoded);
+// 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'),
+});
 
-// Decoding Base64
-const decoder = new BufferEncoder(Chars.Base64_URL_SAFE);
-const decoded = decoder.decode(base64encoded);
+// 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({
-  bytes: bytes.toString('utf8'),
-  base32encoded,
-  base58encoded,
-  base64encoded,
-  isValidAsBase64,
-  decoded: decoded.toString('utf8'),
+  'Codecs.base58': Codecs.base58.encode(bytes),
+  'binary of [5]': binary.encode(Uint8Array.of(5)),
+  'adobe ascii85': adobe.encode(bytes),
 });
-// ┌─────────────────┬─────────────────────────┐
-// │ (index)         │ Values                  │
-// ├─────────────────┼─────────────────────────┤
-// │ bytes           │ 'Hello, World!'         │
-// │ base32encoded   │ '4GSBCDHQJR82QDXS6RS11' │
-// │ base58encoded   │ '72k1xXWG59fYdzSNoA'    │
-// │ base64encoded   │ 'BIZWxsbywgV29ybGQh'    │
-// │ isValidAsBase64 │ true                    │
-// │ decoded         │ 'Hello, World!'         │
-// └─────────────────┴─────────────────────────┘

package/src/functions.ts

@@ -0,0 +1,73 @@
+import type { BufferLike, CodecSpec, DecodeOptions } from './types.js';
+import type { Buffer } from 'node:buffer';
+import { resolveSpec, type BaseName } from './bases.js';
+import { getCodec } from './codec.js';
+
+/** A named encoding, or a spec describing one directly. */
+export type Base = BaseName | CodecSpec;
+
+/**
+ * Encodes a buffer to a base-encoded string.
+ *
+ * @param buffer - Buffer or Uint8Array to encode
+ * @param base - Base name (e.g. `'base58'`) or a codec spec
+ *
+ * @example
+ * ```typescript
+ * encode(Buffer.from('fo'), 'base64');                        // 'Zm8='
+ * encode(Uint8Array.of(5), { alphabet: '01', algorithm: 'radix' }); // '101'
+ * ```
+ */
+export function encode(buffer: BufferLike, base: Base): string {
+  return getCodec(resolveSpec(base)).encode(buffer);
+}
+
+/**
+ * Decodes a base-encoded string to a buffer.
+ *
+ * @param encoded - String to decode
+ * @param base - Base name (e.g. `'base58'`) or a codec spec
+ * @param options - Decode options, such as a required `size`
+ * @throws {InvalidCharacterError} If a character is not in the alphabet
+ * @throws {InvalidLengthError} If the length cannot encode a whole number of bytes
+ * @throws {NonCanonicalError} If spare bits are set and the codec is strict
+ * @throws {BufferSizeError} If the result does not have the requested `size`
+ *
+ * @example
+ * ```typescript
+ * decode('Zm8=', 'base64');              // Buffer('fo')
+ * decode('9Ajdvzr', 'base58', { size: 32 });
+ * ```
+ */
+export function decode(encoded: string, base: Base, options?: DecodeOptions): Buffer {
+  return getCodec(resolveSpec(base)).decode(encoded, options);
+}
+
+/**
+ * Converts a string from one base to another, through the bytes they describe.
+ *
+ * @example
+ * ```typescript
+ * convert('9Ajdvzr', 'base58', 'base64url');
+ * convert(legacy, 'radix64', 'base64'); // migrate data written by bufferbase 2
+ * ```
+ */
+export function convert(input: string, from: Base, to: Base): string {
+  const source = getCodec(resolveSpec(from));
+  const target = getCodec(resolveSpec(to));
+  return source.convertTo(target, input);
+}
+
+/**
+ * Reports whether `decode` would succeed for this input.
+ *
+ * @example
+ * ```typescript
+ * validate('Zm8=', 'base64');  // true
+ * validate('Zm9=', 'base64');  // false — spare bits are not zero
+ * validate('Zm9vd', 'base64'); // false — 5 characters cannot be whole bytes
+ * ```
+ */
+export function validate(input: string, base: Base): boolean {
+  return getCodec(resolveSpec(base)).validate(input);
+}

package/src/index.ts

@@ -1,8 +1,41 @@
+// Types
+export type {
+  Algorithm,
+  Block85Spec,
+  BlockSpec,
+  BufferLike,
+  CodecSpec,
+  DecodeOptions,
+  ICodec,
+  RadixSpec,
+} from './types.js';
+export type { BaseName } from './bases.js';
+export type { Base } from './functions.js';
+export type { CodecName } from './codecs.js';
+
+// Errors
 export {
-  Chars,
-  BufferEncoder,
-  Converter,
+  BufferSizeError,
+  CheckSymbolError,
   InvalidCharacterError,
-  Validator,
-  validate,
-} from './bufferbase.js';
+  InvalidCodecError,
+  InvalidLengthError,
+  NonCanonicalError,
+  UnknownBaseError,
+  ValueRangeError,
+} from './errors.js';
+
+// Codec implementations and factory
+export { Block85Codec, BlockCodec, Codec, RadixCodec, createCodec, getCodec } from './codec.js';
+
+// Character sets, encoding definitions, and lookup helpers
+export { Bases, Chars, isBaseName, resolveSpec } from './bases.js';
+
+// Simple function API
+export { convert, decode, encode, 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';

package/src/types.ts

@@ -0,0 +1,156 @@
+import { Buffer } from 'node:buffer';
+
+/**
+ * Input type accepted by encode functions.
+ *
+ * Supports both Node.js `Buffer` and standard `Uint8Array` for browser compatibility.
+ */
+export type BufferLike = Buffer | Uint8Array;
+
+/**
+ * How bytes are mapped to characters.
+ *
+ * An alphabet alone does not determine an encoding: the same 64 characters can
+ * be used by a radix conversion or by a bit-block encoding, producing different
+ * output. Every codec therefore names its algorithm explicitly.
+ *
+ * - `'radix'` — treats the whole buffer as one big integer and rewrites it in
+ *   base `alphabet.length`. Works with any alphabet and any input length.
+ *   Leading zero bytes are preserved as leading `alphabet[0]` characters.
+ *   Used by Base58, Base36, and custom alphabets. Not RFC 4648.
+ * - `'block'` — regroups the bit stream into `log2(alphabet.length)`-bit chunks,
+ *   as specified by RFC 4648. Requires an alphabet of 2, 4, 8, 16, 32, or 64
+ *   characters. Used by Base16, Base32, and Base64.
+ * - `'block85'` — converts each 4-byte block to 5 characters (85^5 > 2^32).
+ *   Requires an alphabet of exactly 85 characters. Used by Ascii85 and Z85.
+ */
+export type Algorithm = 'radix' | 'block' | 'block85';
+
+/** Options shared by every algorithm. */
+interface CommonSpec {
+  /** Characters used for encoding, ordered by value. */
+  readonly alphabet: string;
+  /**
+   * Reject input that is well-formed but not the canonical encoding of any
+   * byte sequence (RFC 4648 §3.5). Defaults to `true`.
+   *
+   * With `strict: false`, `'Zm9='` and `'Zm8='` both decode to `'fo'`, so
+   * decoding is no longer injective. Only disable it to read data produced by
+   * a lenient encoder.
+   */
+  readonly strict?: boolean;
+  /**
+   * Accept either letter case when decoding, and when validating.
+   * Requires an alphabet that does not contain both cases of the same letter.
+   * Defaults to `false`.
+   */
+  readonly caseInsensitive?: boolean;
+  /**
+   * Extra characters accepted when decoding, each mapped to the alphabet
+   * character it stands for.
+   *
+   * Crockford's Base32 uses `{ I: '1', L: '1', O: '0' }` so that a symbol
+   * written down by hand is read back as the digit it resembles. Encoding
+   * never emits them.
+   */
+  readonly aliases?: Readonly<Record<string, string>>;
+  /**
+   * Characters skipped when decoding, such as the hyphens Crockford's Base32
+   * allows for readability. Encoding never emits them.
+   */
+  readonly ignore?: string;
+}
+
+/** A codec that rewrites the buffer as an integer in base `alphabet.length`. */
+export interface RadixSpec extends CommonSpec {
+  readonly algorithm: 'radix';
+  /**
+   * Symbols that extend the alphabet for a trailing check symbol, which
+   * encodes the value modulo `alphabet.length + checkSymbols.length`.
+   *
+   * Crockford's Base32 uses `'*~$=U'`, giving a modulus of 37. When set, every
+   * encoding carries the symbol and every decoding verifies it.
+   */
+  readonly checkSymbols?: string;
+}
+
+/** A codec that regroups the bit stream, as specified by RFC 4648. */
+export interface BlockSpec extends CommonSpec {
+  readonly algorithm: 'block';
+  /**
+   * Character used to pad the final block to a whole number of characters,
+   * or `false` to emit no padding. Defaults to `'='`.
+   */
+  readonly pad?: string | false;
+}
+
+/** A codec that converts each 4-byte block to 5 characters. */
+export interface Block85Spec extends CommonSpec {
+  readonly algorithm: 'block85';
+  /** Write a block of four zero bytes as `'z'`. Defaults to `false`. */
+  readonly zeroShortcut?: boolean;
+  /** Write a block of four spaces as `'y'`. Defaults to `false`. */
+  readonly spaceShortcut?: boolean;
+  /** Wrap the output in `'<~'` and `'~>'`. Defaults to `false`. */
+  readonly delimiters?: boolean;
+  /**
+   * Require the input length to be a multiple of 4 bytes, as Z85 does.
+   * Defaults to `false`, which encodes a trailing partial block as
+   * `length + 1` characters.
+   */
+  readonly requireFullBlocks?: boolean;
+}
+
+/**
+ * A complete codec definition: an alphabet plus the algorithm that uses it.
+ *
+ * @example
+ * ```typescript
+ * import { encode, type CodecSpec } from 'bufferbase';
+ *
+ * const binary: CodecSpec = { alphabet: '01', algorithm: 'radix' };
+ * encode(Uint8Array.of(5), binary); // '101'
+ * ```
+ */
+export type CodecSpec = RadixSpec | BlockSpec | Block85Spec;
+
+/**
+ * Options for decode operations.
+ */
+export interface DecodeOptions {
+  /**
+   * Required byte length of the result.
+   *
+   * The decoded buffer must be exactly this long, otherwise `BufferSizeError`
+   * is thrown. Because leading zeros carry no value in a radix encoding, a
+   * `'radix'` codec pads a shorter result with leading zero bytes to reach it;
+   * `'block'` and `'block85'` codecs derive the length from the input and can
+   * only check it.
+   */
+  size?: number;
+}
+
+/**
+ * Codec interface for encoding/decoding operations.
+ *
+ * `validate(input)` returns `true` exactly when `decode(input)` succeeds.
+ */
+export interface ICodec {
+  /** Character set used for encoding. */
+  readonly chars: string;
+
+  /** The algorithm this codec applies to `chars`. */
+  readonly algorithm: Algorithm;
+
+  /** Encodes a buffer to a base-encoded string. */
+  encode(buffer: BufferLike): string;
+
+  /** Decodes a base-encoded string to a buffer. */
+  decode(encoded: string, options?: DecodeOptions): Buffer;
+
+  /** Reports whether `decode` would succeed for this input. */
+  validate(input: string): boolean;
+
+  /** Decodes with this codec, then re-encodes with `target`. */
+  convertTo(target: ICodec, input: string): string;
+}

package/dist/cjs/bufferbase.d.mts

@@ -1,60 +0,0 @@
-/// <reference types="node" />
-/**
- * A collection of common bases.
- */
-export declare const Chars: {
-    Decimal: string;
-    Base16: string;
-    Base32: string;
-    Base32Crockford: string;
-    Base36: string;
-    Base52: string;
-    Base58: string;
-    Base64_STD: string;
-    Base64_URL_SAFE: string;
-    Base64_XML_NMTOKEN: string;
-    Base64_XML_NAME: string;
-    Ascii85: string;
-    Base85: string;
-    Z85: string;
-};
-export declare class InvalidCharacterError extends Error {
-    message: string;
-}
-export declare class BufferSizeError extends Error {
-    message: string;
-}
-/**
- * Encodes and decodes buffers to and from a base.
- */
-export declare class BufferEncoder {
-    private baseChars;
-    constructor(baseChars: string);
-    /**
-     * Encodes a buffer to a string.
-     */
-    encode(buffer: Buffer): string;
-    /**
-     * Decodes a string to a buffer.
-     */
-    decode(encoded: string, bufferSize?: number): Buffer;
-}
-/**
- * Creates a converter function that can convert between two bases.
- */
-export declare class Converter {
-    decoder: BufferEncoder;
-    encoder: BufferEncoder;
-    constructor(inputBase: string, outputBase: string);
-    /**
-     * Converts a string from the input base to the output base.
-     */
-    convert(input: string): string;
-}
-export declare class Validator {
-    decorder: BufferEncoder;
-    constructor(inputBase: string);
-    validate(input: string): boolean;
-}
-export declare const validate: (input: string, base: string) => boolean;
-//# sourceMappingURL=bufferbase.d.mts.map

package/dist/cjs/bufferbase.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bufferbase.d.mts","sourceRoot":"","sources":["../../src/bufferbase.mts"],"names":[],"mappings":";AAAA;;GAEG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;CAqBjB,CAAC;AAEF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,OAAO,SAA6B;CACrC;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,OAAO,SAAwC;CAChD;AAED;;GAEG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,MAAM;IAErC;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IA2B9B;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAgCrD;AAED;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;gBAEX,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAKjD;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAG/B;AAED,qBAAa,SAAS;IACpB,QAAQ,EAAE,aAAa,CAAC;gBAEZ,SAAS,EAAE,MAAM;IAI7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAWjC;AAED,eAAO,MAAM,QAAQ,UAAW,MAAM,QAAQ,MAAM,KAAG,OAEtD,CAAC"}