objection 3.9.1 → 4.0.0-rc.2

package/lib/queryBuilder/graph/GraphUpsert.js

@@ -1,30 +1,27 @@
-'use strict';
-
-const { ModelGraph } = require('../../model/graph/ModelGraph');
-const { ModelGraphEdge } = require('../../model/graph/ModelGraphEdge');
-const { createNotModelError } = require('../../model/graph/ModelGraphBuilder');
-const { GraphFetcher } = require('../graph/GraphFetcher');
-const { GraphInsert } = require('./insert/GraphInsert');
-const { GraphPatch } = require('./patch/GraphPatch');
-const { GraphDelete, GraphDereferencedBelongsToOneDelete } = require('./delete/GraphDelete');
-const { GraphRecursiveUpsert } = require('./recursiveUpsert/GraphRecursiveUpsert');
-const { GraphOptions, OPTION_NAMES } = require('./GraphOptions');
-const { ValidationErrorType } = require('../../model/ValidationError');
-const { RelationExpression } = require('../RelationExpression');
-const { GraphNodeDbExistence } = require('./GraphNodeDbExistence');
-const { GraphData } = require('./GraphData');
-const { uniqBy, asArray, isObject } = require('../../utils/objectUtils');
-const { warnOnce } = require('../../utils/warnings');
-
-class GraphUpsert {
+import { GraphNode, createNotModelError, formatPath } from './GraphNode.js';
+import { GraphOptions } from './GraphOptions.js';
+import { GraphPlan } from './GraphPlan.js';
+import { GraphKeys, hasSameColumns, readsWrittenValue } from './graphKeys.js';
+import { GraphSchedule } from './GraphSchedule.js';
+import { GraphWriter } from './GraphWriter.js';
+import { loadCurrentGraph } from './GraphLoader.js';
+import { ValidationErrorType } from '../../model/ValidationError.js';
+import { RelationExpression } from '../RelationExpression.js';
+import { asArray, isObject, nonStrictEquals } from '../../utils/objectUtils.js';
+import { isInternalProp } from '../../utils/internalPropUtils.js';
+
+export class GraphUpsert {
   constructor({ rootModelClass, objects, upsertOptions, insertOnly = false }) {
-    checkCanBeConvertedToModels(rootModelClass, objects);
-    warnOnUnknownOptions(upsertOptions);
+    // Wrap `undefined` too, so that it fails the check:
+    for (const obj of Array.isArray(objects) ? objects : [objects]) {
+      if (!isObject(obj)) {
+        throw createNotModelError(rootModelClass, obj);
+      }
+    }
 
     this.objects = rootModelClass.ensureModelArray(objects, GraphUpsert.modelOptions);
     this.isArray = Array.isArray(objects);
-    this.upsertOpt = upsertOptions;
-    this.insertOnly = insertOnly;
+    this.graphOptions = new GraphOptions(upsertOptions, insertOnly);
   }
 
   static get modelOptions() {
@@ -36,482 +33,592 @@ class GraphUpsert {
   // to. Even applying it to the root table only would be unsound: rows skipped
   // by `ignore()` aren't returned, which leaves the root models without ids,
   // so that related rows would be inserted with missing or wrong foreign keys.
-  // The clause is ignored, and a warning is logged once per method.
-  // TODO: Throw an error instead in objection 4.0 (#53).
-  static warnOnConflict(builder, method) {
+  static checkForOnConflict(builder, method) {
     if (builder.has(isOnConflictOperation)) {
-      warnOnce(
+      throw new Error(
         `onConflict(), ignore() and merge() are not supported by ${method}(). ` +
-          'Insert the conflicting rows with a separate insert() query instead. ' +
-          'This will throw in objection 4.0.',
+          'Insert the conflicting rows with a separate insert() query instead.',
       );
     }
   }
 
-  run(builder) {
-    const modelClass = builder.modelClass();
-    const graphOptions = new GraphOptions(this.upsertOpt, [], this.insertOnly);
-
-    const graph = ModelGraph.create(modelClass, this.objects);
-    assignDbRefsAsRelateProps(graph);
+  async run(builder) {
+    const { graphOptions } = this;
+    const nodes = GraphNode.buildGraph(builder.modelClass(), this.roots);
+    GraphNode.linkReferences(nodes);
+    const restoreMarkers = GraphNode.removeMarkers(nodes);
+
+    // A `#ref` to a model with an id is that model, also when its relations
+    // are loaded and upserted. Models inserted in a pass have their ids in the
+    // next ones:
+    const identifyReferences = (nodes) => {
+      for (const { obj, referencedNode } of nodes) {
+        if (referencedNode?.obj.$hasId() && !obj.$hasId()) {
+          obj.$id(referencedNode.obj.$id());
+        }
+      }
+    };
 
-    return createGraphData(builder, graphOptions, graph)
-      .then(checkForErrors(builder))
-      .then(pruneGraphs())
-      .then(checkForJoinTableRelatedTableErrors(builder))
-      .then(executeOperations(builder))
-      .then(removeReferenceProps(graph.nodes))
-      .then(returnResult(this.objects, this.isArray));
-  }
-}
+    for (const node of nodes) {
+      if (node.parent && node.isDbReference) {
+        node.relation.setRelateProp(node.obj, asArray(node.dbReference));
+      }
+    }
 
-// Misspelled options are silently ignored, so the operation runs with the
-// default behaviour instead (#84). A warning is logged once per option.
-// TODO: Throw an error instead in objection 4.0 (#53).
-function warnOnUnknownOptions(upsertOptions) {
-  // Recursive upserts pass on the already checked options of their parent.
-  if (upsertOptions instanceof GraphOptions) {
-    return;
-  }
+    identifyReferences(nodes);
+
+    try {
+      checkGraph(builder, new GraphPlan({ nodes, graphOptions }));
+      checkPlacements(builder, nodes);
+      checkReferenceCycles(nodes);
+      const writtenNodes = new Set();
+      let keptNodes = new Map();
+      let laterNodes = new Set();
+
+      // Rows that the graph relates into a HasManyRelation or HasOneRelation
+      // and gives relations are moved first, and their relations are upserted
+      // in another pass, against their rows as they are after the move (#214).
+      for (let passNodes = nodes; passNodes.length > 0;) {
+        const plan = new GraphPlan({
+          nodes: passNodes,
+          graphOptions,
+          keptNodes,
+          laterNodes,
+        });
+        const movedNodes = graphOptions.isInsertOnly() ? [] : await loadCurrentGraph(builder, plan);
+
+        plan.defer(movedNodes.flatMap((node) => node.descendants));
+        plan.cacheDecisions();
+        checkMissingModels(builder, plan);
+        plan.prune().plan();
+        checkChangedIds(builder, plan);
+        const [nextLaterNodes, keys] = deferLaterNodes(plan);
+
+        // A pass that only leaves its writes to the next one waits for itself:
+        if (plan.activeNodes.length === 0) {
+          throw new Error('the object graph contains cyclic references');
+        }
 
-  for (const name of Object.keys(upsertOptions)) {
-    if (!OPTION_NAMES.includes(name)) {
-      warnOnce(
-        `Unknown graph option "${name}" is ignored. ` +
-          `Valid options are: ${OPTION_NAMES.join(', ')}. This will throw in objection 4.0.`,
-      );
-    }
-  }
-}
+        // Models that `noInsert` or `noRelate` ignore aren't written, but the
+        // ones marked with `#delete` or `#unrelate` keep their values:
+        for (const node of plan.activeNodes) {
+          if (plan.actions.get(node) !== 'ignore' || node.toBeUnrelatedOrDeleted) {
+            writtenNodes.add(node);
+          }
+        }
 
-function checkCanBeConvertedToModels(modelClass, objects) {
-  asArray(objects).forEach((obj) => {
-    if (!isObject(obj)) {
-      throw createNotModelError(modelClass, obj);
-    }
-  });
-}
+        checkReferences(builder, plan, writtenNodes);
+        checkJoinTables(builder, plan);
+        await new GraphWriter(new GraphSchedule(plan, keys)).write(builder);
+        keptNodes = plan.getNextKeptNodes();
 
-function assignDbRefsAsRelateProps(graph) {
-  for (const node of graph.nodes) {
-    if (!node.parentEdge || !node.parentEdge.relation || !node.isDbReference) {
-      continue;
+        // Moved rows may also wait for a later pass:
+        passNodes = [
+          ...new Set(
+            [...movedNodes, ...nextLaterNodes].flatMap((node) => [node, ...node.descendants]),
+          ),
+        ];
+        laterNodes = new Set(nextLaterNodes);
+        identifyReferences(passNodes);
+      }
+    } catch (err) {
+      // The input can be retried as it was:
+      restoreMarkers();
+      throw err;
     }
 
-    node.parentEdge.relation.setRelateProp(node.obj, asArray(node.dbReference));
+    return this.roots;
   }
-}
-
-async function createGraphData(builder, graphOptions, graph) {
-  const currentGraph = await fetchCurrentGraph(builder, graphOptions, graph);
 
-  const nodeDbExistence = await GraphNodeDbExistence.create({
-    builder,
-    graph,
-    graphOptions,
-    currentGraph,
-  });
-
-  return new GraphData({ graph, currentGraph, graphOptions, nodeDbExistence });
-}
-
-function fetchCurrentGraph(builder, graphOptions, graph) {
-  if (graphOptions.isInsertOnly()) {
-    return Promise.resolve(ModelGraph.createEmpty());
-  } else {
-    return GraphFetcher.fetchCurrentGraph({ builder, graph, graphOptions });
+  get roots() {
+    return this.isArray ? this.objects : this.objects[0];
   }
 }
 
-// Remove branches from the graph that require no operations. For example
-// we never want to do anything for descendant nodes of a node that is
-// deleted or unrelated. We never delete recursively.
-function pruneGraphs() {
-  return (graphData) => {
-    pruneRelatedBranches(graphData);
-    pruneSkippedBranches(graphData);
-
-    if (!graphData.graphOptions.isInsertOnly()) {
-      pruneDeletedBranches(graphData);
-      pruneUnrelatedOrDeletedBranches(graphData);
-    }
-
-    return graphData;
-  };
-}
-
-function pruneRelatedBranches(graphData) {
-  const relateNodes = graphData.graph.nodes.filter((node) => {
-    return (
-      !graphData.currentGraph.nodeForNode(node) &&
-      !graphData.graphOptions.shouldInsertIgnoreDisable(node, graphData)
-    );
-  });
-
-  removeBranchesFromGraph(findRoots(relateNodes), graphData.graph);
-}
-
-// Nothing is written below nodes that `noInsert` skips, as their descendants
-// would be orphans (#215). Branches that references from outside point into
-// are kept, since the references need their models.
-function pruneSkippedBranches(graphData) {
-  const { graph, graphOptions } = graphData;
-
-  const skippedNodes = graph.nodes.filter((node) => {
-    return (
-      graphOptions.shouldInsertIgnoreDisable(node, graphData) &&
-      !graphOptions.shouldInsert(node, graphData) &&
-      !isReferencedFromOutside(node.descendantRelationNodes)
-    );
-  });
+// Leave the writes that need keys or `#ref{}` values that only a later pass
+// gives to that pass, with their branches, and return them with the keys of
+// the rest.
+function deferLaterNodes(plan) {
+  const laterNodes = [];
+  let keys = new GraphKeys(plan);
+
+  for (let nodes = keys.getLaterNodes(); nodes.length > 0; nodes = keys.getLaterNodes()) {
+    laterNodes.push(...nodes);
+    plan.defer([...plan.deferredNodes, ...nodes.flatMap((node) => [node, ...node.descendants])]);
+    keys = new GraphKeys(plan);
+  }
 
-  removeBranchesFromGraph(findRoots(skippedNodes), graph);
+  return [laterNodes, keys];
 }
 
-function isReferencedFromOutside(nodes) {
-  const nodeSet = new Set(nodes);
-
-  return nodes.some((node) =>
-    node.refEdges.some((edge) => edge.isRelatedNode(node) && !nodeSet.has(edge.ownerNode)),
-  );
+// Check the models with ids that are neither at their place nor related, once
+// the current graph of a pass is loaded.
+function checkMissingModels(builder, plan) {
+  for (const node of plan.nodes) {
+    if (plan.intentFor(node) === 'missing') {
+      const id = node.obj.$id();
+
+      throw node.modelClass.createNotFoundError(builder.context(), {
+        message: node.isMissing
+          ? `model (id=${id}) does not exist. If you want to insert it with an id, use the insertMissing option`
+          : node.isRoot
+            ? `root model (id=${id}) does not exist. If you want to insert it with an id, use the insertMissing option`
+            : `model (id=${id}) is not a child of model (id=${node.parent.obj.$id()}). If you want to relate it, use the relate option. If you want to insert it with an id, use the insertMissing option`,
+        dataPath: node.dataPath,
+      });
+    }
+  }
 }
 
-function pruneDeletedBranches(graphData) {
-  const { graph, currentGraph } = graphData;
-
-  const deleteNodes = currentGraph.nodes.filter((currentNode) => !graph.nodeForNode(currentNode));
-  const roots = findRoots(deleteNodes);
+// The graph writes keys of rows that can't change if they're part of the ids
+// of the rows: the foreign key of a row that a HasMany or HasOne relate moves
+// to another owner, and the foreign key of an existing row that its own
+// BelongsToOne relate or insert points to another row, or that `null`,
+// `#unrelate` or `#delete` clears. Keys that aren't known before the writes
+// are compared only where they surely change, as new models get new keys.
+function checkChangedIds(builder, plan) {
+  const { actions } = plan;
+  const newKey = {};
+  const getKey = (node, prop, i) =>
+    actions.get(node) === 'insert' && !node.obj.$hasId()
+      ? newKey
+      : (prop.getProp(node.obj, i) ?? (node.existing && prop.getProp(node.existing.obj, i)));
+
+  const checkKey = (row, relation, rowProp, getNewKey) => {
+    const idProps = row.modelClass.getIdPropertyArray();
+    const isChanged =
+      actions.get(row) !== 'insert' &&
+      rowProp.props.some((prop, i) => {
+        const key = row.obj[prop];
+        const changedKey = getNewKey(i);
+        return (
+          idProps.includes(prop) &&
+          key !== undefined &&
+          changedKey !== undefined &&
+          (changedKey === newKey || !nonStrictEquals(key, changedKey))
+        );
+      });
 
-  // Don't delete relations the current graph doesn't even mention.
-  // So if the parent node doesn't even have the relation, it's not
-  // supposed to be deleted.
-  const rootsNotInRelation = roots.filter((deleteRoot) => {
-    if (!deleteRoot.parentNode) {
-      return false;
+    if (isChanged) {
+      throw builder.modelClass().createValidationError({
+        type: ValidationErrorType.InvalidGraph,
+        message: `the graph changes the key of the ${row.modelClass.name} at ${formatPath(row.dataPathKey)} through ${relation.name}, which is part of its id`,
+      });
     }
+  };
 
-    const { relation } = deleteRoot.parentEdge;
-    const parentNode = graph.nodeForNode(deleteRoot.parentNode);
+  for (const node of plan.activeNodes) {
+    const { relation, parent } = node;
+    const action = actions.get(node);
 
-    if (!parentNode) {
-      return false;
+    if (relation?.keySide === 'related' && action === 'relate') {
+      checkKey(node.referencedNode || node, relation, relation.relatedProp, (i) =>
+        getKey(parent, relation.ownerProp, i),
+      );
+    } else if (relation?.keySide === 'owner' && relation.isOneToOne()) {
+      if (node.toBeUnrelatedOrDeleted) {
+        if (node.current) {
+          checkKey(parent, relation, relation.ownerProp, () => null);
+        }
+      } else if (action === 'relate' || action === 'insert') {
+        checkKey(parent, relation, relation.ownerProp, (i) =>
+          getKey(node.referencedNode || node, relation.relatedProp, i),
+        );
+      }
     }
 
-    return parentNode.obj[relation.name] === undefined;
-  });
+    // `null` clears the key:
+    const nullNames = node.modelClass.getRelationNames().filter((name) => node.obj[name] === null);
 
-  removeBranchesFromGraph(roots, currentGraph);
-  removeNodesFromGraph(new Set(rootsNotInRelation), currentGraph);
-}
-
-// Models marked with `#unrelate` or `#delete` are unrelated or deleted
-// as a whole. Their relations are ignored, both in the upserted graph
-// and in the current graph.
-function pruneUnrelatedOrDeletedBranches(graphData) {
-  const { graph, currentGraph } = graphData;
-
-  const roots = findRoots(graph.nodes.filter((node) => node.toBeUnrelatedOrDeleted));
-  const currentRoots = roots.map((node) => currentGraph.nodeForNode(node)).filter(Boolean);
+    for (const name of nullNames) {
+      const nullRelation = node.modelClass.getRelation(name);
 
-  removeBranchesFromGraph(roots, graph);
-  removeBranchesFromGraph(currentRoots, currentGraph);
+      if (nullRelation.keySide === 'owner' && nullRelation.isOneToOne()) {
+        checkKey(node, nullRelation, nullRelation.ownerProp, () => null);
+      }
+    }
+  }
 }
 
-function findRoots(nodes) {
-  const nodeSet = new Set(nodes);
+// Check the whole graph before anything is written.
+function checkGraph(builder, plan) {
+  const { nodes, graphOptions } = plan;
+  const modelClass = builder.modelClass();
+  const createInvalidGraphError = (message) =>
+    modelClass.createValidationError({ type: ValidationErrorType.InvalidGraph, message });
 
-  return uniqBy(
-    nodes.filter((node) => {
-      let parentNode = node.parentNode;
+  const allowedExpression = builder.allowedGraphExpression();
+  const rootObjs = nodes.filter((node) => node.isRoot).map((node) => node.obj);
+
+  if (
+    allowedExpression &&
+    !allowedExpression.isSubExpression(RelationExpression.fromModelGraph(rootObjs))
+  ) {
+    throw modelClass.createValidationError({
+      type: ValidationErrorType.UnallowedRelation,
+      message: 'trying to upsert an unallowed relation',
+    });
+  }
 
-      while (parentNode) {
-        if (nodeSet.has(parentNode)) {
-          return false;
-        }
+  if (
+    !graphOptions.allowRefs() &&
+    nodes.some((node) => node.isReference || node.propertyReferences.length > 0)
+  ) {
+    throw createInvalidGraphError(
+      '#ref references are not allowed in a graph by default. see the allowRefs insert/upsert graph option',
+    );
+  }
 
-        parentNode = parentNode.parentNode;
-      }
+  // `#unrelate` and `#delete` markers come from the graph data, which may be
+  // untrusted input. Like `#ref`, they have to be allowed explicitly (#2410).
+  // Root models can't be marked even with `allowMarkers`, so report that first.
+  // An insert has nothing to unrelate or delete, so `insertGraph` rejects them.
+  const markedNode = nodes.find((node) => node.toBeUnrelatedOrDeleted);
 
-      return true;
-    }),
-  );
-}
+  if (markedNode) {
+    const { graphUnrelateProp, graphDeleteProp } = markedNode.modelClass;
+    const markers = `${graphUnrelateProp} and ${graphDeleteProp}`;
 
-function removeBranchesFromGraph(branchRoots, graph) {
-  const nodesToRemove = new Set(
-    branchRoots.reduce(
-      (nodesToRemove, node) => [...nodesToRemove, ...node.descendantRelationNodes],
-      [],
-    ),
-  );
+    if (nodes.some((node) => node.isRoot && node.toBeUnrelatedOrDeleted)) {
+      throw createInvalidGraphError(
+        `${markers} can only be used for related models, not for root models`,
+      );
+    } else if (!graphOptions.allowMarkers()) {
+      throw createInvalidGraphError(
+        graphOptions.isInsertOnly()
+          ? `${markers} can only be used in upsertGraph, not in insertGraph`
+          : `${markers} markers are not allowed in a graph by default. see the allowMarkers upsertGraph option`,
+      );
+    }
+  }
 
-  removeNodesFromGraph(nodesToRemove, graph);
-}
+  if (graphOptions.isInsertOnly()) {
+    const relatedNodes = nodes.filter((node) => plan.actionFor(node) === 'relate');
 
-function removeNodesFromGraph(nodesToRemove, graph) {
-  const edgesToRemove = new Set();
+    if (relatedNodes.some((node) => node.relation.keySide === 'related')) {
+      throw new Error(
+        'You cannot relate HasManyRelation or HasOneRelation using insertGraph, because those require update operations. Consider using upsertGraph instead.',
+      );
+    }
 
-  for (const node of nodesToRemove) {
-    for (const edge of node.edges) {
-      const otherNode = edge.getOtherNode(node);
+    // `upsertGraph()` upserts the branches below related models, but
+    // `insertGraph()` leaves them out, which would drop the new models there
+    // (#217). Models with ids below related models are taken as fetched models
+    // with loaded relations, and are ignored.
+    for (const node of relatedNodes) {
+      const newNode = node.descendants.find(
+        (descendant) => !descendant.hasId && plan.actionFor(descendant) === 'insert',
+      );
 
-      if (!nodesToRemove.has(otherNode)) {
-        otherNode.removeEdge(edge);
-        edgesToRemove.add(edge);
+      if (newNode) {
+        throw createInvalidGraphError(
+          `insertGraph cannot insert the new model at ${formatPath(newNode.dataPathKey)} below a related model. Insert it with a separate query or use upsertGraph instead`,
+        );
       }
     }
   }
-
-  graph.nodes = graph.nodes.filter((node) => !nodesToRemove.has(node));
-  graph.edges = graph.edges.filter((edge) => !edgesToRemove.has(edge));
-
-  return graph;
 }
 
-function checkForErrors(builder) {
-  return (graphData) => {
-    checkForNotFoundErrors(graphData, builder);
-    checkForUnallowedRelationErrors(graphData, builder);
-    checkForUnallowedReferenceErrors(graphData, builder);
-    // Root models can't be marked even with `allowMarkers`, so report that
-    // first instead of pointing to the option.
-    checkForRootUnrelateOrDeleteErrors(graphData, builder);
-    checkForUnallowedMarkerErrors(graphData, builder);
-
-    if (graphData.graphOptions.isInsertOnly()) {
-      checkForHasManyRelateErrors(graphData);
-      warnOnInsertBelowRelate(graphData);
-    }
+// One row can't get two values for one column, and the slot of a
+// HasOneRelation can't get two rows. A `#ref` or `#dbRef` model is a place of
+// the row that it refers to. The keys that relations give a row are the values
+// of the key props across them, or stand for these where the graph doesn't
+// give them, e.g. for new models.
+function checkPlacements(builder, nodes) {
+  const newRowIds = new Map();
+  const getRowId = (node) => {
+    const target = node.referencedNode || node;
+
+    if (target.obj.$hasId()) {
+      return target.rowKey;
+    } else {
+      if (!newRowIds.has(target)) {
+        newRowIds.set(target, `new:${newRowIds.size}`);
+      }
 
-    return graphData;
+      return newRowIds.get(target);
+    }
   };
-}
 
-// Inserting or relating a node of a many-to-many relation inserts a join row,
-// which would be a new related row if the join table is also the related
-// table (#133). Check this before this graph is written. It runs after
-// pruning, as the branches below related nodes are upserted and checked by
-// nested `upsertGraph` calls against their own current graphs.
-function checkForJoinTableRelatedTableErrors(builder) {
-  return (graphData) => {
-    const { graphOptions, currentGraph, graph } = graphData;
-
-    for (const node of graph.nodes) {
-      const relation = node.parentEdge && node.parentEdge.relation;
-
-      if (
-        relation &&
-        relation.isObjectionManyToManyRelation &&
-        !currentGraph.nodeForNode(node) &&
-        graphOptions.shouldInsertOrRelate(node, graphData)
-      ) {
-        relation.assertCanModifyJoinTable(
-          builder,
-          graphOptions.shouldRelate(node, graphData) ? 'relate' : 'insert',
-        );
-      }
+  // The values that the graph gives each row, by prop, and the model classes
+  // and relations through which the graph reaches the rows:
+  const rows = new Map();
+  const rowTables = new Map();
+  const rowRelations = new Map();
+  const setValue = (rowId, name, prop, value, path) => {
+    const values = rows.get(rowId) || new Map();
+    const other = values.get(prop);
+    rows.set(rowId, values);
+
+    if (!other) {
+      values.set(prop, { value, path });
+    } else if (!nonStrictEquals(other.value, value)) {
+      throw builder.modelClass().createValidationError({
+        type: ValidationErrorType.InvalidGraph,
+        message: `the graph gives ${prop} of one ${name} two values, at ${formatPath(other.path)} and at ${formatPath(path)}`,
+      });
     }
-
-    return graphData;
   };
-}
+  const setNodeValue = (node, prop, value, path) =>
+    setValue(getRowId(node), node.modelClass.name, prop, value, path);
+
+  // The join row of the pair of models that `node` and its parent are, the
+  // same through both relations of the join table:
+  const getJoinRowId = (node) =>
+    [
+      node.relation.joinTable,
+      ...[
+        [node.relation.joinTableOwnerProp.cols, getRowId(node.parent)],
+        [node.relation.joinTableRelatedProp.cols, getRowId(node)],
+      ]
+        .sort(([cols1], [cols2]) => cols1.join().localeCompare(cols2.join()))
+        .map(([cols, rowId]) => `${cols}=${rowId}`),
+    ].join(':');
+
+  const getPath = (node, ...keys) => [node.dataPathKey, ...keys].filter(Boolean).join('.');
+  const getRelations = (node) =>
+    node.modelClass
+      .getRelationNames()
+      .filter((name) => node.obj[name] !== undefined)
+      .map((name) => node.modelClass.getRelation(name));
+  const isOwnerKey = (relation) => relation.keySide === 'owner' && relation.isOneToOne();
+  const isSlot = (relation) => relation.keySide === 'related' && relation.isOneToOne();
+
+  // The props that the models give, except for the ids and the keys that the
+  // relations of the same model set, which follow these relations:
+  for (const node of nodes) {
+    const { modelClass, obj, relation } = node;
+    const skippedProps = [
+      ...modelClass.getRelationNames(),
+      ...modelClass.getIdPropertyArray(),
+      ...(relation?.keySide === 'related' ? relation.relatedProp.props : []),
+      // The extras of join rows belong to the join rows:
+      ...(relation?.keySide === 'join' ? relation.joinTableExtras.map((e) => e.aliasProp) : []),
+      ...getRelations(node)
+        .filter(isOwnerKey)
+        .flatMap((relation) => relation.ownerProp.props),
+    ];
+
+    const rowId = getRowId(node);
+    rowTables.set(rowId, modelClass.getTableName());
+    rowRelations.set(rowId, (rowRelations.get(rowId) || new Set()).add(relation));
+
+    if (!node.toBeUnrelatedOrDeleted) {
+      for (const prop of Object.keys(obj)) {
+        if (obj[prop] !== undefined && !isInternalProp(prop) && !skippedProps.includes(prop)) {
+          setNodeValue(node, prop, obj[prop], getPath(node, prop));
+        }
+      }
+    }
 
-function checkForNotFoundErrors(graphData, builder) {
-  const { graphOptions, currentGraph, graph } = graphData;
-  // The branches below related nodes are upserted and checked by nested
-  // `upsertGraph` calls, against the current graphs of the related nodes:
-  const nestedNodes = new Set(
-    graph.nodes
-      .filter((node) => graphOptions.shouldRelate(node, graphData))
-      .flatMap((node) => node.descendantRelationNodes),
-  );
-
-  for (const node of graph.nodes) {
-    if (
-      node.obj.$hasId() &&
-      !nestedNodes.has(node) &&
-      !node.toBeUnrelatedOrDeleted &&
-      !graphOptions.shouldInsertIgnoreDisable(node, graphData) &&
-      !graphOptions.shouldRelateIgnoreDisable(node, graphData) &&
-      !currentGraph.nodeForNode(node)
-    ) {
-      if (!node.parentNode) {
-        throw node.modelClass.createNotFoundError(builder.context(), {
-          message: `root model (id=${node.obj.$id()}) does not exist. If you want to insert it with an id, use the insertMissing option`,
-          dataPath: node.dataPath,
-        });
-      } else {
-        throw node.modelClass.createNotFoundError(builder.context(), {
-          message: `model (id=${node.obj.$id()}) is not a child of model (id=${node.parentNode.obj.$id()}). If you want to relate it, use the relate option. If you want to insert it with an id, use the insertMissing option`,
-          dataPath: node.dataPath,
-        });
+    // A pair of models has one join row, which gets the extras of all places
+    // of the pair:
+    if (relation?.keySide === 'join' && !node.toBeUnrelatedOrDeleted) {
+      for (const { aliasProp } of relation.joinTableExtras) {
+        if (obj[aliasProp] !== undefined) {
+          const path = getPath(node, aliasProp);
+          setValue(
+            getJoinRowId(node),
+            `join row of ${relation.name}`,
+            aliasProp,
+            obj[aliasProp],
+            path,
+          );
+        }
       }
     }
   }
-}
-
-function checkForUnallowedRelationErrors(graphData, builder) {
-  const { graph } = graphData;
-  const allowedExpression = builder.allowedGraphExpression();
 
-  if (allowedExpression) {
-    const rootsObjs = graph.nodes.filter((node) => !node.parentEdge).map((node) => node.obj);
-    const expression = RelationExpression.fromModelGraph(rootsObjs);
+  // The value of the key prop `i` of `prop` that `node` gives across a
+  // relation, from wherever the graph gives the row, or one that stands for it:
+  const getKey = (node, prop, i) =>
+    prop.getProp(node.obj, i) ??
+    rows.get(getRowId(node))?.get(prop.props[i])?.value ?? {
+      row: getRowId(node),
+      prop: prop.props[i],
+    };
+
+  // The keys that the relations give the rows, the rows that the graph puts
+  // in the slots of HasOneRelations, and whether the rows are deleted:
+  const slots = [];
+  for (const node of nodes) {
+    const { relation, parent } = node;
+    const path = getPath(node);
+    const isUnrelated = node.toBeUnrelated;
+    const isDeleted = node.toBeDeleted && !isUnrelated;
+
+    if (relation?.keySide === 'related') {
+      // A row that lists itself on the same column restates its own key:
+      const isSelfLink =
+        getRowId(node) === getRowId(parent) &&
+        hasSameColumns(relation.relatedProp, relation.ownerProp);
+
+      if (!isDeleted && !isSelfLink) {
+        relation.relatedProp.forEach((i) => {
+          const key = isUnrelated ? null : getKey(parent, relation.ownerProp, i);
+          setNodeValue(node, relation.relatedProp.props[i], key, path);
+        });
+      }
 
-    if (!allowedExpression.isSubExpression(expression)) {
-      throw builder.modelClass().createValidationError({
-        type: ValidationErrorType.UnallowedRelation,
-        message: 'trying to upsert an unallowed relation',
+      if (isSlot(relation)) {
+        const row = node.toBeUnrelatedOrDeleted ? null : getRowId(node);
+        slots.push({ owner: parent, relation, row, path });
+      }
+    } else if (relation && isOwnerKey(relation)) {
+      relation.ownerProp.forEach((i) => {
+        const key = node.toBeUnrelatedOrDeleted ? null : getKey(node, relation.relatedProp, i);
+        setNodeValue(parent, relation.ownerProp.props[i], key, path);
       });
     }
-  }
-}
 
-function checkForUnallowedReferenceErrors(graphData, builder) {
-  const { graph, graphOptions } = graphData;
+    setNodeValue(node, '#delete', isDeleted, path);
 
-  if (graphOptions.allowRefs()) {
-    return;
-  }
-
-  if (graph.edges.some((edge) => edge.type === ModelGraphEdge.Type.Reference)) {
-    throw builder.modelClass().createValidationError({
-      type: ValidationErrorType.InvalidGraph,
-      message:
-        '#ref references are not allowed in a graph by default. see the allowRefs insert/upsert graph option',
-    });
-  }
-}
-
-// `#unrelate` and `#delete` markers come from the graph data, which may be
-// untrusted input. Like `#ref`, they have to be allowed explicitly (#2410).
-// An insert has nothing to unrelate or delete, so `insertGraph` rejects them.
-function checkForUnallowedMarkerErrors(graphData, builder) {
-  const { graph, graphOptions } = graphData;
-  const isInsertOnly = graphOptions.isInsertOnly();
+    // All places of a pair of models keep or remove its join row:
+    if (relation?.keySide === 'join') {
+      const name = `join row of ${relation.name}`;
+      setValue(getJoinRowId(node), name, '#unrelate', node.toBeUnrelatedOrDeleted, path);
+    }
 
-  if (graphOptions.allowMarkers() && !isInsertOnly) {
-    return;
+    // `null` clears the key or the slot:
+    for (const nullRelation of getRelations(node).filter(({ name }) => node.obj[name] === null)) {
+      if (isOwnerKey(nullRelation)) {
+        nullRelation.ownerProp.forEach((i) => {
+          setNodeValue(
+            node,
+            nullRelation.ownerProp.props[i],
+            null,
+            getPath(node, nullRelation.name),
+          );
+        });
+      } else if (isSlot(nullRelation)) {
+        const path = getPath(node, nullRelation.name);
+        slots.push({ owner: node, relation: nullRelation, row: null, path });
+      }
+    }
   }
 
-  const node = graph.nodes.find((node) => node.toBeUnrelatedOrDeleted);
-
-  if (node) {
-    const { graphUnrelateProp, graphDeleteProp } = node.modelClass;
+  // The rows of a table by the values that the graph gives the props of a key,
+  // with the values that stand for keys as they are and the others as strings,
+  // so that e.g. `1` and `'1'` are the same key:
+  const toIndexKey = (values) =>
+    JSON.stringify(values.map((value) => (isObject(value) ? value : String(value))));
+  const indexes = new Map();
+  const getRowsByKey = (table, props) => {
+    const indexName = `${table}:${props.join()}`;
+    let index = indexes.get(indexName);
+
+    if (!index) {
+      index = new Map();
+      indexes.set(indexName, index);
+
+      for (const [rowId, values] of rows) {
+        const keyValues = props.map((prop) => values.get(prop)?.value);
+
+        if (rowTables.get(rowId) === table && keyValues.every((value) => value != null)) {
+          const indexKey = toIndexKey(keyValues);
+          const rowIds = index.get(indexKey);
+
+          if (rowIds) {
+            rowIds.push(rowId);
+          } else {
+            index.set(indexKey, [rowId]);
+          }
+        }
+      }
+    }
 
-    throw builder.modelClass().createValidationError({
-      type: ValidationErrorType.InvalidGraph,
-      message: isInsertOnly
-        ? `${graphUnrelateProp} and ${graphDeleteProp} can only be used in upsertGraph, not in insertGraph`
-        : `${graphUnrelateProp} and ${graphDeleteProp} markers are not allowed in a graph by default. see the allowMarkers upsertGraph option`,
-    });
-  }
-}
+    return index;
+  };
 
-function checkForRootUnrelateOrDeleteErrors(graphData, builder) {
-  for (const node of graphData.graph.nodes) {
-    if (!node.parentEdge && node.toBeUnrelatedOrDeleted) {
-      const { graphUnrelateProp, graphDeleteProp } = node.modelClass;
+  // Any other row that the graph gives the key of the owner of a slot is a
+  // second row in it, unless the relation filters its rows and the graph
+  // doesn't reach the row through it:
+  for (const { owner, relation, row, path } of slots) {
+    const { relatedModelClass, relatedProp, ownerProp } = relation;
+    const ownerKey = ownerProp.props.map((_, i) => getKey(owner, ownerProp, i));
+    const rowsByKey = getRowsByKey(relatedModelClass.getTableName(), relatedProp.props);
+    const otherRowId = (rowsByKey.get(toIndexKey(ownerKey)) || []).find(
+      (rowId) => rowId !== row && (!relation.modify || rowRelations.get(rowId).has(relation)),
+    );
 
+    if (otherRowId) {
+      const other = rows.get(otherRowId).get(relatedProp.props[0]);
       throw builder.modelClass().createValidationError({
         type: ValidationErrorType.InvalidGraph,
-        message: `${graphUnrelateProp} and ${graphDeleteProp} can only be used for related models, not for root models`,
+        message: `the graph puts two ${relatedModelClass.name} rows in ${relation.name} of one ${owner.modelClass.name}, at ${formatPath(path)} and at ${formatPath(other.path)}`,
       });
     }
   }
 }
 
-function checkForHasManyRelateErrors(graphData) {
-  const { graph, graphOptions } = graphData;
+// References need the ids of the models they point to, which the database
+// only gives the models that the graph writes in the same pass or an earlier
+// one. The ids of new models that the graph doesn't write, e.g. as `noInsert`
+// skips them, are never known. Everything else reads the models as the graph
+// gives them. The references of models that aren't written are never resolved.
+function checkReferences(builder, plan, writtenNodes) {
+  const isReadable = (node, refPath) =>
+    writtenNodes.has(node) ||
+    node.obj.$hasId() ||
+    (!!refPath && !node.modelClass.getIdPropertyArray().includes(refPath[0]));
+
+  for (const node of plan.activeNodes.filter((node) => writtenNodes.has(node))) {
+    const { referencedNode, propertyReferences } = node;
 
-  for (const node of graph.nodes) {
     if (
-      graphOptions.shouldRelate(node, graphData) &&
-      node.parentEdge.relation.isObjectionHasManyRelation
+      (referencedNode && !isReadable(referencedNode)) ||
+      propertyReferences.some(({ referencedNode, refPath }) => !isReadable(referencedNode, refPath))
     ) {
-      throw new Error(
-        'You cannot relate HasManyRelation or HasOneRelation using insertGraph, because those require update operations. Consider using upsertGraph instead.',
-      );
+      throw builder.modelClass().createValidationError({
+        type: ValidationErrorType.InvalidGraph,
+        message: `the reference at ${formatPath(node.dataPathKey)} points to a model that the graph doesn't write before it`,
+      });
     }
   }
 }
 
-// `upsertGraph` upserts the branches below related models recursively, but
-// `insertGraph` prunes them, which drops the models that would be inserted
-// there (#217). A warning is logged once.
-// TODO: Throw an error instead in objection 4.0 (#53).
-function warnOnInsertBelowRelate(graphData) {
-  const { graph, graphOptions } = graphData;
-
-  const hasInsertBelowRelate = graph.nodes.some(
-    (node) =>
-      graphOptions.shouldRelate(node, graphData) &&
-      node.descendantRelationNodes.some((descendantNode) =>
-        graphOptions.shouldInsert(descendantNode, graphData),
-      ),
-  );
-
-  if (hasInsertBelowRelate) {
-    warnOnce(
-      'insertGraph() ignores new models below related models. ' +
-        'Insert them with a separate query or use upsertGraph() instead. ' +
-        'This will throw in objection 4.0.',
-    );
-  }
-}
-
-function executeOperations(builder) {
-  return (graphData) => {
-    const operations = graphData.graphOptions.isInsertOnly()
-      ? [GraphInsert]
-      : [
-          GraphDelete,
-          GraphInsert,
-          GraphPatch,
-          GraphDereferencedBelongsToOneDelete,
-          GraphRecursiveUpsert,
-        ];
-
-    // Create all actions before chaining the first ones, which would run even
-    // if creating the actions of a later operation throws, e.g. for a cycle.
-    const operationActions = operations.map((Operation) =>
-      new Operation(graphData).createActions(),
-    );
-
-    return operationActions.reduce(
-      (promise, actions) => promise.then(() => executeActions(builder, actions)),
-      Promise.resolve(),
-    );
+// A `#ref{}` waits for the model it reads if the value only exists once that
+// model is written. These waits follow from the graph alone, so their cycles
+// are found across all passes, before the first write.
+function checkReferenceCycles(nodes) {
+  const getWaitedNodes = (node) =>
+    node.propertyReferences
+      .filter((reference) => reference.referencedNode !== node && readsWrittenValue(reference))
+      .map(({ referencedNode }) => referencedNode);
+  const visitingNodes = new Set();
+  const visitedNodes = new Set();
+
+  const visit = (node) => {
+    if (visitingNodes.has(node)) {
+      throw new Error('the object graph contains cyclic references');
+    } else if (!visitedNodes.has(node)) {
+      visitingNodes.add(node);
+      getWaitedNodes(node).forEach(visit);
+      visitingNodes.delete(node);
+      visitedNodes.add(node);
+    }
   };
-}
 
-function executeActions(builder, actions) {
-  return actions.reduce(
-    (promise, action) => promise.then(() => action.run(builder)),
-    Promise.resolve(),
-  );
+  nodes.forEach(visit);
 }
 
-// The reference markers only describe the input graph, don't return them.
-// `nodes` are the nodes before pruning, since the results of pruned branches
-// contain markers too.
-function removeReferenceProps(nodes) {
-  return () => {
-    for (const node of nodes) {
-      delete node.obj[node.modelClass.uidRefProp];
-      delete node.obj[node.modelClass.dbRefProp];
-    }
-  };
-}
+// Inserting or relating a model of a many-to-many relation inserts a join row,
+// which would be a new related row if the join table is also the related table
+// (#133).
+function checkJoinTables(builder, plan) {
+  for (const node of plan.activeNodes) {
+    const action = plan.actions.get(node);
 
-function isOnConflictOperation(op) {
-  return op.name === 'onConflict' || op.name === 'ignore' || op.name === 'merge';
+    if (
+      node.relation?.keySide === 'join' &&
+      !node.current &&
+      (action === 'insert' || action === 'relate')
+    ) {
+      node.relation.assertCanModifyJoinTable(builder, action);
+    }
+  }
 }
 
-function returnResult(objects, isArray) {
-  return () => (isArray ? objects : objects[0]);
+function isOnConflictOperation(operation) {
+  return ['onConflict', 'ignore', 'merge'].includes(operation.name);
 }
-
-module.exports = {
-  GraphUpsert,
-};