# `Oban.Period`
[🔗](https://github.com/oban-bg/oban/blob/v2.24.2/lib/oban/period.ex#L1)

Periods represent durations of time as either raw seconds or a unit tuple.

All periods are normalized to seconds internally. The tuple format provides a more expressive
way to specify durations in larger units:

    # Raw seconds
    60

    # Unit tuple
    {1, :minute}
    {5, :minutes}
    {2, :hours}

Supported time units are `:second`, `:minute`, `:hour`, `:day`, `:week`, `:month`, and a plural
variant of each.

# `t`
*since 2.20.0* 

```elixir
@type t() :: pos_integer() | {pos_integer(), time_unit()}
```

A time duration as seconds or a unit tuple.

# `time_unit`
*since 2.20.0* 

```elixir
@type time_unit() ::
  :second
  | :seconds
  | :minute
  | :minutes
  | :hour
  | :hours
  | :day
  | :days
  | :week
  | :weeks
  | :month
  | :months
```

Supported time units for period tuples.

Both singular and plural forms are accepted, e.g. `:minute` and `:minutes`.

# `is_seconds`
*since 2.20.0* *macro* 

Checks whether the given value is a non-negative integer suitable for seconds.

# `is_valid_period`
*since 2.20.0* *macro* 

Checks whether the given value is a valid period, either seconds or a unit tuple.

# `to_milliseconds`
*since 2.20.0* 

```elixir
@spec to_milliseconds(t()) :: pos_integer()
```

Convert a period to milliseconds.

Unlike `to_seconds/1`, a bare integer is considered milliseconds and returned unchanged; only
unit tuples are expanded.

## Examples

    iex> Oban.Period.to_milliseconds(1000)
    1000

    iex> Oban.Period.to_milliseconds({1, :second})
    1000

    iex> Oban.Period.to_milliseconds({2, :minutes})
    120_000

# `to_seconds`
*since 2.20.0* 

```elixir
@spec to_seconds(t()) :: pos_integer()
```

Convert a period to seconds.

## Examples

    iex> Oban.Period.to_seconds(60)
    60

    iex> Oban.Period.to_seconds({1, :minute})
    60

    iex> Oban.Period.to_seconds({2, :hours})
    7200