@spec compress(binary()) :: {:ok, binary()} | {:error, String.t()}

Compresses the given binary using OpenZL.

Returns {:ok, compressed} on success or {:error, reason} on failure.

@spec compress(reference(), binary()) :: {:ok, binary()} | {:error, String.t()}

Compresses the given binary using a reusable compression context.

Creating a context with create_compression_context/0 and reusing it across multiple calls avoids repeated allocation of internal state.

@spec compress_bound(non_neg_integer()) :: non_neg_integer()

Returns the upper bound on compressed output size for a given input size.

Useful for pre-allocating buffers.

@spec compress_multi_typed(reference(), [tuple()]) ::
  {:ok, binary()} | {:error, String.t()}

Compresses multiple typed inputs into a single frame.

Each input is a tagged tuple: {:numeric, data, width}, {:struct, data, struct_width}, or {:string, data, lengths_bin}.

@spec compress_typed(reference(), tuple()) :: {:ok, binary()} | {:error, String.t()}

Compresses typed data (numeric, struct, or string) with type information.

Accepts tagged tuples:

• {:numeric, data, element_width} — width must be 1, 2, 4, or 8
• {:struct, data, struct_width} — fixed-width records
• {:string, data, lengths_bin} — variable-length strings with packed uint32 lengths

@spec create_compression_context() :: {:ok, reference()} | {:error, String.t()}

Creates a reusable compression context.

The context is garbage-collected when no longer referenced.

Contexts are not thread-safe — do not share a context across concurrent processes without external synchronization.

@spec create_decompression_context() :: {:ok, reference()} | {:error, String.t()}

Creates a reusable decompression context.

The context is garbage-collected when no longer referenced.

Contexts are not thread-safe — do not share a context across concurrent processes without external synchronization.

@spec create_sddl_compressor(binary()) :: {:ok, reference()} | {:error, String.t()}

Creates a compressor from compiled SDDL binary.

@spec decompress(binary()) :: {:ok, binary()} | {:error, String.t()}

Decompresses an OpenZL-compressed binary.

Returns {:ok, decompressed} on success or {:error, reason} on failure.

@spec decompress(reference(), binary()) :: {:ok, binary()} | {:error, String.t()}

Decompresses using a reusable decompression context.

@spec decompress_multi_typed(reference(), binary()) ::
  {:ok, [map()]} | {:error, String.t()}

Decompresses a multi-output frame into a list of typed result maps.

@spec decompress_typed(reference(), binary()) :: {:ok, map()} | {:error, String.t()}

Decompresses a single typed output from a compressed frame.

Returns {:ok, info_map} where info_map contains :type, :data, :element_width, :num_elements, and optionally :string_lengths.

@spec frame_info(binary()) :: {:ok, map()} | {:error, String.t()}

Queries frame metadata without decompression.

Returns {:ok, info_map} with :format_version, :num_outputs, and :outputs (a list of per-output metadata maps).

@spec sddl_compile(String.t()) :: {:ok, binary()} | {:error, String.t()}

Compiles SDDL source text to a binary description.

@spec set_compression_level(reference(), integer()) :: :ok | {:error, String.t()}

Sets the compression level on a reusable compression context.

Higher levels produce smaller output but take longer. The level persists across subsequent compress calls on the same context (sticky parameters).

@spec set_compressor(reference(), reference()) :: :ok | {:error, String.t()}

Attaches a compressor to a compression context.

After this call, compress/2 on this context will use the compressor's format-aware compression graph.

@spec version() :: String.t()

Returns the OpenZL library version string.