objection 3.9.1 → 4.0.0-rc.1

package/lib/relations/RelationFindOperation.js

@@ -1,9 +1,9 @@
-'use strict';
+import { FindOperation } from '../queryBuilder/operations/FindOperation.js';
+import { RangeOperation } from '../queryBuilder/operations/RangeOperation.js';
+import { asArray } from '../utils/objectUtils.js';
+import { hasAliasSelection } from '../queryBuilder/operations/select/Selection.js';
 
-const { FindOperation } = require('../queryBuilder/operations/FindOperation');
-const { warnOnce } = require('../utils/warnings');
-
-class RelationFindOperation extends FindOperation {
+export class RelationFindOperation extends FindOperation {
   constructor(name, opt) {
     super(name, opt);
 
@@ -13,6 +13,8 @@ class RelationFindOperation extends FindOperation {
     this.assignResultToOwner = true;
     this.relationProperty = opt.relationProperty || this.relation.name;
     this.alias = null;
+    // Shared with the clones that execute the query, for `assignResult()`.
+    this.ownerKeyByRelated = new Map();
   }
 
   onBuild(builder) {
@@ -20,7 +22,7 @@ class RelationFindOperation extends FindOperation {
     this.relation.findQuery(builder, this.owner);
 
     if (this.owner.isModels) {
-      this.warnOnInvalidOwnerProps();
+      this.checkOwnerProps();
 
       if (this.assignResultToOwner) {
         this.selectMissingJoinColumns(builder);
@@ -29,51 +31,82 @@ class RelationFindOperation extends FindOperation {
   }
 
   onAfter2(_, related) {
-    const isOneToOne = this.relation.isOneToOne();
-
     if (this.assignResultToOwner && this.owner.isModels) {
-      const owners = this.owner.modelArray;
-      const relatedByOwnerId = new Map();
-
-      for (let i = 0, l = related.length; i < l; ++i) {
-        const rel = related[i];
-        const key = this.relation.relatedProp.propKey(rel);
-        let arr = relatedByOwnerId.get(key);
+      this.checkRelatedProps(related);
+      // Read the owner keys before the join columns that were only selected
+      // for them are omitted from the related models.
+      for (const rel of related) {
+        this.ownerKeyByRelated.set(rel, this.getOwnerKey(rel));
+      }
+    }
 
-        if (!arr) {
-          arr = [];
-          relatedByOwnerId.set(key, arr);
-        }
+    return related;
+  }
 
-        arr.push(rel);
-      }
+  onAfter3(builder, related) {
+    const isOneToOne = this.relation.isOneToOne();
 
-      this.warnOnMissingRelatedProps(related);
+    if (!this.alwaysReturnArray && isOneToOne && related.length <= 1) {
+      related = related[0] || undefined;
+    }
 
-      for (let i = 0, l = owners.length; i < l; ++i) {
-        const own = owners[i];
-        const key = this.relation.ownerProp.propKey(own);
-        const related = relatedByOwnerId.get(key);
+    return super.onAfter3(builder, related);
+  }
 
-        if (isOneToOne) {
-          own[this.relationProperty] = (related && related[0]) || null;
-        } else {
-          own[this.relationProperty] = related || [];
+  // Assign what the query returns to the owners, once it has resolved, after its
+  // `afterFind()` hook and `runAfter()` callbacks, which may filter or reorder
+  // the related models. `range()` and `page()` wrap the models in `{ results, total }`.
+  assignResult(builder, result) {
+    if (this.assignResultToOwner && this.owner.isModels) {
+      const related = asArray(builder.has(RangeOperation) ? result.results : result);
+
+      for (const rel of related) {
+        if (!this.ownerKeyByRelated.has(rel)) {
+          throw new Error(
+            `Unable to assign the result to relation "${this.relation.name}" of ` +
+              `${this.relation.ownerModelClass.name}: afterFind() and runAfter() can only ` +
+              'return the related models that the query found, filtered or reordered.',
+          );
         }
       }
+
+      this.assignRelated(related);
     }
 
-    return related;
+    return result;
   }
 
-  onAfter3(builder, related) {
+  // @overridable
+  assignRelated(related) {
     const isOneToOne = this.relation.isOneToOne();
+    const relatedByOwnerKey = new Map();
 
-    if (!this.alwaysReturnArray && isOneToOne && related.length <= 1) {
-      related = related[0] || undefined;
+    for (const rel of related) {
+      const key = this.ownerKeyByRelated.get(rel);
+      let arr = relatedByOwnerKey.get(key);
+
+      if (!arr) {
+        arr = [];
+        relatedByOwnerKey.set(key, arr);
+      }
+
+      arr.push(rel);
     }
 
-    return super.onAfter3(builder, related);
+    for (const owner of this.owner.modelArray) {
+      const related = relatedByOwnerKey.get(this.relation.ownerProp.propKey(owner));
+
+      if (isOneToOne) {
+        owner[this.relationProperty] = (related && related[0]) || null;
+      } else {
+        owner[this.relationProperty] = related || [];
+      }
+    }
+  }
+
+  // The key of the owner that a related model belongs to:
+  getOwnerKey(related) {
+    return this.relation.relatedProp.propKey(related);
   }
 
   // The expressions of the result rows in `table` that hold the keys of their
@@ -84,74 +117,69 @@ class RelationFindOperation extends FindOperation {
       .map((ref) => ref.table(table).toKnexRaw(builder));
   }
 
-  warnOnInvalidOwnerProps() {
-    this.warnOnMissingOwnerProps();
-
-    if (this.assignResultToOwner) {
-      this.warnOnArrayOwnerProps();
-    }
-  }
-
-  // Owner models without the join columns, e.g. loaded with a partial
-  // `select()`, silently get no related models (#1832). Only `undefined`
-  // is reported, as `null` is a legit value for a missing relation, and
-  // owner props that may legitimately be unset are skipped (#132).
-  // TODO: Consider throwing an error instead in objection 4.0 (#272).
-  warnOnMissingOwnerProps() {
-    const { ownerProp } = this.relation;
+  checkOwnerProps() {
+    const { name, ownerModelClass, ownerProp } = this.relation;
+    const owners = this.owner.modelArray;
 
     for (let c = 0, lc = ownerProp.size; c < lc; ++c) {
-      if (this.relation.isOptionalOwnerProp(c)) {
-        continue;
-      }
-
-      if (this.owner.modelArray.some((owner) => ownerProp.getProp(owner, c) === undefined)) {
-        warnOnce(
-          `Fetching relation "${this.relation.name}" of ${this.relation.ownerModelClass.name}: ` +
-            `some owner models are missing the join property "${ownerProp.propDescription(c)}", ` +
-            'so no related models are found for them. Select the column in the owner query.',
+      // Owner models loaded without the join columns, e.g. with a partial
+      // `select()`, would silently get no related models (#1832). Models built
+      // in memory, e.g. returned by `insert()`, may not have them yet (#132).
+      // Check the columns, not the values of JSON field expressions in them,
+      // which a JSON document may leave out.
+      const prop = ownerProp.props[c];
+
+      if (owners.some((owner) => owner.$$isFromDatabase && owner[prop] === undefined)) {
+        throw new Error(
+          `Unable to fetch relation "${name}" of ${ownerModelClass.name}: some owner models ` +
+            'loaded from the database are missing the join property ' +
+            `"${ownerProp.propDescription(c)}". Select the column in the owner query.`,
         );
       }
     }
+
+    if (this.assignResultToOwner) {
+      this.checkOwnerKeys();
+    }
   }
 
-  // Owner join properties holding an array of keys, e.g. a JSON array column,
-  // aren't supported: The query finds the related models, but they can't be
-  // assigned to their owners, so all owners silently get no related models
-  // (#2667). `$relatedQuery()` without assigning the results isn't affected.
-  warnOnArrayOwnerProps() {
-    const { ownerProp, joinTable } = this.relation;
-    // Relations through a join table already are the alternative to arrays.
-    const advice = joinTable
-      ? 'Map the relation from a column that holds a single key instead.'
-      : 'Use a ManyToManyRelation through a join table instead.';
+  // Related models can't be assigned to owner props holding an array of keys,
+  // e.g. a JSON array column (#2667). `$relatedQuery()` without assigning the
+  // results isn't affected.
+  // @overridable
+  checkOwnerKeys() {
+    const { name, ownerModelClass, ownerProp, joinTable } = this.relation;
+    const owners = this.owner.modelArray;
 
     for (let c = 0, lc = ownerProp.size; c < lc; ++c) {
-      if (this.owner.modelArray.some((owner) => Array.isArray(ownerProp.getProp(owner, c)))) {
-        warnOnce(
-          `Fetching relation "${this.relation.name}" of ${this.relation.ownerModelClass.name}: ` +
-            `the join property "${ownerProp.propDescription(c)}" of some owner models holds ` +
-            'an array, which is not supported, so no related models are found for them. ' +
-            advice,
+      if (owners.some((owner) => Array.isArray(ownerProp.getProp(owner, c)))) {
+        throw new Error(
+          `Unable to fetch relation "${name}" of ${ownerModelClass.name}: the join property ` +
+            `"${ownerProp.propDescription(c)}" of some owner models holds an array, which is ` +
+            `not supported. ${
+              joinTable
+                ? 'Map the relation from a column that holds a single key instead.'
+                : 'Use a BelongsToManyRelation or a ManyToManyRelation through a join table instead.'
+            }`,
         );
       }
     }
   }
 
   // Related models without the join properties can't be assigned to their
-  // owners and are silently dropped (#2258). This happens for example when the
-  // relation mapping uses column names but the rows come back with different
-  // property names, e.g. snake_case mappings with `knexSnakeCaseMappers`.
-  warnOnMissingRelatedProps(related) {
-    const { relatedProp } = this.relation;
+  // owners (#2258). This happens for example when the relation mapping uses
+  // column names but the rows come back with different property names, e.g.
+  // snake_case mappings with `knexSnakeCaseMappers`.
+  checkRelatedProps(related) {
+    const { name, ownerModelClass, relatedProp } = this.relation;
 
     for (let c = 0, lc = relatedProp.size; c < lc; ++c) {
       if (related.some((rel) => relatedProp.getProp(rel, c) === undefined)) {
-        warnOnce(
-          `Fetching relation "${this.relation.name}" of ${this.relation.ownerModelClass.name}: ` +
-            `some related models are missing the join property "${relatedProp.propDescription(c)}", ` +
-            'so they are not assigned to any owner. Check that the relation mapping uses the ' +
-            'property names of the models, e.g. camelCase names when using knexSnakeCaseMappers.',
+        throw new Error(
+          `Unable to fetch relation "${name}" of ${ownerModelClass.name}: some related models ` +
+            `are missing the join property "${relatedProp.propDescription(c)}". Check that the ` +
+            'relation mapping uses the property names of the models, e.g. camelCase names when ' +
+            'using knexSnakeCaseMappers.',
         );
       }
     }
@@ -166,7 +194,11 @@ class RelationFindOperation extends FindOperation {
       const prop = relatedProp.props[c];
       const col = relatedProp.cols[c];
 
-      if (!builder.hasSelectionAs(fullCol, col) && addedSelects.indexOf(fullCol) === -1) {
+      if (
+        !builder.hasSelectionAs(fullCol, col) &&
+        !hasAliasSelection(builder, col) &&
+        addedSelects.indexOf(fullCol) === -1
+      ) {
         this.omitFromResult(builder, prop);
         addedSelects.push(fullCol);
       }
@@ -198,11 +230,8 @@ class RelationFindOperation extends FindOperation {
     clone.assignResultToOwner = this.assignResultToOwner;
     clone.relationProperty = this.relationProperty;
     clone.alias = this.alias;
+    clone.ownerKeyByRelated = this.ownerKeyByRelated;
 
     return clone;
   }
 }
-
-module.exports = {
-  RelationFindOperation,
-};

package/lib/relations/RelationInsertOperation.js

@@ -1,8 +1,6 @@
-'use strict';
+import { InsertOperation } from '../queryBuilder/operations/InsertOperation.js';
 
-const { InsertOperation } = require('../queryBuilder/operations/InsertOperation');
-
-class RelationInsertOperation extends InsertOperation {
+export class RelationInsertOperation extends InsertOperation {
   constructor(name, opt) {
     super(name, opt);
 
@@ -39,7 +37,3 @@ class RelationInsertOperation extends InsertOperation {
     return clone;
   }
 }
-
-module.exports = {
-  RelationInsertOperation,
-};

package/lib/relations/RelationOwner.js

@@ -1,8 +1,6 @@
-'use strict';
-
-const { isObject, asArray, asSingle, uniqBy } = require('../utils/objectUtils');
-const { normalizeIds } = require('../utils/normalizeIds');
-const { valuesKey } = require('../model/modelValues');
+import { isObject, asArray, asSingle, uniqBy } from '../utils/objectUtils.js';
+import { normalizeIds } from '../utils/normalizeIds.js';
+import { valuesKey } from '../model/modelValues.js';
 
 const Type = {
   Models: 'Models',
@@ -11,7 +9,7 @@ const Type = {
   Identifiers: 'Identifiers',
 };
 
-class RelationOwner {
+export class RelationOwner {
   constructor(owner) {
     this.owner = owner;
     this.type = detectType(owner);
@@ -224,10 +222,6 @@ function isIdProp(relationProp) {
   return idProp.props.every((prop, i) => prop === relationProp.props[i]);
 }
 
-function isOwnerModelClassQuery(query, relation) {
+export function isOwnerModelClassQuery(query, relation) {
   return query.modelClass().getTableName() === relation.ownerModelClass.getTableName();
 }
-
-module.exports = {
-  RelationOwner,
-};

package/lib/relations/RelationProperty.js

@@ -1,8 +1,6 @@
-'use strict';
-
-const { asArray, isObject, uniqBy, get, set } = require('../utils/objectUtils');
-const { ref: createRef } = require('../queryBuilder/ReferenceBuilder');
-const { valuesKey } = require('../model/modelValues');
+import { asArray, isObject, uniqBy, get, set } from '../utils/objectUtils.js';
+import { ref as createRef } from '../queryBuilder/ReferenceBuilder.js';
+import { valuesKey } from '../model/modelValues.js';
 
 class ModelNotFoundError extends Error {
   constructor(tableName) {
@@ -25,7 +23,7 @@ class InvalidReferenceError extends Error {
 // A relation property can be a single column, an array of columns
 // (composite key) a json column reference, an array of json column
 // references or any combination of the above.
-class RelationProperty {
+export class RelationProperty {
   // references must be a reference string like `Table.column:maybe.some.json[1].path`.
   // or an array of such references (composite key).
   //
@@ -235,7 +233,3 @@ function createPatcher(ref, path) {
     return (patch, value) => (patch[ref.expression] = value);
   }
 }
-
-module.exports = {
-  RelationProperty,
-};

package/lib/relations/RelationUpdateOperation.js

@@ -1,9 +1,6 @@
-'use strict';
+import { UpdateOperation } from '../queryBuilder/operations/UpdateOperation.js';
 
-const { UpdateOperation } = require('../queryBuilder/operations/UpdateOperation');
-const { RelationFindOperation } = require('./RelationFindOperation');
-
-class RelationUpdateOperation extends UpdateOperation {
+export class RelationUpdateOperation extends UpdateOperation {
   constructor(name, opt) {
     super(name, opt);
 
@@ -17,14 +14,7 @@ class RelationUpdateOperation extends UpdateOperation {
     this.relation.findQuery(builder, this.owner);
   }
 
-  toFindOperation() {
-    return new RelationFindOperation('find', {
-      relation: this.relation,
-      owner: this.owner,
-    });
+  toFindOperation(builder) {
+    return this.relation.find(builder, this.owner);
   }
 }
-
-module.exports = {
-  RelationUpdateOperation,
-};

package/lib/relations/RelationWriteResultOperation.js

@@ -0,0 +1,15 @@
+import { QueryBuilderOperation } from '../queryBuilder/operations/QueryBuilderOperation.js';
+
+// Resolves the rows that writes through `$relatedQuery()` of a to-one relation
+// return with `returning()` like its finds: one model, or `undefined`.
+export class RelationWriteResultOperation extends QueryBuilderOperation {
+  onAfter3(_, result) {
+    return Array.isArray(result) && result.length <= 1 ? result[0] : result;
+  }
+
+  // Find queries of the write, e.g. `asFindQuery()` in hooks, resolve to all
+  // rows that it writes.
+  toFindOperation() {
+    return null;
+  }
+}

package/lib/relations/belongsToMany/BelongsToManyDeleteOperation.js

@@ -0,0 +1,23 @@
+import { RelationDeleteOperation } from '../RelationDeleteOperation.js';
+
+export class BelongsToManyDeleteOperation extends RelationDeleteOperation {
+  // Find the keys of the rows to delete first, to remove them from the owners
+  // after the delete.
+  async onBefore2(builder, result) {
+    result = await super.onBefore2(builder, result);
+
+    if (builder.isExecutable()) {
+      this.keys = await this.relation.findKeys(builder, this.owner);
+    }
+
+    return result;
+  }
+
+  async onAfter1(builder, result) {
+    if (this.keys) {
+      await this.relation.updateKeys(builder, this.owner, { remove: this.keys });
+    }
+
+    return result;
+  }
+}

package/lib/relations/belongsToMany/BelongsToManyFindOperation.js

@@ -0,0 +1,35 @@
+import { RelationFindOperation } from '../RelationFindOperation.js';
+import { valuesKey } from '../../model/modelValues.js';
+import { groupBy } from '../../utils/objectUtils.js';
+
+export class BelongsToManyFindOperation extends RelationFindOperation {
+  // Arrays of keys are what the owner props hold here, see `getKeys()`.
+  // @override
+  checkOwnerKeys() {}
+
+  // A related model belongs to every owner that holds its key. They keep the
+  // order of the query, not the order of the keys in the arrays.
+  // @override
+  assignRelated(related) {
+    const indexByRelated = new Map(related.map((rel, index) => [rel, index]));
+    const relatedByKey = groupBy(related, (rel) => this.ownerKeyByRelated.get(rel));
+
+    for (const owner of this.owner.modelArray) {
+      const keys = new Set(this.relation.getKeys(owner).map((key) => valuesKey([key])));
+
+      owner[this.relationProperty] = [...keys]
+        .flatMap((key) => relatedByKey.get(key) || [])
+        .sort((a, b) => indexByRelated.get(a) - indexByRelated.get(b));
+    }
+  }
+
+  // The related models of all owners come back in one list, without a column
+  // to partition them by owner.
+  // @override
+  ownerKeys() {
+    throw this.relation.createError(
+      'limit(), offset() and first() are not supported for each owner. Pass ' +
+        '`limitPerParent: false` to the graph options to limit all owners together.',
+    );
+  }
+}

package/lib/relations/belongsToMany/BelongsToManyInsertOperation.js

@@ -0,0 +1,28 @@
+import { RelationInsertOperation } from '../RelationInsertOperation.js';
+import { InsertGraphOperation } from '../../queryBuilder/operations/InsertGraphOperation.js';
+import { assignRelated } from '../../model/modelSet.js';
+
+export class BelongsToManyInsertOperation extends RelationInsertOperation {
+  async onAfter1(builder, ret) {
+    const inserted = await super.onAfter1(builder, ret);
+
+    // A query resolved without executing it, e.g. with `resolve()`, inserted
+    // nothing. `insertGraph()` resolves the query itself, but always inserts
+    // the graph.
+    if (!builder.isExecutable() && !builder.has(InsertGraphOperation)) {
+      return inserted;
+    }
+
+    if (this.assignResultToOwner && this.owner.isModels) {
+      for (const owner of this.owner.modelArray) {
+        assignRelated(owner, this.relation, inserted, { append: true });
+      }
+    }
+
+    await this.relation.updateKeys(builder, this.owner, {
+      add: this.models.map((model) => this.relation.relatedProp.getProp(model, 0)),
+    });
+
+    return inserted;
+  }
+}

package/lib/relations/belongsToMany/BelongsToManyRelateOperation.js

@@ -0,0 +1,16 @@
+import { normalizeIds } from '../../utils/normalizeIds.js';
+import { RelateOperation } from '../../queryBuilder/operations/RelateOperation.js';
+
+export class BelongsToManyRelateOperation extends RelateOperation {
+  onAdd(_, args) {
+    this.input = args[0];
+    this.ids = normalizeIds(args[0], this.relation.relatedProp, { arrayOutput: true });
+    return true;
+  }
+
+  queryExecutor(builder) {
+    return this.relation.updateKeys(builder, this.owner, {
+      add: this.ids.map(([key]) => key),
+    });
+  }
+}