bufferbase 1.3.0 → 2.0.0

package/dist/cjs/codec.d.ts

@@ -0,0 +1,124 @@
+import { Buffer } from 'node:buffer';
+import type { ICodec, DecodeOptions, BufferLike } from './types.js';
+/**
+ * Codec for encoding and decoding buffers to/from a specific base.
+ *
+ * Use pre-defined codecs from `Codecs` for common encodings,
+ * or create custom codecs with `createCodec()`.
+ *
+ * @example
+ * ```typescript
+ * import { Codec, Codecs, createCodec } from 'bufferbase';
+ *
+ * // Use pre-defined codec
+ * const encoded = Codecs.base58.encode(Buffer.from('Hello'));
+ *
+ * // Create custom codec
+ * const binary = createCodec('01');
+ * const bits = binary.encode(Buffer.from([5])); // '101'
+ * ```
+ */
+export declare class Codec implements ICodec {
+    /** Character set used for encoding. */
+    readonly chars: string;
+    /** @internal */
+    private readonly charToIndex;
+    /**
+     * Creates a new codec with the specified character set.
+     * @param chars - The character set to use for encoding/decoding
+     */
+    constructor(chars: string);
+    /**
+     * Encodes a buffer to a base-encoded string.
+     *
+     * Leading zero bytes in the buffer are preserved as the first character
+     * of the encoding alphabet (e.g., '1' for Base58).
+     *
+     * @param input - The buffer or Uint8Array to encode
+     * @returns Base-encoded string
+     *
+     * @example
+     * ```typescript
+     * const codec = Codecs.base58;
+     * codec.encode(Buffer.from('Hello')); // '9Ajdvzr'
+     * codec.encode(new Uint8Array([0, 0, 1])); // '112' (preserves leading zeros)
+     * ```
+     */
+    encode(input: BufferLike): string;
+    /**
+     * Decodes a base-encoded string to a buffer.
+     *
+     * Leading characters that represent zero (first char of alphabet)
+     * are converted to leading zero bytes in the result.
+     *
+     * @param encoded - The string to decode
+     * @param options - Decode options
+     * @returns Decoded buffer
+     * @throws {InvalidCharacterError} If the string contains invalid characters
+     * @throws {BufferSizeError} If the result exceeds the specified size
+     *
+     * @example
+     * ```typescript
+     * const codec = Codecs.base58;
+     * codec.decode('9Ajdvzr'); // Buffer('Hello')
+     * codec.decode('9Ajdvzr', { size: 32 }); // Pads to 32 bytes
+     * ```
+     */
+    decode(encoded: string, options?: DecodeOptions): Buffer;
+    /**
+     * Validates if a string contains only valid characters for this base.
+     *
+     * This is a fast check that doesn't perform full decoding.
+     *
+     * @param input - The string to validate
+     * @returns `true` if all characters are valid, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * Codecs.base58.validate('9Ajdvzr'); // true
+     * Codecs.base58.validate('0invalid'); // false ('0' not in Base58)
+     * ```
+     */
+    validate(input: string): boolean;
+    /**
+     * Converts a string from this base to another base.
+     *
+     * Internally decodes to a buffer, then encodes with the target codec.
+     *
+     * @param target - Target codec to convert to
+     * @param input - The string to convert
+     * @returns String in the target base encoding
+     * @throws {InvalidCharacterError} If the input contains invalid characters
+     *
+     * @example
+     * ```typescript
+     * const base58str = '9Ajdvzr';
+     * const base64str = Codecs.base58.convertTo(Codecs.base64url, base58str);
+     * ```
+     */
+    convertTo(target: ICodec, input: string): string;
+}
+/**
+ * Creates a new codec with the specified character set.
+ *
+ * Use this to create codecs for custom base encodings.
+ * The base is determined by the length of the character set.
+ *
+ * @param chars - The character set to use for encoding/decoding
+ * @returns A new Codec instance
+ *
+ * @example
+ * ```typescript
+ * import { createCodec } from 'bufferbase';
+ *
+ * // Binary codec (base 2)
+ * const binary = createCodec('01');
+ * binary.encode(Buffer.from([5])); // '101'
+ *
+ * // Octal codec (base 8)
+ * const octal = createCodec('01234567');
+ * octal.encode(Buffer.from([255])); // '377'
+ * ```
+ */
+export declare function createCodec(chars: string): Codec;
+//# sourceMappingURL=codec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAcpE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,KAAM,YAAW,MAAM;IAClC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAElD;;;OAGG;gBACS,KAAK,EAAE,MAAM;IAQzB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IA6CjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM;IAgExD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAShC;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;CAIjD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAEhD"}

package/dist/cjs/codec.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Codec = void 0;
+exports.createCodec = createCodec;
+const node_buffer_1 = require("node:buffer");
+const errors_js_1 = require("./errors.js");
+/**
+ * Converts a BufferLike (Buffer or Uint8Array) to a Buffer.
+ * @internal
+ */
+function toBuffer(input) {
+    if (node_buffer_1.Buffer.isBuffer(input)) {
+        return input;
+    }
+    return node_buffer_1.Buffer.from(input);
+}
+/**
+ * Codec for encoding and decoding buffers to/from a specific base.
+ *
+ * Use pre-defined codecs from `Codecs` for common encodings,
+ * or create custom codecs with `createCodec()`.
+ *
+ * @example
+ * ```typescript
+ * import { Codec, Codecs, createCodec } from 'bufferbase';
+ *
+ * // Use pre-defined codec
+ * const encoded = Codecs.base58.encode(Buffer.from('Hello'));
+ *
+ * // Create custom codec
+ * const binary = createCodec('01');
+ * const bits = binary.encode(Buffer.from([5])); // '101'
+ * ```
+ */
+class Codec {
+    /**
+     * Creates a new codec with the specified character set.
+     * @param chars - The character set to use for encoding/decoding
+     */
+    constructor(chars) {
+        this.chars = chars;
+        this.charToIndex = new Map();
+        for (let i = 0; i < chars.length; i++) {
+            this.charToIndex.set(chars[i], i);
+        }
+    }
+    /**
+     * Encodes a buffer to a base-encoded string.
+     *
+     * Leading zero bytes in the buffer are preserved as the first character
+     * of the encoding alphabet (e.g., '1' for Base58).
+     *
+     * @param input - The buffer or Uint8Array to encode
+     * @returns Base-encoded string
+     *
+     * @example
+     * ```typescript
+     * const codec = Codecs.base58;
+     * codec.encode(Buffer.from('Hello')); // '9Ajdvzr'
+     * codec.encode(new Uint8Array([0, 0, 1])); // '112' (preserves leading zeros)
+     * ```
+     */
+    encode(input) {
+        const buffer = toBuffer(input);
+        if (buffer.length === 0) {
+            return '';
+        }
+        const base = this.chars.length;
+        const result = [];
+        // Count leading zeros
+        let leadingZeros = 0;
+        for (const byte of buffer) {
+            if (byte === 0) {
+                leadingZeros++;
+            }
+            else {
+                break;
+            }
+        }
+        // Convert to base
+        for (const byte of buffer) {
+            let carry = byte;
+            for (let j = 0; j < result.length; j++) {
+                carry += result[j] * 256;
+                result[j] = carry % base;
+                carry = Math.floor(carry / base);
+            }
+            while (carry > 0) {
+                result.push(carry % base);
+                carry = Math.floor(carry / base);
+            }
+        }
+        // Add leading zeros
+        for (let i = 0; i < leadingZeros; i++) {
+            result.push(0);
+        }
+        // Reverse and convert to string
+        return result
+            .reverse()
+            .map((index) => this.chars[index])
+            .join('');
+    }
+    /**
+     * Decodes a base-encoded string to a buffer.
+     *
+     * Leading characters that represent zero (first char of alphabet)
+     * are converted to leading zero bytes in the result.
+     *
+     * @param encoded - The string to decode
+     * @param options - Decode options
+     * @returns Decoded buffer
+     * @throws {InvalidCharacterError} If the string contains invalid characters
+     * @throws {BufferSizeError} If the result exceeds the specified size
+     *
+     * @example
+     * ```typescript
+     * const codec = Codecs.base58;
+     * codec.decode('9Ajdvzr'); // Buffer('Hello')
+     * codec.decode('9Ajdvzr', { size: 32 }); // Pads to 32 bytes
+     * ```
+     */
+    decode(encoded, options) {
+        if (encoded.length === 0) {
+            if (options?.size !== undefined && options.size > 0) {
+                return node_buffer_1.Buffer.alloc(options.size);
+            }
+            return node_buffer_1.Buffer.alloc(0);
+        }
+        const base = this.chars.length;
+        const zeroChar = this.chars[0];
+        // Count leading zeros in encoded string
+        let leadingZeros = 0;
+        for (const char of encoded) {
+            if (char === zeroChar) {
+                leadingZeros++;
+            }
+            else {
+                break;
+            }
+        }
+        // Convert from base
+        const result = [];
+        for (const char of encoded) {
+            const value = this.charToIndex.get(char);
+            if (value === undefined) {
+                throw new errors_js_1.InvalidCharacterError(char);
+            }
+            let carry = value;
+            for (let i = 0; i < result.length; i++) {
+                carry += result[i] * base;
+                result[i] = carry % 256;
+                carry = Math.floor(carry / 256);
+            }
+            while (carry > 0) {
+                result.push(carry % 256);
+                carry = Math.floor(carry / 256);
+            }
+        }
+        // Add leading zeros
+        for (let i = 0; i < leadingZeros; i++) {
+            result.push(0);
+        }
+        result.reverse();
+        // Handle size option
+        const size = options?.size;
+        if (size !== undefined) {
+            if (result.length > size) {
+                throw new errors_js_1.BufferSizeError(result.length, size);
+            }
+            if (result.length < size) {
+                // Pad with leading zeros
+                const padded = new Array(size - result.length).fill(0).concat(result);
+                return node_buffer_1.Buffer.from(padded);
+            }
+        }
+        return node_buffer_1.Buffer.from(result);
+    }
+    /**
+     * Validates if a string contains only valid characters for this base.
+     *
+     * This is a fast check that doesn't perform full decoding.
+     *
+     * @param input - The string to validate
+     * @returns `true` if all characters are valid, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * Codecs.base58.validate('9Ajdvzr'); // true
+     * Codecs.base58.validate('0invalid'); // false ('0' not in Base58)
+     * ```
+     */
+    validate(input) {
+        for (const char of input) {
+            if (!this.charToIndex.has(char)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Converts a string from this base to another base.
+     *
+     * Internally decodes to a buffer, then encodes with the target codec.
+     *
+     * @param target - Target codec to convert to
+     * @param input - The string to convert
+     * @returns String in the target base encoding
+     * @throws {InvalidCharacterError} If the input contains invalid characters
+     *
+     * @example
+     * ```typescript
+     * const base58str = '9Ajdvzr';
+     * const base64str = Codecs.base58.convertTo(Codecs.base64url, base58str);
+     * ```
+     */
+    convertTo(target, input) {
+        const buffer = this.decode(input);
+        return target.encode(buffer);
+    }
+}
+exports.Codec = Codec;
+/**
+ * Creates a new codec with the specified character set.
+ *
+ * Use this to create codecs for custom base encodings.
+ * The base is determined by the length of the character set.
+ *
+ * @param chars - The character set to use for encoding/decoding
+ * @returns A new Codec instance
+ *
+ * @example
+ * ```typescript
+ * import { createCodec } from 'bufferbase';
+ *
+ * // Binary codec (base 2)
+ * const binary = createCodec('01');
+ * binary.encode(Buffer.from([5])); // '101'
+ *
+ * // Octal codec (base 8)
+ * const octal = createCodec('01234567');
+ * octal.encode(Buffer.from([255])); // '377'
+ * ```
+ */
+function createCodec(chars) {
+    return new Codec(chars);
+}
+//# 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":"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"}

package/dist/cjs/codecs.d.ts

@@ -0,0 +1,71 @@
+import { Codec } 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.
+ *
+ * @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
+ * ```
+ *
+ * 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;
+};
+/**
+ * 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;
+//# 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,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"}

package/dist/cjs/codecs.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Codecs = void 0;
+const codec_js_1 = require("./codec.js");
+const bases_js_1 = require("./bases.js");
+/** Decimal (base 10) codec: 0-9 */
+const decimal = new codec_js_1.Codec(bases_js_1.Chars.Decimal);
+/** Hexadecimal (base 16) codec: 0-9A-F */
+const base16 = new codec_js_1.Codec(bases_js_1.Chars.Base16);
+/** Alias for base16 */
+const hex = base16;
+/** RFC 4648 Base32 codec: A-Z2-7 */
+const base32 = new codec_js_1.Codec(bases_js_1.Chars.Base32);
+/** Crockford's Base32 codec: 0-9A-HJKMNP-TV-Z (no I, L, O, U) */
+const base32crockford = new codec_js_1.Codec(bases_js_1.Chars.Base32Crockford);
+/** Base36 codec: 0-9A-Z */
+const base36 = new codec_js_1.Codec(bases_js_1.Chars.Base36);
+/** Base52 codec: A-Za-z (letters only) */
+const base52 = new codec_js_1.Codec(bases_js_1.Chars.Base52);
+/** Bitcoin Base58 codec: 1-9A-HJ-NP-Za-km-z (no 0, O, I, l) */
+const base58 = new codec_js_1.Codec(bases_js_1.Chars.Base58);
+/** Standard Base64 codec: A-Za-z0-9+/ */
+const base64 = new codec_js_1.Codec(bases_js_1.Chars.Base64);
+/** URL-safe Base64 codec: A-Za-z0-9-_ */
+const base64url = new codec_js_1.Codec(bases_js_1.Chars.Base64Url);
+/** XML token Base64 codec: A-Za-z0-9._ */
+const base64xml = new codec_js_1.Codec(bases_js_1.Chars.Base64Xml);
+/** XML name Base64 codec: A-Za-z0-9_: */
+const base64xmlname = new codec_js_1.Codec(bases_js_1.Chars.Base64XmlName);
+/** ASCII85 codec */
+const ascii85 = new codec_js_1.Codec(bases_js_1.Chars.Ascii85);
+/** Base85 codec */
+const base85 = new codec_js_1.Codec(bases_js_1.Chars.Base85);
+/** ZeroMQ Z85 codec */
+const z85 = new codec_js_1.Codec(bases_js_1.Chars.Z85);
+/**
+ * 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.
+ *
+ * @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
+ * ```
+ *
+ * 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
+ */
+exports.Codecs = {
+    decimal,
+    base16,
+    hex,
+    base32,
+    base32crockford,
+    base36,
+    base52,
+    base58,
+    base64,
+    base64url,
+    base64xml,
+    base64xmlname,
+    ascii85,
+    base85,
+    z85,
+};
+//# 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":";;;AAAA,yCAAmC;AACnC,yCAAmC;AAEnC,mCAAmC;AACnC,MAAM,OAAO,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,OAAO,CAAC,CAAC;AAEzC,0CAA0C;AAC1C,MAAM,MAAM,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,uBAAuB;AACvB,MAAM,GAAG,GAAG,MAAM,CAAC;AAEnB,oCAAoC;AACpC,MAAM,MAAM,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,iEAAiE;AACjE,MAAM,eAAe,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,eAAe,CAAC,CAAC;AAEzD,2BAA2B;AAC3B,MAAM,MAAM,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,0CAA0C;AAC1C,MAAM,MAAM,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,+DAA+D;AAC/D,MAAM,MAAM,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,yCAAyC;AACzC,MAAM,MAAM,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,yCAAyC;AACzC,MAAM,SAAS,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,SAAS,CAAC,CAAC;AAE7C,0CAA0C;AAC1C,MAAM,SAAS,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,SAAS,CAAC,CAAC;AAE7C,yCAAyC;AACzC,MAAM,aAAa,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,aAAa,CAAC,CAAC;AAErD,oBAAoB;AACpB,MAAM,OAAO,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,OAAO,CAAC,CAAC;AAEzC,mBAAmB;AACnB,MAAM,MAAM,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,MAAM,CAAC,CAAC;AAEvC,uBAAuB;AACvB,MAAM,GAAG,GAAG,IAAI,gBAAK,CAAC,gBAAK,CAAC,GAAG,CAAC,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACU,QAAA,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"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 {
+    /**
+     * @param char - The invalid character that was encountered (optional)
+     */
+    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"
+ *   }
+ * }
+ * ```
+ */
+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.
+ *
+ * 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 {
+    /**
+     * @param name - The unknown base name that was provided
+     */
+    constructor(name: 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;;;;;;;;;;;;;;;;;;;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"}