@spec available_codecs() :: [codec(), ...]

Returns the list of available codecs.

This function checks which codecs are actually available at runtime. :none and :zlib are always available. Other codecs require the Zig NIFs to be compiled with the system libraries installed.

Examples

ExZarr.Codecs.available_codecs()
# => [:none, :zlib, :zstd, :lz4, :snappy, :blosc, :bzip2]
# (if all system libraries are installed)

Returns

List of codec atoms that can be used with compress/3 and decompress/2.

@spec codec_available?(codec()) :: boolean()

Checks if a codec is available for use.

Returns true if the codec can be used with compress/3 and decompress/2, false otherwise.

This function actually tests if the codec can be used by checking if the necessary functions are exported from the ZigCodecs module.

Examples

ExZarr.Codecs.codec_available?(:zlib)
# => true

ExZarr.Codecs.codec_available?(:zstd)
# => true (if libzstd is installed and NIFs are compiled)

ExZarr.Codecs.codec_available?(:unknown)
# => false

Parameters

• codec - Codec atom to check

Returns

Boolean indicating codec availability.

@spec codec_info(codec()) :: {:ok, map()} | {:error, :not_found}

Gets information about a codec.

Returns metadata including name, version, type, and description.

Examples

{:ok, info} = ExZarr.Codecs.codec_info(:zstd)
# => %{
#   name: "Zstandard",
#   version: "1.0.0",
#   type: :compression,
#   description: "Zstandard compression algorithm"
# }

Returns

• {:ok, map()} - Codec information
• {:error, :not_found} - Codec not registered

@spec compress(binary(), codec(), keyword()) :: {:ok, binary()} | {:error, term()}

Compresses data using the specified codec.

Takes binary data and compresses it using the chosen compression algorithm. The :none codec returns the data unchanged. Other codecs apply compression and return the compressed binary.

Parameters

• data - Binary data to compress
• codec - Compression codec (:none, :zlib, :zstd, :lz4, :snappy, :blosc, :bzip2, or :crc32c)
• opts - Optional keyword list with compression options:
  • :level - Compression level (codec-specific, typically 1-9)

Examples

# Compress with zlib
{:ok, compressed} = ExZarr.Codecs.compress("hello world", :zlib)

# Compress with zstd at level 5
{:ok, compressed} = ExZarr.Codecs.compress("hello world", :zstd, level: 5)

# No compression
{:ok, same} = ExZarr.Codecs.compress("hello", :none)
# same == "hello"

# Compress binary data
data = :crypto.strong_rand_bytes(1000)
{:ok, compressed} = ExZarr.Codecs.compress(data, :zlib)

Returns

• {:ok, compressed_binary} on success
• {:error, {:unsupported_codec, codec}} if codec is not available
• {:error, {:compression_failed, reason}} if compression fails

@spec decompress(binary(), codec()) :: {:ok, binary()} | {:error, term()}

Decompresses data using the specified codec.

Takes compressed binary data and decompresses it using the chosen algorithm. The codec must match the one used for compression. The :none codec returns the data unchanged.

Parameters

• data - Compressed binary data
• codec - Compression codec (:none, :zlib, :zstd, :lz4, :snappy, :blosc, :bzip2, or :crc32c)

Examples

# Compress and decompress
{:ok, compressed} = ExZarr.Codecs.compress("hello world", :zlib)
{:ok, original} = ExZarr.Codecs.decompress(compressed, :zlib)
# original == "hello world"

# No decompression needed
{:ok, same} = ExZarr.Codecs.decompress("hello", :none)
# same == "hello"

Returns

• {:ok, decompressed_binary} on success
• {:error, {:unsupported_codec, codec}} if codec is not available
• {:error, {:decompression_failed, reason}} if decompression fails

Errors

Decompression will fail if:

• The data is not validly compressed with the specified codec
• The data is corrupted
• The wrong codec is specified

Notes

For :lz4 and :bzip2, the original size is stored in the first 8 bytes of the compressed data (prepended during compression).

@spec list_codecs() :: [codec()]

Lists all registered codec IDs.

Includes both built-in and custom codecs, regardless of availability.

Examples

ExZarr.Codecs.list_codecs()
# => [:none, :zlib, :crc32c, :zstd, :lz4, :my_codec]

@spec register_codec(
  codec_module(),
  keyword()
) :: :ok | {:error, term()}

Registers a custom codec.

The codec module must implement the ExZarr.Codecs.Codec behavior.

Examples

defmodule MyApp.CustomCodec do
  @behaviour ExZarr.Codecs.Codec

  def codec_id, do: :my_codec
  def codec_info, do: %{name: "My Codec", version: "1.0", type: :compression, description: "..."}
  def available?, do: true
  def encode(data, _opts), do: {:ok, my_encode(data)}
  def decode(data, _opts), do: {:ok, my_decode(data)}
end

ExZarr.Codecs.register_codec(MyApp.CustomCodec)
{:ok, encoded} = ExZarr.Codecs.compress(data, :my_codec)

Options

• :force - Overwrite existing codec with same ID (default: false)

Returns

• :ok - Codec registered successfully
• {:error, :already_registered} - Codec ID already in use
• {:error, :invalid_codec} - Module doesn't implement Codec behavior

@spec unregister_codec(codec()) :: :ok | {:error, term()}

Unregisters a custom codec.

Built-in codecs cannot be unregistered.

Examples

ExZarr.Codecs.unregister_codec(:my_codec)

Returns

• :ok - Codec unregistered successfully
• {:error, :not_found} - Codec not registered
• {:error, :cannot_unregister_builtin} - Cannot unregister built-in codec