LibTmux.Filter (libtmux v0.0.1-alpha.1)

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.

Summary

Types

criteria()

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

input()

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

limit_option()

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

limits()

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

t()

Validated portable predicate data; executable predicates are prepared separately.

Functions

from_json(entity, json, options \\ [])

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

from_wire(entity, payload, options \\ [])

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

new(entity, criteria, options \\ [])

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

new!(entity, criteria, options \\ [])

Constructs a filter or raises its structured validation error.

to_predicate(filter, options)

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

to_wire(filter)

Returns the explicit versioned string-keyed wire representation.

Types

criteria()

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

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

input()

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

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

limit_option()

@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()

@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()

@opaque t()

Validated portable predicate data; executable predicates are prepared separately.

Functions

from_json(entity, json, options \\ [])

@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(entity, payload, options \\ [])

@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(entity, criteria, options \\ [])

@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!(entity, criteria, options \\ [])

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

Constructs a filter or raises its structured validation error.

to_predicate(filter, options)

@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(filter)

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

Returns the explicit versioned string-keyed wire representation.