fix: refuse filters and sorts that cannot be compiled to SQL

[Helveg]

Three ways to ask for something the database cannot do. Each reached the database and failed there, instead of being answered.

Fixes #1111
Fixes #1109

1. $eq bypassed the operator allowlist (#1111)

filterableColumns: { age: [FilterOperator.GT] }   // filter.age=5 was accepted anyway

A column could not be narrowed to the operators it actually supports. The README promises to reject "a non-whitelisted filter operator/suffix"; that did not hold for the one operator every filter defaults to.

It is also how #1109 happens: filterableColumns: { list: [CONTAINS] } still lets $eq:1 through to an int[] column, which dies as malformed array literal. Refusing the operator refuses the 500.

$eq cannot simply be required, though — it is the operator a suffix negates and a quantifier quantifies, and it is implicit:

filterableColumns: { name: [FilterSuffix.NOT] }                 // $not:John  -> names no operator
filterableColumns: { 'home.pillows': [FilterQuantifier.NONE] }  // $none:red  -> names no operator

Requiring EQ in the list would make [FilterSuffix.NOT] and [FilterQuantifier.NONE] undeclarable. So: a whitelisted modifier licenses the $eq it modifies — $not:John and $not:$eq:John alike — and licenses nothing else. A standalone $eq, bare or spelled out, must be whitelisted like any other operator.

2. A value filter on a top-level json column emitted invalid SQL

operator does not exist: json = unknown

To be clear about what is already there: json is cast to jsonb today. JsonContains emits <col>::jsonb @> :value, exactly as JSON_COLUMN_TYPES documents. But it is only reached for a column resolveJsonbPath recognises, and that function returns early on a single-segment name:

const parts = column.split('.')
// A plain column name without dots is not a JSONB path — callers use checkIsJsonb directly.
if (parts.length < 2) {
    return notJsonb
}

So a key path (metadataJson.length) and a relation-prefixed column (underCoat.metadataJson) are both cast, and both work. A top-level metadataJson is not: it falls through to a plain Equal() → col = :v → the error above. Sorting it fails the same way (could not identify an ordering operator for type json).

Widening that early return so a top-level JSON column is recognised would route it through JsonContains and fix the crash. It would also change what $eq means on a top-level bare jsonb column — from equality (=, what it does today) to containment (@>, what underCoat.metadata does today). That divergence is worth resolving, but not silently, inside this PR.

So this PR takes the narrow option and refuses a value filter on the column itself. Its contents are still reached through a key path, and its emptiness through $null. Whole-document equality is also not something $in/$btw can spell — their values are comma-separated, and a JSON document contains commas.

3. Sorting by a column that names no single value emitted invalid SQL

column distinctAlias.__root_childId does not exist      -- a relation
could not identify an ordering operator for type json   -- a json column

A path that ends on a relation has no value of its own, so it is dropped like any other unsortable column and falls back to defaultSortBy.

A json column does name a value — Postgres just cannot order it, while jsonb has a total order and the cast between them is exact. So it is ordered as jsonb, and sorts like the jsonb column beside it.

Ordering through a to-many (toys.id) names a value and is unaffected — covered by a test.

Tests

Each behaviour is covered: the allowlist rule and the $not/$none idioms it must keep working; the #1109 array case; the json column as filter target and as sort target, against its jsonb twin; and the relation-terminated sort.

Green on sqlite (350), postgres (381) and mariadb (348). The one failing Postgres test is the pre-existing virtual-column sort tie, which fails identically on an untouched master and is fixed by #1158.

🤖 Generated with Claude Code