a note about undefined

tl;dr: Dream will throw CannotPassUndefinedAsAValueToAWhereClause at runtime if a key used in a where clause is set to undefined.

undefined poses a special challenge to a Typescript querying API since, to Typescript, setting an object key to undefined is identical to omitting that key. For example:

const { authSystemId } = (await jwtVerify(jwt, jwks, keys))
  .payload as JwtPayload
const user = await User.findBy({ authSystemId })

In this scenario, if the JWT didn't include an authSystemId key, then authSystemId would be undefined, and the findBy would devolve to simply selecting the first User. Obviously not what we want.

In addition to findBy and the where and whereNot methods, where clauses can also be passed to associationQuery, destroyAssociation, and the various methods that accept a chain of association names and where clauses (preload, leftJoinPreload, pluckThrough, min/maxThrough, etc.). So if undefined were allowed, there would be many ways that it could result in non-obvious, unintended behavior, making mistakes more difficult to spot and prevent. When we see a where clause with someKey: someValue in the code, we expect the SQL query to include a restriction on someKey!

To protect against potentially disastrous omission of where clauses, Dream where clauses, in all their forms, will throw CannotPassUndefinedAsAValueToAWhereClause at runtime when a provided key has undefined for its value. Runtime is sub-optimal, but since Typescript considers passing undefined to a key identical to omitting the key altogether, protecting at the typing layer is not possible.