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.

14 exports Added in v2.0.0 Source

Decoding

decodeBase64

Added in v2.0.0 Source

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.succeed with a Uint8Array when decoding succeeds, or Result.fail with an EncodingError when the input is not valid base64.

Signature

declare function decodeBase64(str: string): Result<Uint8Array<ArrayBufferLike>, EncodingError>

Example

(Decoding Base64 bytes)

import { Encoding, Result } from "effect"

Encoding.decodeBase64("SGVsbG8=") // => Result.succeed(new Uint8Array([72, 101, 108, 108, 111]))

decodeBase64String

Added in v2.0.0 Source

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>

Example

(Decoding Base64 strings)

import { Encoding, Result } from "effect"

Encoding.decodeBase64String("aGVsbG8=") // => Result.succeed("hello")

decodeBase64Url

Added in v2.0.0 Source

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>

Example

(Decoding URL-safe Base64 bytes)

import { Encoding, Result } from "effect"

Encoding.decodeBase64Url("SGVsbG8_") // => Result.succeed(new Uint8Array([72, 101, 108, 108, 111, 63]))

decodeBase64UrlString

Added in v2.0.0 Source

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>

Example

(Decoding URL-safe Base64 strings)

import { Encoding, Result } from "effect"

Encoding.decodeBase64UrlString("aGVsbG8_") // => Result.succeed("hello?")

decodeHex

Added in v2.0.0 Source

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>

Example

(Decoding hex bytes)

import { Encoding, Result } from "effect"

Encoding.decodeHex("48656c6c6f") // => Result.succeed(new Uint8Array([72, 101, 108, 108, 111]))

decodeHexString

Added in v2.0.0 Source

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>

Example

(Decoding hex strings)

import { Encoding, Result } from "effect"

Encoding.decodeHexString("68656c6c6f") // => Result.succeed("hello")

Encoding

encodeBase64

Added in v2.0.0 Source

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

decodeBase64 for decoding standard Base64 to bytes
decodeBase64String for decoding standard Base64 to UTF-8 text
encodeBase64Url for URL-safe unpadded Base64 output

Signature

declare const encodeBase64: (input: Uint8Array | string) => string

Example

(Encoding Base64 strings and bytes)

import { Encoding } from "effect"

// Encode a string
Encoding.encodeBase64("hello") // => "aGVsbG8="

// Encode binary data
const bytes = new Uint8Array([72, 101, 108, 108, 111])
Encoding.encodeBase64(bytes) // => "SGVsbG8="

encodeBase64Url

Added in v2.0.0 Source

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

decodeBase64Url for decoding URL-safe Base64 to bytes
decodeBase64UrlString for decoding URL-safe Base64 to UTF-8 text
encodeBase64 for standard padded Base64 output

Signature

declare const encodeBase64Url: (input: Uint8Array | string) => string

Example

(Encoding URL-safe Base64)

import { Encoding } from "effect"

// URL-safe base64 encoding (uses - and _ instead of + and /)
Encoding.encodeBase64Url("hello?") // => "aGVsbG8_"

const bytes = new Uint8Array([72, 101, 108, 108, 111, 63])
Encoding.encodeBase64Url(bytes) // => "SGVsbG8_"

encodeHex

Added in v2.0.0 Source

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

Example

(Encoding hex strings and bytes)

import { Encoding } from "effect"

// Encode a string to hex
Encoding.encodeHex("hello") // => "68656c6c6f"

// Encode binary data to hex
const bytes = new Uint8Array([72, 101, 108, 108, 111])
Encoding.encodeHex(bytes) // => "48656c6c6f"

randomHex

Added in v4.0.0 Source

Generates a random lowercase hexadecimal string, optimized for lengths that are multiples of 8.

length is not validated. The function generates length >>> 3 random 8-character words, so non-negative lengths below 2 ** 32 are rounded down to a multiple of 8 and other values follow JavaScript's unsigned 32-bit coercion rules.

This function uses Math.random() and is not cryptographically secure. For security-sensitive values, use the Crypto.Crypto service's randomBytes method and encode the result with encodeHex.

Signature

declare function randomHex(length: number): string

Errors

EncodingError

Added in v4.0.0 Source

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

isEncodingError for 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

Added in v4.0.0 Source

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

EncodingError for the structured error produced by failed encoding and decoding operations

Signature

declare function isEncodingError(u: unknown): u is EncodingError

Type IDs

EncodingErrorTypeId

Added in v4.0.0 Source

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

isEncodingError for the public guard that checks this marker

Signature

declare const EncodingErrorTypeId: "~effect/encoding/EncodingError"

EncodingErrorTypeId type

Added in v4.0.0 Source

Literal type of the EncodingErrorTypeId marker.

When to use

Use to type the marker carried by EncodingError values.

Signature

type EncodingErrorTypeId = typeof EncodingErrorTypeId