Encoding
Encoding and decoding helpers for Base64, Base64Url, and hexadecimal text. The functions convert between strings, UTF-8 text, and Uint8Array bytes. Encode functions return strings directly, while decode functions return Result.Result so invalid input is reported as an EncodingError instead of being thrown.
Decoding
decodeBase64
Signature
declare function decodeBase64(str: string): Result<Uint8Array<ArrayBufferLike>, EncodingError>;decodeBase64String
Decodes a base64 (RFC4648) string into a UTF-8 string safely.
When to use
Use to decode a standard padded Base64 string into UTF-8 text without throwing on invalid input.
Details
Returns Result.succeed with the decoded text when decoding succeeds, or Result.fail with an EncodingError when the input is not valid base64.
Signature
declare function decodeBase64String(str: string): Result<string, EncodingError>;decodeBase64Url
Decodes a URL-safe base64 string into bytes safely.
When to use
Use to decode padded or unpadded Base64Url text into bytes without throwing on invalid input.
Details
Returns Result.succeed with a Uint8Array when decoding succeeds, or Result.fail with an EncodingError when the input is not valid URL-safe base64. Both padded and unpadded URL-safe base64 forms are accepted when otherwise valid.
Signature
declare function decodeBase64Url(str: string): Result<Uint8Array<ArrayBufferLike>, EncodingError>;decodeBase64UrlString
Decodes a URL-safe base64 string into a UTF-8 string safely.
When to use
Use to decode padded or unpadded Base64Url text into UTF-8 text without throwing on invalid input.
Details
Returns Result.succeed with the decoded text when decoding succeeds, or Result.fail with an EncodingError when the input is not valid URL-safe base64.
Signature
declare function decodeBase64UrlString(str: string): Result<string, EncodingError>;Decodes a hexadecimal string into bytes safely.
When to use
Use to decode hexadecimal text into bytes without throwing on invalid input.
Details
Returns Result.succeed with a Uint8Array when decoding succeeds, or Result.fail with an EncodingError when the input has an odd length or contains invalid hex characters.
Signature
declare function decodeHex(str: string): Result<Uint8Array<ArrayBufferLike>, EncodingError>;decodeHexString
Decodes a hexadecimal string into a UTF-8 string safely.
When to use
Use to decode hexadecimal text into UTF-8 text without throwing on invalid input.
Details
Returns Result.succeed with the decoded text when decoding succeeds, or Result.fail with an EncodingError when the input is not valid hex.
Signature
declare function decodeHexString(str: string): Result<string, EncodingError>;Encoding
encodeBase64
Encodes the given value into a base64 (RFC4648) string.
When to use
Use to encode text or bytes as a standard padded Base64 string for storage or transport.
Details
String inputs are encoded as UTF-8 bytes before Base64 encoding. Uint8Array inputs are encoded directly. The output uses the standard RFC4648 alphabet with = padding.
See
decodeBase64for decoding standard Base64 to bytesdecodeBase64Stringfor decoding standard Base64 to UTF-8 textencodeBase64Urlfor URL-safe unpadded Base64 output
Signature
declare const encodeBase64: (input: Uint8Array | string) => string;encodeBase64Url
Encodes the given value into a base64 (URL) string.
When to use
Use to encode text or bytes as an unpadded Base64Url string for contexts that require the URL-safe alphabet.
Details
String inputs are encoded as UTF-8 bytes before Base64Url encoding. Uint8Array inputs are encoded directly. The output removes = padding and replaces + with - and / with _.
See
decodeBase64Urlfor decoding URL-safe Base64 to bytesdecodeBase64UrlStringfor decoding URL-safe Base64 to UTF-8 textencodeBase64for standard padded Base64 output
Signature
declare const encodeBase64Url: (input: Uint8Array | string) => string;Encodes the given value into a hex string.
When to use
Use to encode text or bytes as lowercase hexadecimal text.
Signature
declare const encodeHex: (input: Uint8Array | string) => string;Errors
EncodingError
Error returned when an encoding or decoding operation cannot process its input.
When to use
Use when you need to handle or inspect failures from encoding or decoding operations.
Details
The error records whether the failure happened during encoding or decoding, which encoding module reported it, the original input, and a human-readable message.
See
isEncodingErrorfor checking whether a value is an EncodingError
Signature
declare class EncodingError extends YieldableError<this> & {
readonly _tag: "EncodingError";
} & Readonly<{
input: unknown;
kind: "Decode" | "Encode";
message: string;
module: string;
}> {
constructor(args: {
readonly input: unknown;
readonly kind: "Decode" | "Encode";
readonly message: string;
readonly module: string;
});
readonly "~effect/encoding/EncodingError": "~effect/encoding/EncodingError";
}Guards
isEncodingError
Checks whether a value is an EncodingError.
When to use
Use to narrow an unknown value before handling it as an EncodingError from encoding or decoding code.
Details
Returns true when the value carries the EncodingErrorTypeId marker and narrows the value to EncodingError.
See
EncodingErrorfor the structured error produced by failed encoding and decoding operations
Signature
declare function isEncodingError(u: unknown): u is EncodingError;Type IDs
EncodingErrorTypeId
Type identifier stored on EncodingError values and used by isEncodingError.
When to use
Use when implementing low-level EncodingError-compatible values that need to carry the runtime marker.
Details
This marker is part of the runtime representation of EncodingError. Prefer isEncodingError when narrowing unknown values.
See
isEncodingErrorfor the public guard that checks this marker
Signature
declare const EncodingErrorTypeId: "~effect/encoding/EncodingError";EncodingErrorTypeId type
Literal type of the EncodingErrorTypeId marker.
When to use
Use to type the marker carried by EncodingError values.
Signature
type EncodingErrorTypeId = typeof EncodingErrorTypeId;
Decodes a base64 (RFC4648) string into bytes safely.
When to use
Use to decode a standard padded Base64 string into bytes without throwing on invalid input.
Details
Returns
Result.succeedwith aUint8Arraywhen decoding succeeds, orResult.failwith anEncodingErrorwhen the input is not valid base64.