# `LibTmux.Filter`
[🔗](https://github.com/libtmux/libtmux-elixir/blob/b72452c198917433229bdc266a68c163541b6127/lib/libtmux/filter.ex#L1)

A validated portable predicate over one observed entity type.

Keywords are trusted shorthand for maps. Fields in one object conjoin;
duplicate keyword keys are rejected recursively. `not` at a field negates
equality, while Boolean `not` takes one criteria object. Lists require an
explicit operator. Native callbacks belong to `LibTmux.Selection.filter/2`.
This value contains data; executable preparation remains separate.

# `criteria`

```elixir
@type criteria() :: %{optional(atom()) => term()} | keyword(term())
```

Local map criteria or keyword shorthand; field and operand domains are validated at construction.

# `input`

```elixir
@type input() :: criteria() | t()
```

Trusted criteria data or a previously validated filter for the same entity.

# `limit_option`

```elixir
@type limit_option() ::
  {:max_bytes, pos_integer()}
  | {:max_depth, pos_integer()}
  | {:max_nodes, pos_integer()}
  | {:max_list, pos_integer()}
  | {:max_string_bytes, pos_integer()}
```

A positive resource ceiling; byte, depth, node, list and string budgets validate independently.

# `limits`

```elixir
@type limits() :: %{
  max_bytes: pos_integer(),
  max_depth: pos_integer(),
  max_nodes: pos_integer(),
  max_list: pos_integer(),
  max_string_bytes: pos_integer()
}
```

Resolved constructor budgets; wire limits also cover the versioned envelope.

# `t`

```elixir
@opaque t()
```

Validated portable predicate data; executable predicates are prepared separately.

# `from_json`

```elixir
@spec from_json(LibTmux.Schema.entity_selector(), binary(), [limit_option()]) ::
  {:ok, t()} | {:error, LibTmux.Error.t()}
```

Decodes bounded JSON, rejecting duplicate object keys and trailing data.

# `from_wire`

```elixir
@spec from_wire(LibTmux.Schema.entity_selector(), term(), [limit_option()]) ::
  {:ok, t()} | {:error, LibTmux.Error.t()}
```

Decodes a whitelisted versioned map; raw JSON must use from_json to retain duplicate keys.

# `new`

```elixir
@spec new(LibTmux.Schema.entity_selector(), input(), [limit_option()]) ::
  {:ok, t()} | {:error, LibTmux.Error.t()}
```

Normalizes criteria and validates field/operator/value domains before evaluation.

An existing filter retains its constructor's validation when no new limits
are supplied. Explicit limits check the normalized tree directly, without
expanding it into synthetic input syntax.

# `new!`

```elixir
@spec new!(LibTmux.Schema.entity_selector(), input(), [limit_option()]) :: t()
```

Constructs a filter or raises its structured validation error.

# `to_predicate`

```elixir
@spec to_predicate(t(), [{:snapshot, LibTmux.Snapshot.t()}]) ::
  (LibTmux.Schema.observation() ->
     boolean())
```

Prepares a local unary predicate after validating captured coverage, including empty domains.

# `to_wire`

```elixir
@spec to_wire(t()) :: LibTmux.Wire.object()
```

Returns the explicit versioned string-keyed wire representation.

---

*Consult [api-reference.md](api-reference.md) for complete listing*