objection 3.9.1 → 4.0.0-rc.2

package/lib/queryBuilder/graph/GraphNode.js

@@ -0,0 +1,241 @@
+import { asArray, asSingle, isNumber, isObject, isString } from '../../utils/objectUtils.js';
+import { ValidationErrorType } from '../../model/ValidationError.js';
+
+// A model in a graph that is inserted or upserted, or in the current graph that
+// is fetched from the database for it.
+export class GraphNode {
+  constructor(modelClass, obj, { parent = null, relation = null, index = null, relationPath }) {
+    this.modelClass = modelClass;
+    this.obj = obj;
+    this.parent = parent;
+    this.relation = relation;
+    // The index in the array of a to-many relation, or of array input:
+    this.index = index;
+    this.children = [];
+    this.relationPath = parent ? [...parent.relationPath, relation.name] : relationPath;
+    this.relationPathKey = this.relationPath.join('.');
+    // The id state of the input, before the writes complete ids with keys:
+    this.hasId = obj.$hasId();
+
+    // Read the markers of the graph, which `removeMarkers()` removes from the
+    // models once all places of a model are read:
+    const { uidProp, uidRefProp, dbRefProp, graphUnrelateProp, graphDeleteProp } = modelClass;
+    this.uid = obj[uidProp];
+    this.reference = obj[uidRefProp];
+    this.dbReference = obj[dbRefProp];
+    this.toBeUnrelated = obj[graphUnrelateProp] === true;
+    this.toBeDeleted = obj[graphDeleteProp] === true;
+
+    // The node of a `#ref` model, and the `#ref{}` properties of this model:
+    this.referencedNode = null;
+    this.propertyReferences = [];
+    // The nodes whose `#ref` or `#ref{}` point to this node:
+    this.referencingNodes = [];
+    this.propertyReferencingNodes = [];
+
+    // How the graph and the current graph pair up, see `GraphLoader`: The
+    // current node at the place of an input node and the other way around, and
+    // the current node of a related model's row fetched from elsewhere.
+    this.current = null;
+    this.node = null;
+    this.row = null;
+    this.isMissing = false;
+
+    // Set by `GraphPlan`:
+    this.isPruned = false;
+  }
+
+  get isReference() {
+    return this.reference !== undefined;
+  }
+
+  get isDbReference() {
+    return this.dbReference !== undefined;
+  }
+
+  get toBeUnrelatedOrDeleted() {
+    return this.toBeUnrelated || this.toBeDeleted;
+  }
+
+  get isRoot() {
+    return !this.parent;
+  }
+
+  // The current node of the row of this node, at its place or where a relate
+  // moves it from.
+  get existing() {
+    return this.current || this.row;
+  }
+
+  get dataPath() {
+    return this.parent
+      ? [
+          ...this.parent.dataPath,
+          this.relation.name,
+          ...(this.relation.isOneToOne() ? [] : [this.index]),
+        ]
+      : this.index !== null
+        ? [this.index]
+        : [];
+  }
+
+  // The data path in the form of validation errors, like `.pets[0].owner` or
+  // `[1].pets[0].owner` for array input.
+  get dataPathKey() {
+    return this.dataPath.map((key) => (isNumber(key) ? `[${key}]` : `.${key}`)).join('');
+  }
+
+  get descendants() {
+    return this.children.flatMap((child) => [child, ...child.descendants]);
+  }
+
+  get activeChildren() {
+    return this.children.filter((child) => !child.isPruned);
+  }
+
+  get rowKey() {
+    return `${this.modelClass.getTableName()}:${this.obj.$idKey()}`;
+  }
+
+  // Build the nodes of `roots` and their related models in depth-first order.
+  // `relationPath` is the place of the roots in the graph that a current graph
+  // is fetched for. The roots of array input know their index in it.
+  static buildGraph(modelClass, roots, relationPath = []) {
+    const nodes = [];
+
+    const addNode = (modelClass, obj, place) => {
+      if (!isObject(obj) || !obj.$isObjectionModel) {
+        throw createNotModelError(modelClass, obj);
+      }
+
+      const node = new GraphNode(modelClass, obj, place);
+      nodes.push(node);
+      place.parent?.children.push(node);
+
+      for (const name of modelClass.getRelationNames()) {
+        const related = obj[name];
+
+        if (related) {
+          const relation = modelClass.getRelation(name);
+          const items = relation.isOneToOne() ? [asSingle(related)] : asArray(related);
+
+          items.forEach((item, index) => {
+            addNode(relation.relatedModelClass, item, { parent: node, relation, index });
+          });
+        }
+      }
+    };
+
+    asArray(roots).forEach((root, index) => {
+      addNode(modelClass, root, { relationPath, index: Array.isArray(roots) ? index : null });
+    });
+
+    return nodes;
+  }
+
+  // Remove the markers from the models, as they're neither written nor
+  // returned, and return a function that puts them back if the writes fail.
+  static removeMarkers(nodes) {
+    const markers = [];
+
+    for (const { modelClass, obj } of nodes) {
+      for (const prop of [
+        modelClass.uidProp,
+        modelClass.uidRefProp,
+        modelClass.dbRefProp,
+        modelClass.graphUnrelateProp,
+        modelClass.graphDeleteProp,
+      ]) {
+        if (Object.hasOwn(obj, prop)) {
+          markers.push([obj, prop, obj[prop]]);
+          delete obj[prop];
+        }
+      }
+    }
+
+    return () => {
+      for (const [obj, prop, value] of markers) {
+        obj[prop] = value;
+      }
+    };
+  }
+
+  // Link the `#ref` and `#ref{}` references of the nodes to the nodes with the
+  // `#id` that they refer to.
+  static linkReferences(nodes) {
+    const nodesByUid = new Map();
+
+    for (const node of nodes) {
+      if (node.uid !== undefined) {
+        nodesByUid.set(node.uid, node);
+      }
+    }
+
+    const getNode = (uid) => {
+      const node = nodesByUid.get(uid);
+
+      if (!node) {
+        throw new Error(`could not resolve reference ${uid} in a graph.`);
+      }
+
+      return node;
+    };
+
+    for (const node of nodes) {
+      if (node.isReference) {
+        node.referencedNode = getNode(node.reference);
+        node.referencedNode.referencingNodes.push(node);
+      }
+
+      forEachPropertyReference(node.obj, ({ path, match, uid, refPath, isWholeValue }) => {
+        const referencedNode = getNode(uid);
+        node.propertyReferences.push({ path, match, refPath, isWholeValue, referencedNode });
+        referencedNode.propertyReferencingNodes.push(node);
+      });
+    }
+  }
+}
+
+function forEachPropertyReference(obj, callback) {
+  const modelClass = obj.constructor;
+  const relationNames = modelClass.getRelationNames();
+
+  const visit = (value, path) => {
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => visit(item, [...path, index]));
+    } else if (isObject(value) && !Buffer.isBuffer(value)) {
+      for (const key of Object.keys(value)) {
+        visit(value[key], [...path, key]);
+      }
+    } else if (isString(value)) {
+      for (const [match, uid, refPath] of value.matchAll(modelClass.propRefRegex)) {
+        callback({
+          path,
+          match,
+          uid,
+          refPath: refPath.trim().split('.'),
+          isWholeValue: match === value,
+        });
+      }
+    }
+  };
+
+  for (const key of Object.keys(obj)) {
+    if (!relationNames.includes(key)) {
+      visit(obj[key], [key]);
+    }
+  }
+}
+
+export function createNotModelError(modelClass, value) {
+  return modelClass.createValidationError({
+    type: ValidationErrorType.InvalidGraph,
+    message: `expected value "${value}" to be an instance of ${modelClass.name}`,
+  });
+}
+
+// Name the place of a model in error messages, by its data path.
+export function formatPath(dataPathKey) {
+  const path = dataPathKey.replace(/^\./, '');
+  return path ? `'${path}'` : 'the root';
+}

package/lib/queryBuilder/graph/GraphOptions.js

@@ -1,7 +1,5 @@
-'use strict';
-
-const { RelationExpression } = require('../RelationExpression');
-const { isString } = require('../../utils/objectUtils');
+import { RelationExpression } from '../RelationExpression.js';
+import { isString } from '../../utils/objectUtils.js';
 
 const NO_RELATE = 'noRelate';
 const NO_UNRELATE = 'noUnrelate';
@@ -18,7 +16,7 @@ const ALLOW_REFS = 'allowRefs';
 const ALLOW_MARKERS = 'allowMarkers';
 
 // The options that are matched against the relation path of each node, see
-// `_hasOption()`.
+// `has()`.
 const NODE_OPTION_NAMES = [
   NO_RELATE,
   NO_UNRELATE,
@@ -33,27 +31,31 @@ const NODE_OPTION_NAMES = [
 
 const OPTION_NAMES = [...NODE_OPTION_NAMES, FETCH_STRATEGY, ALLOW_REFS, ALLOW_MARKERS];
 
-const FetchStrategy = {
+// `insertGraph` never fetches, updates or removes existing rows, so only the
+// options about inserting and relating apply to it, and the others are set:
+const INSERT_OPTION_NAMES = [RELATE, NO_RELATE, NO_INSERT, ALLOW_REFS];
+const INSERT_ONLY_OPTIONS = {
+  [NO_UPDATE]: true,
+  [NO_DELETE]: true,
+  [NO_UNRELATE]: true,
+  [INSERT_MISSING]: true,
+};
+
+export const FetchStrategy = {
   OnlyIdentifiers: 'OnlyIdentifiers',
   Everything: 'Everything',
   OnlyNeeded: 'OnlyNeeded',
 };
 
-class GraphOptions {
-  // `rootRelationPath` is the relation path of the root node of a recursive
-  // upsert in the original graph, against which the relation paths and
-  // expressions of the options match. `insertOnly` is only set by
-  // `insertGraph`, which never fetches, updates or removes existing rows.
-  constructor(options, rootRelationPath = [], insertOnly = false) {
-    if (options instanceof GraphOptions) {
-      this.options = options.options;
-      this.rootRelationPath = options.rootRelationPath;
-      this.insertOnly = options.insertOnly;
-    } else {
-      this.options = parseRelationExpressions(options);
-      this.rootRelationPath = rootRelationPath;
-      this.insertOnly = insertOnly;
-    }
+export class GraphOptions {
+  // `insertOnly` is only set by `insertGraph`, which never fetches, updates or
+  // removes existing rows.
+  constructor(options, insertOnly = false) {
+    checkForUnknownOptions(options, insertOnly);
+    this.options = parseRelationExpressions(
+      insertOnly ? { ...options, ...INSERT_ONLY_OPTIONS } : options,
+    );
+    this.insertOnly = insertOnly;
   }
 
   isFetchStrategy(strategy) {
@@ -72,136 +74,15 @@ class GraphOptions {
     return this.insertOnly;
   }
 
-  // Like `shouldRelate` but ignores settings that explicitly disable relate operations.
-  shouldRelateIgnoreDisable(node, graphData) {
-    if (node.toBeUnrelatedOrDeleted) {
-      return false;
-    }
-
-    if (node.isReference || node.isDbReference) {
-      return true;
-    }
-
-    return (
-      this._hasOption(node, RELATE) &&
-      !getCurrentNode(node, graphData) &&
-      !!node.parentEdge &&
-      !!node.parentEdge.relation &&
-      hasRelateProp(node) &&
-      graphData.nodeDbExistence.doesNodeExistInDb(node)
-    );
-  }
-
-  shouldRelate(node, graphData) {
-    return !this._hasOption(node, NO_RELATE) && this.shouldRelateIgnoreDisable(node, graphData);
-  }
-
-  // Like `shouldInsert` but ignores settings that explicitly disable insert operations.
-  shouldInsertIgnoreDisable(node, graphData) {
-    if (node.toBeUnrelatedOrDeleted) {
-      return false;
-    }
-
-    return (
-      !getCurrentNode(node, graphData) &&
-      !this.shouldRelateIgnoreDisable(node, graphData) &&
-      (!node.hasId || this.shouldInsertMissing(node))
-    );
-  }
-
-  shouldInsert(node, graphData) {
-    return !this._hasOption(node, NO_INSERT) && this.shouldInsertIgnoreDisable(node, graphData);
-  }
-
-  shouldInsertMissing(node) {
-    return this._hasOption(node, INSERT_MISSING);
-  }
-
-  // Like `shouldPatch() || shouldUpdate()` but ignores settings that explicitly disable
-  // update or patch operations.
-  shouldPatchOrUpdateIgnoreDisable(node, graphData) {
-    if (node.toBeUnrelatedOrDeleted) {
-      return false;
-    }
-
-    if (this.shouldRelate(node, graphData)) {
-      // We should update all nodes that are going to be related. Note that
-      // we don't actually update anything unless there is something to update
-      // so this is just a preliminary test.
-      return true;
-    }
-
-    return !!getCurrentNode(node, graphData);
-  }
-
-  shouldPatch(node, graphData) {
-    return (
-      this.shouldPatchOrUpdateIgnoreDisable(node, graphData) &&
-      !this._hasOption(node, NO_UPDATE) &&
-      !this._hasOption(node, UPDATE)
-    );
-  }
-
-  shouldUpdate(node, graphData) {
-    return (
-      this.shouldPatchOrUpdateIgnoreDisable(node, graphData) &&
-      !this._hasOption(node, NO_UPDATE) &&
-      this._hasOption(node, UPDATE)
-    );
-  }
-
-  // Like `shouldUnrelate` but ignores settings that explicitly disable unrelate operations.
-  shouldUnrelateIgnoreDisable(currentNode) {
-    return this._hasOption(currentNode, UNRELATE);
-  }
-
-  shouldUnrelate(currentNode, graphData) {
-    const node = getNode(currentNode, graphData.graph);
-    if (node && node.toBeUnrelated) return true;
-
-    return (
-      !node &&
-      !hasIgnoredOtherModel(currentNode, graphData) &&
-      !this._hasOption(currentNode, NO_UNRELATE) &&
-      (this.shouldUnrelateIgnoreDisable(currentNode) ||
-        // The unrelate replaces a delete, so `noDelete` disables it too.
-        (!this._hasOption(currentNode, NO_DELETE) && shouldUnrelateKeptRow(currentNode, graphData)))
-    );
-  }
-
-  shouldDelete(currentNode, graphData) {
-    const node = getNode(currentNode, graphData.graph);
-    // `#unrelate` takes precedence over `#delete` if both are set.
-    if (node && node.toBeDeleted && !node.toBeUnrelated) return true;
-
-    return (
-      !node &&
-      !hasIgnoredOtherModel(currentNode, graphData) &&
-      !this._hasOption(currentNode, NO_DELETE) &&
-      !this.shouldUnrelateIgnoreDisable(currentNode) &&
-      // Rows that the graph keeps in another place must not be deleted (#214).
-      !graphData.keptNodeForRow(currentNode)
-    );
-  }
-
-  shouldInsertOrRelate(node, graphData) {
-    return this.shouldInsert(node, graphData) || this.shouldRelate(node, graphData);
+  // Whether a node that the graph relates or patches is written with `patch()`
+  // or `update()`. With `noUpdate`, it's neither, and only the foreign keys of
+  // its relates and BelongsToOneRelations are patched.
+  shouldPatch(node) {
+    return !this.has(node, NO_UPDATE) && !this.has(node, UPDATE);
   }
 
-  // The graph ignores models that it neither inserts, relates nor patches, like
-  // models marked with `#unrelate` or `#delete` and models skipped by `noInsert`
-  // or `noRelate`. Inserted models have ids and can look like models to relate
-  // afterwards, so we check that they were inserted too.
-  shouldIgnore(node, graphData) {
-    return (
-      !node.userData.inserted &&
-      !this.shouldInsertOrRelate(node, graphData) &&
-      !this.shouldPatchOrUpdateIgnoreDisable(node, graphData)
-    );
-  }
-
-  shouldDeleteOrUnrelate(currentNode, graphData) {
-    return this.shouldDelete(currentNode, graphData) || this.shouldUnrelate(currentNode, graphData);
+  shouldUpdate(node) {
+    return !this.has(node, NO_UPDATE) && this.has(node, UPDATE);
   }
 
   allowRefs() {
@@ -212,38 +93,37 @@ class GraphOptions {
     return !!this.options[ALLOW_MARKERS];
   }
 
-  // The options of recursive upserts keep matching against the relation paths
-  // of the original graph, which the relation paths of the new root lead to.
-  rebasedOptions(newRoot) {
-    return new GraphOptions(this.options, [...this.rootRelationPath, ...newRoot.relationPath]);
+  // Whether the option applies to the relation path of `node`.
+  has(node, optionName) {
+    const option = this.options[optionName];
+
+    return isRelationExpression(option)
+      ? matchesRelationExpression(option, node.relationPath)
+      : Array.isArray(option)
+        ? option.includes(node.relationPathKey)
+        : !!option;
   }
+}
 
-  _hasOption(node, optionName) {
-    const option = this.options[optionName];
+// Reject misspelled options and options of `upsertGraph` passed to
+// `insertGraph`, which would otherwise be ignored silently (#84). Options set
+// to `undefined` count as not set.
+function checkForUnknownOptions(options, insertOnly) {
+  const [method, optionNames] = insertOnly
+    ? ['insertGraph', INSERT_OPTION_NAMES]
+    : ['upsertGraph', OPTION_NAMES];
 
-    if (isRelationExpression(option)) {
-      return matchesRelationExpression(option, this._relationPath(node));
-    } else if (Array.isArray(option)) {
-      return option.includes(this._relationPath(node).join('.'));
-    } else if (typeof option === 'boolean') {
-      return option;
-    } else if (option === undefined) {
-      return false;
-    } else {
+  for (const [name, value] of Object.entries(options)) {
+    if (value !== undefined && !optionNames.includes(name)) {
       throw new Error(
-        `expected ${optionName} option value "${option}" to be a boolean, an array of relation paths or a relation expression`,
+        `"${name}" is not an option of ${method}(). Valid options are: ${optionNames.join(', ')}.`,
       );
     }
   }
-
-  // The relation path of the node in the original graph, see `rebasedOptions()`.
-  _relationPath(node) {
-    return [...this.rootRelationPath, ...node.relationPath];
-  }
 }
 
 // Parses the string values of the node options into relation expressions,
-// once per operation.
+// once per operation, and checks the types of the other values.
 function parseRelationExpressions(options) {
   let parsedOptions = options;
 
@@ -256,6 +136,10 @@ function parseRelationExpressions(options) {
       }
 
       parsedOptions[optionName] = parseRelationExpression(optionName, option);
+    } else if (!(option === undefined || typeof option === 'boolean' || Array.isArray(option))) {
+      throw new Error(
+        `expected ${optionName} option value "${option}" to be a boolean, an array of relation paths or a relation expression`,
+      );
     }
   }
 
@@ -288,14 +172,6 @@ function parseRelationExpression(optionName, expression) {
     throw createError(`aliases like "${alias.$relation} as ${alias.$name}" are not supported`);
   }
 
-  // `*` and `^` only have a meaning at the end of a relation path. Anywhere else
-  // they are parsed as relation names that would never match.
-  const token = findNode(parsedExpression.node, (node) => /^(\*|\^\d*)$/.test(node.$relation));
-
-  if (token) {
-    throw createError(`"${token.$relation}" is only supported at the end of a relation path`);
-  }
-
   return parsedExpression;
 }
 
@@ -342,72 +218,3 @@ function matchesRelationExpression(expression, relationPath) {
 function isRelationExpression(value) {
   return !!value && value.isObjectionRelationExpression === true;
 }
-
-function getCurrentNode(node, graphData) {
-  if (!graphData || !node) {
-    return null;
-  }
-
-  return graphData.currentGraph.nodeForNode(node);
-}
-
-// For `HasMany` and `HasOne` relations, the relate prop is the id of the
-// related model. Use the id state of the input graph, since the parent's
-// insert copies the foreign key into the related model, which can complete
-// a composite id that contains it and would turn an insert into a relate (#2544).
-function hasRelateProp(node) {
-  const relation = node.parentEdge.relation;
-
-  if (relation.isObjectionHasManyRelation) {
-    return node.hasId;
-  } else {
-    return relation.hasRelateProp(node.obj);
-  }
-}
-
-// An ignored model that isn't the current model of a BelongsToOneRelation
-// doesn't replace it, so we keep the current one instead of removing it as
-// missing.
-function hasIgnoredOtherModel(currentNode, graphData) {
-  const { relation } = currentNode.parentEdge;
-  const parentNode = getNode(currentNode.parentNode, graphData.graph);
-
-  return (
-    relation.isObjectionBelongsToOneRelation &&
-    !!parentNode &&
-    parentNode.edges.some(
-      (edge) =>
-        edge.relation === relation &&
-        edge.isOwnerNode(parentNode) &&
-        graphData.graphOptions.shouldIgnore(edge.relatedNode, graphData),
-    )
-  );
-}
-
-// A row that the graph keeps in another place is unrelated here instead of
-// being deleted, unless it's a has-many row that the graph relates through the
-// same relation: That relate moves it by overwriting the foreign key, which
-// may not be nullable.
-function shouldUnrelateKeptRow(currentNode, graphData) {
-  const keptNode = graphData.keptNodeForRow(currentNode);
-  const { relation } = currentNode.parentEdge;
-
-  return (
-    !!keptNode &&
-    !(relation.isObjectionHasManyRelation && keptNode.parentEdge?.relation === relation)
-  );
-}
-
-function getNode(currentNode, graph) {
-  if (!graph || !currentNode) {
-    return null;
-  }
-
-  return graph.nodeForNode(currentNode);
-}
-
-module.exports = {
-  GraphOptions,
-  OPTION_NAMES,
-  FetchStrategy,
-};