# `Concord.Compression`
[🔗](https://github.com/gsmlg-dev/concord/blob/main/lib/concord/compression.ex#L1)

Value compression for Concord KV store.

Provides transparent compression for large values to reduce memory usage
and improve performance. Compression is automatically applied based on
configurable size thresholds.

## Configuration

    config :concord,
      compression: [
        enabled: true,
        algorithm: :zlib,        # :zlib or :gzip
        threshold_bytes: 1024,   # Compress values larger than 1KB
        level: 6                 # Compression level 0-9 (0=none, 9=max)
      ]

## Compression Format

Compressed values are stored as tuples: `{:compressed, algorithm, binary}`
Uncompressed values are stored as-is.

## Examples

    # Compress a value
    compressed = Concord.Compression.compress("large data...")
    # {:compressed, :zlib, <<...>>}

    # Decompress automatically
    value = Concord.Compression.decompress(compressed)
    # "large data..."

    # Check if value should be compressed
    Concord.Compression.should_compress?("small")  # false
    Concord.Compression.should_compress?(large_data)  # true

# `algorithm`

```elixir
@type algorithm() :: :zlib | :gzip
```

# `compressed_value`

```elixir
@type compressed_value() :: {:compressed, algorithm(), binary()}
```

# `compress`

```elixir
@spec compress(
  term(),
  keyword()
) :: term() | compressed_value()
```

Compresses a value if it exceeds the configured size threshold.

## Options

- `:algorithm` - Compression algorithm (:zlib or :gzip)
- `:level` - Compression level 0-9 (default: 6)
- `:force` - Force compression regardless of size (default: false)

## Examples

    iex> Concord.Compression.compress("small value")
    "small value"

    iex> large_value = String.duplicate("x", 2048)
    iex> Concord.Compression.compress(large_value)
    {:compressed, :zlib, <<...>>}

    iex> Concord.Compression.compress("force compress", force: true)
    {:compressed, :zlib, <<...>>}

# `config`

```elixir
@spec config() :: keyword()
```

Returns the compression configuration.

# `decompress`

```elixir
@spec decompress(term() | compressed_value()) :: term()
```

Decompresses a value if it was compressed.

Automatically detects compressed values and decompresses them.
Non-compressed values are returned as-is.

## Examples

    iex> Concord.Compression.decompress("plain value")
    "plain value"

    iex> compressed = {:compressed, :zlib, binary}
    iex> Concord.Compression.decompress(compressed)
    "original value"

# `should_compress?`

```elixir
@spec should_compress?(
  term(),
  keyword()
) :: boolean()
```

Checks if a value should be compressed based on size threshold.

## Examples

    iex> Concord.Compression.should_compress?("small")
    false

    iex> large = String.duplicate("x", 2048)
    iex> Concord.Compression.should_compress?(large)
    true

# `stats`

```elixir
@spec stats(term()) :: map()
```

Returns compression statistics for a value.

## Examples

    iex> value = String.duplicate("x", 2048)
    iex> Concord.Compression.stats(value)
    %{
      original_size: 2048,
      compressed_size: 45,
      compression_ratio: 45.5,
      savings_bytes: 2003,
      savings_percent: 97.8
    }