objection 3.5.0 → 3.6.0

package/README.md

@@ -36,9 +36,9 @@ What objection.js **doesn't** give you:
   For simple things it is useful that the database schema is automatically generated from the model definitions,
   but usually just gets in your way when doing anything non-trivial. Objection.js leaves the schema related things
   to you. knex has a great [migration tool](https://knexjs.org/guide/migrations.html) that we recommend for this job. Check
-  out the [example project](https://github.com/Vincit/objection.js/tree/main/examples/koa-ts).
+  out the [example project](https://github.com/ditojs/objection/tree/main/examples/koa-ts).
 
-The best way to get started is to clone our [example project](https://github.com/Vincit/objection.js/tree/main/examples/koa) and start playing with it. There's also a [typescript version](https://github.com/Vincit/objection.js/tree/main/examples/koa-ts) available.
+The best way to get started is to clone our [example project](https://github.com/ditojs/objection/tree/main/examples/koa) and start playing with it. There's also a [typescript version](https://github.com/ditojs/objection/tree/main/examples/koa-ts) available.
 
 Check out [this issue](https://github.com/Vincit/objection.js/issues/1069) to see who is using objection and what they think about it.
 
@@ -46,7 +46,7 @@ Shortcuts:
 
 - [Who uses objection.js](https://github.com/Vincit/objection.js/discussions/2464)
 - [API reference](https://ditojs.github.io/objection/api/query-builder/)
-- [Example projects](https://github.com/Vincit/objection.js/tree/main/examples)
+- [Example projects](https://github.com/ditojs/objection/tree/main/examples)
 - [Changelog](https://ditojs.github.io/objection/release-notes/changelog.html)
 - [v1 -> v2 -> v3 migration guide](https://ditojs.github.io/objection/release-notes/migration.html)
 - [Contribution guide](https://ditojs.github.io/objection/guide/contributing.html)

package/lib/queryBuilder/InternalOptions.js

@@ -6,6 +6,7 @@ class InternalOptions {
     this.keepImplicitJoinProps = false;
     this.returnImmediatelyValue = undefined;
     this.isInternalQuery = false;
+    this.skipRelationFilter = false;
     this.debug = false;
     this.schema = undefined;
   }
@@ -17,6 +18,7 @@ class InternalOptions {
     copy.keepImplicitJoinProps = this.keepImplicitJoinProps;
     copy.returnImmediatelyValue = this.returnImmediatelyValue;
     copy.isInternalQuery = this.isInternalQuery;
+    copy.skipRelationFilter = this.skipRelationFilter;
     copy.debug = this.debug;
     copy.schema = this.schema;
 

package/lib/queryBuilder/graph/GraphOptions.js

@@ -1,5 +1,8 @@
 'use strict';
 
+const { RelationExpression } = require('../RelationExpression');
+const { isString } = require('../../utils/objectUtils');
+
 const NO_RELATE = 'noRelate';
 const NO_UNRELATE = 'noUnrelate';
 const NO_INSERT = 'noInsert';
@@ -27,6 +30,20 @@ const OPTION_NAMES = [
   ALLOW_REFS,
 ];
 
+// The options that are matched against the relation path of each node, see
+// `_hasOption()`.
+const NODE_OPTION_NAMES = [
+  NO_RELATE,
+  NO_UNRELATE,
+  NO_INSERT,
+  NO_UPDATE,
+  NO_DELETE,
+  UPDATE,
+  RELATE,
+  UNRELATE,
+  INSERT_MISSING,
+];
+
 const FetchStrategy = {
   OnlyIdentifiers: 'OnlyIdentifiers',
   Everything: 'Everything',
@@ -34,12 +51,20 @@ const FetchStrategy = {
 };
 
 class GraphOptions {
-  constructor(options) {
+  // `rootRelationPath` is the relation path of the root node of a recursive
+  // upsert in the original graph, against which relation expressions match.
+  constructor(options, rootRelationPath = []) {
     if (options instanceof GraphOptions) {
       this.options = options.options;
+      this.rootRelationPath = options.rootRelationPath;
     } else {
-      this.options = options;
+      this.options = parseRelationExpressions(options);
+      this.rootRelationPath = rootRelationPath;
     }
+
+    // Caches the result of matching relation expressions against relation
+    // paths, by option name and relation path key.
+    this.expressionMatches = new Map();
   }
 
   isFetchStrategy(strategy) {
@@ -190,7 +215,7 @@ class GraphOptions {
 
       if (Array.isArray(value)) {
         newOpt[name] = value
-          .filter((it) => it.startsWith(newRootRelationPath))
+          .filter((it) => it === newRootRelationPath || it.startsWith(`${newRootRelationPath}.`))
           .map((it) => it.slice(newRootRelationPath.length + 1))
           .filter((it) => !!it);
       } else {
@@ -198,13 +223,15 @@ class GraphOptions {
       }
     }
 
-    return new GraphOptions(newOpt);
+    return new GraphOptions(newOpt, [...this.rootRelationPath, ...newRoot.relationPath]);
   }
 
   _hasOption(node, optionName) {
     const option = this.options[optionName];
 
-    if (Array.isArray(option)) {
+    if (isRelationExpression(option)) {
+      return this._matchesRelationExpression(node, optionName, option);
+    } else if (Array.isArray(option)) {
       return option.indexOf(node.relationPathKey) !== -1;
     } else if (typeof option === 'boolean') {
       return option;
@@ -212,10 +239,130 @@ class GraphOptions {
       return false;
     } else {
       throw new Error(
-        `expected ${optionName} option value "${option}" to be an instance of boolean or array of strings`,
+        `expected ${optionName} option value "${option}" to be a boolean, an array of relation paths or a relation expression`,
       );
     }
   }
+
+  // A node matches a relation expression when its relation path leads to a
+  // leaf of the expression, like it would match the same relation paths in an
+  // array: `'movies.reviews'` matches `movies.reviews` but not `movies`.
+  // `'*'` matches all relations below it and recursive expressions like
+  // `'parent.^'` match every level of the recursion. The root has no relation
+  // path and never matches.
+  _matchesRelationExpression(node, optionName, expression) {
+    const relationPath = [...this.rootRelationPath, ...node.relationPath];
+
+    if (relationPath.length === 0) {
+      return false;
+    }
+
+    const relationPathKey = relationPath.join('.');
+
+    let matches = this.expressionMatches.get(optionName);
+
+    if (!matches) {
+      matches = new Map();
+      this.expressionMatches.set(optionName, matches);
+    }
+
+    let isMatch = matches.get(relationPathKey);
+
+    if (isMatch === undefined) {
+      isMatch = matchesRelationPath(expression, relationPath);
+      matches.set(relationPathKey, isMatch);
+    }
+
+    return isMatch;
+  }
+}
+
+// Parses the string values of the node options into relation expressions,
+// once per operation.
+function parseRelationExpressions(options) {
+  let parsedOptions = options;
+
+  for (const optionName of NODE_OPTION_NAMES) {
+    const option = options[optionName];
+
+    if (isString(option)) {
+      if (parsedOptions === options) {
+        parsedOptions = { ...options };
+      }
+
+      parsedOptions[optionName] = parseRelationExpression(optionName, option);
+    }
+  }
+
+  return parsedOptions;
+}
+
+function parseRelationExpression(optionName, expression) {
+  const createError = (message) => {
+    return new Error(
+      `invalid relation expression "${expression}" in ${optionName} option: ${message}`,
+    );
+  };
+
+  let parsedExpression;
+
+  try {
+    parsedExpression = RelationExpression.create(expression);
+  } catch (err) {
+    throw createError(err.message);
+  }
+
+  if (parsedExpression.isEmpty && !parsedExpression.node.$allRecursive) {
+    throw createError('the expression is empty');
+  }
+
+  // Relation paths are matched by relation name, so aliases would never match.
+  const alias = findAlias(parsedExpression.node);
+
+  if (alias) {
+    throw createError(`aliases like "${alias.$relation} as ${alias.$name}" are not supported`);
+  }
+
+  return parsedExpression;
+}
+
+function findAlias(node) {
+  for (const childName of node.$childNames) {
+    const child = node[childName];
+
+    if (child.$name !== child.$relation) {
+      return child;
+    }
+
+    const alias = findAlias(child);
+
+    if (alias) {
+      return alias;
+    }
+  }
+
+  return null;
+}
+
+function matchesRelationPath(expression, relationPath) {
+  for (const relationName of relationPath) {
+    expression = expression.childExpression(relationName);
+
+    if (!expression) {
+      return false;
+    }
+  }
+
+  // Below `*`, the expression stays on the same node with increasing depth.
+  if (expression.node.$allRecursive) {
+    return expression.recursionDepth > 0;
+  } else {
+    return expression.isEmpty;
+  }
+}
+
+function isRelationExpression(value) {
+  return !!value && value.isObjectionRelationExpression === true;
 }
 
 function getCurrentNode(node, graphData) {

package/lib/queryBuilder/graph/GraphUpsert.js

@@ -57,6 +57,7 @@ class GraphUpsert {
     return createGraphData(builder, graphOptions, graph)
       .then(checkForErrors(builder))
       .then(pruneGraphs())
+      .then(checkForJoinTableRelatedTableErrors(builder))
       .then(executeOperations(builder))
       .then(returnResult(this.objects, this.isArray));
   }
@@ -66,6 +67,11 @@ class GraphUpsert {
 // default behaviour instead (#84). A warning is logged once per option.
 // TODO: Throw an error instead in objection 4.0.
 function warnOnUnknownOptions(upsertOptions) {
+  // Recursive upserts pass on the already checked options of their parent.
+  if (upsertOptions instanceof GraphOptions) {
+    return;
+  }
+
   for (const name of Object.keys(upsertOptions)) {
     if (!OPTION_NAMES.includes(name)) {
       deprecate(
@@ -249,6 +255,35 @@ function checkForErrors(builder) {
   };
 }
 
+// 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',
+        );
+      }
+    }
+
+    return graphData;
+  };
+}
+
 function checkForNotFoundErrors(graphData, builder) {
   const { graphOptions, currentGraph, graph } = graphData;
 

package/lib/queryBuilder/graph/patch/GraphPatchAction.js

@@ -85,6 +85,9 @@ class GraphPatchAction extends GraphAction {
 
     const updateBuilder = this._createBuilder(node)
       .childQueryOf(builder, childQueryOptions())
+      // The current graph was fetched through the relations, so the patched
+      // models are known to be related to their parents.
+      .internalOptions({ skipRelationFilter: true })
       .copyFrom(builder, GraphAction.ReturningAllSelector);
 
     if (hasBeforeUpdate) {