@spec compact(
  map() | list() | any(),
  keyword()
) :: map() | list() | any()

Recursively removes nil map values, then prunes containers left empty by that removal.

compact/2 uses the same traversal semantics and :structs option as reject/3: non-container list elements are untouched by default, and structs are treated as opaque leaves unless structs: :convert or structs: :error is supplied.

Options

• :prune_empty - when true (default), removes map entries and list elements whose cleaned value is an empty map or list
• :strip_list_nils - when true, also removes nil elements from lists; defaults to false
• :structs - same meaning as in reject/3

Examples

iex> NestedFilter.compact(%{a: 1, b: nil, c: %{d: nil}, e: %{f: 1, g: nil}})
%{a: 1, e: %{f: 1}}

iex> NestedFilter.compact(%{a: [1, nil, 2]}, strip_list_nils: true)
%{a: [1, 2]}

@spec drop_by_key(map(), [key()], keyword()) :: map()

Recursively removes map entries whose key is in keys_to_reject.

Sugar for reject(map, fn key, _val -> key in keys_to_reject end, opts) — see reject/3 for the traversal semantics and options.

Examples

iex> NestedFilter.drop_by_key(%{a: 1, b: %{a: 2, c: 3}}, [:a])
%{b: %{c: 3}}

@spec drop_by_value(map(), [val()], keyword()) :: map()

Recursively removes map entries whose value is in values_to_reject.

Sugar for reject(map, fn _key, val -> val in values_to_reject end, opts) — see reject/3 for the traversal semantics and options.

Examples

iex> NestedFilter.drop_by_value(%{a: 1, b: %{m: nil, n: 2}}, [nil])
%{a: 1, b: %{n: 2}}

@spec filter(map() | list() | any(), predicate(), keyword()) :: map() | list() | any()

Recursively keeps map entries for which predicate returns a truthy value.

A matched entry is kept whole: its value is not recursed into, so the entire subtree survives. A container entry (map or list) that is not matched itself is kept only if it has surviving descendants; branches and list elements with no surviving content are pruned entirely. Any other input is returned unchanged.

Structure is always preserved — matches stay at the path where they were found, and sibling branches are never merged.

Options

Accepts the same :structs option as reject/3. With the default :leaf, a struct is an opaque value: kept whole when its entry is matched, pruned otherwise.

Examples

iex> NestedFilter.filter(
...>   %{a: %{x: 1}, b: %{y: 2}, c: [%{x: 3, y: 4}, %{y: 5}]},
...>   fn k, _v -> k in [:x] end
...> )
%{a: %{x: 1}, c: [%{x: 3}]}

iex> NestedFilter.filter(%{user: %{name: "ada"}, meta: %{z: 1}}, fn k, _v -> k == :user end)
%{user: %{name: "ada"}}

@spec redact(map() | list() | any(), [key()] | predicate(), keyword()) ::
  map() | list() | any()

Recursively replaces values whose map entry matches keys_or_predicate.

keys_or_predicate may be a list of keys or a two-arity predicate function. A matched entry is replaced with opts[:replacement], which defaults to "[REDACTED]". Unmatched entries are recursively redacted, and lists are traversed while non-container list elements are left unchanged.

Options

• :replacement - value used for matched entries; defaults to "[REDACTED]"
• :recurse_into_matched - when true, matched map or list values are recursed into instead of replaced wholesale; matched scalar values are still replaced. Defaults to false
• :structs - same meaning as in reject/3

Examples

iex> NestedFilter.redact(%{user: %{name: "Ana", password: "hunter2"}, token: "abc"}, [:password, :token])
%{user: %{name: "Ana", password: "[REDACTED]"}, token: "[REDACTED]"}

iex> NestedFilter.redact(%{card: "4111111111111111"}, fn _k, v -> is_binary(v) and String.match?(v, ~r/^\d{13,16}$/) end)
%{card: "[REDACTED]"}

iex> NestedFilter.redact(%{token: %{value: "abc", meta: %{token: "nested-secret"}}}, [:token], recurse_into_matched: true)
%{token: %{value: "abc", meta: %{token: "[REDACTED]"}}}

@spec reject(map() | list() | any(), predicate(), keyword()) :: map() | list() | any()

Recursively removes map entries for which predicate returns a truthy value.

Values are cleaned depth-first: the predicate receives each key and its already-cleaned value. Empty maps produced by rejection are preserved. Lists are traversed, but their non-container elements are untouched — the predicate only applies to map entries, which have keys. Any other input is returned unchanged.

Options

• :structs — how to handle structs encountered at any depth:
  • :leaf (default) — the struct passes through as an opaque value, never recursed into and never altered
  • :convert — the struct is converted with Map.from_struct/1 and recursed into; the result is a plain map
  • :error — raises ArgumentError on any struct

Examples

iex> NestedFilter.reject(%{a: 1, b: %{c: nil}}, fn _k, v -> is_nil(v) end)
%{a: 1, b: %{}}

iex> NestedFilter.reject(%{a: [1, nil, %{b: nil}]}, fn _k, v -> is_nil(v) end)
%{a: [1, nil, %{}]}

@spec take_by_key(map(), keys_to_select(), keyword()) :: map()

Recursively keeps map entries whose key is in keys_to_select, preserving the structure they were found in.

Sugar for filter(map, fn key, _val -> key in keys_to_select end, opts) — see filter/3 for the traversal semantics and options. Matches stay at the path where they were found; sibling branches are never merged, and branches without a match are pruned.

Examples

iex> NestedFilter.take_by_key(%{a: %{x: 1}, b: %{x: 2}}, [:x])
%{a: %{x: 1}, b: %{x: 2}}