objection 4.0.0-rc.1 → 4.0.0-rc.2

package/lib/queryBuilder/graph/graphKeys.js

@@ -0,0 +1,929 @@
+import { difference, get, jsonEquals, set } from '../../utils/objectUtils.js';
+import { ValidationErrorType } from '../../model/ValidationError.js';
+import { formatPath } from './GraphNode.js';
+
+const UNRESOLVED = Symbol('unresolved');
+
+// Resolve the keys and `#ref{}` values of the models of a planned graph.
+
+// The keys of the rows of a planned graph, as slots: Each place of this pass
+// that puts a row into a relation through a key says that a key column of the
+// row, or of its owner for a BelongsToOne row, equals a column of the other
+// side. These columns form a slot. Its anchors give it its value: the columns
+// that no place of this pass sets, and the values that a node gives whose own
+// place doesn't set them. Anchors have to agree. A slot without any takes the
+// common current value of the rows its places read. Each place writes the
+// columns that it sets, and reads the others, from their slots.
+export class GraphKeys {
+  constructor(plan) {
+    this.plan = plan;
+    this.activeNodes = new Set(plan.activeNodes);
+    this.rows = new Map();
+    this.nodesByRow = new Map();
+    this.cells = new Map();
+    // The props that each node only reads, and that other nodes write:
+    this.readProps = new Map();
+    this.descriptions = new Map();
+    // The columns that each place sets or reads:
+    this.placeCells = new Map();
+    // The rows that this pass inserts, and the ones that it inserted already:
+    this.insertRows = new Set();
+    this.insertedRows = new Set();
+    // The rows that only a later pass inserts:
+    this.laterRows = new Set();
+    // The nodes whose `#ref{}` values are resolved:
+    this.resolvedNodes = new Set();
+
+    // The rows are decided before the inserts give new rows their ids:
+    for (const node of plan.activeNodes) {
+      const row = this._getRow(node);
+
+      if (plan.actions.get(node) === 'insert') {
+        this.insertRows.add(row);
+      }
+    }
+
+    // The columns that a whole `#ref{}` gives the rows at their places, see
+    // `hasWholeReference()`:
+    this.wholeReferences = new Set(
+      plan.activeNodes.flatMap((node) =>
+        node.propertyReferences
+          .filter(({ path }) => hasWholeReference(plan, node, path[0]))
+          .map(({ path }) => this._getPlaceKey(node, path[0])),
+      ),
+    );
+
+    for (const node of plan.deferredNodes) {
+      const row = this._getRow(node);
+
+      if (plan.actionFor(node) === 'insert' && !this.insertRows.has(row)) {
+        this.laterRows.add(row);
+      }
+    }
+
+    // Places that the graph ignores, and many-to-many places, only read:
+    const deferredNodes = new Set(plan.deferredNodes);
+
+    for (const node of [...plan.activeNodes, ...deferredNodes]) {
+      const { parent, relation } = node;
+
+      if (parent && !node.toBeUnrelatedOrDeleted) {
+        const isDeferred = deferredNodes.has(node) && !this._isMovedWithRow(node);
+        const [target, targetProp, source, sourceProp] =
+          relation.keySide === 'related'
+            ? [node, relation.relatedProp, parent, relation.ownerProp]
+            : hasOwnerKey(relation)
+              ? [parent, relation.ownerProp, node, relation.relatedProp]
+              : [];
+
+        if (
+          target &&
+          !isPlacingReference(plan, target) &&
+          (isDeferred || plan.actions.get(node) !== 'ignore')
+        ) {
+          this._addPlace(node, target, targetProp, source, sourceProp, isDeferred);
+        } else if (!isDeferred && (relation.keySide !== 'owner' || hasOwnerKey(relation))) {
+          // Arrays of keys are written by `setKeyArrays()`. Join rows read the
+          // keys of both sides, and wait for them like the other places:
+          const cells = [
+            ...this._addCells(parent, this._getCells(parent, relation.ownerProp)),
+            ...(relation.keySide === 'join'
+              ? this._addCells(node, this._getCells(node, relation.relatedProp))
+              : []),
+          ];
+
+          if (relation.keySide === 'join') {
+            for (const cell of cells) {
+              cell.placeNodes.add(node);
+            }
+          }
+        }
+      }
+    }
+
+    // The key columns that the plan clears in this pass, with the nodes that
+    // clear them: rows that relations leave out, and the keys of removed
+    // BelongsToOne rows. The places of a node read them as `null` if another
+    // node clears them:
+    this.clearingNodes = new Map();
+    const addClearingNode = (row, prop, node) =>
+      prop.props.forEach((_, i) => {
+        const key = this._getKey(row, prop, i);
+        this.clearingNodes.set(key, (this.clearingNodes.get(key) || new Set()).add(node));
+      });
+
+    for (const currentNode of plan.activeCurrentNodes) {
+      const { relation, parent } = currentNode;
+
+      if (relation?.keySide === 'related' && plan.actions.get(currentNode) === 'unrelate') {
+        addClearingNode(currentNode.rowKey, relation.relatedProp, parent.node);
+      }
+    }
+
+    for (const node of plan.activeNodes) {
+      for (const currentChild of node.existing?.activeChildren || []) {
+        const { relation } = currentChild;
+
+        if (
+          hasOwnerKey(relation) &&
+          (node.obj[relation.name] === null || currentChild.node?.toBeUnrelatedOrDeleted) &&
+          plan.actions.get(currentChild) !== 'keep'
+        ) {
+          addClearingNode(this._getRow(node), relation.ownerProp, node);
+        }
+      }
+    }
+
+    this._checkSlots();
+  }
+
+  // Return true if the BelongsToOne row of `node` gives its moved owner a key
+  // that the owner's to-many relations in the graph are keyed on: The move
+  // writes it, as its key is known, so that the later pass reads these
+  // relations at the new key.
+  _isMovedWithRow(node) {
+    const { parent, relation } = node;
+    return (
+      hasOwnerKey(relation) &&
+      this.activeNodes.has(parent) &&
+      node.obj.$hasId() &&
+      !node.toBeUnrelatedOrDeleted &&
+      hasRelationsOnKey(parent, relation.ownerProp)
+    );
+  }
+
+  // Return the nodes whose writes need values that only a later pass gives:
+  // the ones whose places set columns of slots without anchors that a later
+  // pass sets, or with anchors of rows that a later pass inserts, and the ones
+  // with `#ref{}` values of models that a later pass writes. The owners of
+  // BelongsToOne places get their keys patched in there.
+  getLaterNodes() {
+    const { activeNodes, deferredNodes } = this.plan;
+    const nodes = new Set();
+
+    for (const slot of this._getSlots()) {
+      const anchorCells = this._getAnchorCells(slot);
+
+      if (
+        anchorCells.length === 0
+          ? slot.cells.some((cell) => cell.isPending)
+          : anchorCells.some((cell) => this.laterRows.has(cell.row))
+      ) {
+        for (const cell of slot.cells) {
+          for (const node of cell.placeNodes) {
+            nodes.add(node);
+          }
+        }
+      }
+    }
+
+    for (const node of activeNodes) {
+      if (
+        node.propertyReferences.some(
+          (reference) =>
+            deferredNodes.has(reference.referencedNode) && readsWrittenValue(reference),
+        )
+      ) {
+        nodes.add(node);
+      }
+    }
+
+    return [...nodes];
+  }
+
+  // Bind the columns of the rows of the inserted `nodes` to their values.
+  setInserted(nodes) {
+    for (const node of nodes) {
+      this.insertedRows.add(this.rows.get(node));
+    }
+  }
+
+  // Fill the columns that the place of `node` sets or reads with the values of
+  // their slots, as far as they're known.
+  fill(node) {
+    for (const cell of this.placeCells.get(node) || []) {
+      const value = this._getSlotValue(cell);
+
+      // A place that only reads a column that other nodes write leaves the
+      // write to them:
+      if (
+        !cell.setNodes.has(node) &&
+        cell.prop.getProp(node.obj, cell.index) === undefined &&
+        (cell.setNodes.size > 0 ||
+          this._isCleared(cell) ||
+          this._getGivenValues(cell).value !== undefined)
+      ) {
+        let readProps = this.readProps.get(node);
+
+        if (!readProps) {
+          readProps = new Set();
+          this.readProps.set(node, readProps);
+        }
+
+        readProps.add(cell.prop.props[cell.index]);
+      }
+
+      if (value !== undefined) {
+        cell.prop.setProp(node.obj, cell.index, value);
+      }
+    }
+  }
+
+  // Return the props of `node` that the places of its row set.
+  getFilledProps(node) {
+    return [...(this.placeCells.get(node) || [])]
+      .filter(({ setNodes }) => setNodes.size > 0)
+      .map(({ prop, index }) => prop.props[index]);
+  }
+
+  // Return the values of the key columns `prop` of the row of `node`.
+  getProps(node, prop) {
+    return this._getCells(node, prop).map((cell) => this._getSlotValue(cell));
+  }
+
+  // Return true if `node` only reads its key column `prop`, which other nodes
+  // write, so that it leaves the write to them.
+  isOnlyRead(node, prop) {
+    return !!this.readProps.get(node)?.has(prop);
+  }
+
+  // Return true if a place of `node` in this pass sets the key column `prop`
+  // of its row:
+  isSet(node, prop, index) {
+    return !!this.cells.get(this._getKey(this._getRow(node), prop, index))?.setNodes.has(node);
+  }
+
+  // Return the nodes whose inserts or `#ref{}` values bind the slots of the
+  // columns that the place of `node` sets or reads.
+  waitsFor(node) {
+    const waits = [];
+
+    for (const cell of this.placeCells.get(node) || []) {
+      for (const anchorCell of this._getAnchorCells(cell.slot)) {
+        const { row, prop, index } = anchorCell;
+        anchorCell.waitedNodes ??= this.nodesByRow
+          .get(row)
+          .filter(
+            (other) =>
+              (this.insertRows.has(row) && this.plan.actions.get(other) === 'insert') ||
+              this._hasReference(other, prop, index),
+          );
+
+        for (const other of anchorCell.waitedNodes) {
+          if (this.rows.get(other) !== this.rows.get(node)) {
+            waits.push({ node: other, prop: cell.prop.props[cell.index] });
+          }
+        }
+      }
+    }
+
+    return waits;
+  }
+
+  // The place of `node` gives `target` the key of `source`, for each column of
+  // the relation. A place of a later pass only marks the columns it sets there:
+  _addPlace(node, target, targetProp, source, sourceProp, isDeferred) {
+    const targetCells = this._getCells(target, targetProp);
+    const sourceCells = this._getCells(source, sourceProp);
+
+    // A row below itself, e.g. in its own `siblings`, restates its own key and
+    // writes nothing:
+    if (isDeferred) {
+      targetCells.forEach((cell, i) => {
+        cell.isPending ||= cell !== sourceCells[i];
+      });
+    } else if (targetCells.some((cell, i) => cell !== sourceCells[i])) {
+      this._addCells(target, targetCells);
+      this._addCells(source, sourceCells);
+
+      targetCells.forEach((cell, i) => {
+        sourceCells[i].readerNodes.add(source);
+
+        // A whole `#ref{}` value wins over the key of its place, also where the
+        // place lists the row again:
+        if (!this.wholeReferences.has(this._getPlaceKey(target, cell.prop.props[cell.index]))) {
+          cell.setNodes.add(target);
+          cell.placeNodes.add(node);
+          joinCells(cell, sourceCells[i]);
+        }
+      });
+    }
+  }
+
+  // The key of a column of the row of `node` at its place: the row of its
+  // parent and the relation.
+  _getPlaceKey(node, prop) {
+    const { parent, relation } = node;
+    return `${this._getRow(node)}|${parent ? this._getRow(parent) : ''}|${relation?.name}|${prop}`;
+  }
+
+  _addCells(node, cells) {
+    let placeCells = this.placeCells.get(node);
+
+    if (!placeCells) {
+      placeCells = new Set();
+      this.placeCells.set(node, placeCells);
+    }
+
+    for (const cell of cells) {
+      placeCells.add(cell);
+    }
+
+    return cells;
+  }
+
+  _getCells(node, prop) {
+    return prop.props.map((_, i) => this._getCell(node, prop, i));
+  }
+
+  // The row of `node`, also of the owners of a later pass, which earlier
+  // passes wrote:
+  _getRow(node) {
+    let row = this.rows.get(node);
+
+    if (row === undefined) {
+      // A `#ref` model has the row of the model it refers to, and a new model
+      // a row of its own:
+      const { referencedNode } = node;
+      row = referencedNode
+        ? this._getRow(referencedNode)
+        : node.obj.$hasId()
+          ? node.rowKey
+          : `new:${this.rows.size}`;
+      this.rows.set(node, row);
+
+      const nodes = this.nodesByRow.get(row);
+
+      if (nodes) {
+        nodes.push(node);
+      } else {
+        this.nodesByRow.set(row, [node]);
+      }
+    }
+
+    return row;
+  }
+
+  _getKey(row, prop, index) {
+    let descriptions = this.descriptions.get(prop);
+
+    if (!descriptions) {
+      descriptions = prop.props.map((_, i) => prop.propDescription(i));
+      this.descriptions.set(prop, descriptions);
+    }
+
+    return `${row}|${descriptions[index]}`;
+  }
+
+  _getCell(node, prop, index) {
+    const row = this._getRow(node);
+    const key = this._getKey(row, prop, index);
+    let cell = this.cells.get(key);
+
+    if (!cell) {
+      cell = {
+        key,
+        row,
+        node,
+        prop,
+        index,
+        isId: node.modelClass.getIdPropertyArray().includes(prop.props[index]),
+        setNodes: new Set(),
+        placeNodes: new Set(),
+        readerNodes: new Set(),
+        isPending: false,
+        slot: null,
+      };
+      cell.slot = { cells: [cell] };
+      this.cells.set(key, cell);
+    }
+
+    return cell;
+  }
+
+  // The cells that give a slot its value, known once the slots are built: the
+  // ones that no place of this pass sets, unless a place of a later pass sets
+  // them, and the ones that a node gives whose own place doesn't set them.
+  _getAnchorCells(slot) {
+    return (slot.anchorCells ??= slot.cells.filter((cell) =>
+      cell.setNodes.size === 0 ? !cell.isPending : this._getGivenValues(cell).value !== undefined,
+    ));
+  }
+
+  // The values that the nodes of a row give a column that their own places
+  // don't set, as the graph gives them: `value` from any write, `writtenValue`
+  // from a patch or relate. A `#ref{}` is `UNRESOLVED` until it's resolved.
+  _getGivenValues(cell) {
+    if (!cell.givenValues) {
+      const { row, prop, index, setNodes } = cell;
+      const { actions, graphOptions } = this.plan;
+      const givenValues = {};
+
+      for (const node of this.nodesByRow.get(row)) {
+        const action = actions.get(node);
+
+        if (
+          !setNodes.has(node) &&
+          !isPlacingReference(this.plan, node) &&
+          // A whole `#ref{}` doesn't win over the key of another place:
+          !(setNodes.size > 0 && hasWholeReference(this.plan, node, prop.props[index])) &&
+          ['insert', 'patch', 'relate'].includes(action) &&
+          !node.toBeUnrelatedOrDeleted &&
+          (action === 'insert' || graphOptions.shouldPatch(node) || graphOptions.shouldUpdate(node))
+        ) {
+          const value = this._hasReference(node, prop, index)
+            ? UNRESOLVED
+            : (prop.getProp(node.obj, index) ??
+              (node.referencedNode && !setNodes.has(node.referencedNode)
+                ? prop.getProp(node.referencedNode.obj, index)
+                : undefined));
+          if (givenValues.value === undefined) {
+            givenValues.value = value;
+          }
+
+          if (givenValues.writtenValue === undefined && action !== 'insert') {
+            givenValues.writtenValue = value;
+          }
+
+          if (givenValues.writtenValue !== undefined) {
+            break;
+          }
+        }
+      }
+
+      if (givenValues.value === UNRESOLVED || givenValues.writtenValue === UNRESOLVED) {
+        return givenValues;
+      }
+
+      cell.givenValues = givenValues;
+    }
+
+    return cell.givenValues;
+  }
+
+  // Return true if a column of `node` holds a `#ref{}` that isn't resolved yet:
+  _hasReference(node, prop, index) {
+    return (
+      !this.resolvedNodes.has(node) &&
+      node.propertyReferences.some(({ path }) => path[0] === prop.props[index])
+    );
+  }
+
+  // The value of an anchor cell: of a row that this pass inserts once it's
+  // inserted, with `null` for the columns the graph doesn't give, a value that
+  // a patch or relate writes, which wins over the inserted one, an id, or the
+  // current value.
+  _getAnchorValue(cell) {
+    const { row, prop, index } = cell;
+    const nodes = this.nodesByRow.get(row);
+    const [node] = nodes;
+    const getValue = (obj) => (obj ? prop.getProp(obj, index) : undefined);
+    const { writtenValue } = this._getGivenValues(cell);
+
+    if (this.insertRows.has(row)) {
+      const insertNode = nodes.find((node) => this.plan.actions.get(node) === 'insert');
+      return writtenValue ?? getValue(insertNode.obj) ?? null;
+    } else if (writtenValue !== undefined) {
+      return writtenValue;
+    } else if (cell.isId) {
+      return getValue(node.obj) ?? getValue(node.existing?.obj);
+    } else {
+      // A related row that isn't loaded is found by the key that its
+      // BelongsToOne place reads, so that is its key:
+      const relateNode = nodes.find(
+        (node) =>
+          this.plan.actions.get(node) === 'relate' &&
+          hasOwnerKey(node.relation) &&
+          node.relation.relatedProp.props.includes(prop.props[index]),
+      );
+      const currentValue = this._getCurrentValue(cell);
+      return currentValue === undefined && relateNode ? getValue(relateNode.obj) : currentValue;
+    }
+  }
+
+  // Return true if an anchor cell waits for an insert or a `#ref{}` value:
+  _isWaiting(cell) {
+    return (
+      (this.insertRows.has(cell.row) && !this.insertedRows.has(cell.row)) ||
+      this._getGivenValues(cell).writtenValue === UNRESOLVED
+    );
+  }
+
+  // The value of an anchor cell that is known before the writes, as a key to
+  // compare: the given value, or for the id of a new row the row itself, which
+  // differs from all other values.
+  _getKnownKey(cell) {
+    const { row, prop, index } = cell;
+
+    if (this.insertRows.has(row)) {
+      const { value } = this._getGivenValues(cell);
+      return value === UNRESOLVED
+        ? undefined
+        : value !== undefined
+          ? `=${value}`
+          : cell.isId
+            ? row
+            : undefined;
+    } else {
+      const value = this._isWaiting(cell) ? undefined : this._getAnchorValue(cell);
+      return value !== undefined ? `=${value}` : undefined;
+    }
+  }
+
+  // The value of the slot of `cell`, from its anchors, which agree, or without
+  // any, from the current values of the columns its places read. `undefined`
+  // until the inserts and `#ref{}` values that bind it are written.
+  _getSlotValue({ slot }) {
+    if (!('value' in slot)) {
+      const cells = this._getAnchorCells(slot);
+
+      if (cells.length === 0) {
+        // Without anchors, the rows that the places read their keys from give it:
+        slot.value = slot.cells
+          .filter((cell) => cell.readerNodes.size > 0)
+          .map((cell) => this._getCurrentValue(cell))
+          .find((value) => value !== undefined);
+      } else if (!cells.some((cell) => this._isWaiting(cell))) {
+        // Once nothing waits, the value doesn't change anymore:
+        slot.value = cells
+          .map((cell) => this._getAnchorValue(cell))
+          .find((value) => value !== undefined);
+      }
+    }
+
+    return slot.value;
+  }
+
+  // The current value of the column of `cell`: of its current row, or for the
+  // owners from earlier passes, what these passes wrote into their models.
+  _getCurrentValue(cell) {
+    const { row, prop, index } = cell;
+
+    if (this._isCleared(cell)) {
+      return null;
+    }
+
+    for (const node of this.nodesByRow.get(row)) {
+      const value =
+        !this.activeNodes.has(node) && prop.getProp(node.obj, index) !== undefined
+          ? prop.getProp(node.obj, index)
+          : node.existing
+            ? prop.getProp(node.existing.obj, index)
+            : undefined;
+
+      if (value !== undefined) {
+        return value;
+      }
+    }
+  }
+
+  // Return true if another node than the ones that read the column of `cell`
+  // clears it in this pass:
+  _isCleared(cell) {
+    const clearingNodes = this.clearingNodes.get(cell.key);
+    return (cell.isCleared ??=
+      !!clearingNodes && [...clearingNodes].some((node) => !cell.readerNodes.has(node)));
+  }
+
+  _getSlots() {
+    return new Set([...this.cells.values()].map((cell) => cell.slot));
+  }
+
+  // Throw for slots whose anchors, or whose rows without any, give different
+  // values that are known before the writes.
+  _checkSlots() {
+    for (const slot of [...this._getSlots()].filter(({ cells }) => cells.length > 1)) {
+      const anchorCells = this._getAnchorCells(slot);
+      const known = (
+        anchorCells.length > 0
+          ? anchorCells.map((cell) => [cell, this._getKnownKey(cell)])
+          : slot.cells
+              .filter((cell) => cell.readerNodes.size > 0)
+              .map((cell) => [cell, this._getCurrentValue(cell)])
+      ).filter(([, value]) => value !== undefined);
+      const [cell, value] = known[0] || [];
+      const [otherCell] = known.find(([, other]) => String(other) !== String(value)) || [];
+
+      if (otherCell) {
+        // Name the column that the places set, e.g. not the id they read it from:
+        const { prop, index, node } = slot.cells.find((cell) => cell.setNodes.size > 0) || cell;
+        throw node.modelClass.createValidationError({
+          type: ValidationErrorType.InvalidGraph,
+          message: `the graph gives ${prop.props[index]} of one ${node.modelClass.name} two values, at ${formatPath(cell.node.dataPathKey)} and at ${formatPath(otherCell.node.dataPathKey)}`,
+        });
+      }
+    }
+  }
+}
+
+// Join the slots of both cells, moving the cells of the smaller one:
+function joinCells(cell, otherCell) {
+  const [slot, otherSlot] =
+    cell.slot.cells.length >= otherCell.slot.cells.length
+      ? [cell.slot, otherCell.slot]
+      : [otherCell.slot, cell.slot];
+
+  if (slot !== otherSlot) {
+    for (const other of otherSlot.cells) {
+      other.slot = slot;
+      slot.cells.push(other);
+    }
+  }
+}
+
+// Copy the keys and `#ref{}` values that `node` waits for into its model.
+export function resolveDependencies(schedule, node) {
+  for (const dependency of schedule.dependencies.get(node) || []) {
+    if (!schedule.deferredDependencies.has(dependency)) {
+      if (dependency.relation) {
+        // Hooks see the props of the models that `#ref` models refer to:
+        resolveReference(dependency.related);
+        resolveReference(dependency.dependent);
+      } else if (dependency.reference) {
+        resolvePropertyReference(dependency.dependent, dependency.reference);
+      }
+    }
+  }
+
+  schedule.keys.resolvedNodes.add(node);
+  schedule.keys.fill(node);
+}
+
+// Copy the keys and `#ref{}` values that `node` waits for into its model,
+// after those that the graph fills into the models that it reads them from,
+// e.g. the new key of an owner whose BelongsToOne row is replaced. Rows that
+// move first only wait for rows that exist, see `GraphSchedule#_waitsForInserts()`.
+export function resolveFilledDependencies(schedule, node, visitedNodes = new Set()) {
+  visitedNodes.add(node);
+
+  for (const dependency of schedule.dependencies.get(node) || []) {
+    const referencedNode = dependency.node.referencedNode || dependency.node;
+
+    if (
+      !visitedNodes.has(referencedNode) &&
+      (dependency.isKeyWait || schedule.readsFilledProps(dependency))
+    ) {
+      resolveFilledDependencies(schedule, referencedNode, visitedNodes);
+    }
+  }
+
+  resolveDependencies(schedule, node);
+}
+
+// Change the arrays of keys that `node` holds for the relations that the graph
+// gives it: Remove the keys of the current related rows that it deletes or
+// unrelates, and add the keys of the related models that it writes. Other
+// keys stay, e.g. of rows that the relation's filter leaves out. Relations
+// that the graph leaves out keep their arrays (#1202). Return the props that
+// change.
+export function setKeyArrays(plan, node) {
+  const { actions, graphOptions } = plan;
+  const { existing } = node;
+  const props = [];
+
+  for (const name of node.modelClass.getRelationNames()) {
+    const relation = node.obj[name] !== undefined && node.modelClass.getRelation(name);
+
+    if (relation && hasOwnerKeyArray(relation)) {
+      const { ownerProp, relatedProp } = relation;
+      const getKey = (related) => relatedProp.getProp(related.obj, 0);
+      const keys = relation.getKeys(existing ? existing.obj : node.obj);
+      const removed = (existing?.activeChildren || []).filter(
+        (child) =>
+          child.relation.name === name && ['delete', 'unrelate'].includes(actions.get(child)),
+      );
+      const added = node.activeChildren.filter(
+        (child) =>
+          child.relation.name === name &&
+          !child.toBeUnrelatedOrDeleted &&
+          actions.get(child) !== 'ignore',
+      );
+
+      for (const related of added) {
+        resolveReference(related);
+      }
+
+      const newKeys = relation.changeKeys(keys, {
+        add: added.map(getKey),
+        remove: removed.map(getKey),
+      });
+
+      if (!existing || graphOptions.shouldUpdate(node)) {
+        // Inserts and updates write the whole row:
+        ownerProp.setProp(node.obj, 0, newKeys);
+        props.push(ownerProp.props[0]);
+      } else if (!jsonEquals(keys, newKeys)) {
+        const patch = relation.createKeysPatch(existing.obj, newKeys);
+        Object.assign(node.obj, patch);
+        props.push(...Object.keys(patch));
+      }
+    }
+  }
+
+  return props;
+}
+
+// Return the keys of `node` that point to other BelongsToOne rows than before,
+// which the graph inserts or relates, and which `GraphKeys` filled in for the
+// places of this pass.
+export function getChangedKeysOfRelatedRows(plan, keys, node) {
+  const { actions } = plan;
+  const props = [];
+
+  for (const child of node.activeChildren) {
+    const { relation } = child;
+
+    // Ignored models don't replace the current one, and models marked with
+    // `#unrelate` or `#delete` are handled below:
+    if (hasOwnerKey(relation) && actions.get(child) !== 'ignore') {
+      relation.ownerProp.forEach((i) => {
+        const currentValue = node.existing && relation.ownerProp.getProp(node.existing.obj, i);
+        const value = relation.ownerProp.getProp(node.obj, i);
+
+        if (
+          value !== undefined &&
+          currentValue != value &&
+          keys.isSet(node, relation.ownerProp, i)
+        ) {
+          props.push(relation.ownerProp.props[i]);
+        }
+      });
+    }
+  }
+
+  return props;
+}
+
+// Clear the keys of `node` that point to BelongsToOne rows that are removed,
+// and return the props that change.
+export function clearKeysOfRemovedRows(plan, node) {
+  const { actions } = plan;
+  const props = [];
+
+  for (const currentChild of node.existing?.activeChildren || []) {
+    const { relation } = currentChild;
+
+    if (
+      hasOwnerKey(relation) &&
+      (node.obj[relation.name] === null || currentChild.node?.toBeUnrelatedOrDeleted) &&
+      actions.get(currentChild) !== 'keep'
+    ) {
+      relation.ownerProp.forEach((i) => {
+        if (relation.ownerProp.getProp(node.existing.obj, i) != null) {
+          relation.ownerProp.setProp(node.obj, i, null);
+          props.push(relation.ownerProp.props[i]);
+        }
+      });
+    }
+  }
+
+  return props;
+}
+
+// Give a `#ref` model the props of the model it refers to that it doesn't have,
+// and the `filledProps` again, as they may have changed since. Its own keys
+// stay its own, and the join table extras of the place of the model belong to
+// the join row there.
+export function resolveReference(node, filledProps = []) {
+  const { referencedNode, relation } = node;
+
+  if (referencedNode) {
+    const ownKeys = relation?.keySide === 'related' ? relation.relatedProp.props : [];
+    const modelExtras =
+      referencedNode.relation?.keySide === 'join'
+        ? referencedNode.relation.joinTableExtras.map((extra) => extra.aliasProp)
+        : [];
+
+    for (const prop of difference(Object.keys(referencedNode.obj), modelExtras)) {
+      if (
+        !Object.hasOwn(node.obj, prop) ||
+        (filledProps.includes(prop) && !ownKeys.includes(prop))
+      ) {
+        node.obj[prop] = referencedNode.obj[prop];
+      }
+    }
+  }
+}
+
+// Return true if `node` is a `#ref` model in a many-to-many or BelongsToOne
+// relation whose model writes its row, so that it only places the row there,
+// and neither sets nor gives the keys of that row.
+function isPlacingReference(plan, node) {
+  const { referencedNode, relation } = node;
+  return (
+    !!referencedNode &&
+    (relation.keySide === 'join' || hasOwnerKey(relation)) &&
+    plan.isCoveredByModel(node)
+  );
+}
+
+// Return true if `node` gives `prop` a whole `#ref{}` value that wins over the
+// key that its place in its parent sets, or that any place sets when `node` is
+// inserted (Vincit#1378). The column then keeps that value for all its readers.
+function hasWholeReference(plan, node, prop) {
+  return (
+    (plan.actions.get(node) === 'insert' ||
+      (node.relation?.keySide === 'related' && node.relation.relatedProp.props.includes(prop))) &&
+    node.propertyReferences.some(
+      ({ path, isWholeValue }) => isWholeValue && path.length === 1 && path[0] === prop,
+    )
+  );
+}
+
+// Replace a `#ref{}` in a prop of `node` with the value it refers to:
+function resolvePropertyReference(node, { path, match, refPath, isWholeValue, referencedNode }) {
+  const value = get(referencedNode.obj, refPath);
+  set(node.obj, path, isWholeValue ? value : get(node.obj, path).replace(match, value));
+}
+
+// Fetch the keys that the relations of the inserted nodes need, but that the
+// database generated and the insert didn't return, like a uuid that isn't the
+// id (Vincit#853).
+export async function fetchGeneratedKeys(builder, modelClass, nodes) {
+  const keyProps = (node) => [
+    ...(node.relation && node.relation.keySide !== 'related' ? [node.relation.relatedProp] : []),
+    ...node.activeChildren
+      .filter((child) => child.relation.keySide !== 'owner')
+      .map((child) => child.relation.ownerProp),
+  ];
+  const missingNodes = nodes.filter((node) =>
+    keyProps(node).some((prop) => prop.getProps(node.obj).some((value) => value === undefined)),
+  );
+
+  if (missingNodes.length > 0 && missingNodes.every((node) => node.obj.$hasId())) {
+    // SQL Server returns columns selected twice as arrays, so the ids are
+    // part of the set:
+    const columns = new Set([
+      ...modelClass.getIdColumnArray(),
+      ...missingNodes.flatMap((node) => keyProps(node)).flatMap((prop) => prop.cols),
+    ]);
+    const rows = await modelClass
+      .query()
+      .childQueryOf(builder, { fork: true, isInternalQuery: true })
+      .findByIds(missingNodes.map((node) => node.obj.$id()))
+      .select([...columns]);
+    const rowsByKey = new Map(rows.map((row) => [row.$idKey(), row]));
+
+    for (const node of missingNodes) {
+      const row = rowsByKey.get(node.obj.$idKey());
+
+      for (const prop of keyProps(node)) {
+        prop.forEach((i) => {
+          if (prop.getProp(node.obj, i) === undefined) {
+            prop.setProp(node.obj, i, prop.getProp(row, i));
+          }
+        });
+      }
+    }
+  }
+}
+
+// Return true if a `#ref{}` reads a value that only exists once the model it
+// refers to is written: the id of a new model, or another `#ref{}`.
+export function readsWrittenValue({ referencedNode, refPath: [prop] }) {
+  return (
+    (!referencedNode.obj.$hasId() &&
+      referencedNode.modelClass.getIdPropertyArray().includes(prop)) ||
+    referencedNode.propertyReferences.some(({ path }) => path[0] === prop)
+  );
+}
+
+// Return true if the graph gives `node` to-many relations keyed on `prop`, e.g.
+// `siblings` on `ownerId`.
+function hasRelationsOnKey(node, prop) {
+  const { modelClass, obj } = node;
+  return modelClass
+    .getRelationNames()
+    .filter((name) => obj[name] !== undefined)
+    .map((name) => modelClass.getRelation(name))
+    .some((relation) => relation.keySide === 'related' && hasSameColumns(relation.ownerProp, prop));
+}
+
+export function hasOwnerKey(relation) {
+  return relation.keySide === 'owner' && relation.isOneToOne();
+}
+
+function hasOwnerKeyArray(relation) {
+  return relation.keySide === 'owner' && !relation.isOneToOne();
+}
+
+// Return true if both relations keep the keys of their related rows in the same
+// columns, also the same JSON paths of them.
+export function hasSameKey(relation, otherRelation) {
+  const { relatedProp } = relation;
+  const otherProp = otherRelation?.keySide === 'related' ? otherRelation.relatedProp : null;
+  return (
+    !!otherProp &&
+    relation.relatedModelClass.getTableName() === otherRelation.relatedModelClass.getTableName() &&
+    hasSameColumns(relatedProp, otherProp)
+  );
+}
+
+// Return true if both props are the same columns, also the same JSON paths of
+// them.
+export function hasSameColumns(prop, otherProp) {
+  return (
+    prop.size === otherProp.size &&
+    prop.props.every((_, i) => prop.propDescription(i) === otherProp.propDescription(i))
+  );
+}