bufferbase 2.0.0 → 3.0.0

package/dist/esm/codecs.d.ts

@@ -1,71 +1,20 @@
-import { Codec } from './codec.js';
+import type { ICodec } from './types.js';
+import { type BaseName } from './bases.js';
 /**
- * Pre-defined codec instances for common base encodings.
- *
- * Use these for encoding/decoding without creating codec instances manually.
- * Each codec provides `encode()`, `decode()`, `validate()`, and `convertTo()` methods.
+ * A ready-made codec for every name in `Bases`.
  *
  * @example
  * ```typescript
  * import { Codecs } from 'bufferbase';
  *
- * // Encode to Base58
- * const encoded = Codecs.base58.encode(Buffer.from('Hello'));
- *
- * // Decode from Base58
- * const decoded = Codecs.base58.decode(encoded);
- *
- * // Convert between bases
- * const base64 = Codecs.base58.convertTo(Codecs.base64url, encoded);
- *
- * // Validate
- * Codecs.base58.validate(encoded); // true
+ * Codecs.base58.encode(Buffer.from('Hello'));      // '9Ajdvzr'
+ * Codecs.base64.encode(Buffer.from('fo'));         // 'Zm8='
+ * Codecs.base58.convertTo(Codecs.base64url, '9Ajdvzr');
  * ```
- *
- * Available codecs:
- * - `decimal` - Base 10 (0-9)
- * - `base16` / `hex` - Hexadecimal (0-9A-F)
- * - `base32` - RFC 4648 Base32 (A-Z2-7)
- * - `base32crockford` - Crockford's Base32
- * - `base36` - Alphanumeric (0-9A-Z)
- * - `base52` - Letters only (A-Za-z)
- * - `base58` - Bitcoin alphabet
- * - `base64` - Standard Base64
- * - `base64url` - URL-safe Base64
- * - `base64xml` - XML token Base64
- * - `base64xmlname` - XML name Base64
- * - `ascii85` - ASCII85 encoding
- * - `base85` - Base85 encoding
- * - `z85` - ZeroMQ Z85 encoding
  */
-export declare const Codecs: {
-    readonly decimal: Codec;
-    readonly base16: Codec;
-    readonly hex: Codec;
-    readonly base32: Codec;
-    readonly base32crockford: Codec;
-    readonly base36: Codec;
-    readonly base52: Codec;
-    readonly base58: Codec;
-    readonly base64: Codec;
-    readonly base64url: Codec;
-    readonly base64xml: Codec;
-    readonly base64xmlname: Codec;
-    readonly ascii85: Codec;
-    readonly base85: Codec;
-    readonly z85: Codec;
-};
+export declare const Codecs: Record<BaseName, ICodec>;
 /**
  * Type representing valid codec names in the `Codecs` object.
- *
- * @example
- * ```typescript
- * import { Codecs, CodecName } from 'bufferbase';
- *
- * function getCodec(name: CodecName) {
- *   return Codecs[name];
- * }
- * ```
  */
-export type CodecName = keyof typeof Codecs;
+export type CodecName = BaseName;
 //# sourceMappingURL=codecs.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../../src/codecs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAgDnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;CAgBT,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,MAAM,CAAC"}
+{"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

@@ -1,89 +1,16 @@
-import { Codec } from './codec.js';
-import { Chars } from './bases.js';
-/** Decimal (base 10) codec: 0-9 */
-const decimal = new Codec(Chars.Decimal);
-/** Hexadecimal (base 16) codec: 0-9A-F */
-const base16 = new Codec(Chars.Base16);
-/** Alias for base16 */
-const hex = base16;
-/** RFC 4648 Base32 codec: A-Z2-7 */
-const base32 = new Codec(Chars.Base32);
-/** Crockford's Base32 codec: 0-9A-HJKMNP-TV-Z (no I, L, O, U) */
-const base32crockford = new Codec(Chars.Base32Crockford);
-/** Base36 codec: 0-9A-Z */
-const base36 = new Codec(Chars.Base36);
-/** Base52 codec: A-Za-z (letters only) */
-const base52 = new Codec(Chars.Base52);
-/** Bitcoin Base58 codec: 1-9A-HJ-NP-Za-km-z (no 0, O, I, l) */
-const base58 = new Codec(Chars.Base58);
-/** Standard Base64 codec: A-Za-z0-9+/ */
-const base64 = new Codec(Chars.Base64);
-/** URL-safe Base64 codec: A-Za-z0-9-_ */
-const base64url = new Codec(Chars.Base64Url);
-/** XML token Base64 codec: A-Za-z0-9._ */
-const base64xml = new Codec(Chars.Base64Xml);
-/** XML name Base64 codec: A-Za-z0-9_: */
-const base64xmlname = new Codec(Chars.Base64XmlName);
-/** ASCII85 codec */
-const ascii85 = new Codec(Chars.Ascii85);
-/** Base85 codec */
-const base85 = new Codec(Chars.Base85);
-/** ZeroMQ Z85 codec */
-const z85 = new Codec(Chars.Z85);
+import { Bases } from './bases.js';
+import { getCodec } from './codec.js';
 /**
- * Pre-defined codec instances for common base encodings.
- *
- * Use these for encoding/decoding without creating codec instances manually.
- * Each codec provides `encode()`, `decode()`, `validate()`, and `convertTo()` methods.
+ * A ready-made codec for every name in `Bases`.
  *
  * @example
  * ```typescript
  * import { Codecs } from 'bufferbase';
  *
- * // Encode to Base58
- * const encoded = Codecs.base58.encode(Buffer.from('Hello'));
- *
- * // Decode from Base58
- * const decoded = Codecs.base58.decode(encoded);
- *
- * // Convert between bases
- * const base64 = Codecs.base58.convertTo(Codecs.base64url, encoded);
- *
- * // Validate
- * Codecs.base58.validate(encoded); // true
+ * Codecs.base58.encode(Buffer.from('Hello'));      // '9Ajdvzr'
+ * Codecs.base64.encode(Buffer.from('fo'));         // 'Zm8='
+ * Codecs.base58.convertTo(Codecs.base64url, '9Ajdvzr');
  * ```
- *
- * Available codecs:
- * - `decimal` - Base 10 (0-9)
- * - `base16` / `hex` - Hexadecimal (0-9A-F)
- * - `base32` - RFC 4648 Base32 (A-Z2-7)
- * - `base32crockford` - Crockford's Base32
- * - `base36` - Alphanumeric (0-9A-Z)
- * - `base52` - Letters only (A-Za-z)
- * - `base58` - Bitcoin alphabet
- * - `base64` - Standard Base64
- * - `base64url` - URL-safe Base64
- * - `base64xml` - XML token Base64
- * - `base64xmlname` - XML name Base64
- * - `ascii85` - ASCII85 encoding
- * - `base85` - Base85 encoding
- * - `z85` - ZeroMQ Z85 encoding
  */
-export const Codecs = {
-    decimal,
-    base16,
-    hex,
-    base32,
-    base32crockford,
-    base36,
-    base52,
-    base58,
-    base64,
-    base64url,
-    base64xml,
-    base64xmlname,
-    ascii85,
-    base85,
-    z85,
-};
+export const Codecs = Object.fromEntries(Object.entries(Bases).map(([name, spec]) => [name, getCodec(spec)]));
 //# sourceMappingURL=codecs.js.map

package/dist/esm/codecs.js.map

@@ -1 +1 @@
-{"version":3,"file":"codecs.js","sourceRoot":"","sources":["../../src/codecs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,mCAAmC;AACnC,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAEzC,0CAA0C;AAC1C,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,uBAAuB;AACvB,MAAM,GAAG,GAAG,MAAM,CAAC;AAEnB,oCAAoC;AACpC,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,iEAAiE;AACjE,MAAM,eAAe,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;AAEzD,2BAA2B;AAC3B,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,0CAA0C;AAC1C,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,+DAA+D;AAC/D,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,yCAAyC;AACzC,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,yCAAyC;AACzC,MAAM,SAAS,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AAE7C,0CAA0C;AAC1C,MAAM,SAAS,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AAE7C,yCAAyC;AACzC,MAAM,aAAa,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;AAErD,oBAAoB;AACpB,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAEzC,mBAAmB;AACnB,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,uBAAuB;AACvB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,OAAO;IACP,MAAM;IACN,GAAG;IACH,MAAM;IACN,eAAe;IACf,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,SAAS;IACT,SAAS;IACT,aAAa;IACb,OAAO;IACP,MAAM;IACN,GAAG;CACK,CAAC"}
+{"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

@@ -1,18 +1,5 @@
 /**
  * Error thrown when an invalid character is encountered during decoding.
- *
- * @example
- * ```typescript
- * import { decode, InvalidCharacterError } from 'bufferbase';
- *
- * try {
- *   decode('invalid!', 'base58');
- * } catch (e) {
- *   if (e instanceof InvalidCharacterError) {
- *     console.log(e.message); // "Invalid character found: '!'"
- *   }
- * }
- * ```
  */
 export declare class InvalidCharacterError extends Error {
     /**
@@ -21,24 +8,8 @@ export declare class InvalidCharacterError extends Error {
     constructor(char?: string);
 }
 /**
- * Error thrown when decoded buffer size exceeds the specified size.
- *
- * This error is thrown when using the `size` option in decode operations
- * and the decoded data is larger than the specified size.
- *
- * @example
- * ```typescript
- * import { decode, BufferSizeError } from 'bufferbase';
- *
- * try {
- *   // Trying to decode into a buffer too small
- *   decode('72k1xXWG59fYdzSNoA', 'base58', { size: 2 });
- * } catch (e) {
- *   if (e instanceof BufferSizeError) {
- *     console.log(e.message); // "Buffer size 13 exceeds specified size 2"
- *   }
- * }
- * ```
+ * Error thrown when the decoded buffer does not have the size requested
+ * through `DecodeOptions.size`.
  */
 export declare class BufferSizeError extends Error {
     /**
@@ -49,23 +20,6 @@ export declare class BufferSizeError extends Error {
 }
 /**
  * Error thrown when an unknown base name is provided.
- *
- * This error is thrown when using the function API with an invalid base name
- * that is neither a known encoding name nor a valid custom character set
- * (character sets must be longer than 15 characters).
- *
- * @example
- * ```typescript
- * import { encode, UnknownBaseError } from 'bufferbase';
- *
- * try {
- *   encode(Buffer.from('test'), 'invalidbase');
- * } catch (e) {
- *   if (e instanceof UnknownBaseError) {
- *     console.log(e.message); // "Unknown base encoding: 'invalidbase'"
- *   }
- * }
- * ```
  */
 export declare class UnknownBaseError extends Error {
     /**
@@ -73,4 +27,67 @@ export declare class UnknownBaseError extends Error {
      */
     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

@@ -1 +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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC;;;OAGG;gBACS,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI7C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC;;OAEG;gBACS,IAAI,EAAE,MAAM;CAIzB"}
+{"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

@@ -1,18 +1,5 @@
 /**
  * Error thrown when an invalid character is encountered during decoding.
- *
- * @example
- * ```typescript
- * import { decode, InvalidCharacterError } from 'bufferbase';
- *
- * try {
- *   decode('invalid!', 'base58');
- * } catch (e) {
- *   if (e instanceof InvalidCharacterError) {
- *     console.log(e.message); // "Invalid character found: '!'"
- *   }
- * }
- * ```
  */
 export class InvalidCharacterError extends Error {
     /**
@@ -25,24 +12,8 @@ export class InvalidCharacterError extends Error {
     }
 }
 /**
- * Error thrown when decoded buffer size exceeds the specified size.
- *
- * This error is thrown when using the `size` option in decode operations
- * and the decoded data is larger than the specified size.
- *
- * @example
- * ```typescript
- * import { decode, BufferSizeError } from 'bufferbase';
- *
- * try {
- *   // Trying to decode into a buffer too small
- *   decode('72k1xXWG59fYdzSNoA', 'base58', { size: 2 });
- * } catch (e) {
- *   if (e instanceof BufferSizeError) {
- *     console.log(e.message); // "Buffer size 13 exceeds specified size 2"
- *   }
- * }
- * ```
+ * Error thrown when the decoded buffer does not have the size requested
+ * through `DecodeOptions.size`.
  */
 export class BufferSizeError extends Error {
     /**
@@ -50,37 +21,99 @@ export class BufferSizeError extends Error {
      * @param expected - The expected (specified) buffer size
      */
     constructor(actual, expected) {
-        super(`Buffer size ${actual} exceeds specified size ${expected}`);
+        super(`Buffer size ${actual} does not match specified size ${expected}`);
         this.name = 'BufferSizeError';
     }
 }
 /**
  * Error thrown when an unknown base name is provided.
- *
- * This error is thrown when using the function API with an invalid base name
- * that is neither a known encoding name nor a valid custom character set
- * (character sets must be longer than 15 characters).
- *
- * @example
- * ```typescript
- * import { encode, UnknownBaseError } from 'bufferbase';
- *
- * try {
- *   encode(Buffer.from('test'), 'invalidbase');
- * } catch (e) {
- *   if (e instanceof UnknownBaseError) {
- *     console.log(e.message); // "Unknown base encoding: 'invalidbase'"
- *   }
- * }
- * ```
  */
 export class UnknownBaseError extends Error {
     /**
      * @param name - The unknown base name that was provided
      */
     constructor(name) {
-        super(`Unknown base encoding: '${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

@@ -1 +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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC;;;OAGG;IACH,YAAY,MAAc,EAAE,QAAgB;QAC1C,KAAK,CAAC,eAAe,MAAM,2BAA2B,QAAQ,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC;;OAEG;IACH,YAAY,IAAY;QACtB,KAAK,CAAC,2BAA2B,IAAI,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}
+{"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,30 +1,53 @@
 import { Buffer } from 'node:buffer';
-import { encode, decode, convert, validate, Codecs } from './index.js';
-// Example buffer
+import { encode, decode, convert, validate, createCodec, Chars, Codecs } from './index.js';
 const bytes = Buffer.from('Hello, World!', 'utf8');
-// Using simple function API
-const base32encoded = encode(bytes, 'base32crockford');
-const base58encoded = convert(base32encoded, 'base32crockford', 'base58');
-const base64encoded = convert(base58encoded, 'base58', 'base64url');
-const isValidAsBase64 = validate(base64encoded, 'base64url');
-const decoded = decode(base64encoded, 'base64url');
-console.log('=== Function API ===');
+// 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,
 });
-// Using Codecs object
-console.log('\n=== Codecs API ===');
-const encoded = Codecs.base58.encode(bytes);
-const converted = Codecs.base58.convertTo(Codecs.base64url, encoded);
 console.table({
-    original: bytes.toString('utf8'),
-    base58: encoded,
-    base64url: converted,
-    valid: Codecs.base64url.validate(converted),
+    'Codecs.base58': Codecs.base58.encode(bytes),
+    'binary of [5]': binary.encode(Uint8Array.of(5)),
+    'adobe ascii85': adobe.encode(bytes),
 });
 //# sourceMappingURL=example.js.map

package/dist/esm/example.js.map

@@ -1 +1 @@
-{"version":3,"file":"example.js","sourceRoot":"","sources":["../../src/example.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEvE,iBAAiB;AACjB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAEnD,4BAA4B;AAC5B,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC;AACvD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,EAAE,iBAAiB,EAAE,QAAQ,CAAC,CAAC;AAC1E,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;AACpE,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;AAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;AAEnD,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AACpC,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;AAEH,sBAAsB;AACtB,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AACpC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5C,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AACrE,OAAO,CAAC,KAAK,CAAC;IACZ,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IAChC,MAAM,EAAE,OAAO;IACf,SAAS,EAAE,SAAS;IACpB,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC;CAC5C,CAAC,CAAC"}
+{"version":3,"file":"example.js","sourceRoot":"","sources":["../../src/example.ts"],"names":[],"mappings":"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"}