Vaultx.Base.JSON (Vaultx v0.7.0)

View Source

Adaptive JSON processing for Vaultx HashiCorp Vault client.

This module provides a unified JSON interface that automatically selects the best available JSON library for optimal performance and compatibility. It supports both modern Elixir built-in JSON and the popular Jason library.

Library Selection Strategy

  1. Elixir 1.18+ built-in JSON - Preferred for maximum performance
  2. Jason - Fallback for compatibility with older Elixir versions

Key Features

  • Automatic Detection: Intelligently selects the best available library
  • Performance Optimized: Leverages Elixir's native JSON for speed
  • Backward Compatible: Seamless fallback to Jason when needed
  • Configurable: Override selection via environment variables
  • Error Handling: Comprehensive error context and recovery
  • Type Safe: Full type specifications and validation

Configuration Options

Override automatic detection with environment variables:

# Force Elixir built-in JSON (Elixir 1.18+)
export VAULTX_JSON_LIBRARY="elixir"

# Force Jason library
export VAULTX_JSON_LIBRARY="jason"

References

Examples

# Encoding
{:ok, json} = Vaultx.Base.JSON.encode(%{"key" => "value"})
json_string = Vaultx.Base.JSON.encode!(%{"key" => "value"})

# Decoding
{:ok, data} = Vaultx.Base.JSON.decode(~s({"key": "value"}))
data = Vaultx.Base.JSON.decode!(~s({"key": "value"}))

# Check current library
library = Vaultx.Base.JSON.current_library()
# Returns :elixir or :jason

Summary

Types

decode_error()
encode_error()
json_library()

Functions

current_library()

Returns the currently selected JSON library.

decode(json)

Safely decodes a JSON string to term.

decode!(json)

Decodes a JSON string to term, raising on error.

encode(term)

Safely encodes a term to JSON string.

encode!(term)

Encodes a term to JSON string, raising on error.

library_available?(atom)

Checks if a specific JSON library is available.

library_info()

Returns information about available JSON libraries.

Types

decode_error()

@type decode_error() :: Vaultx.Types.result(term())

encode_error()

@type encode_error() :: Vaultx.Types.result(String.t())

json_library()

@type json_library() :: :elixir | :jason

Functions

current_library()

@spec current_library() :: json_library()

Returns the currently selected JSON library.

Examples

iex> Vaultx.Base.JSON.current_library()
:elixir

decode(json)

@spec decode(String.t()) :: {:ok, term()} | decode_error()

Safely decodes a JSON string to term.

Examples

iex> Vaultx.Base.JSON.decode(~s({"key":"value"}))
{:ok, %{"key" => "value"}}

iex> Vaultx.Base.JSON.decode("invalid json")
{:error, %Vaultx.Base.Error{type: :json_decode_error}}

decode!(json)

@spec decode!(String.t()) :: term()

Decodes a JSON string to term, raising on error.

Examples

iex> Vaultx.Base.JSON.decode!(~s({"key":"value"}))
%{"key" => "value"}

iex> Vaultx.Base.JSON.decode!("invalid json")
 (Vaultx.Base.Error) JSON decoding failed

encode(term)

@spec encode(term()) :: {:ok, String.t()} | encode_error()

Safely encodes a term to JSON string.

Examples

iex> Vaultx.Base.JSON.encode(%{"key" => "value"})
{:ok, ~s({"key":"value"})}

iex> Vaultx.Base.JSON.encode({:invalid, :tuple})
{:error, %Vaultx.Base.Error{type: :json_encode_error}}

encode!(term)

@spec encode!(term()) :: String.t()

Encodes a term to JSON string, raising on error.

Examples

iex> Vaultx.Base.JSON.encode!(%{"key" => "value"})
~s({"key":"value"})

iex> Vaultx.Base.JSON.encode!({:invalid, :tuple})
 (Vaultx.Base.Error) JSON encoding failed

library_available?(atom)

@spec library_available?(json_library()) :: boolean()

Checks if a specific JSON library is available.

Examples

iex> Vaultx.Base.JSON.library_available?(:elixir)
true

iex> Vaultx.Base.JSON.library_available?(:jason)
true

library_info()

@spec library_info() :: %{
  current: json_library(),
  available: [json_library()],
  elixir_available: boolean(),
  jason_available: boolean()
}

Returns information about available JSON libraries.

Examples

iex> info = Vaultx.Base.JSON.library_info()
iex> info.current
:elixir