bufferbase 1.3.0 → 3.0.0

package/dist/cjs/codec.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Codec = exports.Block85Codec = exports.BlockCodec = exports.RadixCodec = void 0;
+exports.createCodec = createCodec;
+exports.getCodec = getCodec;
+const codec_radix_js_1 = require("./codec-radix.js");
+const codec_block_js_1 = require("./codec-block.js");
+const codec_block85_js_1 = require("./codec-block85.js");
+/**
+ * Builds the codec described by a spec.
+ *
+ * A bare string is read as a custom alphabet for a radix conversion, which is
+ * the only algorithm that works with an alphabet of any length.
+ *
+ * @example
+ * ```typescript
+ * import { createCodec } from 'bufferbase';
+ *
+ * const binary = createCodec('01');
+ * binary.encode(Uint8Array.of(5)); // '101'
+ *
+ * const paddedHex = createCodec({ alphabet: '0123456789abcdef', algorithm: 'block' });
+ * paddedHex.encode(Uint8Array.of(0, 1)); // '0001'
+ * ```
+ */
+function createCodec(spec) {
+    const resolved = typeof spec === 'string' ? { alphabet: spec, algorithm: 'radix' } : spec;
+    switch (resolved.algorithm) {
+        case 'radix':
+            return new codec_radix_js_1.RadixCodec(resolved);
+        case 'block':
+            return new codec_block_js_1.BlockCodec(resolved);
+        case 'block85':
+            return new codec_block85_js_1.Block85Codec(resolved);
+    }
+}
+const cache = new WeakMap();
+/**
+ * Returns the codec for a spec, building it once per spec object.
+ *
+ * Named bases always resolve to the same spec object, so they are built once
+ * for the lifetime of the process.
+ */
+function getCodec(spec) {
+    const cached = cache.get(spec);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const codec = createCodec(spec);
+    cache.set(spec, codec);
+    return codec;
+}
+var codec_radix_js_2 = require("./codec-radix.js");
+Object.defineProperty(exports, "RadixCodec", { enumerable: true, get: function () { return codec_radix_js_2.RadixCodec; } });
+var codec_block_js_2 = require("./codec-block.js");
+Object.defineProperty(exports, "BlockCodec", { enumerable: true, get: function () { return codec_block_js_2.BlockCodec; } });
+var codec_block85_js_2 = require("./codec-block85.js");
+Object.defineProperty(exports, "Block85Codec", { enumerable: true, get: function () { return codec_block85_js_2.Block85Codec; } });
+/**
+ * @deprecated Use `createCodec({ alphabet, algorithm: 'radix' })`, or
+ * `createCodec(alphabet)` for the same thing.
+ */
+class Codec extends codec_radix_js_1.RadixCodec {
+    constructor(chars) {
+        super({ alphabet: chars, algorithm: 'radix' });
+    }
+}
+exports.Codec = Codec;
+//# sourceMappingURL=codec.js.map

package/dist/cjs/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/codec.ts"],"names":[],"mappings":";;;AAsBA,kCAYC;AAUD,4BAQC;AAnDD,qDAA8C;AAC9C,qDAA8C;AAC9C,yDAAkD;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,WAAW,CAAC,IAAwB;IAClD,MAAM,QAAQ,GACZ,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAE3E,QAAQ,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC3B,KAAK,OAAO;YACV,OAAO,IAAI,2BAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,KAAK,OAAO;YACV,OAAO,IAAI,2BAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,KAAK,SAAS;YACZ,OAAO,IAAI,+BAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,OAAO,EAAqB,CAAC;AAE/C;;;;;GAKG;AACH,SAAgB,QAAQ,CAAC,IAAe;IACtC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAChC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mDAA8C;AAArC,4GAAA,UAAU,OAAA;AACnB,mDAA8C;AAArC,4GAAA,UAAU,OAAA;AACnB,uDAAkD;AAAzC,gHAAA,YAAY,OAAA;AAErB;;;GAGG;AACH,MAAa,KAAM,SAAQ,2BAAU;IACnC,YAAY,KAAa;QACvB,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;CACF;AAJD,sBAIC"}

package/dist/cjs/codecs.d.ts

@@ -0,0 +1,20 @@
+import type { ICodec } from './types.js';
+import { type BaseName } from './bases.js';
+/**
+ * A ready-made codec for every name in `Bases`.
+ *
+ * @example
+ * ```typescript
+ * import { Codecs } from 'bufferbase';
+ *
+ * Codecs.base58.encode(Buffer.from('Hello'));      // '9Ajdvzr'
+ * Codecs.base64.encode(Buffer.from('fo'));         // 'Zm8='
+ * Codecs.base58.convertTo(Codecs.base64url, '9Ajdvzr');
+ * ```
+ */
+export declare const Codecs: Record<BaseName, ICodec>;
+/**
+ * Type representing valid codec names in the `Codecs` object.
+ */
+export type CodecName = BaseName;
+//# sourceMappingURL=codecs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../../src/codecs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAS,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,EAEd,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAE9B;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC"}

package/dist/cjs/codecs.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Codecs = void 0;
+const bases_js_1 = require("./bases.js");
+const codec_js_1 = require("./codec.js");
+/**
+ * A ready-made codec for every name in `Bases`.
+ *
+ * @example
+ * ```typescript
+ * import { Codecs } from 'bufferbase';
+ *
+ * Codecs.base58.encode(Buffer.from('Hello'));      // '9Ajdvzr'
+ * Codecs.base64.encode(Buffer.from('fo'));         // 'Zm8='
+ * Codecs.base58.convertTo(Codecs.base64url, '9Ajdvzr');
+ * ```
+ */
+exports.Codecs = Object.fromEntries(Object.entries(bases_js_1.Bases).map(([name, spec]) => [name, (0, codec_js_1.getCodec)(spec)]));
+//# sourceMappingURL=codecs.js.map

package/dist/cjs/codecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.js","sourceRoot":"","sources":["../../src/codecs.ts"],"names":[],"mappings":";;;AACA,yCAAkD;AAClD,yCAAsC;AAEtC;;;;;;;;;;;GAWG;AACU,QAAA,MAAM,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,gBAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAA,mBAAQ,EAAC,IAAI,CAAC,CAAC,CAAC,CACxC,CAAC"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Error thrown when an invalid character is encountered during decoding.
+ */
+export declare class InvalidCharacterError extends Error {
+    /**
+     * @param char - The invalid character that was encountered (optional)
+     */
+    constructor(char?: string);
+}
+/**
+ * Error thrown when the decoded buffer does not have the size requested
+ * through `DecodeOptions.size`.
+ */
+export declare class BufferSizeError extends Error {
+    /**
+     * @param actual - The actual decoded buffer size
+     * @param expected - The expected (specified) buffer size
+     */
+    constructor(actual: number, expected: number);
+}
+/**
+ * Error thrown when an unknown base name is provided.
+ */
+export declare class UnknownBaseError extends Error {
+    /**
+     * @param name - The unknown base name that was provided
+     */
+    constructor(name: string);
+}
+/**
+ * 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 declare class InvalidLengthError extends Error {
+    /**
+     * @param length - The length that cannot occur
+     * @param detail - What the length should have been
+     */
+    constructor(length: number, detail: string);
+}
+/**
+ * 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 declare class NonCanonicalError extends Error {
+    /**
+     * @param detail - What made the input non-canonical
+     */
+    constructor(detail: string);
+}
+/**
+ * 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 declare class InvalidCodecError extends Error {
+    /**
+     * @param detail - Why the spec is unusable
+     */
+    constructor(detail: string);
+}
+/**
+ * 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 declare class ValueRangeError extends Error {
+    /**
+     * @param group - The group of characters that is out of range
+     */
+    constructor(group: string);
+}
+/**
+ * Error thrown when a trailing check symbol does not match the value it
+ * follows, which means the string was mistyped or corrupted.
+ */
+export declare 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);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C;;OAEG;gBACS,IAAI,CAAC,EAAE,MAAM;CAK1B;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC;;;OAGG;gBACS,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI7C;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC;;OAEG;gBACS,IAAI,EAAE,MAAM;CAOzB;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C;;;OAGG;gBACS,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI3C;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C;;OAEG;gBACS,MAAM,EAAE,MAAM;CAI3B;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C;;OAEG;gBACS,MAAM,EAAE,MAAM;CAI3B;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC;;OAEG;gBACS,KAAK,EAAE,MAAM;CAI1B;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC;;;OAGG;gBACS,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI5C"}

package/dist/cjs/errors.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckSymbolError = exports.ValueRangeError = exports.InvalidCodecError = exports.NonCanonicalError = exports.InvalidLengthError = exports.UnknownBaseError = exports.BufferSizeError = exports.InvalidCharacterError = void 0;
+/**
+ * Error thrown when an invalid character is encountered during decoding.
+ */
+class InvalidCharacterError extends Error {
+    /**
+     * @param char - The invalid character that was encountered (optional)
+     */
+    constructor(char) {
+        const message = char ? `Invalid character found: '${char}'` : 'Invalid character found';
+        super(message);
+        this.name = 'InvalidCharacterError';
+    }
+}
+exports.InvalidCharacterError = InvalidCharacterError;
+/**
+ * Error thrown when the decoded buffer does not have the size requested
+ * through `DecodeOptions.size`.
+ */
+class BufferSizeError extends Error {
+    /**
+     * @param actual - The actual decoded buffer size
+     * @param expected - The expected (specified) buffer size
+     */
+    constructor(actual, expected) {
+        super(`Buffer size ${actual} does not match specified size ${expected}`);
+        this.name = 'BufferSizeError';
+    }
+}
+exports.BufferSizeError = BufferSizeError;
+/**
+ * Error thrown when an unknown base name is provided.
+ */
+class UnknownBaseError extends Error {
+    /**
+     * @param name - The unknown base name that was provided
+     */
+    constructor(name) {
+        super(`Unknown base encoding: '${name}'. ` +
+            'Pass a CodecSpec such as { alphabet, algorithm: \'radix\' } to use a custom alphabet.');
+        this.name = 'UnknownBaseError';
+    }
+}
+exports.UnknownBaseError = 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.
+ */
+class InvalidLengthError extends Error {
+    /**
+     * @param length - The length that cannot occur
+     * @param detail - What the length should have been
+     */
+    constructor(length, detail) {
+        super(`Invalid encoded length ${length}: ${detail}`);
+        this.name = 'InvalidLengthError';
+    }
+}
+exports.InvalidLengthError = 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.
+ */
+class NonCanonicalError extends Error {
+    /**
+     * @param detail - What made the input non-canonical
+     */
+    constructor(detail) {
+        super(`Non-canonical encoding: ${detail}`);
+        this.name = 'NonCanonicalError';
+    }
+}
+exports.NonCanonicalError = 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.
+ */
+class InvalidCodecError extends Error {
+    /**
+     * @param detail - Why the spec is unusable
+     */
+    constructor(detail) {
+        super(`Invalid codec: ${detail}`);
+        this.name = 'InvalidCodecError';
+    }
+}
+exports.InvalidCodecError = 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.
+ */
+class ValueRangeError extends Error {
+    /**
+     * @param group - The group of characters that is out of range
+     */
+    constructor(group) {
+        super(`Encoded group '${group}' exceeds the maximum value for its block`);
+        this.name = 'ValueRangeError';
+    }
+}
+exports.ValueRangeError = ValueRangeError;
+/**
+ * Error thrown when a trailing check symbol does not match the value it
+ * follows, which means the string was mistyped or corrupted.
+ */
+class CheckSymbolError extends Error {
+    /**
+     * @param found - The check symbol present in the input
+     * @param expected - The check symbol the value calls for
+     */
+    constructor(found, expected) {
+        super(`Check symbol '${found}' does not match the expected '${expected}'`);
+        this.name = 'CheckSymbolError';
+    }
+}
+exports.CheckSymbolError = CheckSymbolError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAC9C;;OAEG;IACH,YAAY,IAAa;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,6BAA6B,IAAI,GAAG,CAAC,CAAC,CAAC,yBAAyB,CAAC;QACxF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AATD,sDASC;AAED;;;GAGG;AACH,MAAa,eAAgB,SAAQ,KAAK;IACxC;;;OAGG;IACH,YAAY,MAAc,EAAE,QAAgB;QAC1C,KAAK,CAAC,eAAe,MAAM,kCAAkC,QAAQ,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AATD,0CASC;AAED;;GAEG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IACzC;;OAEG;IACH,YAAY,IAAY;QACtB,KAAK,CACH,2BAA2B,IAAI,KAAK;YAClC,uFAAuF,CAC1F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAXD,4CAWC;AAED;;;;;;GAMG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAC3C;;;OAGG;IACH,YAAY,MAAc,EAAE,MAAc;QACxC,KAAK,CAAC,0BAA0B,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AATD,gDASC;AAED;;;;;;;GAOG;AACH,MAAa,iBAAkB,SAAQ,KAAK;IAC1C;;OAEG;IACH,YAAY,MAAc;QACxB,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AARD,8CAQC;AAED;;;GAGG;AACH,MAAa,iBAAkB,SAAQ,KAAK;IAC1C;;OAEG;IACH,YAAY,MAAc;QACxB,KAAK,CAAC,kBAAkB,MAAM,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AARD,8CAQC;AAED;;;;;;;GAOG;AACH,MAAa,eAAgB,SAAQ,KAAK;IACxC;;OAEG;IACH,YAAY,KAAa;QACvB,KAAK,CAAC,kBAAkB,KAAK,2CAA2C,CAAC,CAAC;QAC1E,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AARD,0CAQC;AAED;;;GAGG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IACzC;;;OAGG;IACH,YAAY,KAAa,EAAE,QAAgB;QACzC,KAAK,CAAC,iBAAiB,KAAK,kCAAkC,QAAQ,GAAG,CAAC,CAAC;QAC3E,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AATD,4CASC"}

package/dist/cjs/example.js

@@ -1,39 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const bufferbase_js_1 = require("./bufferbase.js");
-// Example buffer
-const bytes = Buffer.from('Hello, World!', 'utf8');
-// Encoding buffer to Base32
-const encoder = new bufferbase_js_1.BufferEncoder(bufferbase_js_1.Chars.Base32Crockford);
-const base32encoded = encoder.encode(bytes);
-// Converting Base32 to Base58
-const converter_32to58 = new bufferbase_js_1.Converter(bufferbase_js_1.Chars.Base32Crockford, bufferbase_js_1.Chars.Base58);
-const base58encoded = converter_32to58.convert(base32encoded);
-// Converting Base32 to Base58
-const converter_58to64 = new bufferbase_js_1.Converter(bufferbase_js_1.Chars.Base58, bufferbase_js_1.Chars.Base64_URL_SAFE);
-const base64encoded = converter_58to64.convert(base58encoded);
-// Validating Base64
-const validatorB64 = new bufferbase_js_1.Validator(bufferbase_js_1.Chars.Base64_URL_SAFE);
-const isValidAsBase64 = validatorB64.validate(base64encoded);
-// Decoding Base64
-const decoder = new bufferbase_js_1.BufferEncoder(bufferbase_js_1.Chars.Base64_URL_SAFE);
-const decoded = decoder.decode(base64encoded);
+const node_buffer_1 = require("node:buffer");
+const index_js_1 = require("./index.js");
+const bytes = node_buffer_1.Buffer.from('Hello, World!', 'utf8');
+// The same bytes under each algorithm.
+console.log('=== Algorithms ===');
+console.table({
+    'block   base64': (0, index_js_1.encode)(bytes, 'base64'),
+    'block   base32': (0, index_js_1.encode)(bytes, 'base32'),
+    'block85 ascii85': (0, index_js_1.encode)(bytes, 'ascii85'),
+    'radix   base58': (0, index_js_1.encode)(bytes, 'base58'),
+    'radix   base32crockford': (0, index_js_1.encode)(bytes, 'base32crockford'),
+});
+// Converting goes through the bytes, so any pair works.
+console.log('\n=== Function API ===');
+const base58 = (0, index_js_1.encode)(bytes, 'base58');
+const base64url = (0, index_js_1.convert)(base58, 'base58', 'base64url');
 console.table({
     bytes: bytes.toString('utf8'),
-    base32encoded,
-    base58encoded,
-    base64encoded,
-    isValidAsBase64,
-    decoded: decoded.toString('utf8'),
+    base58,
+    base64url,
+    valid: (0, index_js_1.validate)(base64url, 'base64url'),
+    decoded: (0, index_js_1.decode)(base64url, 'base64url').toString('utf8'),
+});
+// validate() agrees with decode(): it checks length, padding and canonicality.
+console.log('\n=== Rejected input ===');
+console.table({
+    "'Zm8=' (canonical)": (0, index_js_1.validate)('Zm8=', 'base64'),
+    "'Zm9=' (spare bits set)": (0, index_js_1.validate)('Zm9=', 'base64'),
+    "'Zm9vd' (5 characters)": (0, index_js_1.validate)('Zm9vd', 'base64'),
+});
+// Crockford's Base32 reads what a person is likely to have written down.
+console.log('\n=== Crockford ===');
+const crockford = (0, index_js_1.encode)(bytes, 'base32crockfordcheck');
+console.table({
+    encoded: crockford,
+    'as typed': (0, index_js_1.decode)(`${crockford.slice(0, 4)}-${crockford.slice(4)}`.toLowerCase(), 'base32crockfordcheck').toString('utf8'),
+    'one character changed': (0, index_js_1.validate)(`${crockford.slice(0, -2)}Z${crockford.slice(-1)}`, 'base32crockfordcheck'),
+});
+// Codecs, and a custom alphabet.
+console.log('\n=== Codecs and custom alphabets ===');
+const binary = (0, index_js_1.createCodec)('01');
+const adobe = (0, index_js_1.createCodec)({
+    alphabet: index_js_1.Chars.Ascii85,
+    algorithm: 'block85',
+    zeroShortcut: true,
+    delimiters: true,
+});
+console.table({
+    'Codecs.base58': index_js_1.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!'         │
-// └─────────────────┴─────────────────────────┘
 //# sourceMappingURL=example.js.map

package/dist/cjs/example.js.map

@@ -1 +1 @@
-{"version":3,"file":"example.js","sourceRoot":"","sources":["../../src/example.ts"],"names":[],"mappings":";;AAAA,mDAA6E;AAE7E,iBAAiB;AACjB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAEnD,4BAA4B;AAC5B,MAAM,OAAO,GAAG,IAAI,6BAAa,CAAC,qBAAK,CAAC,eAAe,CAAC,CAAC;AACzD,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAE5C,8BAA8B;AAC9B,MAAM,gBAAgB,GAAG,IAAI,yBAAS,CAAC,qBAAK,CAAC,eAAe,EAAE,qBAAK,CAAC,MAAM,CAAC,CAAC;AAC5E,MAAM,aAAa,GAAG,gBAAgB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;AAE9D,8BAA8B;AAC9B,MAAM,gBAAgB,GAAG,IAAI,yBAAS,CAAC,qBAAK,CAAC,MAAM,EAAE,qBAAK,CAAC,eAAe,CAAC,CAAC;AAC5E,MAAM,aAAa,GAAG,gBAAgB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;AAE9D,oBAAoB;AACpB,MAAM,YAAY,GAAG,IAAI,yBAAS,CAAC,qBAAK,CAAC,eAAe,CAAC,CAAC;AAC1D,MAAM,eAAe,GAAG,YAAY,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AAE7D,kBAAkB;AAClB,MAAM,OAAO,GAAG,IAAI,6BAAa,CAAC,qBAAK,CAAC,eAAe,CAAC,CAAC;AACzD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;AAE9C,OAAO,CAAC,KAAK,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC7B,aAAa;IACb,aAAa;IACb,aAAa;IACb,eAAe;IACf,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;CAClC,CAAC,CAAC;AACH,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD"}
+{"version":3,"file":"example.js","sourceRoot":"","sources":["../../src/example.ts"],"names":[],"mappings":"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"}

package/dist/cjs/functions.d.ts

@@ -0,0 +1,58 @@
+import type { BufferLike, CodecSpec, DecodeOptions } from './types.js';
+import type { Buffer } from 'node:buffer';
+import { type BaseName } from './bases.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 declare function encode(buffer: BufferLike, base: Base): string;
+/**
+ * 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 declare function decode(encoded: string, base: Base, options?: DecodeOptions): Buffer;
+/**
+ * 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 declare function convert(input: string, from: Base, to: Base): string;
+/**
+ * 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 declare function validate(input: string, base: Base): boolean;
+//# sourceMappingURL=functions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../src/functions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGxD,2DAA2D;AAC3D,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,SAAS,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAEnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,CAInE;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAE3D"}

package/dist/cjs/functions.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encode = encode;
+exports.decode = decode;
+exports.convert = convert;
+exports.validate = validate;
+const bases_js_1 = require("./bases.js");
+const codec_js_1 = require("./codec.js");
+/**
+ * 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'
+ * ```
+ */
+function encode(buffer, base) {
+    return (0, codec_js_1.getCodec)((0, bases_js_1.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 });
+ * ```
+ */
+function decode(encoded, base, options) {
+    return (0, codec_js_1.getCodec)((0, bases_js_1.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
+ * ```
+ */
+function convert(input, from, to) {
+    const source = (0, codec_js_1.getCodec)((0, bases_js_1.resolveSpec)(from));
+    const target = (0, codec_js_1.getCodec)((0, bases_js_1.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
+ * ```
+ */
+function validate(input, base) {
+    return (0, codec_js_1.getCodec)((0, bases_js_1.resolveSpec)(base)).validate(input);
+}
+//# sourceMappingURL=functions.js.map

package/dist/cjs/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sourceRoot":"","sources":["../../src/functions.ts"],"names":[],"mappings":";;AAoBA,wBAEC;AAmBD,wBAEC;AAWD,0BAIC;AAYD,4BAEC;AAtED,yCAAwD;AACxD,yCAAsC;AAKtC;;;;;;;;;;;GAWG;AACH,SAAgB,MAAM,CAAC,MAAkB,EAAE,IAAU;IACnD,OAAO,IAAA,mBAAQ,EAAC,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,MAAM,CAAC,OAAe,EAAE,IAAU,EAAE,OAAuB;IACzE,OAAO,IAAA,mBAAQ,EAAC,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,OAAO,CAAC,KAAa,EAAE,IAAU,EAAE,EAAQ;IACzD,MAAM,MAAM,GAAG,IAAA,mBAAQ,EAAC,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAA,mBAAQ,EAAC,IAAA,sBAAW,EAAC,EAAE,CAAC,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,QAAQ,CAAC,KAAa,EAAE,IAAU;IAChD,OAAO,IAAA,mBAAQ,EAAC,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC"}

package/dist/cjs/index.d.ts

@@ -1,2 +1,11 @@
-export { Chars, BufferEncoder, Converter, InvalidCharacterError, Validator, validate, } from './bufferbase.js';
+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';
+export { BufferSizeError, CheckSymbolError, InvalidCharacterError, InvalidCodecError, InvalidLengthError, NonCanonicalError, UnknownBaseError, ValueRangeError, } from './errors.js';
+export { Block85Codec, BlockCodec, Codec, RadixCodec, createCodec, getCodec } from './codec.js';
+export { Bases, Chars, isBaseName, resolveSpec } from './bases.js';
+export { convert, decode, encode, validate } from './functions.js';
+export { Codecs } from './codecs.js';
+export { BufferEncoder, Converter, Validator } from './bufferbase.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,aAAa,EACb,SAAS,EACT,qBAAqB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,UAAU,EACV,SAAS,EACT,aAAa,EACb,MAAM,EACN,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGhG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGnE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAGnE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}