Typings revised for passing result type down the query builder chain

doc/includes/API.md

@@ -1,5 +1,9 @@
 # API reference
 
+__NOTE__: Everything not mentioned in the API documentation is considered private implementation
+and shouldn't be relied upon. Private implemementation can change without any notice even between
+patch versions. Public API described here follows [semantic versioning](https://semver.org/).
+
 
 
 
@@ -5668,11 +5672,6 @@ Shortcut for `Person.knex().fn`
 
 
 
-#### formatter
-
-Shortcut for `Person.knex().client.formatter()`
-
-
 
 #### knexQuery
 
@@ -6086,6 +6085,70 @@ Object.<string, [`Relation`](#relation)>|Object whose keys are relation na
 
 
 
+#### columnNameToPropertyName
+
+```js
+const propertyName = Person.columnNameToPropertyName(columnName);
+```
+
+> For example, if you have defined `columnNameMappers = snakeCaseMappers()` for your model:
+
+```js
+const propName = Person.columnNameToPropertyName('foo_bar');
+console.log(propName); // --> 'fooBar'
+```
+
+Runs the property through possible `columnNameMappers` and `$parseDatabaseJson` hooks to apply
+any possible conversion for the column name.
+
+##### Arguments
+
+Argument|Type|Description
+--------|----|-------------------
+columnName|string|A column name
+
+##### Return value
+
+Type|Description
+----|-----------------------------
+string|The property name
+
+
+
+
+
+#### propertyNameToColumnName
+
+```js
+const columnName = Person.propertyNameToColumnName(propertyName);
+```
+
+> For example, if you have defined `columnNameMappers = snakeCaseMappers()` for your model:
+
+```js
+const columnName = Person.propertyNameToColumnName('fooBar');
+console.log(columnName); // --> 'foo_bar'
+```
+
+Runs the property through possible `columnNameMappers` and `$formatDatabaseJson` hooks to apply
+any possible conversion for the property name.
+
+##### Arguments
+
+Argument|Type|Description
+--------|----|-------------------
+propertyName|string|A property name
+
+##### Return value
+
+Type|Description
+----|-----------------------------
+string|The column name
+
+
+
+
+
 
 ### Instance methods
 

doc/includes/CHANGELOG.md

@@ -6,15 +6,17 @@
 
   * The static [`relatedQuery`](#relatedquery) method.
   * New reflection methods:
-    [`isFind`](http://vincit.github.io/objection.js/#isfind),
-    [`isInsert`](http://vincit.github.io/objection.js/#isinsert),
-    [`isUpdate`](http://vincit.github.io/objection.js/#isupdate),
-    [`isDelete`](http://vincit.github.io/objection.js/#isdelete),
-    [`isRelate`](http://vincit.github.io/objection.js/#isrelate),
-    [`isUnrelate`](http://vincit.github.io/objection.js/#isunrelate),
-    [`hasWheres`](http://vincit.github.io/objection.js/#haswheres),
-    [`hasSelects`](http://vincit.github.io/objection.js/#hasselects),
-    [`hasEager`](http://vincit.github.io/objection.js/#haseager).
+    [`isFind`](#isfind),
+    [`isInsert`](#isinsert),
+    [`isUpdate`](#isupdate),
+    [`isDelete`](#isdelete),
+    [`isRelate`](#isrelate),
+    [`isUnrelate`](#isunrelate),
+    [`hasWheres`](#haswheres),
+    [`hasSelects`](#hasselects),
+    [`hasEager`](#haseager),
+    [`columnNameToPropertyName`](#columnnametopropertyname),
+    [`propertyNameToColumnName`](#propertynametocolumnname).
 
 ### Breaking changes
 

doc/includes/RECIPES.md

@@ -706,6 +706,147 @@ select "Tweet".*, (select count(*) from "Like" where "Like"."tweetId" = "Tweet".
 Naturally you can add as many subquery selects as you like. For example you could also get the count of retweets
 in the same query. [`relatedQuery`](#relatedquery) method works with all relations and not just `HasManyRelation`.
 
+## Error handling
+
+> An example error handler function that handles all possible errors. This example uses the [`objection-db-errors`](https://github.com/Vincit/objection-db-errors) library.
+
+```js
+const {
+  ValidationError,
+  NotFoundError
+} = require('objection');
+
+const {
+  DbError,
+  ConstraintViolationError,
+  UniqueViolationError,
+  NotNullViolationError,
+  ForeignKeyViolationError,
+  CheckViolationError,
+  DataError
+} = require('objection-db-errors');
+
+function errorHandler(err, res) {
+  if (err instanceof ValidationError) {
+    switch (err.type) {
+      case 'ModelValidation':
+        res.status(400).send({
+          message: err.message,
+          type: 'ModelValidation',
+          data: err.data
+        });
+        break;
+      case 'RelationExpression':
+        res.status(400).send({
+          message: err.message,
+          type: 'InvalidRelationExpression',
+          data: {}
+        });
+        break;
+      case 'UnallowedRelation':
+        res.status(400).send({
+          message: err.message,
+          type: 'UnallowedRelation',
+          data: {}
+        });
+        break;
+      case 'InvalidGraph':
+        res.status(400).send({
+          message: err.message,
+          type: 'InvalidGraph',
+          data: {}
+        });
+        break;
+      default:
+        res.status(400).send({
+          message: err.message,
+          type: 'UnknownValidationError',
+          data: {}
+        });
+        break;
+    }
+  } else if (err instanceof NotFoundError) {
+    res.status(404).send({
+      message: err.message,
+      type: 'NotFound',
+      data: {}
+    });
+  } else if (err instanceof UniqueViolationError) {
+    res.status(409).send({
+      message: err.message,
+      type: 'UniqueViolation',
+      data: {
+        columns: err.columns,
+        table: err.table,
+        constraint: err.constraint
+      }
+    });
+  } else if (err instanceof NotNullViolationError) {
+    res.status(400).send({
+      message: err.message,
+      type: 'NotNullViolation',
+      data: {
+        column: err.column,
+        table: err.table,
+      }
+    });
+  } else if (err instanceof ForeignKeyViolationError) {
+    res.status(409).send({
+      message: err.message,
+      type: 'ForeignKeyViolation',
+      data: {
+        table: err.table,
+        constraint: err.constraint
+      }
+    });
+  } else if (err instanceof CheckViolationError) {
+    res.status(400).send({
+      message: err.message,
+      type: 'CheckViolation',
+      data: {
+        table: err.table,
+        constraint: err.constraint
+      }
+    });
+  } else if (err instanceof DataError) {
+    res.status(400).send({
+      message: err.message,
+      type: 'InvalidData',
+      data: {}
+    });
+  } else if (err instanceof DbError) {
+    res.status(500).send({
+      message: err.message,
+      type: 'UnknownDatabaseError',
+      data: {}
+    });
+  } else {
+    res.status(500).send({
+      message: err.message,
+      type: 'UnknownError',
+      data: {}
+    });
+  }
+}
+```
+
+Objection throws four kinds of errors:
+
+1. [`ValidationError`](#validationerror) when an input that could come from the outside world is invalid. These inputs
+    include model instances and POJO's, eager expressions object graphs etc. `ValidationError` has a `type` property
+    that can be used to distinguish the different error types.
+
+2. [`NotFoundError`](#notfounderror) when [`throwIfNotFound`](#throwifnotfound) was called for a query and no
+    results were found.
+
+3. Database errors (unique violation error etc.) are thrown by the database client libraries and the error types depend on the
+    library. You can use the [`objection-db-errors`](https://github.com/Vincit/objection-db-errors) plugin to handle these.
+
+4. A basic javascript `Error` when a programming or logic error is detected. In these cases there is nothing the users
+    can do and the only correct way to handle the error is to send a 500 response to the user and to fix the program.
+
+See the example error handler that handles each error type.
+
 ## Indexing PostgreSQL JSONB columns
 
 Good reading on the subject:

lib/model/DbMetadata.js

@@ -0,0 +1,15 @@
+class DbMetadata {
+  constructor(columnInfo) {
+    this.columns = Object.keys(columnInfo);
+  }
+
+  static fetch({ modelClass, parentBuilder = null, knex = null } = {}) {
+    return modelClass
+      .query(knex)
+      .childQueryOf(parentBuilder)
+      .columnInfo()
+      .then(columnInfo => new DbMetadata(columnInfo));
+  }
+}
+
+module.exports = DbMetadata;

lib/model/Model.js

@@ -20,6 +20,7 @@ const {
   propertyNameToColumnName
 } = require('./modelColPropMap');
 
+const DbMetadata = require('./DbMetadata');
 const AjvValidator = require('./AjvValidator');
 const QueryBuilder = require('../queryBuilder/QueryBuilder');
 const NotFoundError = require('./NotFoundError');
@@ -523,6 +524,30 @@ class Model {
     return modelClass.query().findOperationFactory(builder => relation.subQuery(builder));
   }
 
+  static dbMetadata({ parentBuilder = null, knex = null } = {}) {
+    // Memoize metadata but only for this class. The hasOwnProperty check
+    // will fail for subclasses and the value gets recreated.
+    if (!this.hasOwnProperty('$$dbMetadata')) {
+      defineNonEnumerableProperty(this, '$$dbMetadata', Object.create(null));
+    }
+
+    // The table isn't necessarily same as `this.getTableName()` for example if
+    // a view is queried instead.
+    const table = (parentBuilder && parentBuilder.tableNameFor(this)) || this.getTableName();
+
+    if (this.$$dbMetadata[table]) {
+      return Promise.resolve(this.$$dbMetadata[table]);
+    } else {
+      const promise = DbMetadata.fetch({ modelClass: this, parentBuilder, knex }).then(metadata => {
+        this.$$dbMetadata[table] = metadata;
+        return metadata;
+      });
+
+      this.$$dbMetadata[table] = promise;
+      return promise;
+    }
+  }
+
   static knex() {
     if (arguments.length) {
       defineNonEnumerableProperty(this, '$$knex', arguments[0]);

lib/model/modelSet.js

@@ -100,8 +100,9 @@ function setDatabaseJson(model, json) {
 
 function setFast(model, obj) {
   if (obj) {
-    // Don't try to set read-only virtual properties. They can easily get here through `fromJson`
-    // when parsing an object that was previously serialized from a model instance.
+    // Don't try to set read-only virtual properties. They can easily get here
+    // through `fromJson` when parsing an object that was previously serialized
+    // from a model instance.
     const readOnlyVirtuals = model.constructor.getReadOnlyVirtualAttributes();
     const keys = Object.keys(obj);
 

lib/model/modelUtils.js

@@ -12,7 +12,8 @@ const staticHiddenProps = [
   '$$relations',
   '$$relationArray',
   '$$jsonAttributes',
-  '$$columnNameMappers'
+  '$$columnNameMappers',
+  '$$dbMetadata'
 ];
 
 function defineNonEnumerableProperty(obj, prop, value) {

lib/model/modelValidate.js

@@ -1,19 +1,20 @@
 const clone = require('./modelClone').clone;
 const { defineNonEnumerableProperty } = require('./modelUtils');
 
-function validate(model, json, options) {
+function validate(model, json, options = {}) {
   json = json || model;
-  options = options || {};
+  const inputJson = json;
+  const validatingModelInstance = inputJson && inputJson.$isObjectionModel;
 
-  if (json && json.$isObjectionModel) {
+  if (options.skipValidation) {
+    return json;
+  }
+
+  if (validatingModelInstance) {
     // Strip away relations and other internal stuff.
     json = clone(json, true, true);
     // We can mutate `json` now that we took a copy of it.
-    options.mutable = true;
-  }
-
-  if (options.skipValidation) {
-    return json;
+    options = Object.assign({}, options, { mutable: true });
   }
 
   const ModelClass = model.constructor;
@@ -29,7 +30,12 @@ function validate(model, json, options) {
   json = validator.validate(args);
   validator.afterValidate(args);
 
-  return json;
+  if (validatingModelInstance) {
+    // If we cloned `json`, we need to copy the possible default values.
+    return inputJson.$set(json);
+  } else {
+    return json;
+  }
 }
 
 module.exports = {