# `NeoFaker.Date`
[🔗](https://github.com/muzhawir/neo_faker/blob/main/lib/neo_faker/date.ex#L1)

Functions for generating random dates.

Provides utilities to generate random dates, including dates relative to today,
dates within a custom range, birthdays, and past and future dates. Every function
returns a `Date` struct; call `Date.to_iso8601/1` yourself if you need a string.

# `add`
*since 0.9.0* 

```elixir
@spec add(Range.t()) :: Date.t()
```

Generates a random date within a specified range relative to today.

By default, returns a date between 365 days before and 365 days after the current date.
`range` specifies the number of days to add or subtract from today.

## Examples

    iex> NeoFaker.Date.add()
    ~D[2025-03-25]

    iex> NeoFaker.Date.add(0..31)
    ~D[2025-03-30]

# `between`
*since 0.9.0* 

```elixir
@spec between(Date.t(), Date.t()) :: Date.t()
```

Generates a random date between two given dates.

Both `start` and `finish` are inclusive. Defaults to a date between the Unix
epoch (`~D[1970-01-01]`) and today.

## Examples

    iex> NeoFaker.Date.between()
    ~D[2025-03-25]

    iex> NeoFaker.Date.between(~D[2020-01-01], ~D[2025-01-01])
    ~D[2022-08-17]

# `birthday`
*since 0.10.0* 

```elixir
@spec birthday(non_neg_integer(), non_neg_integer()) :: Date.t()
```

Generates a random birthday within the specified age range.

Calculates the valid date window from the current date and `min_age`/`max_age` (defaulting
to `18` and `65` respectively), then returns a random date within that window.

## Examples

    iex> NeoFaker.Date.birthday()
    ~D[1997-01-02]

    iex> NeoFaker.Date.birthday(18, 65)
    ~D[1998-03-04]

# `future`
*since 0.9.0* 

```elixir
@spec future(pos_integer()) :: Date.t()
```

Generates a random date in the future.

Returns a random date between today and `days` from now (defaults to `365`). Equivalent to
`add(0..days)`.

## Examples

    iex> NeoFaker.Date.future(30)
    ~D[2025-04-24]

# `past`
*since 0.9.0* 

```elixir
@spec past(pos_integer()) :: Date.t()
```

Generates a random date in the past.

Returns a random date between `days` ago (defaults to `365`) and today. Equivalent to
`add(-days..0)`.

## Examples

    iex> NeoFaker.Date.past(30)
    ~D[2025-02-25]

# `today`
*since 0.9.0* 

```elixir
@spec today() :: Date.t()
```

Returns today's local date.

A convenience wrapper that always returns the current date without any randomisation.

## Examples

    iex> NeoFaker.Date.today()
    ~D[2025-03-25]

---

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