byte-encodings/dist/unstable_base64.d.ts

Utilities for encoding and decoding common formats like hex, base64, and varint. Ported from Deno's @std/encoding.

import { U as Uint8Array_ } from './_types-UoFpvNJp.js';
import { B as Base64Options } from './_common64-Ct2VviPe.js';
export { a as Base64Alphabet, c as calcSizeBase64 } from './_common64-Ct2VviPe.js';

/**
 * Functions to encode and decode to and from base64 strings.
 *
 * ```ts
 * import { assertEquals } from "@std/assert";
 * import { encodeBase64, type Uint8Array_ } from "@std/encoding/unstable-base64";
 *
 * assertEquals(encodeBase64("Hello World", { alphabet: "base64" }), "SGVsbG8gV29ybGQ=");
 * assertEquals(
 *   encodeBase64(
 *     new TextEncoder().encode("Hello World") as Uint8Array_,
 *     { alphabet: "base64" }
 *   ),
 *   "SGVsbG8gV29ybGQ=",
 * );
 * ```
 *
 * @see {@link https://www.rfc-editor.org/rfc/rfc4648.html#section-4}
 * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @module
 */

/**
 * `encodeBase64` takes an input source and encodes it into a base64 string. If
 * a {@linkcode Uint8Array<ArrayBuffer>} or {@linkcode ArrayBuffer} is provided,
 * the underlying source will be detached and reused for the encoding. If you
 * need the input source after providing it to this function, call `.slice()`
 * to pass in a copy.
 *
 * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @param input The input source to encode.
 * @param options The options to use for encoding.
 * @returns The base64 string representation of the input.
 *
 * @example Basic Usage
 * ```ts
 * import { assertEquals } from "@std/assert";
 * import {
 *   encodeBase64,
 *   type Uint8Array_
 * } from "@std/encoding/unstable-base64";
 *
 * assertEquals(encodeBase64("Hello World"), "SGVsbG8gV29ybGQ=");
 * assertEquals(
 *   encodeBase64(new TextEncoder().encode("Hello World") as Uint8Array_),
 *   "SGVsbG8gV29ybGQ=",
 * );
 *
 * assertEquals(
 *   encodeBase64("Hello World", { alphabet: "base64url" }),
 *   "SGVsbG8gV29ybGQ",
 * );
 * assertEquals(
 *   encodeBase64(
 *     new TextEncoder().encode("Hello World") as Uint8Array_,
 *     { alphabet: "base64url" },
 *   ),
 *   "SGVsbG8gV29ybGQ",
 * );
 * ```
 */
declare function encodeBase64(input: string | Uint8Array_ | ArrayBuffer, options?: Base64Options): string;
/**
 * `encodeIntoBase64` takes an input source and encodes it as base64 into the
 * output buffer.
 *
 * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @param input the source to encode.
 * @param output the buffer to write the encoded source to.
 * @param options the options to use for encoding.
 * @returns the number of bytes written to the buffer.
 *
 * @example Basic Usage
 * ```ts
 * import { assertEquals } from "@std/assert";
 * import {
 *   calcSizeBase64,
 *   encodeBase64,
 *   encodeIntoBase64,
 * } from "@std/encoding/unstable-base64";
 *
 * const prefix = "data:url/fake,";
 * const input = await Deno.readFile("./deno.lock");
 * const output = new Uint8Array(prefix.length + calcSizeBase64(input.length));
 *
 * let o = new TextEncoder().encodeInto(prefix, output).written;
 * o += encodeIntoBase64(input, output.subarray(o), { alphabet: "base64url" });
 * assertEquals(
 *   new TextDecoder().decode(output.subarray(0, o)),
 *   "data:url/fake," +
 *     encodeBase64(
 *       await Deno.readFile("./deno.lock"),
 *       { alphabet: "base64url" },
 *     ),
 * );
 * ```
 */
declare function encodeIntoBase64(input: string | Uint8Array_ | ArrayBuffer, output: Uint8Array_, options?: Base64Options): number;
/**
 * `decodeBase64` takes an input source and decodes it into a
 * {@linkcode Uint8Array<ArrayBuffer>} using the specified format.
 *
 * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @param input The input source to decode.
 * @param options The options to use for decoding.
 * @returns The decoded {@linkcode Uint8Array<ArrayBuffer>}.
 *
 * @example Basic Usage
 * ```ts
 * import { assertEquals } from "@std/assert";
 * import { decodeBase64 } from "@std/encoding/unstable-base64";
 *
 * assertEquals(
 *   decodeBase64("SGVsbG8gV29ybGQ=", { alphabet: "base64" }),
 *   new TextEncoder().encode("Hello World"),
 * );
 *
 * assertEquals(
 *   decodeBase64("SGVsbG8gV29ybGQ", { alphabet: "base64url" }),
 *   new TextEncoder().encode("Hello World"),
 * );
 * ```
 */
declare function decodeBase64(input: string | Uint8Array_, options?: Base64Options): Uint8Array_;

export { Base64Options, Uint8Array_, decodeBase64, encodeBase64, encodeIntoBase64 };