Absinthe middleware that projects an incoming query's selection set into an exact Repo.preload/2 tree.

Declare it per field, naming the root Ecto schema of the field's return type:

query do
  field :order, :order do
    middleware(AbsintheProjector, schema: MyApp.Order)
    resolve(&Resolvers.order/3)
  end
end

Before the resolver runs, the middleware obtains the projected child fields via Absinthe.Resolution.project/1, feeds them plus the declared schema to AbsintheProjector.Engine.project/2, and stores the resulting nested preload tree in resolution.context[:absinthe_projector]. The resolver then hands that tree to its domain service (via AbsintheProjector.preloads/1):

def order(_parent, %{id: id}, resolution) do
  preloads = AbsintheProjector.preloads(resolution)
  {:ok, Orders.get_order!(id, preloads)}
end

The middleware behaves identically on query and mutation fields, and is idempotent — reapplying it recomputes and overwrites the same context key with the same value.

Pagination envelopes

List/paginated fields whose entities live inside a wrapper (Flop's data, or a multi-level page { entries }) add the opt-in :envelope option so projection starts inside that wrapper instead of at the field root:

field :orders, :order_page do
  middleware(AbsintheProjector, schema: MyApp.Order, envelope: :data)
  resolve(&Resolvers.list_orders/3)
end

:envelope accepts a single atom (:data), a list of atoms ([:page, :entries]) descended in order, or is absent (no envelope — projection from the field root). Only the innermost selection is projected against :schema; sibling fields outside the envelope (meta, total) are never projected, and a query that omits the envelope field stores []. See AbsintheProjector.Envelope for the descent contract. Everything else — context key, tree format, error pass-through, idempotency — is identical to a single-record field.

Validation

The :schema option is validated eagerly and fail-loud at the top of call/2, before any error pass-through, so a static misconfiguration never hides behind an unrelated runtime error:

• omitting :schema raises ArgumentError with the declaration usage;
• passing a module that is not an Ecto schema raises ArgumentError naming the module (delegated to AbsintheProjector.Introspection, the single validation point);
• an :envelope value that is neither an atom, nil, nor a list of atoms raises ArgumentError naming the received value, so a mistyped envelope path never silently degrades to an empty preload tree.

Error pass-through

When the incoming resolution already carries errors (resolution.errors != []), the middleware is a strict pass-through: it returns the resolution unchanged, with no projection and no context write, so upstream failures are never masked or reordered.

Empty result

When the selection contains no associations, the stored tree is [] (never nil), so a downstream Repo.preload/2 is always a safe no-op.