# `Macaw.Data.Delivery`
[🔗](https://github.com/dcoai/macaw_data/blob/v0.5.3/lib/macaw/data/delivery.ex#L1)

One answer of a source: its rows, as a table, and what it actually served (spec/01 §3).

A delivery is a handful of terms beside its table, never per row:

- `table`: the rows, a `Macaw.Data.Table`. `new/2` reads any source shape into one at
  the edge, so a gap stays `nil`: **absence is never zero**.
- `schema`: the **version** of the schema the rows were produced under
  (`Macaw.Data.Schema.version/1`), never the schema itself, which
  `Macaw.Data.Schema.Cache` holds by version; `nil` when the source has none.
- `served`: what this answer served, which may differ from what was asked:
  - `window`: a range `[from, to]`, a box over a `:point` window field
    `%{west: w, south: s, east: e, north: n}`, or `nil`;
  - `resolution`: the spacing of the rows as served (seconds, or a name such as
    `:minute`), or `nil`;
  - `capped`: whether the source stopped short of the window it was asked for;
  - `reduced_by`: who brought the rows within budget, `:source` or `:runtime`, or `nil`
    when nobody had to;
  - `params`: the parameters it was answered for, a map;
  - `note`: a line for a person (`"coarsened from raw"`), or `nil`.
- `origin`: where it came from, `%{source: name, request: digest, as_of: time | nil}`,
  or `nil`.

The shape of visualize's `Visualize.Data.Delivery`, whose facts are flat and whose
`reduced_by` is `:feed` or `:visualize`, is spec/01 §3's here.

## Examples

    iex> alias Macaw.Data.{Delivery, Table}
    iex> d = Delivery.new(%{t: [1, 2], v: [3, nil]}, served: [window: [0, 10]], schema: "ab12")
    iex> Table.rows(d.table)
    [%{t: 1, v: 3}, %{t: 2, v: nil}]
    iex> {d.served.window, d.served.capped, d.served.reduced_by}
    {[0, 10], false, nil}

# `origin`

```elixir
@type origin() ::
  %{source: term(), request: String.t(), as_of: DateTime.t() | nil} | nil
```

Where an answer came from.

# `served`

```elixir
@type served() :: %{
  window: window(),
  resolution: term(),
  capped: boolean(),
  reduced_by: :source | :runtime | nil,
  params: map(),
  note: String.t() | nil
}
```

What one answer served (spec/01 §3).

# `t`

```elixir
@type t() :: %Macaw.Data.Delivery{
  origin: origin(),
  schema: String.t() | nil,
  served: served(),
  table: Macaw.Data.Table.t()
}
```

# `window`

```elixir
@type window() ::
  [term()]
  | %{west: number(), south: number(), east: number(), north: number()}
  | nil
```

A window as served: a range, a box over positions, or none.

# `new`

```elixir
@spec new(Macaw.Data.Table.source() | Macaw.Data.Table.t(), keyword()) :: t()
```

A delivery of `rows`, any source `Macaw.Data.Table.from/2` reads (a table passes as it
is), with `served:` (a keyword list or map of the served facts), `schema:` (a version)
and `origin:`. `types:` is passed to `Table.from/2`.

Raises `ArgumentError` naming the fault: a key that is not a delivery's or a served
fact, a value a field does not take, or rows no table reads.

# `rows`

```elixir
@spec rows(t()) :: [map()]
```

The rows a delivery carries, one map per row (`Macaw.Data.Table.rows/1`).

---

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