bufferbase 1.3.0 → 3.0.0

package/dist/esm/codec-radix.js

@@ -0,0 +1,177 @@
+import { Buffer } from 'node:buffer';
+import { BaseCodec, toBuffer } from './codec-base.js';
+import { BufferSizeError, CheckSymbolError, InvalidCharacterError, InvalidCodecError, InvalidLengthError, } from './errors.js';
+/**
+ * Reads the buffer as one big integer and rewrites it in base
+ * `alphabet.length`.
+ *
+ * This is the Base58 family of encodings. It accepts any alphabet and any
+ * input length, but it is not RFC 4648: the output length is not a fixed
+ * function of the input length, so it cannot be streamed, and encoding is
+ * O(n²) in the input size.
+ *
+ * Leading zero bytes carry no value in an integer, so they are recorded
+ * separately as leading `alphabet[0]` characters.
+ *
+ * @example
+ * ```typescript
+ * import { RadixCodec } from 'bufferbase';
+ *
+ * const binary = new RadixCodec({ alphabet: '01', algorithm: 'radix' });
+ * binary.encode(Uint8Array.of(5)); // '101'
+ * ```
+ */
+export class RadixCodec extends BaseCodec {
+    constructor(spec) {
+        super(spec);
+        this.algorithm = 'radix';
+        const extra = spec.checkSymbols;
+        if (extra === undefined || extra === '') {
+            this.checkChars = null;
+            this.checkValues = new Map();
+            return;
+        }
+        const combined = spec.alphabet + extra;
+        if (new Set(combined).size !== combined.length) {
+            throw new InvalidCodecError('checkSymbols repeat a character of the alphabet');
+        }
+        // The symbol is matched by value, so that a case-insensitive codec accepts
+        // it in either case just as it does the rest of the string.
+        const values = new Map();
+        for (let i = 0; i < combined.length; i++) {
+            const char = combined[i];
+            values.set(char, i);
+            if (spec.caseInsensitive === true) {
+                values.set(char.toLowerCase(), i);
+                values.set(char.toUpperCase(), i);
+            }
+        }
+        this.checkChars = combined;
+        this.checkValues = values;
+    }
+    encode(input) {
+        const buffer = toBuffer(input);
+        const base = this.chars.length;
+        const digits = [];
+        for (const byte of buffer) {
+            let carry = byte;
+            for (let i = 0; i < digits.length; i++) {
+                carry += digits[i] * 256;
+                digits[i] = carry % base;
+                carry = Math.floor(carry / base);
+            }
+            while (carry > 0) {
+                digits.push(carry % base);
+                carry = Math.floor(carry / base);
+            }
+        }
+        for (let i = 0; i < buffer.length && buffer[i] === 0; i++) {
+            digits.push(0);
+        }
+        let out = '';
+        for (let i = digits.length - 1; i >= 0; i--) {
+            out += this.chars[digits[i]];
+        }
+        if (this.checkChars !== null) {
+            out += this.checkChars[this.remainderOf(buffer, this.checkChars.length)];
+        }
+        return out;
+    }
+    decode(encoded, options) {
+        const bytes = this.read(this.strip(encoded));
+        const size = options?.size;
+        if (size === undefined) {
+            return Buffer.from(bytes);
+        }
+        if (bytes.length > size) {
+            throw new BufferSizeError(bytes.length, size);
+        }
+        const padded = Buffer.alloc(size);
+        Buffer.from(bytes).copy(padded, size - bytes.length);
+        return padded;
+    }
+    validate(input) {
+        const stripped = this.strip(input);
+        if (this.checkChars === null) {
+            // Every string over the alphabet decodes, so the characters settle it.
+            for (let i = 0; i < stripped.length; i++) {
+                if (this.valueAt(stripped, i) < 0) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        try {
+            this.read(stripped);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Decodes the body, verifying the check symbol when the codec carries one.
+     *
+     * Everything `decode` can reject other than `DecodeOptions.size` is checked
+     * here, so `validate` and `decode` always agree.
+     */
+    read(input) {
+        let body = input;
+        if (this.checkChars !== null) {
+            if (body.length === 0) {
+                throw new InvalidLengthError(0, 'a checked encoding always carries a check symbol');
+            }
+            const found = body.slice(-1);
+            body = body.slice(0, -1);
+            const bytes = this.toBytes(body);
+            const expected = this.remainderOf(bytes, this.checkChars.length);
+            if (this.checkValues.get(found) !== expected) {
+                throw new CheckSymbolError(found, this.checkChars[expected]);
+            }
+            return bytes;
+        }
+        return this.toBytes(input);
+    }
+    /** Rewrites the digits of `body` as bytes, most significant first. */
+    toBytes(body) {
+        const base = this.chars.length;
+        const bytes = [];
+        let leadingZeros = 0;
+        let stillLeading = true;
+        for (let at = 0; at < body.length; at++) {
+            const value = this.valueAt(body, at);
+            if (value < 0) {
+                throw new InvalidCharacterError(body[at]);
+            }
+            if (stillLeading && value === 0) {
+                leadingZeros++;
+                continue;
+            }
+            stillLeading = false;
+            let carry = value;
+            for (let i = 0; i < bytes.length; i++) {
+                carry += bytes[i] * base;
+                bytes[i] = carry % 256;
+                carry = Math.floor(carry / 256);
+            }
+            while (carry > 0) {
+                bytes.push(carry % 256);
+                carry = Math.floor(carry / 256);
+            }
+        }
+        for (let i = 0; i < leadingZeros; i++) {
+            bytes.push(0);
+        }
+        bytes.reverse();
+        return bytes;
+    }
+    /** The value the bytes denote, modulo `divisor`. */
+    remainderOf(bytes, divisor) {
+        let remainder = 0;
+        for (const byte of bytes) {
+            remainder = (remainder * 256 + byte) % divisor;
+        }
+        return remainder;
+    }
+}
+//# sourceMappingURL=codec-radix.js.map

package/dist/esm/codec-radix.js.map

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

package/dist/esm/codec.d.ts

@@ -0,0 +1,38 @@
+import type { CodecSpec, ICodec } from './types.js';
+import { RadixCodec } from './codec-radix.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'
+ * ```
+ */
+export declare function createCodec(spec: CodecSpec | string): ICodec;
+/**
+ * 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.
+ */
+export declare function getCodec(spec: CodecSpec): ICodec;
+export { RadixCodec } from './codec-radix.js';
+export { BlockCodec } from './codec-block.js';
+export { Block85Codec } from './codec-block85.js';
+/**
+ * @deprecated Use `createCodec({ alphabet, algorithm: 'radix' })`, or
+ * `createCodec(alphabet)` for the same thing.
+ */
+export declare class Codec extends RadixCodec {
+    constructor(chars: string);
+}
+//# sourceMappingURL=codec.d.ts.map

package/dist/esm/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAI9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAY5D;AAID;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAQhD;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;GAGG;AACH,qBAAa,KAAM,SAAQ,UAAU;gBACvB,KAAK,EAAE,MAAM;CAG1B"}

package/dist/esm/codec.js

@@ -0,0 +1,60 @@
+import { RadixCodec } from './codec-radix.js';
+import { BlockCodec } from './codec-block.js';
+import { Block85Codec } from './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'
+ * ```
+ */
+export function createCodec(spec) {
+    const resolved = typeof spec === 'string' ? { alphabet: spec, algorithm: 'radix' } : spec;
+    switch (resolved.algorithm) {
+        case 'radix':
+            return new RadixCodec(resolved);
+        case 'block':
+            return new BlockCodec(resolved);
+        case 'block85':
+            return new 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.
+ */
+export function getCodec(spec) {
+    const cached = cache.get(spec);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const codec = createCodec(spec);
+    cache.set(spec, codec);
+    return codec;
+}
+export { RadixCodec } from './codec-radix.js';
+export { BlockCodec } from './codec-block.js';
+export { Block85Codec } from './codec-block85.js';
+/**
+ * @deprecated Use `createCodec({ alphabet, algorithm: 'radix' })`, or
+ * `createCodec(alphabet)` for the same thing.
+ */
+export class Codec extends RadixCodec {
+    constructor(chars) {
+        super({ alphabet: chars, algorithm: 'radix' });
+    }
+}
+//# sourceMappingURL=codec.js.map

package/dist/esm/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/codec.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,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,UAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,KAAK,OAAO;YACV,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,KAAK,SAAS;YACZ,OAAO,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,OAAO,EAAqB,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,UAAU,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,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;GAGG;AACH,MAAM,OAAO,KAAM,SAAQ,UAAU;IACnC,YAAY,KAAa;QACvB,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;CACF"}

package/dist/esm/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/esm/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/esm/codecs.js

@@ -0,0 +1,16 @@
+import { Bases } from './bases.js';
+import { getCodec } from './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');
+ * ```
+ */
+export const Codecs = Object.fromEntries(Object.entries(Bases).map(([name, spec]) => [name, getCodec(spec)]));
+//# sourceMappingURL=codecs.js.map

package/dist/esm/codecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.js","sourceRoot":"","sources":["../../src/codecs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAiB,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CACxC,CAAC"}

package/dist/esm/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/esm/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/esm/errors.js

@@ -0,0 +1,119 @@
+/**
+ * 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) {
+        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, expected) {
+        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) {
+        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, detail) {
+        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) {
+        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) {
+        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) {
+        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, expected) {
+        super(`Check symbol '${found}' does not match the expected '${expected}'`);
+        this.name = 'CheckSymbolError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,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;AAED;;;GAGG;AACH,MAAM,OAAO,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;AAED;;GAEG;AACH,MAAM,OAAO,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;AAED;;;;;;GAMG;AACH,MAAM,OAAO,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;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,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;AAED;;;GAGG;AACH,MAAM,OAAO,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;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,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;AAED;;;GAGG;AACH,MAAM,OAAO,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"}

package/dist/esm/example.js

@@ -1,37 +1,53 @@
-import { Chars, BufferEncoder, Converter, Validator } from './bufferbase.js';
-// Example buffer
+import { Buffer } from 'node:buffer';
+import { encode, decode, convert, validate, createCodec, Chars, Codecs } from './index.js';
 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);
+// 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 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'),
-    base32encoded,
-    base58encoded,
-    base64encoded,
-    isValidAsBase64,
-    decoded: decoded.toString('utf8'),
+    base58,
+    base64url,
+    valid: validate(base64url, 'base64url'),
+    decoded: decode(base64url, 'base64url').toString('utf8'),
+});
+// 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'),
+});
+// 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({
+    '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!'         │
-// └─────────────────┴─────────────────────────┘
 //# sourceMappingURL=example.js.map