# `ACP.MaybeUndefined`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L1)

A three-state value type: `:undefined`, `nil` (null), or `{:value, term}`.

Similar to `Option<T>`, but distinguishes between a missing field (undefined)
and an explicitly null field. This is important for partial update semantics
where omitting a field means "don't change" and setting it to null means "clear".

## JSON Serialization

- `:undefined` → field is omitted from JSON output
- `nil` → `null`
- `{:value, x}` → the JSON encoding of `x`

## Examples

    iex> ACP.MaybeUndefined.is_undefined(:undefined)
    true

    iex> ACP.MaybeUndefined.is_undefined(nil)
    false

    iex> ACP.MaybeUndefined.is_undefined({:value, "hello"})
    false

# `t`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L27)

```elixir
@type t(value) :: :undefined | nil | {:value, value}
```

# `as_opt_ref`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L46)

Converts to `Option<Option<T>>` equivalent: nil | {:some, nil} | {:some, value}.

# `from_json`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L84)

Decodes a MaybeUndefined value from JSON deserialization.
Call with `:missing` if the key was not present, or the value if it was.

# `from_opt`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L51)

Converts from a nested option back to MaybeUndefined.

# `is_null`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L34)

Returns true if the value is null.

# `is_undefined`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L30)

Returns true if the value is undefined.

# `is_value`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L38)

Returns true if the value contains a value.

# `map_value`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L56)

Maps a function over the value, preserving undefined/null.

# `to_json`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L76)

Encodes a MaybeUndefined value for JSON serialization.
Returns `{:skip}` for undefined (caller should omit the field),
`nil` for null, or the value itself.

# `update_to`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L67)

Updates a target value if the MaybeUndefined is not undefined.

- `:undefined` → returns the current value unchanged
- `nil` → returns nil (clear)
- `{:value, v}` → returns v (set)

# `value`
[🔗](https://github.com/f1729/agent-client-protocol-elixir/blob/main/lib/acp/maybe_undefined.ex#L42)

Returns the inner value, or nil if undefined or null.

---

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