filter

type Error struct {
	Param   string   `json:"param"`
	Value   string   `json:"value,omitempty"`
	Reason  string   `json:"reason"`
	Allowed []string `json:"allowed,omitempty"`
}

type Errors []*Error

type Node struct {
	Op       string `json:"op"`
	Children []Node `json:"children,omitempty"`
	Field    string `json:"field,omitempty"`
	Value    any    `json:"value,omitempty"`
}

type Options struct {
	// Model supplies the columns and their capabilities. Required.
	Model *sqlb.Model

	DefaultPageSize int
	// MaxFilters bounds the number of leaf conditions a request may ask for,
	// counting the ones inside `or=`/`and=` groups. Counting top-level
	// parameters instead would leave the budget open to a single group holding
	// as many conditions as the client cared to write.
	MaxFilters   int
	MaxPageSize  int
	MaxSortTerms int
	// MaxListValues bounds one `in`/`nin` list; MaxValueLength bounds one
	// filter value or search term.
	MaxListValues  int
	MaxValueLength int
	// MaxOffset bounds how deep ?page= and ?offset= may reach. A request past
	// it is refused with a message pointing at ?cursor=, which has no such
	// cost.
	MaxOffset int

	// Expandable lists the relation names ?expand may name. Parsing validates
	// against it and Apply performs the join, so a parsed ?expand is never
	// silently dropped: a name that is not here is a 400 listing the ones that
	// are.
	//
	// The rest package validates these against the model at startup, so a
	// relation that cannot be expanded is a mounting error rather than a
	// request-time surprise.
	Expandable []string

	// Computed lists the computed columns this resource is willing to pay for.
	// Empty means none, and none is the default on purpose.
	//
	// A computed column is declared on the model, which is shared, and wanted
	// by one screen. Projecting every declared one attached a correlated
	// subquery per column to every read of the model, and a column carrying a
	// Needs bind made unrelated reads fail outright (#92). So declaring stays
	// global — the expression, its type, its binds — and *selecting* is per
	// resource, beside the other things a mount already decides.
	//
	// A column not listed here is not reachable from this resource at all: not
	// projected, not filterable, not sortable, and not nameable in ?select.
	// Being unreachable rather than merely unprojected is what keeps the cost
	// opt-in, since a filter on a correlated subquery costs what the projection
	// would have.
	Computed []string

	// Columns narrows this resource to the columns it names. Empty means every
	// column the model has, which is the default and what almost every resource
	// wants.
	//
	// It is the same per-resource reachability Computed has, generalised to
	// stored columns, and it is here because a model is shared in the other
	// direction too: one table, two surfaces, and the privileged one is the
	// reason the sensitive column exists (#148). A public catalogue and an
	// admin panel over the same products differ in which columns each may see,
	// and Hidden cannot say that — Hidden is a property of the model, and there
	// is one model.
	//
	// A column not listed is not reachable from this resource at all: not
	// projected, not filterable, not sortable, not nameable in ?select, not
	// searched by ?search, and not named in the list a rejection offers. That
	// last one matters — a narrowed resource that advertised the column it is
	// about to refuse would leak the schema it was narrowed to hide.
	//
	// Names are column names, as Computed's are. The rest package checks them
	// against the model at startup, where a typo is a resource missing a column
	// rather than a request-time surprise.
	Columns []string

	// DisableSearch rejects ?search even when columns are searchable.
	DisableSearch bool
}

type Query struct {
	Where  []sqlb.Pred
	Order  []sqlb.Order
	Select []string
	Expand []string
	Search string

	Page     int
	PageSize int
	Limit    int
	Offset   int

	// Computed names the computed columns this resource selects, copied from
	// Options so that Apply projects exactly what parsing validated against.
	Computed []string

	// Columns is the resource's surface, copied from Options for the same
	// reason: the default projection is built in Apply, and a narrowed resource
	// whose parser refused a column while its projection selected it anyway
	// would read the value out of the database on every request and drop it on
	// the way out — which is a narrowing in the response only, and not the one
	// Options.Columns describes.
	Columns []string

	// Cursor is the keyset position `?cursor=` asked to resume from, empty for
	// the first page. It is the alternative to Page and Offset rather than an
	// addition to them: a request carrying both is refused, since the two
	// answer the same question with different answers.
	Cursor sqlb.Cursor
}