objection 3.4.0 → 3.5.0

package/lib/queryBuilder/QueryBuilderBase.js

@@ -616,9 +616,14 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
   // whereJson(Not)SupersetOf / whereJson(Not)SubsetOf are now supported by knex >= 1.0, but for now
   // objection handles them differently and only for postgres.
   // Changing them to utilize knex methods directly may require a major version bump and upgrade guide.
+  // On MySQL, the simple `(column, object | array)` form is passed on to knex (ditojs#113).
   whereJsonSupersetOf(...args) {
     return this.addOperation(
-      new WhereJsonPostgresOperation('whereJsonSupersetOf', { operator: '@>', bool: 'and' }),
+      new WhereJsonPostgresOperation('whereJsonSupersetOf', {
+        operator: '@>',
+        bool: 'and',
+        knexMethod: 'whereJsonSupersetOf',
+      }),
       args,
     );
   }
@@ -629,7 +634,11 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
 
   orWhereJsonSupersetOf(...args) {
     return this.addOperation(
-      new WhereJsonPostgresOperation('orWhereJsonSupersetOf', { operator: '@>', bool: 'or' }),
+      new WhereJsonPostgresOperation('orWhereJsonSupersetOf', {
+        operator: '@>',
+        bool: 'or',
+        knexMethod: 'whereJsonSupersetOf',
+      }),
       args,
     );
   }
@@ -640,13 +649,14 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
         operator: '@>',
         bool: 'and',
         prefix: 'not',
+        knexMethod: 'whereJsonNotSupersetOf',
       }),
       args,
     );
   }
 
   andWhereJsonNotSupersetOf(...args) {
-    return this.andWhereJsonNotSupersetOf(...args);
+    return this.whereJsonNotSupersetOf(...args);
   }
 
   orWhereJsonNotSupersetOf(...args) {
@@ -655,6 +665,7 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
         operator: '@>',
         bool: 'or',
         prefix: 'not',
+        knexMethod: 'whereJsonNotSupersetOf',
       }),
       args,
     );
@@ -662,7 +673,11 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
 
   whereJsonSubsetOf(...args) {
     return this.addOperation(
-      new WhereJsonPostgresOperation('whereJsonSubsetOf', { operator: '<@', bool: 'and' }),
+      new WhereJsonPostgresOperation('whereJsonSubsetOf', {
+        operator: '<@',
+        bool: 'and',
+        knexMethod: 'whereJsonSubsetOf',
+      }),
       args,
     );
   }
@@ -673,7 +688,11 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
 
   orWhereJsonSubsetOf(...args) {
     return this.addOperation(
-      new WhereJsonPostgresOperation('orWhereJsonSubsetOf', { operator: '<@', bool: 'or' }),
+      new WhereJsonPostgresOperation('orWhereJsonSubsetOf', {
+        operator: '<@',
+        bool: 'or',
+        knexMethod: 'whereJsonSubsetOf',
+      }),
       args,
     );
   }
@@ -684,6 +703,7 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
         operator: '<@',
         bool: 'and',
         prefix: 'not',
+        knexMethod: 'whereJsonNotSubsetOf',
       }),
       args,
     );
@@ -699,6 +719,7 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
         operator: '<@',
         bool: 'or',
         prefix: 'not',
+        knexMethod: 'whereJsonNotSubsetOf',
       }),
       args,
     );
@@ -772,20 +793,34 @@ class QueryBuilderBase extends QueryBuilderOperationSupport {
     );
   }
 
+  // Not passed on to knex like `whereJsonSupersetOf()`, as MySQL's `json_contains()`
+  // also matches `{}` in arrays of objects.
   whereJsonIsArray(fieldExpression) {
-    return this.whereJsonSupersetOf(fieldExpression, []);
+    return this.addOperation(
+      new WhereJsonPostgresOperation('whereJsonSupersetOf', { operator: '@>', bool: 'and' }),
+      [fieldExpression, []],
+    );
   }
 
   orWhereJsonIsArray(fieldExpression) {
-    return this.orWhereJsonSupersetOf(fieldExpression, []);
+    return this.addOperation(
+      new WhereJsonPostgresOperation('orWhereJsonSupersetOf', { operator: '@>', bool: 'or' }),
+      [fieldExpression, []],
+    );
   }
 
   whereJsonIsObject(fieldExpression) {
-    return this.whereJsonSupersetOf(fieldExpression, {});
+    return this.addOperation(
+      new WhereJsonPostgresOperation('whereJsonSupersetOf', { operator: '@>', bool: 'and' }),
+      [fieldExpression, {}],
+    );
   }
 
   orWhereJsonIsObject(fieldExpression) {
-    return this.orWhereJsonSupersetOf(fieldExpression, {});
+    return this.addOperation(
+      new WhereJsonPostgresOperation('orWhereJsonSupersetOf', { operator: '@>', bool: 'or' }),
+      [fieldExpression, {}],
+    );
   }
 
   whereColumn(...args) {

package/lib/queryBuilder/ReferenceBuilder.js

@@ -5,6 +5,7 @@ const {
   toPostgresJsonPathLiteral,
 } = require('../utils/parseFieldExpression');
 const { isObject } = require('../utils/objectUtils');
+const { warnIfNotPostgres } = require('./operations/jsonApi/postgresJsonApi');
 
 class ReferenceBuilder {
   constructor(expr) {
@@ -163,7 +164,13 @@ class ReferenceBuilder {
   }
 
   toKnexRaw(builder) {
-    return builder.knex().raw(...this._createRawArgs(builder));
+    const knex = builder.knex();
+
+    if (this._parsedExpr.access.length > 0) {
+      warnIfNotPostgres(knex);
+    }
+
+    return knex.raw(...this._createRawArgs(builder));
   }
 
   _parseExpression(expr) {

package/lib/queryBuilder/graph/insert/GraphInsertAction.js

@@ -208,7 +208,11 @@ class GraphInsertAction extends GraphAction {
     return Promise.all(
       nodes.map((node) => {
         if (node.parentEdge) {
-          return node.parentEdge.relation.beforeInsert(node.obj, parentBuilder.context());
+          return node.parentEdge.relation.beforeInsert(
+            node.obj,
+            parentBuilder.context(),
+            node.parentNode.obj,
+          );
         } else {
           return null;
         }

package/lib/queryBuilder/join/RelationJoiner.js

@@ -2,6 +2,7 @@
 
 const { uniqBy } = require('../../utils/objectUtils');
 const { Selection } = require('../operations/select/Selection');
+const { SelectOperation } = require('../operations/select/SelectOperation');
 const { createModifier } = require('../../utils/createModifier');
 const { map: mapPromise } = require('../../utils/promiseUtils');
 const { ValidationErrorType } = require('../../model/ValidationError');
@@ -124,7 +125,7 @@ class RelationJoiner {
     // also contain selects.
     userSelectQuery.modify(tableNode.relation.modify);
 
-    if (selectsOnlyAliasesKeepingSelectAll(userSelectQuery.findAllSelections())) {
+    if (selectsOnlyAliasesKeepingSelectAll(findJoinSelections(userSelectQuery))) {
       // All columns are selected from the joined subquery in the main query,
       // so the subquery needs to select them too.
       subqueryToJoin.select(`${subqueryToJoin.tableRef()}.*`);
@@ -268,7 +269,7 @@ function ensureIdAndRelationPropsAreSelected({ builder, tableNode }) {
   ];
 
   const selectStrings = uniqBy(cols)
-    .filter((col) => !builder.hasSelectionAs(col, col))
+    .filter((col) => !hasSelectionAs(builder, col))
     .map((col) => `${tableRef}.${col}`);
 
   return builder.select(selectStrings);
@@ -276,7 +277,7 @@ function ensureIdAndRelationPropsAreSelected({ builder, tableNode }) {
 
 function getSelectionsForNode({ builder, tableNode, userSelectQueries }) {
   const userSelectQuery = userSelectQueries.get(tableNode);
-  const userSelections = userSelectQuery.findAllSelections();
+  const userSelections = findUserSelections(userSelectQuery, tableNode);
   const userSelectedAllColumns = isSelectAllSelectionSet(userSelections);
 
   let selections = [];
@@ -298,7 +299,7 @@ function getSelectionsForNode({ builder, tableNode, userSelectQueries }) {
     const idSelections = getIdSelectionsForNode({ tableNode });
 
     for (const idSelection of idSelections) {
-      if (!userSelectQuery.hasSelectionAs(idSelection.column, idSelection.column)) {
+      if (!hasUserSelectionAs(userSelectQuery, tableNode, idSelection.column)) {
         selections.push(idSelection);
         internalSelections.push(idSelection);
       }
@@ -318,6 +319,54 @@ function getSelectionsForNode({ builder, tableNode, userSelectQueries }) {
   };
 }
 
+// Like `builder.findAllSelections()`, but aggregates select their aliases
+// instead of the columns they're passed. Aggregates without an alias are left
+// out, as their column name differs between databases.
+function findJoinSelections(builder) {
+  let selections = [];
+
+  builder.forEachOperation(true, (op) => {
+    if (op.constructor === SelectOperation) {
+      selections = selections.concat(op.aggregateSelections || op.selections);
+    }
+  });
+
+  return selections;
+}
+
+// Like `builder.hasSelectionAs(column, column)`, but ignoring the columns
+// passed to aggregates, as they don't select them.
+function hasSelectionAs(builder, column) {
+  if (builder.has(isAggregateOperation)) {
+    // Explicit, as a query with only aggregates doesn't select all columns.
+    return builder.clone().clear(isAggregateOperation).hasSelectionAs(column, column, true);
+  } else {
+    return builder.hasSelectionAs(column, column);
+  }
+}
+
+// Only the joined subqueries select aggregates by their aliases. The root
+// query keeps treating the columns passed to them as selected.
+function findUserSelections(builder, tableNode) {
+  if (tableNode.parentNode) {
+    return findJoinSelections(builder);
+  } else {
+    return builder.findAllSelections();
+  }
+}
+
+function hasUserSelectionAs(builder, tableNode, column) {
+  if (tableNode.parentNode) {
+    return hasSelectionAs(builder, column);
+  } else {
+    return builder.hasSelectionAs(column, column);
+  }
+}
+
+function isAggregateOperation(op) {
+  return op.constructor === SelectOperation && op.aggregateSelections !== null;
+}
+
 function mapUserSelectionsFromSubqueryToMainQuery({ userSelections, tableNode }) {
   return userSelections.filter(isNotSelectAll).map((selection) => {
     return new Selection(

package/lib/queryBuilder/operations/InsertGraphOperation.js

@@ -63,7 +63,12 @@ class InsertGraphOperation extends DelegateOperation {
     if (this.relation) {
       // We still need to call the relation before insert hook if the the
       // delegate operation is a RelationInsertOperation.
-      return this.relation.executeBeforeInsert(this.models, builder.context(), result);
+      return this.relation.executeBeforeInsert(
+        this.models,
+        builder.context(),
+        result,
+        this.delegate.ownerModel,
+      );
     } else {
       return result;
     }

package/lib/queryBuilder/operations/UpdateOperation.js

@@ -5,6 +5,7 @@ const { isEmpty } = require('../../utils/objectUtils');
 const { toPostgresJsonPathLiteral } = require('../../utils/parseFieldExpression');
 const { isKnexRaw, isKnexQueryBuilder } = require('../../utils/knexUtils');
 const { QueryBuilderOperation } = require('./QueryBuilderOperation');
+const { warnIfNotPostgres } = require('./jsonApi/postgresJsonApi');
 const { StaticHookArguments } = require('../StaticHookArguments');
 
 class UpdateOperation extends QueryBuilderOperation {
@@ -103,6 +104,7 @@ function convertFieldExpressionsToRaw(builder, model, json) {
     if (key.indexOf(':') > -1) {
       // 'col:attr' : ref('other:lol') is transformed to
       // "col" : raw(`jsonb_set("col", '{attr}', to_jsonb("other"#>'{lol}'), true)`)
+      warnIfNotPostgres(knex);
 
       let parsed = ref(key);
       let jsonPath = toPostgresJsonPathLiteral(parsed.parsedExpr.access);

package/lib/queryBuilder/operations/jsonApi/WhereJsonHasPostgresOperation.js

@@ -5,6 +5,7 @@ const { ObjectionToKnexConvertingOperation } = require('../ObjectionToKnexConver
 
 class WhereJsonHasPostgresOperation extends ObjectionToKnexConvertingOperation {
   onBuildKnex(knexBuilder, builder) {
+    jsonApi.warnIfNotPostgres(builder.knex());
     const args = this.getKnexArgs(builder);
 
     const rawArgs = jsonApi.whereJsonFieldRightStringArrayOnLeftQuery(

package/lib/queryBuilder/operations/jsonApi/WhereJsonNotObjectPostgresOperation.js

@@ -5,6 +5,7 @@ const { ObjectionToKnexConvertingOperation } = require('../ObjectionToKnexConver
 
 class WhereJsonNotObjectPostgresOperation extends ObjectionToKnexConvertingOperation {
   onBuildKnex(knexBuilder, builder) {
+    jsonApi.warnIfNotPostgres(builder.knex());
     return this.whereJsonNotObject(knexBuilder, builder.knex(), this.getKnexArgs(builder)[0]);
   }
 

package/lib/queryBuilder/operations/jsonApi/WhereJsonPostgresOperation.js

@@ -2,9 +2,28 @@
 
 const jsonApi = require('./postgresJsonApi');
 const { ObjectionToKnexConvertingOperation } = require('../ObjectionToKnexConvertingOperation');
+const { parseFieldExpression } = require('../../../utils/parseFieldExpression');
+const { isPlainObject, isString, isFunction } = require('../../../utils/objectUtils');
+const { isMySql } = require('../../../utils/knexUtils');
 
 class WhereJsonPostgresOperation extends ObjectionToKnexConvertingOperation {
   onBuildKnex(knexBuilder, builder) {
+    const knex = builder.knex();
+
+    if (isMySql(knex) && this.canDelegateToKnex(knexBuilder)) {
+      // On MySQL, knex's version of the method works (ditojs#113). The `or`
+      // variants are wrapped in `orWhere()`, as knex < 3 ignores their `or`.
+      const [column, value] = this.getKnexArgs(builder);
+      const { knexMethod } = this.opt;
+
+      if (this.opt.bool === 'or') {
+        return knexBuilder.orWhere((qb) => qb[knexMethod](column, value));
+      } else {
+        return knexBuilder[knexMethod](column, value);
+      }
+    }
+
+    jsonApi.warnIfNotPostgres(knex);
     const args = this.getKnexArgs(builder);
 
     const rawArgs = jsonApi.whereJsonbRefOnLeftJsonbValOrRefOnRightRawQueryParams(
@@ -22,6 +41,20 @@ class WhereJsonPostgresOperation extends ObjectionToKnexConvertingOperation {
 
     return knexBuilder;
   }
+
+  // Only the simple form with a plain column and a plain object or array value
+  // can be passed on to knex, as knex doesn't understand field expressions.
+  canDelegateToKnex(knexBuilder) {
+    const [column, value] = this.args;
+
+    return (
+      !!this.opt.knexMethod &&
+      isFunction(knexBuilder[this.opt.knexMethod]) &&
+      isString(column) &&
+      parseFieldExpression(column).access.length === 0 &&
+      (isPlainObject(value) || Array.isArray(value))
+    );
+  }
 }
 
 module.exports = {

package/lib/queryBuilder/operations/jsonApi/postgresJsonApi.js

@@ -2,7 +2,8 @@
 
 const parser = require('../../../utils/parseFieldExpression');
 const { asArray, isObject, isString } = require('../../../utils/objectUtils');
-const { isKnexRaw, isKnexQueryBuilder } = require('../../../utils/knexUtils');
+const { isKnexRaw, isKnexQueryBuilder, isPostgres } = require('../../../utils/knexUtils');
+const { deprecate } = require('../../../utils/deprecate');
 
 /**
  * @typedef {String} FieldExpression
@@ -44,6 +45,19 @@ const { isKnexRaw, isKnexQueryBuilder } = require('../../../utils/knexUtils');
  *     not currently supported
  */
 
+// JSON field expressions and the `whereJson*()` methods generate Postgres-only
+// SQL (ditojs#113). As some of it happens to run on other databases, only warn.
+// TODO: Consider throwing an error instead in objection 4.0.
+function warnIfNotPostgres(knex) {
+  if (!isPostgres(knex)) {
+    deprecate(
+      'JSON field expressions and the whereJson*() methods of objection are only supported ' +
+        'on PostgreSQL. Use the JSON methods of knex like whereJsonPath() or jsonExtract() ' +
+        'with other databases.',
+    );
+  }
+}
+
 // Returns the SQL and bindings of a field expression. The column is passed as an
 // identifier binding (`??`), so that knex's `wrapIdentifier` (e.g. used by
 // `knexSnakeCaseMappers()`) is applied to it.
@@ -168,6 +182,7 @@ function normalizeOperator(knex, operator) {
 }
 
 module.exports = {
+  warnIfNotPostgres,
   parseFieldExpression: parseFieldExpression,
   whereJsonbRefOnLeftJsonbValOrRefOnRight: whereJsonbRefOnLeftJsonbValOrRefOnRight,
   whereJsonbRefOnLeftJsonbValOrRefOnRightRawQueryParams:

package/lib/queryBuilder/operations/select/SelectOperation.js

@@ -1,15 +1,30 @@
 'use strict';
 
-const { flatten } = require('../../../utils/objectUtils');
+const { flatten, isString, isPlainObject } = require('../../../utils/objectUtils');
 const { Selection } = require('./Selection');
 const { ObjectionToKnexConvertingOperation } = require('../ObjectionToKnexConvertingOperation');
 
 const COUNT_REGEX = /count/i;
+const ALIAS_REGEX = /\s+as\s+/i;
+
+const AGGREGATE_METHODS = new Set([
+  'count',
+  'countDistinct',
+  'min',
+  'max',
+  'sum',
+  'sumDistinct',
+  'avg',
+  'avgDistinct',
+]);
 
 class SelectOperation extends ObjectionToKnexConvertingOperation {
   constructor(name, opt) {
     super(name, opt);
     this.selections = [];
+    // The selections that aggregates select, by their aliases. `null` for
+    // non-aggregate operations.
+    this.aggregateSelections = AGGREGATE_METHODS.has(name) ? [] : null;
   }
 
   onAdd(builder, args) {
@@ -31,6 +46,12 @@ class SelectOperation extends ObjectionToKnexConvertingOperation {
       }
     }
 
+    if (this.aggregateSelections) {
+      this.aggregateSelections = getAggregateAliases(selections).map(
+        (alias) => new Selection(null, null, alias),
+      );
+    }
+
     return ret;
   }
 
@@ -57,10 +78,27 @@ class SelectOperation extends ObjectionToKnexConvertingOperation {
   clone() {
     const clone = super.clone();
     clone.selections = this.selections.slice();
+    clone.aggregateSelections = this.aggregateSelections && this.aggregateSelections.slice();
     return clone;
   }
 }
 
+// Returns the aliases of the columns an aggregate selects, supporting the same
+// argument forms as knex: `count('col as alias')`, `count('col', { as: 'alias' })`
+// and `count({ alias: 'col' })`. Aggregates without an alias are skipped, as
+// their column name differs between databases.
+function getAggregateAliases([column, options]) {
+  if (isString(column) && ALIAS_REGEX.test(column)) {
+    return [column.split(ALIAS_REGEX)[1].trim()];
+  } else if (isPlainObject(options) && isString(options.as)) {
+    return [options.as];
+  } else if (isPlainObject(column)) {
+    return Object.keys(column);
+  } else {
+    return [];
+  }
+}
+
 module.exports = {
   SelectOperation,
 };

package/lib/relations/Relation.js

@@ -219,8 +219,12 @@ class Relation {
     });
   }
 
-  executeBeforeInsert(models, queryContext, result) {
-    return mapAfterAllReturn(models, (model) => this.beforeInsert(model, queryContext), result);
+  executeBeforeInsert(models, queryContext, result, owner) {
+    return mapAfterAllReturn(
+      models,
+      (model) => this.beforeInsert(model, queryContext, owner),
+      result,
+    );
   }
 
   createError(message) {

package/lib/relations/RelationFindOperation.js

@@ -24,6 +24,7 @@ class RelationFindOperation extends FindOperation {
       this.warnOnMissingOwnerProps();
 
       if (this.assignResultToOwner) {
+        this.warnOnArrayOwnerProps();
         this.selectMissingJoinColumns(builder);
       }
     }
@@ -100,6 +101,25 @@ class RelationFindOperation extends FindOperation {
     }
   }
 
+  // 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 } = this.relation;
+
+    for (let c = 0, lc = ownerProp.size; c < lc; ++c) {
+      if (this.owner.modelArray.some((owner) => Array.isArray(ownerProp.getProp(owner, c)))) {
+        deprecate(
+          `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. ' +
+            'Use 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

package/lib/relations/RelationInsertOperation.js

@@ -11,9 +11,21 @@ class RelationInsertOperation extends InsertOperation {
     this.assignResultToOwner = true;
   }
 
+  get ownerModel() {
+    // The owner model passed to the relation's `beforeInsert` hook. Only known
+    // if the query was started from a single model instance.
+    const { owner } = this;
+    return owner && owner.isModels && owner.modelArray.length === 1 ? owner.model : undefined;
+  }
+
   async onBefore2(builder, result) {
     const queryContext = builder.context();
-    result = await this.relation.executeBeforeInsert(this.models, queryContext, result);
+    result = await this.relation.executeBeforeInsert(
+      this.models,
+      queryContext,
+      result,
+      this.ownerModel,
+    );
     return super.onBefore2(builder, result);
   }
 

package/lib/relations/manyToMany/find/ManyToManyFindOperation.js

@@ -2,6 +2,7 @@
 
 const { RelationFindOperation } = require('../../RelationFindOperation');
 const { getTempColumn } = require('../../../utils/tmpColumnUtils');
+const { deprecate } = require('../../../utils/deprecate');
 
 class ManyToManyFindOperation extends RelationFindOperation {
   constructor(name, opt) {
@@ -34,8 +35,12 @@ class ManyToManyFindOperation extends RelationFindOperation {
       }
     }
 
-    if (this.assignResultToOwner && this.owner.isModels) {
-      this.selectMissingJoinColumns(builder);
+    if (this.owner.isModels) {
+      this.warnOnMissingOwnerProps();
+
+      if (this.assignResultToOwner) {
+        this.selectMissingJoinColumns(builder);
+      }
     }
   }
 
@@ -60,6 +65,8 @@ class ManyToManyFindOperation extends RelationFindOperation {
         arr.push(rel);
       }
 
+      this.warnOnMissingRelatedProps(related);
+
       for (let i = 0, l = owners.length; i < l; ++i) {
         const own = owners[i];
         const key = ownerProp.propKey(own);
@@ -76,6 +83,27 @@ class ManyToManyFindOperation extends RelationFindOperation {
     return related;
   }
 
+  // The related models are assigned to their owners by the owner join columns
+  // selected from the join table. If they get lost, e.g. in a custom
+  // `$parseDatabaseJson()`, the related models are silently dropped (#2258).
+  warnOnMissingRelatedProps(related) {
+    const { joinTableOwnerProp } = this.relation;
+
+    for (let c = 0, lc = this.ownerJoinColumnAlias.length; c < lc; ++c) {
+      const alias = this.ownerJoinColumnAlias[c];
+
+      if (related.some((rel) => rel[alias] === undefined)) {
+        deprecate(
+          `Fetching relation "${this.relation.name}" of ${this.relation.ownerModelClass.name}: ` +
+            `some related models are missing the join table column ` +
+            `"${joinTableOwnerProp.propDescription(c)}" selected as "${alias}", so they are not ` +
+            'assigned to any owner. Check that $parseDatabaseJson() and the column name mappers ' +
+            'of the related model keep it.',
+        );
+      }
+    }
+  }
+
   clone() {
     const clone = super.clone();
     clone.ownerJoinColumnAlias = this.ownerJoinColumnAlias.slice();

package/lib/utils/identifierMapping.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { isObject } = require('./objectUtils');
+const { isObject, isPlainObject } = require('./objectUtils');
 
 // Super fast memoize for single argument functions.
 function memoize(func) {
@@ -149,8 +149,9 @@ function mapLastPart(mapper, separator) {
 }
 
 // Returns a function that takes an object as an input and maps the object's keys
-// using `mapper`. If the input is not an object, the input is returned unchanged.
-function keyMapper(mapper) {
+// using `mapper`, and its values using the optional `valueMapper`. If the input
+// is not an object, the input is returned unchanged.
+function keyMapper(mapper, valueMapper) {
   return (obj) => {
     if (!isObject(obj) || Array.isArray(obj)) {
       return obj;
@@ -161,7 +162,7 @@ function keyMapper(mapper) {
 
     for (let i = 0, l = keys.length; i < l; ++i) {
       const key = keys[i];
-      out[mapper(key)] = obj[key];
+      out[mapper(key)] = valueMapper ? valueMapper(obj[key]) : obj[key];
     }
 
     return out;
@@ -189,10 +190,16 @@ function snakeCaseMappers(opt = {}) {
   };
 }
 
-function knexIdentifierMappers({ parse, format, idSeparator = ':' } = {}) {
+function knexIdentifierMappers({ parse, format, idSeparator = ':', mapNestedKeys = false } = {}) {
   const formatId = memoize(mapLastPart(format, idSeparator));
   const parseId = memoize(mapLastPart(parse, idSeparator));
   const parseKeys = keyMapper(parseId);
+  // With `mapNestedKeys`, also map the keys of plain objects one level down, as
+  // in the rows knex returns with its `nestTables: true` option on MySQL:
+  // `{ tableName: { columnName: value } }`.
+  const parseRow = mapNestedKeys
+    ? keyMapper(parseId, (value) => (isPlainObject(value) ? parseKeys(value) : value))
+    : parseKeys;
 
   return {
     wrapIdentifier(identifier, origWrap) {
@@ -204,12 +211,12 @@ function knexIdentifierMappers({ parse, format, idSeparator = ':' } = {}) {
         const output = new Array(result.length);
 
         for (let i = 0, l = result.length; i < l; ++i) {
-          output[i] = parseKeys(result[i]);
+          output[i] = parseRow(result[i]);
         }
 
         return output;
       } else {
-        return parseKeys(result);
+        return parseRow(result);
       }
     },
   };
@@ -219,10 +226,11 @@ function knexSnakeCaseMappers(opt = {}) {
   return knexIdentifierMappers({
     parse: (str) => camelCase(str, opt),
     format: (str) => snakeCase(str, opt),
+    mapNestedKeys: opt.mapNestedKeys,
   });
 }
 
-function knexIdentifierMapping(colToProp) {
+function knexIdentifierMapping(colToProp, { mapNestedKeys } = {}) {
   const propToCol = Object.keys(colToProp).reduce((propToCol, column) => {
     propToCol[colToProp[column]] = column;
     return propToCol;
@@ -231,6 +239,7 @@ function knexIdentifierMapping(colToProp) {
   return knexIdentifierMappers({
     parse: (column) => colToProp[column] || column,
     format: (prop) => propToCol[prop] || prop,
+    mapNestedKeys,
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objection",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "An SQL-friendly ORM for Node.js",
   "main": "lib/objection.js",
   "license": "MIT",

package/typings/objection/index.d.ts

@@ -19,6 +19,11 @@ import { Knex } from 'knex';
 // Export the entire Objection namespace.
 export = Objection;
 
+// Phantom brand of the relation types, used by `TypedRelationMappings`.
+declare const relationKind: unique symbol;
+// Phantom brand of `Generated` properties.
+declare const generated: unique symbol;
+
 declare namespace Objection {
   const raw: RawFunction;
   const val: ValueFunction;
@@ -462,6 +467,65 @@ declare namespace Objection {
           : Expression<F>
         : Expression<F>;
 
+  /**
+   * Marks a model property whose value the database generates, like an
+   * auto-incremented id, a timestamp or a column with a default value. It
+   * reads as T and accepts T, but `Insertable` and `InsertableGraph` treat
+   * the property as optional:
+   *
+   *   id!: Generated<number>;
+   */
+  export type Generated<T> = T extends null | undefined ? T : T & GeneratedBrand;
+
+  interface GeneratedBrand {
+    readonly [generated]?: true;
+  }
+
+  /**
+   * Insert keys are optional for optional, nullable and generated properties.
+   */
+  type OptionalInsertPropertyNames<M> = {
+    [K in keyof M]-?: {} extends Pick<M, K>
+      ? K
+      : null extends M[K]
+        ? K
+        : typeof generated extends keyof NonNullable<M[K]>
+          ? K
+          : never;
+  }[keyof M];
+
+  type InsertablePropertyNames<M> = Exclude<DataPropertyNames<M>, RelationPropertyNames<M>>;
+
+  /**
+   * The data to insert a model M with `insert()`. Unlike `PartialModelObject`,
+   * all properties are required except optional, nullable and `Generated`
+   * ones. Relation properties are left out.
+   */
+  export type Insertable<M extends Model> = {
+    [K in Exclude<InsertablePropertyNames<M>, OptionalInsertPropertyNames<M>>]: Expression<M[K]>;
+  } & {
+    [K in Extract<InsertablePropertyNames<M>, OptionalInsertPropertyNames<M>>]?: Expression<M[K]>;
+  };
+
+  /**
+   * Like `Insertable`, but for `insertGraph()`: relation properties are
+   * optional and hold the insertable graphs of the related models, or
+   * references to existing ones through `#dbRef` or `#ref`.
+   */
+  export type InsertableGraph<M extends Model> = Insertable<M> &
+    Omit<GraphParameters, '#dbRef' | '#ref'> & {
+      [K in RelationPropertyNames<M>]?: InsertableGraphField<M[K]>;
+    };
+
+  type InsertableGraphReference = { '#dbRef': MaybeCompositeId } | { '#ref': string };
+
+  type InsertableGraphField<F> =
+    NonNullable<F> extends (infer I extends Model)[]
+      ? (InsertableGraph<I> | InsertableGraphReference)[]
+      : NonNullable<F> extends infer I extends Model
+        ? InsertableGraph<I> | InsertableGraphReference | Extract<F, null>
+        : never;
+
   /**
    * Extracts the property names (excluding relations) of a model class.
    */
@@ -1488,6 +1552,11 @@ declare namespace Objection {
     model: M,
     context: QueryContext,
   ) => Promise<void> | void;
+  type RelationMappingBeforeInsertHook<M extends Model> = (
+    model: M,
+    context: QueryContext,
+    owner?: Model,
+  ) => Promise<void> | void;
   type StringOrReferenceBuilder = string | ReferenceBuilder;
   type RelationMappingColumnRef = StringOrReferenceBuilder | StringOrReferenceBuilder[];
 
@@ -1497,7 +1566,7 @@ declare namespace Objection {
     join: RelationJoin;
     modify?: Modifier<QueryBuilderType<M>>;
     filter?: Modifier<QueryBuilderType<M>>;
-    beforeInsert?: RelationMappingHook<M>;
+    beforeInsert?: RelationMappingBeforeInsertHook<M>;
   }
 
   export interface RelationJoin {
@@ -1518,6 +1587,67 @@ declare namespace Objection {
 
   export interface RelationType extends Constructor<Relation> {}
 
+  // The relation types are branded so that `TypedRelationMappings` can tell
+  // them apart. The brand is optional, so any `RelationType` is assignable.
+  export interface BelongsToOneRelationType extends RelationType {
+    readonly [relationKind]?: 'BelongsToOne';
+  }
+  export interface HasOneRelationType extends RelationType {
+    readonly [relationKind]?: 'HasOne';
+  }
+  export interface HasManyRelationType extends RelationType {
+    readonly [relationKind]?: 'HasMany';
+  }
+  export interface ManyToManyRelationType extends RelationType {
+    readonly [relationKind]?: 'ManyToMany';
+  }
+  export interface HasOneThroughRelationType extends RelationType {
+    readonly [relationKind]?: 'HasOneThrough';
+  }
+
+  /**
+   * Names of the properties of M that hold related models.
+   */
+  type RelationPropertyNames<M> = {
+    [K in keyof M]-?: NonNullable<M[K]> extends Model | Model[] ? K : never;
+  }[keyof M];
+
+  type TypedModelClassSpecifier<M extends Model> =
+    string | ModelConstructor<M> | (() => ModelConstructor<M>);
+
+  /**
+   * A `RelationMapping` for related models of type M with relation type R.
+   */
+  export interface TypedRelationMapping<
+    M extends Model,
+    R extends RelationType = RelationType,
+  > extends RelationMapping<M> {
+    relation: R;
+    modelClass: TypedModelClassSpecifier<M>;
+  }
+
+  type TypedRelationMappingFor<T> =
+    NonNullable<T> extends (infer I extends Model)[]
+      ? TypedRelationMapping<I, HasManyRelationType | ManyToManyRelationType>
+      : NonNullable<T> extends infer I extends Model
+        ? TypedRelationMapping<
+            I,
+            BelongsToOneRelationType | HasOneRelationType | HasOneThroughRelationType
+          >
+        : never;
+
+  /**
+   * Relation mappings checked against the relation properties of model M.
+   * Use it with `satisfies`, so the inferred type of the mappings is kept:
+   *
+   *   static relationMappings = {
+   *     pets: { ... },
+   *   } satisfies TypedRelationMappings<Person>;
+   */
+  export type TypedRelationMappings<M extends Model> = [RelationPropertyNames<M>] extends [never]
+    ? Record<string, never>
+    : { [K in RelationPropertyNames<M>]?: TypedRelationMappingFor<M[K]> };
+
   export interface Relation {
     name: string;
     ownerModelClass: typeof Model;
@@ -1528,6 +1658,7 @@ declare namespace Objection {
     joinTable: string;
     joinTableOwnerProp: RelationProperty;
     joinTableRelatedProp: RelationProperty;
+    isOneToOne(): boolean;
   }
 
   export interface RelationProperty {
@@ -1598,6 +1729,22 @@ declare namespace Objection {
      * Only used by `snakeCaseMappers`.
      */
     preserveJsonKeys?: boolean;
+    /**
+     * Also convert the keys of plain objects one level down in the results,
+     * e.g. the rows of knex's `nestTables: true` option on MySQL. Also applies
+     * to JSON columns parsed by the driver.
+     * Only used by `knexSnakeCaseMappers`.
+     */
+    mapNestedKeys?: boolean;
+  }
+
+  export interface KnexIdentifierMappingOptions {
+    /**
+     * Also convert the keys of plain objects one level down in the results,
+     * e.g. the rows of knex's `nestTables: true` option on MySQL. Also applies
+     * to JSON columns parsed by the driver.
+     */
+    mapNestedKeys?: boolean;
   }
 
   export interface ColumnNameMappers {
@@ -1619,7 +1766,7 @@ declare namespace Objection {
   }
 
   export interface KnexIdentifierMappingFactory {
-    (colToProp: Record<string, string>): KnexMappers;
+    (colToProp: Record<string, string>, options?: KnexIdentifierMappingOptions): KnexMappers;
   }
 
   export type ValidationErrorType =
@@ -1732,11 +1879,11 @@ declare namespace Objection {
     ref: ReferenceFunction;
     fn: FunctionFunction;
 
-    BelongsToOneRelation: RelationType;
-    HasOneRelation: RelationType;
-    HasManyRelation: RelationType;
-    ManyToManyRelation: RelationType;
-    HasOneThroughRelation: RelationType;
+    BelongsToOneRelation: BelongsToOneRelationType;
+    HasOneRelation: HasOneRelationType;
+    HasManyRelation: HasManyRelationType;
+    ManyToManyRelation: ManyToManyRelationType;
+    HasOneThroughRelation: HasOneThroughRelationType;
 
     defaultGraphOptions?: GraphOptions;
 
@@ -1843,11 +1990,11 @@ declare namespace Objection {
     static ref: ReferenceFunction;
     static fn: FunctionFunction;
 
-    static BelongsToOneRelation: RelationType;
-    static HasOneRelation: RelationType;
-    static HasManyRelation: RelationType;
-    static ManyToManyRelation: RelationType;
-    static HasOneThroughRelation: RelationType;
+    static BelongsToOneRelation: BelongsToOneRelationType;
+    static HasOneRelation: HasOneRelationType;
+    static HasManyRelation: HasManyRelationType;
+    static ManyToManyRelation: ManyToManyRelationType;
+    static HasOneThroughRelation: HasOneThroughRelationType;
 
     static defaultGraphOptions?: GraphOptions;