bufferbase 1.2.3 → 2.0.0

package/README.md

@@ -1,33 +1,114 @@
 # bufferbase
 
-Buffer-to-BaseN Encoding and Decoding for Node.js.
-
-bufferbase is a Node.js library that provides straightforward encoding and decoding of buffer objects into various BaseN formats. It's designed to be simple, efficient, and flexible for different application needs.
-
-## Features
-
-- Supports multiple base encoding formats.
-- Optimized for Node.js buffer handling.
-- Intuitive API for easy integration.
-- Suitable for various data types.
-- Consistent and reliable performance.
+Buffer-to-BaseN encoding and decoding for Node.js.
 
 ## Installation
 
-Install bufferbase using npm:
-
 ```bash
 npm install bufferbase
 ```
 
 ## Usage
 
-See [src/example.ts](/src/example.ts)
+### Simple Function API
+
+```typescript
+import { encode, decode, convert, validate } from 'bufferbase';
+
+// Encode buffer to base58
+const encoded = encode(Buffer.from('Hello'), 'base58');
+
+// Decode base58 string to buffer
+const decoded = decode(encoded, 'base58');
+
+// Decode with fixed size (pads with leading zeros)
+const fixed = decode(encoded, 'base58', { size: 32 });
+
+// Convert between bases
+const base64 = convert(encoded, 'base58', 'base64url');
+
+// Validate string
+validate('9Ajdvz', 'base58'); // true
+validate('0Ajdvz', 'base58'); // false ('0' not in base58)
+```
+
+### Pre-defined Codecs
+
+```typescript
+import { Codecs } from 'bufferbase';
+
+const encoded = Codecs.base58.encode(Buffer.from('Hello'));
+const decoded = Codecs.base58.decode(encoded);
+
+// Convert between codecs
+const base64 = Codecs.base58.convertTo(Codecs.base64url, encoded);
+
+// Validate
+Codecs.base58.validate('9Ajdvz'); // true
+```
+
+### Custom Character Set
+
+```typescript
+import { createCodec } from 'bufferbase';
+
+const binary = createCodec('01');
+binary.encode(Buffer.from([5])); // '101'
+binary.decode('101'); // Buffer([5])
+```
+
+## Supported Encodings
+
+| Name | Characters |
+|------|------------|
+| `decimal` | 0-9 |
+| `base16` / `hex` | 0-9A-F |
+| `base32` | A-Z2-7 |
+| `base32crockford` | 0-9A-HJKMNP-TV-Z |
+| `base36` | 0-9A-Z |
+| `base52` | A-Za-z |
+| `base58` | Bitcoin alphabet (no 0OIl) |
+| `base64` | A-Za-z0-9+/ |
+| `base64url` | A-Za-z0-9-_ |
+| `base64xml` | A-Za-z0-9._ |
+| `base64xmlname` | A-Za-z0-9_: |
+| `ascii85` | ASCII85 |
+| `base85` | Base85 |
+| `z85` | ZeroMQ Z85 |
+
+## API
+
+### Functions
+
+- `encode(buffer, base)` - Encode buffer to string
+- `decode(encoded, base, options?)` - Decode string to buffer
+- `convert(input, from, to)` - Convert between bases
+- `validate(input, base)` - Check if string is valid for base
+- `createCodec(chars)` - Create codec with custom character set
+
+### Codecs Object
+
+```typescript
+Codecs.base58.encode(buffer)
+Codecs.base58.decode(encoded, options?)
+Codecs.base58.validate(input)
+Codecs.base58.convertTo(targetCodec, input)
+```
+
+### Options
+
+```typescript
+interface DecodeOptions {
+  size?: number; // Expected buffer size (pads with zeros if smaller)
+}
+```
 
+### Errors
 
-## Contributing
+- `InvalidCharacterError` - Invalid character in decode input
+- `BufferSizeError` - Decoded buffer exceeds specified size
+- `UnknownBaseError` - Unknown base name
 
-Contributions to bufferbase are welcome! Please read our contributing guidelines for more information.
-License
+## License
 
-bufferbase is ISC licensed.
+ISC

package/dist/cjs/bases.d.ts

@@ -0,0 +1,82 @@
+import type { BaseName } from './types.js';
+/**
+ * Character sets for common base encodings.
+ *
+ * Use these with `createCodec()` or the deprecated `BufferEncoder` class
+ * when you need direct access to character sets.
+ *
+ * @example
+ * ```typescript
+ * import { Chars, createCodec } from 'bufferbase';
+ *
+ * const codec = createCodec(Chars.Base58);
+ * const encoded = codec.encode(Buffer.from('Hello'));
+ * ```
+ */
+export declare const Chars: {
+    /** Base 10: 0-9 */
+    readonly Decimal: "0123456789";
+    /** Hexadecimal: 0-9A-F */
+    readonly Base16: "0123456789ABCDEF";
+    /** RFC 4648 Base32: A-Z2-7 */
+    readonly Base32: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+    /** Crockford's Base32: 0-9A-HJKMNP-TV-Z (no I, L, O, U) */
+    readonly Base32Crockford: "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    /** Alphanumeric: 0-9A-Z */
+    readonly Base36: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+    /** Letters only: A-Za-z */
+    readonly Base52: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+    /** Bitcoin alphabet: 1-9A-HJ-NP-Za-km-z (no 0, O, I, l) */
+    readonly Base58: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    /** Standard Base64: A-Za-z0-9+/ */
+    readonly Base64: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    /** URL-safe Base64: A-Za-z0-9-_ */
+    readonly Base64Url: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+    /** XML token Base64: A-Za-z0-9._ */
+    readonly Base64Xml: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._";
+    /** XML name Base64: A-Za-z0-9_: */
+    readonly Base64XmlName: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_:";
+    /** ASCII85 encoding */
+    readonly Ascii85: "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstu";
+    /** Base85 encoding */
+    readonly Base85: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!#$%&()*+-;<=>?@^_`{|}~";
+    /** ZeroMQ Z85 encoding */
+    readonly Z85: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#";
+};
+/**
+ * Resolves a base name or character set string to a character set.
+ *
+ * This function is used internally by the function API to convert
+ * base names (like `'base58'`) to their character sets.
+ *
+ * @param base - Base name (e.g., `'base58'`) or custom character set string
+ * @returns The character set string
+ * @throws {UnknownBaseError} If base name is not recognized and string length <= 15
+ *
+ * @example
+ * ```typescript
+ * import { resolveChars } from 'bufferbase';
+ *
+ * resolveChars('base58'); // Returns Bitcoin alphabet
+ * resolveChars('0123456789ABCDEF'); // Returns the string as-is (custom charset)
+ * resolveChars('invalid'); // Throws UnknownBaseError
+ * ```
+ */
+export declare function resolveChars(base: BaseName | string): string;
+/**
+ * Checks if a string is a valid base name.
+ *
+ * @param value - The string to check
+ * @returns `true` if the value is a valid `BaseName`, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isBaseName } from 'bufferbase';
+ *
+ * isBaseName('base58'); // true
+ * isBaseName('BASE58'); // true (case-insensitive)
+ * isBaseName('unknown'); // false
+ * ```
+ */
+export declare function isBaseName(value: string): value is BaseName;
+//# sourceMappingURL=bases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bases.d.ts","sourceRoot":"","sources":["../../src/bases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK;IAChB,mBAAmB;;IAEnB,0BAA0B;;IAE1B,8BAA8B;;IAE9B,2DAA2D;;IAE3D,2BAA2B;;IAE3B,2BAA2B;;IAE3B,2DAA2D;;IAE3D,mCAAmC;;IAEnC,mCAAmC;;IAEnC,oCAAoC;;IAEpC,mCAAmC;;IAEnC,uBAAuB;;IAEvB,sBAAsB;;IAEtB,0BAA0B;;CAElB,CAAC;AAwBX;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAW5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D"}

package/dist/cjs/bases.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Chars = void 0;
+exports.resolveChars = resolveChars;
+exports.isBaseName = isBaseName;
+const errors_js_1 = require("./errors.js");
+/**
+ * Character sets for common base encodings.
+ *
+ * Use these with `createCodec()` or the deprecated `BufferEncoder` class
+ * when you need direct access to character sets.
+ *
+ * @example
+ * ```typescript
+ * import { Chars, createCodec } from 'bufferbase';
+ *
+ * const codec = createCodec(Chars.Base58);
+ * const encoded = codec.encode(Buffer.from('Hello'));
+ * ```
+ */
+exports.Chars = {
+    /** Base 10: 0-9 */
+    Decimal: '0123456789',
+    /** Hexadecimal: 0-9A-F */
+    Base16: '0123456789ABCDEF',
+    /** RFC 4648 Base32: A-Z2-7 */
+    Base32: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567',
+    /** Crockford's Base32: 0-9A-HJKMNP-TV-Z (no I, L, O, U) */
+    Base32Crockford: '0123456789ABCDEFGHJKMNPQRSTVWXYZ',
+    /** Alphanumeric: 0-9A-Z */
+    Base36: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ',
+    /** Letters only: A-Za-z */
+    Base52: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+    /** Bitcoin alphabet: 1-9A-HJ-NP-Za-km-z (no 0, O, I, l) */
+    Base58: '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz',
+    /** Standard Base64: A-Za-z0-9+/ */
+    Base64: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/',
+    /** URL-safe Base64: A-Za-z0-9-_ */
+    Base64Url: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_',
+    /** XML token Base64: A-Za-z0-9._ */
+    Base64Xml: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._',
+    /** XML name Base64: A-Za-z0-9_: */
+    Base64XmlName: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_:',
+    /** ASCII85 encoding */
+    Ascii85: '!"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstu',
+    /** Base85 encoding */
+    Base85: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!#$%&()*+-;<=>?@^_`{|}~',
+    /** ZeroMQ Z85 encoding */
+    Z85: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#',
+};
+/**
+ * Internal mapping from base names to character sets.
+ * @internal
+ */
+const baseNameToChars = {
+    decimal: exports.Chars.Decimal,
+    base16: exports.Chars.Base16,
+    hex: exports.Chars.Base16,
+    base32: exports.Chars.Base32,
+    base32crockford: exports.Chars.Base32Crockford,
+    base36: exports.Chars.Base36,
+    base52: exports.Chars.Base52,
+    base58: exports.Chars.Base58,
+    base64: exports.Chars.Base64,
+    base64url: exports.Chars.Base64Url,
+    base64xml: exports.Chars.Base64Xml,
+    base64xmlname: exports.Chars.Base64XmlName,
+    ascii85: exports.Chars.Ascii85,
+    base85: exports.Chars.Base85,
+    z85: exports.Chars.Z85,
+};
+/**
+ * Resolves a base name or character set string to a character set.
+ *
+ * This function is used internally by the function API to convert
+ * base names (like `'base58'`) to their character sets.
+ *
+ * @param base - Base name (e.g., `'base58'`) or custom character set string
+ * @returns The character set string
+ * @throws {UnknownBaseError} If base name is not recognized and string length <= 15
+ *
+ * @example
+ * ```typescript
+ * import { resolveChars } from 'bufferbase';
+ *
+ * resolveChars('base58'); // Returns Bitcoin alphabet
+ * resolveChars('0123456789ABCDEF'); // Returns the string as-is (custom charset)
+ * resolveChars('invalid'); // Throws UnknownBaseError
+ * ```
+ */
+function resolveChars(base) {
+    const normalized = base.toLowerCase();
+    if (normalized in baseNameToChars) {
+        return baseNameToChars[normalized];
+    }
+    // If not a known base name, treat as custom character set
+    // (must be longer than 15 chars to distinguish from typos)
+    if (base.length > 15) {
+        return base;
+    }
+    throw new errors_js_1.UnknownBaseError(base);
+}
+/**
+ * Checks if a string is a valid base name.
+ *
+ * @param value - The string to check
+ * @returns `true` if the value is a valid `BaseName`, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isBaseName } from 'bufferbase';
+ *
+ * isBaseName('base58'); // true
+ * isBaseName('BASE58'); // true (case-insensitive)
+ * isBaseName('unknown'); // false
+ * ```
+ */
+function isBaseName(value) {
+    return value.toLowerCase() in baseNameToChars;
+}
+//# sourceMappingURL=bases.js.map

package/dist/cjs/bases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bases.js","sourceRoot":"","sources":["../../src/bases.ts"],"names":[],"mappings":";;;AAyFA,oCAWC;AAiBD,gCAEC;AAtHD,2CAA+C;AAE/C;;;;;;;;;;;;;GAaG;AACU,QAAA,KAAK,GAAG;IACnB,mBAAmB;IACnB,OAAO,EAAE,YAAY;IACrB,0BAA0B;IAC1B,MAAM,EAAE,kBAAkB;IAC1B,8BAA8B;IAC9B,MAAM,EAAE,kCAAkC;IAC1C,2DAA2D;IAC3D,eAAe,EAAE,kCAAkC;IACnD,2BAA2B;IAC3B,MAAM,EAAE,sCAAsC;IAC9C,2BAA2B;IAC3B,MAAM,EAAE,sDAAsD;IAC9D,2DAA2D;IAC3D,MAAM,EAAE,4DAA4D;IACpE,mCAAmC;IACnC,MAAM,EAAE,kEAAkE;IAC1E,mCAAmC;IACnC,SAAS,EAAE,kEAAkE;IAC7E,oCAAoC;IACpC,SAAS,EAAE,kEAAkE;IAC7E,mCAAmC;IACnC,aAAa,EAAE,kEAAkE;IACjF,uBAAuB;IACvB,OAAO,EAAE,uFAAuF;IAChG,sBAAsB;IACtB,MAAM,EAAE,uFAAuF;IAC/F,0BAA0B;IAC1B,GAAG,EAAE,uFAAuF;CACpF,CAAC;AAEX;;;GAGG;AACH,MAAM,eAAe,GAA6B;IAChD,OAAO,EAAE,aAAK,CAAC,OAAO;IACtB,MAAM,EAAE,aAAK,CAAC,MAAM;IACpB,GAAG,EAAE,aAAK,CAAC,MAAM;IACjB,MAAM,EAAE,aAAK,CAAC,MAAM;IACpB,eAAe,EAAE,aAAK,CAAC,eAAe;IACtC,MAAM,EAAE,aAAK,CAAC,MAAM;IACpB,MAAM,EAAE,aAAK,CAAC,MAAM;IACpB,MAAM,EAAE,aAAK,CAAC,MAAM;IACpB,MAAM,EAAE,aAAK,CAAC,MAAM;IACpB,SAAS,EAAE,aAAK,CAAC,SAAS;IAC1B,SAAS,EAAE,aAAK,CAAC,SAAS;IAC1B,aAAa,EAAE,aAAK,CAAC,aAAa;IAClC,OAAO,EAAE,aAAK,CAAC,OAAO;IACtB,MAAM,EAAE,aAAK,CAAC,MAAM;IACpB,GAAG,EAAE,aAAK,CAAC,GAAG;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,YAAY,CAAC,IAAuB;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAc,CAAC;IAClD,IAAI,UAAU,IAAI,eAAe,EAAE,CAAC;QAClC,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,0DAA0D;IAC1D,2DAA2D;IAC3D,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,4BAAgB,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,WAAW,EAAE,IAAI,eAAe,CAAC;AAChD,CAAC"}

package/dist/cjs/bufferbase.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @deprecated Use the new API instead:
+ * - `encode(buffer, 'base58')` or `base58.encode(buffer)`
+ * - `decode(encoded, 'base58')` or `base58.decode(encoded)`
+ * - `convert(input, 'base58', 'base64')` or `base58.convertTo(base64, input)`
+ * - `validate(input, 'base58')` or `base58.validate(input)`
+ */
+import { Buffer } from 'node:buffer';
+import { InvalidCharacterError, BufferSizeError } from './errors.js';
+export { Chars } from './bases.js';
+export { InvalidCharacterError, BufferSizeError };
+/**
+ * @deprecated Use `Codec` or `createCodec()` instead.
+ */
+export declare class BufferEncoder {
+    private baseChars;
+    private codec;
+    constructor(baseChars: string);
+    encode(buffer: Buffer): string;
+    decode(encoded: string, bufferSize?: number): Buffer;
+}
+/**
+ * @deprecated Use `convert()` function or `codec.convertTo()` instead.
+ */
+export declare class Converter {
+    decoder: BufferEncoder;
+    encoder: BufferEncoder;
+    constructor(inputBase: string, outputBase: string);
+    convert(input: string): string;
+}
+/**
+ * @deprecated Use `validate()` function or `codec.validate()` instead.
+ */
+export declare class Validator {
+    private codec;
+    constructor(inputBase: string);
+    validate(input: string): boolean;
+}
+/**
+ * @deprecated Use `validate()` from the main module instead.
+ */
+export declare const validate: (input: string, base: string) => boolean;
+//# sourceMappingURL=bufferbase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bufferbase.d.ts","sourceRoot":"","sources":["../../src/bufferbase.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGrE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,CAAC;AAElD;;GAEG;AACH,qBAAa,aAAa;IAGZ,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,KAAK,CAAQ;gBAED,SAAS,EAAE,MAAM;IAIrC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAI9B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAGrD;AAED;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;gBAEX,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAKjD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAG/B;AAED;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAQ;gBAET,SAAS,EAAE,MAAM;IAI7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGjC;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,OAEtD,CAAC"}

package/dist/cjs/bufferbase.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * @deprecated Use the new API instead:
+ * - `encode(buffer, 'base58')` or `base58.encode(buffer)`
+ * - `decode(encoded, 'base58')` or `base58.decode(encoded)`
+ * - `convert(input, 'base58', 'base64')` or `base58.convertTo(base64, input)`
+ * - `validate(input, 'base58')` or `base58.validate(input)`
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validate = exports.Validator = exports.Converter = exports.BufferEncoder = exports.BufferSizeError = exports.InvalidCharacterError = exports.Chars = void 0;
+const codec_js_1 = require("./codec.js");
+const errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "InvalidCharacterError", { enumerable: true, get: function () { return errors_js_1.InvalidCharacterError; } });
+Object.defineProperty(exports, "BufferSizeError", { enumerable: true, get: function () { return errors_js_1.BufferSizeError; } });
+// Re-export Chars for backward compatibility
+var bases_js_1 = require("./bases.js");
+Object.defineProperty(exports, "Chars", { enumerable: true, get: function () { return bases_js_1.Chars; } });
+/**
+ * @deprecated Use `Codec` or `createCodec()` instead.
+ */
+class BufferEncoder {
+    constructor(baseChars) {
+        this.baseChars = baseChars;
+        this.codec = new codec_js_1.Codec(baseChars);
+    }
+    encode(buffer) {
+        return this.codec.encode(buffer);
+    }
+    decode(encoded, bufferSize) {
+        return this.codec.decode(encoded, bufferSize !== undefined ? { size: bufferSize } : undefined);
+    }
+}
+exports.BufferEncoder = BufferEncoder;
+/**
+ * @deprecated Use `convert()` function or `codec.convertTo()` instead.
+ */
+class Converter {
+    constructor(inputBase, outputBase) {
+        this.decoder = new BufferEncoder(inputBase);
+        this.encoder = new BufferEncoder(outputBase);
+    }
+    convert(input) {
+        return this.encoder.encode(this.decoder.decode(input));
+    }
+}
+exports.Converter = Converter;
+/**
+ * @deprecated Use `validate()` function or `codec.validate()` instead.
+ */
+class Validator {
+    constructor(inputBase) {
+        this.codec = new codec_js_1.Codec(inputBase);
+    }
+    validate(input) {
+        return this.codec.validate(input);
+    }
+}
+exports.Validator = Validator;
+/**
+ * @deprecated Use `validate()` from the main module instead.
+ */
+const validate = (input, base) => {
+    return new Validator(base).validate(input);
+};
+exports.validate = validate;
+//# sourceMappingURL=bufferbase.js.map

package/dist/cjs/bufferbase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferbase.js","sourceRoot":"","sources":["../../src/bufferbase.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAGH,yCAAmC;AACnC,2CAAqE;AAM5D,sGANA,iCAAqB,OAMA;AAAE,gGANA,2BAAe,OAMA;AAJ/C,6CAA6C;AAC7C,uCAAmC;AAA1B,iGAAA,KAAK,OAAA;AAKd;;GAEG;AACH,MAAa,aAAa;IAGxB,YAAoB,SAAiB;QAAjB,cAAS,GAAT,SAAS,CAAQ;QACnC,IAAI,CAAC,KAAK,GAAG,IAAI,gBAAK,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,CAAC,MAAc;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,OAAe,EAAE,UAAmB;QACzC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACjG,CAAC;CACF;AAdD,sCAcC;AAED;;GAEG;AACH,MAAa,SAAS;IAIpB,YAAY,SAAiB,EAAE,UAAkB;QAC/C,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,CAAC,KAAa;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC;CACF;AAZD,8BAYC;AAED;;GAEG;AACH,MAAa,SAAS;IAGpB,YAAY,SAAiB;QAC3B,IAAI,CAAC,KAAK,GAAG,IAAI,gBAAK,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,QAAQ,CAAC,KAAa;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;CACF;AAVD,8BAUC;AAED;;GAEG;AACI,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,IAAY,EAAW,EAAE;IAC/D,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC,CAAC;AAFW,QAAA,QAAQ,YAEnB"}

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"}