/** * Encoding & decoding for Base64 (RFC4648), Base64Url, and Hex. * * @since 4.0.0 */ import * as Data from "./Data.ts" import { hasProperty } from "./Predicate.ts" import * as Result from "./Result.ts" // ------------------------------------------------------------------------------------- // EncodingError // ------------------------------------------------------------------------------------- /** * @since 4.0.0 * @category symbols */ export const EncodingErrorTypeId = "~effect/encoding/EncodingError" as const /** * @since 4.0.0 * @category symbols */ export type EncodingErrorTypeId = typeof EncodingErrorTypeId /** * @since 4.0.0 * @category constructors */ export class EncodingError extends Data.TaggedError("EncodingError")<{ kind: "Decode" | "Encode" module: string input: unknown message: string }> { /** * @since 4.0.0 */ readonly [EncodingErrorTypeId]: EncodingErrorTypeId = EncodingErrorTypeId } /** * @since 4.0.0 * @category guards */ export const isEncodingError = (u: unknown): u is EncodingError => hasProperty(u, EncodingErrorTypeId) // ------------------------------------------------------------------------------------- // Base64 // ------------------------------------------------------------------------------------- /** * Encodes the given value into a base64 (RFC4648) `string`. * * @example * ```ts * import { Encoding } from "effect" * * // Encode a string * console.log(Encoding.encodeBase64("hello")) // "aGVsbG8=" * * // Encode binary data * const bytes = new Uint8Array([72, 101, 108, 108, 111]) * console.log(Encoding.encodeBase64(bytes)) // "SGVsbG8=" * ``` * * @since 4.0.0 * @category encoding */ export const encodeBase64: (input: Uint8Array | string) => string = (input) => typeof input === "string" ? base64EncodeUint8Array(encoder.encode(input)) : base64EncodeUint8Array(input) /** * Decodes a base64 (RFC4648) encoded `string` into a `Uint8Array`. * * @example * ```ts * import { Encoding, Result } from "effect" * * const result = Encoding.decodeBase64("SGVsbG8=") * if (Result.isSuccess(result)) { * console.log(Array.from(result.success)) // [72, 101, 108, 108, 111] * } * ``` * * @since 4.0.0 * @category decoding */ export const decodeBase64 = (str: string): Result.Result => { const stripped = stripCrlf(str) const length = stripped.length if (length % 4 !== 0) { return Result.fail( new EncodingError({ kind: "Decode", module: "Base64", input: stripped, message: `Length must be a multiple of 4, but is ${length}` }) ) } const index = stripped.indexOf("=") if (index !== -1 && ((index < length - 2) || (index === length - 2 && stripped[length - 1] !== "="))) { return Result.fail( new EncodingError({ kind: "Decode", module: "Base64", input: stripped, message: `Found a '=' character, but it is not at the end` }) ) } try { const missingOctets = stripped.endsWith("==") ? 2 : stripped.endsWith("=") ? 1 : 0 const result = new Uint8Array(3 * (length / 4) - missingOctets) for (let i = 0, j = 0; i < length; i += 4, j += 3) { const buffer = getBase64Code(stripped.charCodeAt(i)) << 18 | getBase64Code(stripped.charCodeAt(i + 1)) << 12 | getBase64Code(stripped.charCodeAt(i + 2)) << 6 | getBase64Code(stripped.charCodeAt(i + 3)) result[j] = buffer >> 16 result[j + 1] = (buffer >> 8) & 0xff result[j + 2] = buffer & 0xff } return Result.succeed(result) } catch (e) { return Result.fail( new EncodingError({ kind: "Decode", module: "Base64", input: stripped, message: e instanceof Error ? e.message : "Invalid input" }) ) } } /** * Decodes a base64 (RFC4648) encoded `string` into a UTF-8 `string`. * * @example * ```ts * import { Encoding, Result } from "effect" * * const result = Encoding.decodeBase64String("aGVsbG8=") * if (Result.isSuccess(result)) { * console.log(result.success) // "hello" * } * ``` * * @since 4.0.0 * @category decoding */ export const decodeBase64String = (str: string) => Result.map(decodeBase64(str), (_) => decoder.decode(_)) // ------------------------------------------------------------------------------------- // Base64Url // ------------------------------------------------------------------------------------- /** * Encodes the given value into a base64 (URL) `string`. * * @example * ```ts * import { Encoding } from "effect" * * // URL-safe base64 encoding (uses - and _ instead of + and /) * console.log(Encoding.encodeBase64Url("hello?")) // "aGVsbG8_" * * const bytes = new Uint8Array([72, 101, 108, 108, 111, 63]) * console.log(Encoding.encodeBase64Url(bytes)) // "SGVsbG8_" * ``` * * @since 4.0.0 * @category encoding */ export const encodeBase64Url: (input: Uint8Array | string) => string = (input) => typeof input === "string" ? base64UrlEncodeUint8Array(encoder.encode(input)) : base64UrlEncodeUint8Array(input) /** * Decodes a base64 (URL) encoded `string` into a `Uint8Array`. * * @example * ```ts * import { Encoding, Result } from "effect" * * const result = Encoding.decodeBase64Url("SGVsbG8_") * if (Result.isSuccess(result)) { * console.log(Array.from(result.success)) // [72, 101, 108, 108, 111, 63] * } * ``` * * @since 4.0.0 * @category decoding */ export const decodeBase64Url = (str: string): Result.Result => { const stripped = stripCrlf(str) const length = stripped.length if (length % 4 === 1) { return Result.fail( new EncodingError({ module: "Base64Url", kind: "Decode", input: stripped, message: `Length should be a multiple of 4, but is ${length}` }) ) } if (!/^[-_A-Z0-9]*?={0,2}$/i.test(stripped)) { return Result.fail( new EncodingError({ module: "Base64Url", kind: "Decode", input: stripped, message: "Invalid input" }) ) } // Some variants allow or require omitting the padding '=' signs let sanitized = length % 4 === 2 ? `${stripped}==` : length % 4 === 3 ? `${stripped}=` : stripped sanitized = sanitized.replace(/-/g, "+").replace(/_/g, "/") return decodeBase64(sanitized) } /** * Decodes a base64 (URL) encoded `string` into a UTF-8 `string`. * * @example * ```ts * import { Encoding, Result } from "effect" * * const result = Encoding.decodeBase64UrlString("aGVsbG8_") * if (Result.isSuccess(result)) { * console.log(result.success) // "hello?" * } * ``` * * @since 4.0.0 * @category decoding */ export const decodeBase64UrlString = (str: string) => Result.map(decodeBase64Url(str), (_) => decoder.decode(_)) // ------------------------------------------------------------------------------------- // Hex // ------------------------------------------------------------------------------------- /** * Encodes the given value into a hex `string`. * * @example * ```ts * import { Encoding } from "effect" * * // Encode a string to hex * console.log(Encoding.encodeHex("hello")) // "68656c6c6f" * * // Encode binary data to hex * const bytes = new Uint8Array([72, 101, 108, 108, 111]) * console.log(Encoding.encodeHex(bytes)) // "48656c6c6f" * ``` * * @since 4.0.0 * @category encoding */ export const encodeHex: (input: Uint8Array | string) => string = (input) => typeof input === "string" ? hexEncodeUint8Array(encoder.encode(input)) : hexEncodeUint8Array(input) /** * Decodes a hex encoded `string` into a `Uint8Array`. * * @example * ```ts * import { Encoding, Result } from "effect" * * const result = Encoding.decodeHex("48656c6c6f") * if (Result.isSuccess(result)) { * console.log(Array.from(result.success)) // [72, 101, 108, 108, 111] * } * ``` * * @since 4.0.0 * @category decoding */ export const decodeHex = (str: string): Result.Result => { const bytes = new TextEncoder().encode(str) if (bytes.length % 2 !== 0) { return Result.fail( new EncodingError({ module: "Hex", kind: "Decode", input: str, message: `Length must be a multiple of 2, but is ${bytes.length}` }) ) } try { const length = bytes.length / 2 const result = new Uint8Array(length) for (let i = 0; i < length; i++) { const a = fromHexChar(bytes[i * 2]) const b = fromHexChar(bytes[i * 2 + 1]) result[i] = (a << 4) | b } return Result.succeed(result) } catch (e) { return Result.fail( new EncodingError({ module: "Hex", kind: "Decode", input: str, message: e instanceof Error ? e.message : "Invalid input" }) ) } } /** * Decodes a hex encoded `string` into a UTF-8 `string`. * * @example * ```ts * import { Encoding, Result } from "effect" * * const result = Encoding.decodeHexString("68656c6c6f") * if (Result.isSuccess(result)) { * console.log(result.success) // "hello" * } * ``` * * @since 4.0.0 * @category decoding */ export const decodeHexString = (str: string) => Result.map(decodeHex(str), (_) => decoder.decode(_)) // ------------------------------------------------------------------------------------- // internals // ------------------------------------------------------------------------------------- const encoder = new TextEncoder() const decoder = new TextDecoder() const stripCrlf = (str: string) => str.replace(/[\n\r]/g, "") // Base64 internals const base64EncodeUint8Array = (bytes: Uint8Array) => { const length = bytes.length let result = "" let i: number for (i = 2; i < length; i += 3) { result += base64abc[bytes[i - 2] >> 2] result += base64abc[((bytes[i - 2] & 0x03) << 4) | (bytes[i - 1] >> 4)] result += base64abc[((bytes[i - 1] & 0x0f) << 2) | (bytes[i] >> 6)] result += base64abc[bytes[i] & 0x3f] } if (i === length + 1) { result += base64abc[bytes[i - 2] >> 2] result += base64abc[(bytes[i - 2] & 0x03) << 4] result += "==" } if (i === length) { result += base64abc[bytes[i - 2] >> 2] result += base64abc[((bytes[i - 2] & 0x03) << 4) | (bytes[i - 1] >> 4)] result += base64abc[(bytes[i - 1] & 0x0f) << 2] result += "=" } return result } function getBase64Code(charCode: number) { if (charCode >= base64codes.length) { throw new TypeError(`Invalid character ${String.fromCharCode(charCode)}`) } const code = base64codes[charCode] if (code === 255) { throw new TypeError(`Invalid character ${String.fromCharCode(charCode)}`) } return code } const base64abc = [ "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", "+", "/" ] const base64codes = [ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 62, 255, 255, 255, 63, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 255, 255, 255, 0, 255, 255, 255, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 255, 255, 255, 255, 255, 255, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51 ] // Base64Url internals const base64UrlEncodeUint8Array = (data: Uint8Array) => base64EncodeUint8Array(data).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_") // Hex internals const hexEncodeUint8Array = (bytes: Uint8Array) => { let result = "" for (let i = 0; i < bytes.length; ++i) { result += bytesToHex[bytes[i]] } return result } const fromHexChar = (byte: number) => { if (48 <= byte && byte <= 57) { return byte - 48 } if (97 <= byte && byte <= 102) { return byte - 97 + 10 } if (65 <= byte && byte <= 70) { return byte - 65 + 10 } throw new TypeError("Invalid input") } const bytesToHex = [ "00", "01", "02", "03", "04", "05", "06", "07", "08", "09", "0a", "0b", "0c", "0d", "0e", "0f", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "1a", "1b", "1c", "1d", "1e", "1f", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "2a", "2b", "2c", "2d", "2e", "2f", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "3a", "3b", "3c", "3d", "3e", "3f", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "4a", "4b", "4c", "4d", "4e", "4f", "50", "51", "52", "53", "54", "55", "56", "57", "58", "59", "5a", "5b", "5c", "5d", "5e", "5f", "60", "61", "62", "63", "64", "65", "66", "67", "68", "69", "6a", "6b", "6c", "6d", "6e", "6f", "70", "71", "72", "73", "74", "75", "76", "77", "78", "79", "7a", "7b", "7c", "7d", "7e", "7f", "80", "81", "82", "83", "84", "85", "86", "87", "88", "89", "8a", "8b", "8c", "8d", "8e", "8f", "90", "91", "92", "93", "94", "95", "96", "97", "98", "99", "9a", "9b", "9c", "9d", "9e", "9f", "a0", "a1", "a2", "a3", "a4", "a5", "a6", "a7", "a8", "a9", "aa", "ab", "ac", "ad", "ae", "af", "b0", "b1", "b2", "b3", "b4", "b5", "b6", "b7", "b8", "b9", "ba", "bb", "bc", "bd", "be", "bf", "c0", "c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8", "c9", "ca", "cb", "cc", "cd", "ce", "cf", "d0", "d1", "d2", "d3", "d4", "d5", "d6", "d7", "d8", "d9", "da", "db", "dc", "dd", "de", "df", "e0", "e1", "e2", "e3", "e4", "e5", "e6", "e7", "e8", "e9", "ea", "eb", "ec", "ed", "ee", "ef", "f0", "f1", "f2", "f3", "f4", "f5", "f6", "f7", "f8", "f9", "fa", "fb", "fc", "fd", "fe", "ff" ]