bufferbase 1.3.0 → 2.0.0

package/dist/esm/codec.js

@@ -0,0 +1,242 @@
+import { Buffer } from 'node:buffer';
+import { InvalidCharacterError, BufferSizeError } from './errors.js';
+/**
+ * Converts a BufferLike (Buffer or Uint8Array) to a Buffer.
+ * @internal
+ */
+function toBuffer(input) {
+    if (Buffer.isBuffer(input)) {
+        return input;
+    }
+    return 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'
+ * ```
+ */
+export 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 Buffer.alloc(options.size);
+            }
+            return 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 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 BufferSizeError(result.length, size);
+            }
+            if (result.length < size) {
+                // Pad with leading zeros
+                const padded = new Array(size - result.length).fill(0).concat(result);
+                return Buffer.from(padded);
+            }
+        }
+        return 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);
+    }
+}
+/**
+ * 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 function createCodec(chars) {
+    return new Codec(chars);
+}
+//# 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":"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"}

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

@@ -0,0 +1,89 @@
+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);
+/**
+ * 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 const Codecs = {
+    decimal,
+    base16,
+    hex,
+    base32,
+    base32crockford,
+    base36,
+    base52,
+    base58,
+    base64,
+    base64url,
+    base64xml,
+    base64xmlname,
+    ascii85,
+    base85,
+    z85,
+};
+//# 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":"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"}

package/dist/esm/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/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;;;;;;;;;;;;;;;;;;;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"}

package/dist/esm/errors.js

@@ -0,0 +1,86 @@
+/**
+ * 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 {
+    /**
+     * @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 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 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} exceeds 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}'`);
+        this.name = 'UnknownBaseError';
+    }
+}
+//# 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;;;;;;;;;;;;;;;;;;;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"}

package/dist/esm/example.js

@@ -1,21 +1,14 @@
-import { Chars, BufferEncoder, Converter, Validator } from './bufferbase.js';
+import { Buffer } from 'node:buffer';
+import { encode, decode, convert, validate, Codecs } from './index.js';
 // Example buffer
 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);
+// 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 ===');
 console.table({
     bytes: bytes.toString('utf8'),
     base32encoded,
@@ -24,14 +17,14 @@ console.table({
     isValidAsBase64,
     decoded: decoded.toString('utf8'),
 });
-// ┌─────────────────┬─────────────────────────┐
-// │ (index)         │ Values                  │
-// ├─────────────────┼─────────────────────────┤
-// │ bytes           │ 'Hello, World!'         │
-// │ base32encoded   │ '4GSBCDHQJR82QDXS6RS11' │
-// │ base58encoded   │ '72k1xXWG59fYdzSNoA'    │
-// │ base64encoded   │ 'BIZWxsbywgV29ybGQh'    │
-// │ isValidAsBase64 │ true                    │
-// │ decoded         │ 'Hello, World!'         │
-// └─────────────────┴─────────────────────────┘
+// 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),
+});
 //# 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,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE7E,iBAAiB;AACjB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAEnD,4BAA4B;AAC5B,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;AACzD,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAE5C,8BAA8B;AAC9B,MAAM,gBAAgB,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;AAC5E,MAAM,aAAa,GAAG,gBAAgB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;AAE9D,8BAA8B;AAC9B,MAAM,gBAAgB,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;AAC5E,MAAM,aAAa,GAAG,gBAAgB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;AAE9D,oBAAoB;AACpB,MAAM,YAAY,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;AAC1D,MAAM,eAAe,GAAG,YAAY,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AAE7D,kBAAkB;AAClB,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;AACzD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;AAE9C,OAAO,CAAC,KAAK,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC7B,aAAa;IACb,aAAa;IACb,aAAa;IACb,eAAe;IACf,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;CAClC,CAAC,CAAC;AACH,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD;AAChD,gDAAgD"}
+{"version":3,"file":"example.js","sourceRoot":"","sources":["../../src/example.ts"],"names":[],"mappings":"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"}