feat!: relation chains through hasMany, semi-join filters, strict errors

[fratzinger]

Relation paths may mix belongsTo and hasMany hops in any order and to any depth, every relation filter compiles to a correlated EXISTS (a semi-join), and sorting goes through an aggregate rather than a join that can duplicate rows.

await app.service('assignment-events').find({
  query: {
    assignment: {
      assignmentCategories: { $some: { typeId: { $in: ids } } },
    },
  },
})

select "assignment_events".* from "assignment_events"
where exists (
  select 1 from "assignments" as "assignment"
  where "assignment"."id" = "assignment_events"."assignmentId"
    and exists (
      select 1 from "assignment_categories" as "assignment__assignmentCategories"
      where "assignment__assignmentCategories"."assignmentId" = "assignment"."id"
        and "assignment__assignmentCategories"."typeId" in (?)
    )
)

A belongsTo inside $some / $none / $every resolves in the related service's own scope, so 'assignment.assignmentCategories.type.name' works too.

Breaking changes

Unresolvable filters and sorts are rejected

A filter the adapter could not resolve used to be dropped from the WHERE clause. That widens the result set, which is how an authorization filter built by a hook turns into a data leak — the same reasoning already applied to $or: []. It was also inconsistent: an unknown column raises a database error and an unknown operator a BadRequest, while an unknown relation path returned every row. Now rejected:

• a collection operator on anything but a hasMany relation
• a path that starts at a declared relation but breaks further along (typo, missing target service, or a chain that cannot be walked because app.setup() never ran)
• a dot path inside a hasMany sub-filter that is neither a relation of the related service nor one of its own columns
• the same for $sort, plus a hasMany reached through another relation (unsupported)

Still quiet, because neither can be proven wrong: a dot path whose first segment is not a declared relation (indistinguishable from a qualified column ref or JSON access), and an empty condition object, which is a no-op like $not: {}.

Relation filters no longer join

A belongsTo hop used to be a LEFT JOIN plus a null-protect predicate. That broke in three places, all from the same choice:

• $not with a relation path emitted a ref to a table that was never joined — the JOIN pass descended into $and/$or but not $not. Even with the JOIN registered, the null-protect would have ended up inside the negation.
• patch and remove failed the same way on postgres and sqlite: UPDATE/DELETE take no portable JOIN, so that branch never ran the JOIN pass. (The mysql branch resolves ids with a find first and was unaffected.)
• A relation declared asArray: false on a non-unique column multiplied parent rows — two rows came back as four, with total reporting four.

A semi-join cannot duplicate rows, needs no null-protect, and stays correct under negation and in UPDATE/DELETE. $none semantics behind a belongsTo are unchanged (a missing parent excludes the row), now because the outer EXISTS is false.

Sorting goes through an aggregate

Filters stopped duplicating; sorting still did, because sorting needs the related value and not just its existence. asArray: false is intent, not a guarantee, so a to-one hop is now joined only when the adapter can prove it matches at most one row — keyThere is the target service's id, which is how belongsTo is declared in practice and needs no promise from the caller. Anything else, and every to-many hop, takes the ordering value from a GROUP BY derived table keyed on the join column: exactly one row per key by construction.

That makes it the mechanism for both sort paths, replacing the correlated aggregate the hasMany sort evaluated once per candidate row.

Performance

Measured with the benchmark below, same harness, only src/adapter.ts swapped. Noise floor established by running the same code twice: median 3.8%, max 8.4%.

Filters (JOIN → semi-join): 16 of 19 comparable cases inside the noise floor. Two moved:

case	JOIN	EXISTS
$or over two relation legs	1.774 ms	1.035 ms	−41.6%
filter and sort on the same relation	0.319 ms	0.359 ms	+12.6%

$or gets faster because the EXISTS form lets postgres decorrelate both legs into hashed subplans built once (540 → 56 buffer hits); JOIN + OR forces a nested loop re-evaluating the correlated subplan per row. The slower case reads assignments twice — once for the sort's join, once for the filter's subquery — where one join used to serve both.

Sorting (correlated aggregate → derived table):

case	before	after
$sort by hasMany column	221.8 ms	1.3 ms	−99.4%

Buffer hits on postgres: 49,513 → 46. Every other case stayed inside the noise floor.

Regression guards

test/sql-shape.test.ts snapshots the compiled SQL and parameters for 20 relation cases. Kysely compiles without a database, so it runs in the normal suite with no schema and no data, pinned to sqlite regardless of DB — the subject is our own output, not per-dialect syntax.

bench/relations.bench.ts executes the same cases against a seeded database (~11k rows, fixed PRNG seed, secondary indexes off by default because that is where the SQL shape decides the plan):

pnpm bench --outputJson=bench/baseline.json   # reference commit
pnpm bench --compare=bench/baseline.json      # after the change

test/query-costs.test.ts reports blocks touched, rows returned and the plan spine per case from EXPLAIN (ANALYZE, BUFFERS). Deterministic where timings are not, and the row count doubles as a correctness signal. Postgres only, opt-in via BENCH_COSTS.

Details and traps in bench/README.md.

Deliberate choices

• Dot notation implies $some at every hasMany hop. $none / $every stay nested-notation only — not expressible in a path.
• JSON traversal does not apply inside $some / $none / $every: column types come from the queried service's own properties, so a dot path in a sub-filter is a relation path, and now raises a BadRequest instead of emitting a ref to the outer table.
• A hasMany reached through another relation cannot be sorted by. Rejected explicitly rather than emitting broken SQL.

Testing

795 tests pass against postgres, 672 against sqlite, typecheck clean, lint warnings at baseline. New tests cover mixed chains in both notations, $none with an orphan parent, belongsTo inside $some, nested hasMany alias namespacing, three chained hasMany hops, $not over relation paths, patch/remove by relation filters including a self-referencing one, non-duplication for both filters and sorts on a non-unique to-one, the aggregate direction for a non-unique sort, and every rejection case.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@fratzinger/feathers-kysely@37

commit: 2d45b5e

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	feathers-kysely	2d45b5e	Commit Preview URL Branch Preview URL	Sep 02 2026, 08:52 AM