# `AshWorkflow.Entities.Timeout`
[🔗](https://github.com/team-alembic/ash_workflow/blob/v0.12.0/lib/ash_workflow/entities/timeout.ex#L1)

Defines a workflow timeout entity with its configuration schema.

## The `field` option

By default, timeouts measure duration against `state_entered_at` — the timestamp
of when the workflow entered its current state. The `field` option overrides this
to measure against any datetime attribute or calculation on the resource.

This enables data-driven deadlines: "3 months since their last session" rather than
"3 months since they entered the active state."

## The `fire_at` option

`fire_at` names a datetime attribute or expression calculation that already holds
the deadline instant, rather than an anchor to measure an offset from:

    timeout :dormant do
      fire_at :next_check_at
      transition_to :dormant_review
    end

The timeout fires once `next_check_at` has passed, at whatever resolution the
selected scheduler polls or arms timers with.

`fire_at` and `fire_after` are mutually exclusive, and exactly one of them is
required. `field` is the anchor `fire_after` measures from, so it has no meaning
alongside `fire_at` and is rejected in combination with it.

`AshWorkflow.Scheduler.due_at/2` reads the deadline field with `Map.get/2`, so a
`fire_at` pointing at an expression calculation only holds a value once that
calculation has been loaded. `AshWorkflow.Scheduler.Precise.Timeline` loads it
with the records it arms timers from.

For a recurring action that fires on an interval for as long as a record sits
in its step, use `AshWorkflow.Entities.Every` instead — see its moduledoc for
why that is a separate entity rather than a `repeat` option here.

# `duration_unit`

```elixir
@type duration_unit() :: AshWorkflow.Duration.unit()
```

# `t`

```elixir
@type t() :: %AshWorkflow.Entities.Timeout{
  __spark_metadata__: term(),
  action: atom() | nil,
  check_interval: String.t() | nil,
  emits: [AshWorkflow.Entities.Emit.t()],
  field: atom() | nil,
  fire_after: {pos_integer(), duration_unit()} | nil,
  fire_at: atom() | nil,
  name: atom(),
  retry: AshWorkflow.Entities.Retry.t() | nil,
  self_scheduled?: boolean(),
  transition_to: atom() | nil
}
```

# `anchor_field`

```elixir
@spec anchor_field(t()) :: atom()
```

The anchor `fire_after` is measured from, defaulting to `:state_entered_at`.

# `attribute_schema`

# `deadline_field`

```elixir
@spec deadline_field(t()) :: atom()
```

The datetime field this timeout reads: `fire_at` when it is given, otherwise
the `fire_after` anchor.

# `fired_field`

```elixir
@spec fired_field(atom(), t()) :: atom() | nil
```

The column an action timeout writes when it fires, named
`<step>_<timeout>_fired_at`, or `nil` for a transition timeout.

An action timeout does not change state, so this column is the only record
that it fired. A transition timeout leaves the step, which is record enough.

# `validate_duration`

---

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