@i-xi-dev/base64
Version:
A JavaScript Base64 encoder and decoder, implements Forgiving base64 defined in WHATWG Infra Standard.
268 lines (267 loc) • 11.2 kB
TypeScript
import { BytesEncoding } from "../deps.js";
/**
* Provides Base64 decoding and Base64 encoding methods.
*/
declare namespace Base64 {
/**
* Decodes a Base64-encoded string into an `Uint8Array`.
*
* @param encoded The string to decode.
* @param options The `Base64.Options` dictionary.
* @returns An `Uint8Array` containing the decoded byte sequence.
* @throws {RangeError} The `options.rawTable` contains duplicate characters, or the `options.paddingChar` character is contained in the `options.rawTable`.
* @throws {TypeError} The `encoded` is not Base64-encoded string.
* @example
* ```javascript
* Base64.decode("AwIBAP/+/fw=");
* // → Uint8Array[ 0x03, 0x02, 0x01, 0x00, 0xFF, 0xFE, 0xFD, 0xFC ]
* ```
* @example
* ```javascript
* const rfc4648urlOptions = Base64.Options.RFC4648URL;
* Base64.decode("AwIBAP_-_fw", rfc4648urlOptions);
* // → Uint8Array[ 0x03, 0x02, 0x01, 0x00, 0xFF, 0xFE, 0xFD, 0xFC ]
* ```
*/
function decode(encoded: string, options?: Options): Uint8Array;
/**
* Encodes the specified byte sequence into a string.
*
* @param toEncode The byte sequence to encode.
* @param options The `Base64.Options` dictionary.
* @returns A string containing the Base64-encoded characters.
* @throws {RangeError} The `options.rawTable` contains duplicate characters, or the `options.paddingChar` character is contained in the `options.rawTable`.
* @example
* ```javascript
* Base64.encode(Uint8Array.of(0x03, 0x02, 0x01, 0x00, 0xFF, 0xFE, 0xFD, 0xFC));
* // → "AwIBAP/+/fw="
* ```
* @example
* ```javascript
* const rfc4648urlOptions = Base64.Options.RFC4648URL;
* Base64.encode(Uint8Array.of(0x03, 0x02, 0x01, 0x00, 0xFF, 0xFE, 0xFD, 0xFC), rfc4648urlOptions);
* // → "AwIBAP_-_fw"
* ```
*/
function encode(toEncode: Uint8Array, options?: Options): string;
/**
* The object with the following optional fields.
* The defaults are the values that conforms to the RFC 4648 Base64 specification.
*
* ***
*
* **`rawTable`**:
*
* The 64 characters index table.
* The default is `[ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "/" ]`.
*
* The following restrictions apply:
* - The `length` of the `rawTable` must be 64.
* - The `length` of all elements contained in the `rawTable` must be 1.
* - The `rawTable` must not contain duplicate characters.
*
* ***
*
* **`table`**:
*
* [deprecated] Alias for the `rawTable`.
*
* ***
*
* **`tableLastChars`**:
*
* The last two characters of the 64 characters index table.
* The default is `[ "+", "/" ]`.
*
* `tableLastChars` and `rawTable` are mutually exclusive, with `tableLastChars` taking precedence over `rawTable`.
* If `tableLastChars` is specified, the first to 62nd characters of the 64 characters index table are `[ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" ]`.
*
* ***
*
* **`noPadding`**:
*
* Whether to omit the padding.
* The default is `false`.
* However, the decoder ignores this value.
*
* ***
*
* **`paddingChar`**:
*
* The padding character.
* The default is `"="`.
*
* The following restrictions apply:
* - The `length` of the `paddingChar` must be 1.
* - The `paddingChar` must not be a character contained in the `rawTable`.
*/
type Options = {
/**
* The 64 characters index table.
* The default is `[ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "/" ]`.
*
* The following restrictions apply:
* - The `length` of the `rawTable` must be 64.
* - The `length` of all elements contained in the `rawTable` must be 1.
* - The `rawTable` must not contain duplicate characters.
*/
rawTable?: Readonly<Array<string>>;
/**
* @deprecated
*
* Alias for the `rawTable`.
*/
table?: Readonly<Array<string>>;
/**
* The last two characters of the 64 characters index table.
* The default is `[ "+", "/" ]`.
*
* `tableLastChars` and `rawTable` are mutually exclusive, with `tableLastChars` taking precedence over `rawTable`.
* If `tableLastChars` is specified, the first to 62nd characters of the 64 characters index table are `[ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" ]`.
*/
tableLastChars?: Readonly<[string, string]>;
/**
* Whether to omit the padding.
* The default is `false`.
* However, the decoder ignores this value.
*/
noPadding?: boolean;
/**
* The padding character.
* The default is `"="`.
*
* The following restrictions apply:
* - The `length` of the `paddingChar` must be 1.
* - The `paddingChar` must not be a character contained in the `rawTable`.
*/
paddingChar?: string;
};
namespace Options {
/**
* The options for [RFC 4648 Base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4).
*
* | field | value |
* | :--- | :--- |
* | `rawTable` | `[ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "/" ]` |
* | `noPadding` | `false` |
* | `paddingChar` | `"="` |
*/
const RFC4648: Options;
/**
* The options for [RFC 4648 Base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5).
*
* | field | value |
* | :--- | :--- |
* | `rawTable` | `[ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "-", "_" ]` |
* | `noPadding` | `true` |
* | `paddingChar` | `"="` |
*/
const RFC4648URL: Options;
}
/**
* Base64 decoder
*
* @example
* ```javascript
* const decoder = new Base64.Decoder();
*
* decoder.decode("AwIBAP/+/fw=");
* // → Uint8Array[ 0x03, 0x02, 0x01, 0x00, 0xFF, 0xFE, 0xFD, 0xFC ]
* ```
* @example
* ```javascript
* const rfc4648urlOptions = Base64.Options.RFC4648URL;
* const decoder = new Base64.Decoder(rfc4648urlOptions);
*
* decoder.decode("AwIBAP_-_fw");
* // → Uint8Array[ 0x03, 0x02, 0x01, 0x00, 0xFF, 0xFE, 0xFD, 0xFC ]
* ```
*/
class Decoder implements BytesEncoding.Decoder {
#private;
/**
* @param options The `Base64.Options` dictionary.
* @throws {RangeError} The `options.rawTable` contains duplicate characters, or the `options.padding` character is contained in the `options.rawTable`.
*/
constructor(options?: Options);
/**
* Decodes a Base64-encoded string into an `Uint8Array`.
*
* @param encoded The string to decode.
* @returns An `Uint8Array` containing the decoded byte sequence.
* @throws {TypeError} The `encoded` is not Base64-encoded string.
*/
decode(encoded: string): Uint8Array;
}
/**
* Base64 encoder
*
* @example
* ```javascript
* const encoder = new Base64.Encoder();
*
* encoder.encode(Uint8Array.of(0x03, 0x02, 0x01, 0x00, 0xFF, 0xFE, 0xFD, 0xFC));
* // → "AwIBAP/+/fw="
* ```
* @example
* ```javascript
* const rfc4648urlOptions = Base64.Options.RFC4648URL;
* const encoder = new Base64.Encoder(rfc4648urlOptions);
*
* encoder.encode(Uint8Array.of(0x03, 0x02, 0x01, 0x00, 0xFF, 0xFE, 0xFD, 0xFC));
* // → "AwIBAP_-_fw"
* ```
*/
class Encoder implements BytesEncoding.Encoder {
#private;
/**
* @param options The `Base64.Options` dictionary.
* @throws {RangeError} The `options.rawTable` contains duplicate characters, or the `options.padding` character is contained in the `options.rawTable`.
*/
constructor(options?: Options);
/**
* Encodes the specified byte sequence into a string.
*
* @param toEncode The byte sequence to encode.
* @returns A string containing the Base64-encoded characters.
*/
encode(toEncode: Uint8Array): string;
}
/**
* The `TransformStream` that decodes a stream of Base64-encoded string into `Uint8Array` stream.
*
* @example
* ```javascript
* const decoderStream = new Base64.DecoderStream();
* // readableStream: ReadableStream<string>
* // writableStream: WritableStream<Uint8Array>
*
* readableStream.pipeThrough(decoderStream).pipeTo(writableStream);
* ```
*/
class DecoderStream extends BytesEncoding.DecoderStream {
/**
* @param options The `Base64.Options` dictionary.
*/
constructor(options?: Base64.Options);
}
/**
* The `TransformStream` that encodes a stream of `Uint8Array` into Base64-encoded string stream.
*
* @example
* ```javascript
* const encoderStream = new Base64.EncoderStream();
* // readableStream: ReadableStream<Uint8Array>
* // writableStream: WritableStream<string>
*
* readableStream.pipeThrough(encoderStream).pipeTo(writableStream);
* ```
*/
class EncoderStream extends BytesEncoding.EncoderStream {
/**
* @param options The `Base64.Options` dictionary.
*/
constructor(options?: Base64.Options);
}
}
export { Base64 };