bufferbase 1.3.0 → 3.0.0

package/README.md

@@ -1,33 +1,202 @@
 # bufferbase
 
-Buffer-to-BaseN Encoding and Decoding for Node.js.
+Buffer-to-BaseN encoding for Node.js and the browser, across three algorithms:
+RFC 4648 bit-block encodings, Ascii85/Z85, and Base58-style radix conversion.
 
-bufferbase is a Node.js library that provides straightforward encoding and decoding of buffer objects into various BaseN formats. It's designed to be simple, efficient, and flexible for different application needs.
+## Installation
 
-## Features
+```bash
+npm install bufferbase
+```
 
-- Supports multiple base encoding formats.
-- Optimized for Node.js buffer handling.
-- Intuitive API for easy integration.
-- Suitable for various data types.
-- Consistent and reliable performance.
+## The three algorithms
 
-## Installation
+An alphabet does not describe an encoding on its own. The same 64 characters
+can be read as a radix conversion or as a bit-block encoding, and the two
+produce different strings for the same bytes. Every codec here therefore names
+its algorithm.
 
-Install bufferbase using npm:
+| Algorithm | How it works | Alphabet | Used by |
+|---|---|---|---|
+| `block` | Regroups the bit stream into `log2(n)`-bit chunks, per RFC 4648 | 2, 4, 8, 16, 32, or 64 characters | Base16, Base32, Base64 |
+| `block85` | Converts each 4-byte block to 5 characters | exactly 85 characters | Ascii85, Z85 |
+| `radix` | Reads the buffer as one integer and rewrites it in base `n` | any length | Base58, Base36, Crockford |
 
-```bash
-npm install bufferbase
+```typescript
+import { encode } from 'bufferbase';
+
+encode(Buffer.from('fo'), 'base64');  // 'Zm8='  — RFC 4648
+encode(Buffer.from('fo'), 'radix64'); // 'GZv'   — radix conversion
 ```
 
+Only `radix` accepts an alphabet of any length, and only `radix` preserves
+leading zero bytes as leading characters. Only `block` and `block85` have an
+output length that is a fixed function of the input length.
+
+## Supported encodings
+
+| Name | Algorithm | Characters | Notes |
+|---|---|---|---|
+| `base16`, `hex` | `block` | 0-9A-F | RFC 4648 Table 5, unpadded |
+| `base32` | `block` | A-Z2-7 | RFC 4648 Table 3 |
+| `base32hex` | `block` | 0-9A-V | RFC 4648 Table 4 |
+| `base64` | `block` | A-Za-z0-9+/ | RFC 4648 Table 1 |
+| `base64url` | `block` | A-Za-z0-9-_ | RFC 4648 Table 2, unpadded |
+| `base64xml` | `block` | A-Za-z0-9._ | unpadded |
+| `base64xmlname` | `block` | A-Za-z0-9_: | unpadded |
+| `ascii85` | `block85` | `!` to `u` | zero-block shortcut on |
+| `z85` | `block85` | ZeroMQ RFC 32 | whole 4-byte blocks only |
+| `base58` | `radix` | Bitcoin alphabet | |
+| `base32crockford` | `radix` | 0-9A-HJKMNP-TV-Z | |
+| `base32crockfordcheck` | `radix` | as above, plus `*~$=U` | carries a check symbol |
+| `base36` | `radix` | 0-9A-Z | case-insensitive |
+| `base52` | `radix` | A-Za-z | |
+| `decimal` | `radix` | 0-9 | |
+| `radix16`, `radix32`, `radix64`, `radix64url` | `radix` | the RFC alphabets | radix conversion, not RFC 4648 |
+
+Base16, Base32, Base32hex, Base36 and both Crockford codecs decode in either
+case.
+
 ## Usage
 
-See [src/example.ts](/src/example.ts)
+### Functions
+
+```typescript
+import { encode, decode, convert, validate } from 'bufferbase';
+
+encode(Buffer.from('Hello'), 'base58');       // '9Ajdvzr'
+decode('9Ajdvzr', 'base58');                  // Buffer('Hello')
+decode('9Ajdvzr', 'base58', { size: 32 });    // padded to 32 bytes
+convert('9Ajdvzr', 'base58', 'base64url');    // through the bytes
+validate('Zm8=', 'base64');                   // true
+```
+
+`validate(input, base)` returns `true` exactly when `decode(input, base)`
+succeeds, so the two never disagree.
+
+### Codecs
+
+```typescript
+import { Codecs } from 'bufferbase';
+
+Codecs.base64.encode(Buffer.from('fo'));      // 'Zm8='
+Codecs.base58.convertTo(Codecs.base64url, '9Ajdvzr');
+```
+
+### Custom codecs
+
+Pass a spec anywhere a base name is accepted.
+
+```typescript
+import { createCodec, encode } from 'bufferbase';
+
+encode(Uint8Array.of(5), { alphabet: '01', algorithm: 'radix' }); // '101'
+
+const lowerHex = createCodec({ alphabet: '0123456789abcdef', algorithm: 'block', pad: false });
+lowerHex.encode(Uint8Array.of(0, 1)); // '0001'
+
+createCodec('01'); // a bare string means a radix codec over that alphabet
+```
+
+### Crockford's Base32
+
+Crockford's specification describes a notation for numbers rather than for byte
+streams, so a radix conversion is the right reading of it. Decoding accepts
+either case, reads `I` and `L` as `1` and `O` as `0`, and ignores the hyphens
+that may be inserted for readability. Encoding emits only the alphabet.
+
+```typescript
+decode('91jprv3f', 'base32crockford');   // Buffer('Hello')
+decode('91JP-RV3F', 'base32crockford');  // the same
+decode('9IJPRV3F', 'base32crockford');   // the same, reading I as 1
+```
+
+`base32crockfordcheck` appends the check symbol, the value modulo 37 written
+with the alphabet extended by `*~$=U`. Decoding verifies it, so a mistyped
+character is caught rather than decoded into different bytes.
+
+```typescript
+encode(Buffer.from('Hello'), 'base32crockfordcheck'); // '91JPRV3FG'
+validate('91JPRV3XG', 'base32crockfordcheck');        // false
+```
+
+### Ascii85 variants
+
+Several incompatible encodings share the Ascii85 algorithm and alphabet,
+differing only in the shortcuts and framing they add. They are options rather
+than separate codecs. The `ascii85` default is `zeroShortcut` alone, which
+matches Python's `base64.a85encode`.
+
+```typescript
+import { createCodec, Chars } from 'bufferbase';
+
+const btoa = createCodec({
+  alphabet: Chars.Ascii85, algorithm: 'block85',
+  zeroShortcut: true, spaceShortcut: true,      // '    ' -> 'y'
+});
+
+const adobe = createCodec({
+  alphabet: Chars.Ascii85, algorithm: 'block85',
+  zeroShortcut: true, delimiters: true,          // '<~ ... ~>'
+});
+```
+
+## Canonical encodings
+
+A trailing partial block leaves spare bits in the final character. RFC 4648
+§3.5 requires them to be zero; input that sets them decodes to the same bytes
+as the canonical form, so accepting it makes decoding non-injective.
+
+```typescript
+decode('Zm8=', 'base64'); // Buffer('fo')
+decode('Zm9=', 'base64'); // throws NonCanonicalError — also 'fo'
+```
+
+This is rejected by default. Pass `strict: false` to read data from a lenient
+encoder.
+
+```typescript
+createCodec({ alphabet: Chars.Base64, algorithm: 'block', strict: false });
+```
+
+The same check rejects lengths that cannot be a whole number of bytes
+(`'Zm9vd'`), misplaced or excess padding, and Ascii85 groups above 2^32.
+
+## API
+
+```typescript
+encode(buffer, base)              // string
+decode(encoded, base, options?)   // Buffer
+convert(input, from, to)          // string
+validate(input, base)             // boolean
+createCodec(spec | alphabet)      // ICodec
+```
+
+`base` is a name from the table above or a `CodecSpec`. Every spec accepts
+`strict`, `caseInsensitive`, `aliases` and `ignore`:
+
+```typescript
+type CodecSpec =
+  | { alphabet: string; algorithm: 'radix'; checkSymbols?: string }
+  | { alphabet: string; algorithm: 'block'; pad?: string | false }
+  | { alphabet: string; algorithm: 'block85';
+      zeroShortcut?: boolean; spaceShortcut?: boolean;
+      delimiters?: boolean; requireFullBlocks?: boolean };
+```
 
+### Errors
 
-## Contributing
+| Error | Thrown when |
+|---|---|
+| `InvalidCharacterError` | a character is not in the alphabet |
+| `InvalidLengthError` | the length cannot encode a whole number of bytes |
+| `NonCanonicalError` | spare bits are set and the codec is strict |
+| `ValueRangeError` | a block85 group is 2^32 or above |
+| `CheckSymbolError` | a check symbol does not match the value it follows |
+| `BufferSizeError` | the result does not have the requested `size` |
+| `UnknownBaseError` | the base name is not known |
+| `InvalidCodecError` | the spec cannot be realised |
 
-Contributions to bufferbase are welcome! Please read our contributing guidelines for more information.
-License
+## License
 
-bufferbase is ISC licensed.
+ISC

package/dist/cjs/bases.d.ts

@@ -0,0 +1,189 @@
+import type { CodecSpec } from './types.js';
+/**
+ * Character sets, ordered by value.
+ *
+ * A character set does not by itself describe an encoding — see `Bases` for
+ * the alphabet/algorithm pairs that do.
+ */
+export declare const Chars: {
+    /** Base 10: 0-9 */
+    readonly Decimal: "0123456789";
+    /** RFC 4648 Table 5 — Base16: 0-9A-F */
+    readonly Base16: "0123456789ABCDEF";
+    /** RFC 4648 Table 3 — Base32: A-Z2-7 */
+    readonly Base32: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+    /** RFC 4648 Table 4 — Base32 with extended hex alphabet: 0-9A-V */
+    readonly Base32Hex: "0123456789ABCDEFGHIJKLMNOPQRSTUV";
+    /** Crockford's Base32: 0-9A-HJKMNP-TV-Z (no I, L, O, U) */
+    readonly Base32Crockford: "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    /** Alphanumeric: 0-9A-Z */
+    readonly Base36: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+    /** Letters only: A-Za-z */
+    readonly Base52: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+    /** Bitcoin alphabet: 1-9A-HJ-NP-Za-km-z (no 0, O, I, l) */
+    readonly Base58: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    /** RFC 4648 Table 1 — Base64: A-Za-z0-9+/ */
+    readonly Base64: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    /** RFC 4648 Table 2 — URL-safe Base64: A-Za-z0-9-_ */
+    readonly Base64Url: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+    /** XML token Base64: A-Za-z0-9._ */
+    readonly Base64Xml: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._";
+    /** XML name Base64: A-Za-z0-9_: */
+    readonly Base64XmlName: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_:";
+    /** Ascii85: the 85 printable characters from `!` (0x21) to `u` (0x75) */
+    readonly Ascii85: "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstu";
+    /** ZeroMQ Z85 (RFC 32): avoids the quote and backslash characters */
+    readonly Z85: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#";
+    /** The five symbols Crockford's Base32 adds for its check symbol, giving a modulus of 37 */
+    readonly CrockfordCheck: "*~$=U";
+};
+/**
+ * The encodings this package knows by name.
+ *
+ * Each entry pairs an alphabet with the algorithm that reads it, because the
+ * alphabet alone is ambiguous: `base64` and `radix64` share Table 1 but
+ * produce different strings for the same bytes.
+ *
+ * @example
+ * ```typescript
+ * import { encode, Bases } from 'bufferbase';
+ *
+ * encode(Buffer.from('fo'), 'base64');  // 'Zm8='  — RFC 4648
+ * encode(Buffer.from('fo'), 'radix64'); // 'GZv'   — radix conversion
+ * ```
+ */
+export declare const Bases: {
+    readonly decimal: {
+        readonly alphabet: "0123456789";
+        readonly algorithm: "radix";
+    };
+    readonly base36: {
+        readonly alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+        readonly algorithm: "radix";
+        readonly caseInsensitive: true;
+    };
+    readonly base52: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+        readonly algorithm: "radix";
+    };
+    readonly base58: {
+        readonly alphabet: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+        readonly algorithm: "radix";
+    };
+    /**
+     * Crockford's Base32, which specifies a notation for numbers rather than for
+     * byte streams, so a radix conversion is the right reading of it.
+     *
+     * Decoding accepts either case, reads `I` and `L` as `1` and `O` as `0`, and
+     * ignores hyphens.
+     */
+    readonly base32crockford: {
+        readonly alphabet: "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+        readonly algorithm: "radix";
+        readonly caseInsensitive: true;
+        readonly aliases: {
+            readonly I: "1";
+            readonly L: "1";
+            readonly O: "0";
+        };
+        readonly ignore: "-";
+    };
+    /** Crockford's Base32 carrying its trailing check symbol. */
+    readonly base32crockfordcheck: {
+        readonly alphabet: "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+        readonly algorithm: "radix";
+        readonly caseInsensitive: true;
+        readonly aliases: {
+            readonly I: "1";
+            readonly L: "1";
+            readonly O: "0";
+        };
+        readonly ignore: "-";
+        readonly checkSymbols: "*~$=U";
+    };
+    readonly base16: {
+        readonly alphabet: "0123456789ABCDEF";
+        readonly algorithm: "block";
+        readonly pad: false;
+        readonly caseInsensitive: true;
+    };
+    readonly hex: {
+        readonly alphabet: "0123456789ABCDEF";
+        readonly algorithm: "block";
+        readonly pad: false;
+        readonly caseInsensitive: true;
+    };
+    readonly base32: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+        readonly algorithm: "block";
+        readonly caseInsensitive: true;
+    };
+    readonly base32hex: {
+        readonly alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUV";
+        readonly algorithm: "block";
+        readonly caseInsensitive: true;
+    };
+    readonly base64: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+        readonly algorithm: "block";
+    };
+    /** Unpadded, as used by JWT and other URL-facing formats. */
+    readonly base64url: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+        readonly algorithm: "block";
+        readonly pad: false;
+    };
+    readonly base64xml: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._";
+        readonly algorithm: "block";
+        readonly pad: false;
+    };
+    readonly base64xmlname: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_:";
+        readonly algorithm: "block";
+        readonly pad: false;
+    };
+    /** Ascii85 with the zero-block shortcut, matching Python's `a85encode`. */
+    readonly ascii85: {
+        readonly alphabet: "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstu";
+        readonly algorithm: "block85";
+        readonly zeroShortcut: true;
+    };
+    /** ZeroMQ Z85, which has no padding and so encodes whole blocks only. */
+    readonly z85: {
+        readonly alphabet: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#";
+        readonly algorithm: "block85";
+        readonly requireFullBlocks: true;
+    };
+    readonly radix16: {
+        readonly alphabet: "0123456789ABCDEF";
+        readonly algorithm: "radix";
+    };
+    readonly radix32: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+        readonly algorithm: "radix";
+    };
+    readonly radix64: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+        readonly algorithm: "radix";
+    };
+    readonly radix64url: {
+        readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+        readonly algorithm: "radix";
+    };
+};
+/**
+ * The names accepted wherever a base is expected.
+ */
+export type BaseName = keyof typeof Bases;
+/**
+ * Resolves a base name to its codec spec, and passes a spec through unchanged.
+ *
+ * @throws {UnknownBaseError} If the name is not one of `Bases`
+ */
+export declare function resolveSpec(base: BaseName | CodecSpec): CodecSpec;
+/**
+ * Checks whether a string names one of the encodings in `Bases`.
+ */
+export declare function isBaseName(value: string): value is BaseName;
+//# sourceMappingURL=bases.d.ts.map

package/dist/cjs/bases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bases.d.ts","sourceRoot":"","sources":["../../src/bases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB,mBAAmB;;IAEnB,wCAAwC;;IAExC,wCAAwC;;IAExC,mEAAmE;;IAEnE,2DAA2D;;IAE3D,2BAA2B;;IAE3B,2BAA2B;;IAE3B,2DAA2D;;IAE3D,6CAA6C;;IAE7C,sDAAsD;;IAEtD,oCAAoC;;IAEpC,mCAAmC;;IAEnC,yEAAyE;;IAEzE,qEAAqE;;IAErE,4FAA4F;;CAEpF,CAAC;AAKX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;IAOhB;;;;;;OAMG;;;;;;;;;;;;IAQH,6DAA6D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAgB7D,6DAA6D;;;;;;;;;;;;;;;;IAM7D,2EAA2E;;;;;;IAE3E,yEAAyE;;;;;;;;;;;;;;;;;;;;;;CAQ7B,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,KAAK,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CASjE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D"}

package/dist/cjs/bases.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bases = exports.Chars = void 0;
+exports.resolveSpec = resolveSpec;
+exports.isBaseName = isBaseName;
+const errors_js_1 = require("./errors.js");
+/**
+ * Character sets, ordered by value.
+ *
+ * A character set does not by itself describe an encoding — see `Bases` for
+ * the alphabet/algorithm pairs that do.
+ */
+exports.Chars = {
+    /** Base 10: 0-9 */
+    Decimal: '0123456789',
+    /** RFC 4648 Table 5 — Base16: 0-9A-F */
+    Base16: '0123456789ABCDEF',
+    /** RFC 4648 Table 3 — Base32: A-Z2-7 */
+    Base32: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567',
+    /** RFC 4648 Table 4 — Base32 with extended hex alphabet: 0-9A-V */
+    Base32Hex: '0123456789ABCDEFGHIJKLMNOPQRSTUV',
+    /** Crockford's Base32: 0-9A-HJKMNP-TV-Z (no I, L, O, U) */
+    Base32Crockford: '0123456789ABCDEFGHJKMNPQRSTVWXYZ',
+    /** Alphanumeric: 0-9A-Z */
+    Base36: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ',
+    /** Letters only: A-Za-z */
+    Base52: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+    /** Bitcoin alphabet: 1-9A-HJ-NP-Za-km-z (no 0, O, I, l) */
+    Base58: '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz',
+    /** RFC 4648 Table 1 — Base64: A-Za-z0-9+/ */
+    Base64: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/',
+    /** RFC 4648 Table 2 — URL-safe Base64: A-Za-z0-9-_ */
+    Base64Url: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_',
+    /** XML token Base64: A-Za-z0-9._ */
+    Base64Xml: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._',
+    /** XML name Base64: A-Za-z0-9_: */
+    Base64XmlName: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_:',
+    /** Ascii85: the 85 printable characters from `!` (0x21) to `u` (0x75) */
+    Ascii85: '!"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstu',
+    /** ZeroMQ Z85 (RFC 32): avoids the quote and backslash characters */
+    Z85: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#',
+    /** The five symbols Crockford's Base32 adds for its check symbol, giving a modulus of 37 */
+    CrockfordCheck: '*~$=U',
+};
+/** The characters Crockford's Base32 reads as the digit they resemble. */
+const CROCKFORD_ALIASES = { I: '1', L: '1', O: '0' };
+/**
+ * The encodings this package knows by name.
+ *
+ * Each entry pairs an alphabet with the algorithm that reads it, because the
+ * alphabet alone is ambiguous: `base64` and `radix64` share Table 1 but
+ * produce different strings for the same bytes.
+ *
+ * @example
+ * ```typescript
+ * import { encode, Bases } from 'bufferbase';
+ *
+ * encode(Buffer.from('fo'), 'base64');  // 'Zm8='  — RFC 4648
+ * encode(Buffer.from('fo'), 'radix64'); // 'GZv'   — radix conversion
+ * ```
+ */
+exports.Bases = {
+    // Radix conversion. No external standard fixes these, so nothing here can
+    // disagree with one.
+    decimal: { alphabet: exports.Chars.Decimal, algorithm: 'radix' },
+    base36: { alphabet: exports.Chars.Base36, algorithm: 'radix', caseInsensitive: true },
+    base52: { alphabet: exports.Chars.Base52, algorithm: 'radix' },
+    base58: { alphabet: exports.Chars.Base58, algorithm: 'radix' },
+    /**
+     * Crockford's Base32, which specifies a notation for numbers rather than for
+     * byte streams, so a radix conversion is the right reading of it.
+     *
+     * Decoding accepts either case, reads `I` and `L` as `1` and `O` as `0`, and
+     * ignores hyphens.
+     */
+    base32crockford: {
+        alphabet: exports.Chars.Base32Crockford,
+        algorithm: 'radix',
+        caseInsensitive: true,
+        aliases: CROCKFORD_ALIASES,
+        ignore: '-',
+    },
+    /** Crockford's Base32 carrying its trailing check symbol. */
+    base32crockfordcheck: {
+        alphabet: exports.Chars.Base32Crockford,
+        algorithm: 'radix',
+        caseInsensitive: true,
+        aliases: CROCKFORD_ALIASES,
+        ignore: '-',
+        checkSymbols: exports.Chars.CrockfordCheck,
+    },
+    // Bit-block encoding, RFC 4648.
+    base16: { alphabet: exports.Chars.Base16, algorithm: 'block', pad: false, caseInsensitive: true },
+    hex: { alphabet: exports.Chars.Base16, algorithm: 'block', pad: false, caseInsensitive: true },
+    base32: { alphabet: exports.Chars.Base32, algorithm: 'block', caseInsensitive: true },
+    base32hex: { alphabet: exports.Chars.Base32Hex, algorithm: 'block', caseInsensitive: true },
+    base64: { alphabet: exports.Chars.Base64, algorithm: 'block' },
+    /** Unpadded, as used by JWT and other URL-facing formats. */
+    base64url: { alphabet: exports.Chars.Base64Url, algorithm: 'block', pad: false },
+    base64xml: { alphabet: exports.Chars.Base64Xml, algorithm: 'block', pad: false },
+    base64xmlname: { alphabet: exports.Chars.Base64XmlName, algorithm: 'block', pad: false },
+    // Four bytes to five characters.
+    /** Ascii85 with the zero-block shortcut, matching Python's `a85encode`. */
+    ascii85: { alphabet: exports.Chars.Ascii85, algorithm: 'block85', zeroShortcut: true },
+    /** ZeroMQ Z85, which has no padding and so encodes whole blocks only. */
+    z85: { alphabet: exports.Chars.Z85, algorithm: 'block85', requireFullBlocks: true },
+    // Radix conversion over the RFC alphabets.
+    radix16: { alphabet: exports.Chars.Base16, algorithm: 'radix' },
+    radix32: { alphabet: exports.Chars.Base32, algorithm: 'radix' },
+    radix64: { alphabet: exports.Chars.Base64, algorithm: 'radix' },
+    radix64url: { alphabet: exports.Chars.Base64Url, algorithm: 'radix' },
+};
+/**
+ * Resolves a base name to its codec spec, and passes a spec through unchanged.
+ *
+ * @throws {UnknownBaseError} If the name is not one of `Bases`
+ */
+function resolveSpec(base) {
+    if (typeof base !== 'string') {
+        return base;
+    }
+    const spec = exports.Bases[base.toLowerCase()];
+    if (spec === undefined) {
+        throw new errors_js_1.UnknownBaseError(base);
+    }
+    return spec;
+}
+/**
+ * Checks whether a string names one of the encodings in `Bases`.
+ */
+function isBaseName(value) {
+    return value.toLowerCase() in exports.Bases;
+}
+//# sourceMappingURL=bases.js.map

package/dist/cjs/bases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bases.js","sourceRoot":"","sources":["../../src/bases.ts"],"names":[],"mappings":"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"}

package/dist/cjs/bufferbase.d.ts

@@ -1,60 +1,37 @@
-/// <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.
+ * @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.
  */
+import type { Buffer } from 'node:buffer';
+import type { BufferLike } from './types.js';
+/** @deprecated Import `Chars` from the package root. */
+export { Chars } from './bases.js';
+/** @deprecated Import these from the package root. */
+export { BufferSizeError, InvalidCharacterError } from './errors.js';
+/** @deprecated Use `createCodec(alphabet)`. */
 export declare class BufferEncoder {
-    private baseChars;
+    private readonly codec;
     constructor(baseChars: string);
-    /**
-     * Encodes a buffer to a string.
-     */
-    encode(buffer: Buffer): string;
-    /**
-     * Decodes a string to a buffer.
-     */
+    encode(buffer: BufferLike): string;
     decode(encoded: string, bufferSize?: number): Buffer;
 }
-/**
- * Creates a converter function that can convert between two bases.
- */
+/** @deprecated Use `convert()` or `codec.convertTo()`. */
 export declare class Converter {
-    decoder: BufferEncoder;
-    encoder: BufferEncoder;
+    readonly decoder: BufferEncoder;
+    readonly encoder: BufferEncoder;
     constructor(inputBase: string, outputBase: string);
-    /**
-     * Converts a string from the input base to the output base.
-     */
     convert(input: string): string;
 }
+/** @deprecated Use `validate()` or `codec.validate()`. */
 export declare class Validator {
-    decorder: BufferEncoder;
+    private readonly codec;
     constructor(inputBase: string);
     validate(input: string): boolean;
 }
-export declare const validate: (input: string, base: string) => boolean;
 //# sourceMappingURL=bufferbase.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bufferbase.d.ts","sourceRoot":"","sources":["../../src/bufferbase.ts"],"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"}
+{"version":3,"file":"bufferbase.d.ts","sourceRoot":"","sources":["../../src/bufferbase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,wDAAwD;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,sDAAsD;AACtD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAErE,+CAA+C;AAC/C,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;gBAEvB,SAAS,EAAE,MAAM;IAI7B,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;IAIlC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAGrD;AAED,0DAA0D;AAC1D,qBAAa,SAAS;IACpB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;gBAEpB,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAKjD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAG/B;AAED,0DAA0D;AAC1D,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;gBAEvB,SAAS,EAAE,MAAM;IAI7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGjC"}