Strict mode for upsertGraph() #429

upsertGraph() infers what each entry of a graph means: the same { id: 10 } can update, relate, move or keep a row, depending on whether it exists, where it currently is, and option paths like relate: ['pets.siblings']. Rows can appear in several places, key props can contradict relations, and leaving a row out can unrelate or delete it. 4.0 makes the result deterministic, but the rules needed to resolve all of this are hard to predict without reading them.

A strict option would remove the ambiguities at the API level, while keeping the graph shape and the familiar options:

• One place per row. A row appears in one place only; other places refer to it with #ref. A graph that repeats a row throws.
• Key props never compete with relations. A key column that a relation of the same row sets must not be given as a prop, and a key prop that isn't written (e.g. under noUpdate) throws instead of being ignored.
• One option says what happens to rows left out, per relation: missing: { pets: 'keep' | 'unrelate' | 'delete' }, replacing the combinations of unrelate, noDelete and friends. #unrelate and #delete stay for single rows.
• relate takes relation paths only, so every relation that may move rows is named. It stays opt-in: graphs often come from clients, and relating any id they send would be a security risk.

Plan: introduce it as an opt-in option in 4.x, and consider making it the default in a later major. It fits the remaining refactor of the graph writer: loading all rows once, solving one value per key, and ordering the writes by foreign keys.

Each rule is a breaking change for graphs that rely on the current behaviour, so I'll decide them one by one before implementing anything.

Measured on 4.0: the one-place rule on its own, with rows still repeated by id or as #ref, removes no code from the writer, as these places still set the keys that its slots resolve, and it breaks graphs fetched with withGraphFetched() and sent back, which repeat a row with all its props, e.g. the same tag under several movies. The rules only make the writer simpler together: #ref models without data, keys only from relations, and one place per row including repeats by id. Strict mode also needs a way to send fetched graphs back, e.g. by accepting repeats whose data equals the row's place.

Decided:

• A key prop that the graph gives but doesn't write (under noUpdate or noRelate, or at a #ref place of a BelongsToOneRelation) throws an InvalidGraph error when it differs from the stored value. Without strict, it stays ignored.
• A graph that clears a key and uses the same key to place rows elsewhere throws an InvalidGraph error instead of writing a value that depends on which place is read. Done in 4.0 for all graphs, without strict (Write upsertGraph() in one plan, with the relations of moved rows read where they end up #438).