feature: support multiple references

```js
class Foo extends Model {}
Foo.fields = { id: 'integer' };

class Bar extends Model {}
Bar.fields = { id: 'integer' };

class Quux extends Model {}
Foo.fields = {
  refId: {
    type: 'integer',
    // multiple references can be defined as an array
    // or as a function that returns an array
    references: [Foo.fields.id, Bar.fields.id]
  }
};

// these fetches would now supported:
Quux.fetch({ join: Foo });
Quux.fetch({ join: Bar });
Foo.fetch({ join: Quux });
Bar.fetch({ join: Quux });
```

Author: joelmukuthu

lib/KnormRelations.js

@@ -1,26 +1,42 @@
 const { Knorm } = require('@knorm/knorm');
 const { camelCase } = require('lodash');
 
+const isArray = Array.isArray;
+
 const addReference = (references, field, reference) => {
   const toModel = reference.model;
   references[toModel.name] = references[toModel.name] || {};
   references[toModel.name][field.name] = field;
 };
 
 const addReferenceByFunction = (references, func, { name, column }) => {
-  const reference = func();
-  // add a pseudo-field to avoid having to overwrite field.references
-  const field = { name, column, references: reference };
-  addReference(references, field, reference);
+  let resolvedReferences = func();
+  resolvedReferences = isArray(resolvedReferences)
+    ? resolvedReferences
+    : [resolvedReferences];
+
+  resolvedReferences.forEach(reference => {
+    // add a pseudo-field to avoid having to overwrite field.references
+    const field = { name, column, references: reference };
+    addReference(references, field, reference);
+  });
 };
 
-const mapReferencesByReferencedField = references =>
-  Object.values(references).reduce((referencesByTo, from) => {
-    const to = from.references.name;
-    referencesByTo[to] = referencesByTo[to] || [];
-    referencesByTo[to].push(from);
+const mapReferencesByReferencedField = (references, fromModel) => {
+  return Object.values(references).reduce((referencesByTo, from) => {
+    const references = isArray(from.references)
+      ? from.references
+      : [from.references];
+    references.forEach(reference => {
+      if (reference.model.name === fromModel.name) {
+        const to = reference.name;
+        referencesByTo[to] = referencesByTo[to] || [];
+        referencesByTo[to].push(from);
+      }
+    });
     return referencesByTo;
   }, {});
+};
 
 class KnormRelations {
   constructor({ name = 'relations' } = {}) {
@@ -57,12 +73,16 @@ class KnormRelations {
         super.addField(field);
 
         if (field.references) {
-          const toField = field.references;
+          const references = field.references;
 
-          if (typeof toField === 'function') {
-            this._config.referenceFunctions[field.name] = toField;
+          if (typeof references === 'function') {
+            this._config.referenceFunctions[field.name] = references;
           } else {
-            addReference(this._config.references, field, toField);
+            (isArray(references) ? references : [references]).forEach(
+              reference => {
+                addReference(this._config.references, field, reference);
+              }
+            );
           }
         }
       }
@@ -103,7 +123,7 @@ class KnormRelations {
       }
 
       addJoin(type, joins, options) {
-        if (!Array.isArray(joins)) {
+        if (!isArray(joins)) {
           joins = [joins];
         }
 
@@ -142,16 +162,18 @@ class KnormRelations {
             );
           }
 
+          const isReverseJoin = !!thisReferences[join.model.name];
           const mergedReferences = Object.assign(
             {},
             thisReferences[join.model.name],
             joinReferences[this.model.name]
           );
           const mergedReferencesReversed = mapReferencesByReferencedField(
-            mergedReferences
+            mergedReferences,
+            isReverseJoin ? join.model : this.model
           );
 
-          join.config.isReverseJoin = !!thisReferences[join.model.name];
+          join.config.isReverseJoin = isReverseJoin;
           join.config.mergedReferences = mergedReferences;
           join.config.mergedReferencesReversed = mergedReferencesReversed;
 
@@ -177,7 +199,8 @@ class KnormRelations {
         return this.setOption('as', as);
       }
 
-      // TODO: support multiple fields for `on`
+      // TODO: v2: support multiple fields for `on` via Query.prototpye.appendOption
+      // TODO: support raw sql
       on(field) {
         return this.addOption('on', field);
       }
@@ -213,27 +236,38 @@ class KnormRelations {
           references = Object.values(this.config.mergedReferences);
         }
 
+        const isReverseJoin = this.config.isReverseJoin;
+
         return references.reduce((columns, field) => {
           const fromColumn = field.column;
-          const toColumn = field.references.column;
-          let from;
-          let to;
-
-          if (this.config.isReverseJoin) {
-            from = this.formatColumn(toColumn);
-            to = this.parent.formatColumn(fromColumn);
-          } else {
-            from = this.formatColumn(fromColumn);
-            to = this.parent.formatColumn(toColumn);
-          }
+          const references = isArray(field.references)
+            ? field.references
+            : [field.references];
+
+          references.forEach(reference => {
+            const toModel = isReverseJoin ? this.model : this.parent.model;
+            if (reference.model.name === toModel.name) {
+              const toColumn = reference.column;
+              let from;
+              let to;
+
+              if (this.config.isReverseJoin) {
+                from = this.formatColumn(toColumn);
+                to = this.parent.formatColumn(fromColumn);
+              } else {
+                from = this.formatColumn(fromColumn);
+                to = this.parent.formatColumn(toColumn);
+              }
 
-          columns[from] = to;
+              columns[from] = to;
+            }
+          });
 
           return columns;
         }, {});
       }
 
-      // TODO: do not rely on `getTable` auto-aliasing (@knorm/knorm v2)
+      // TODO: v2: do not rely on `getTable` auto-aliasing (@knorm/knorm v2)
       async prepareJoin(sql, options) {
         const method = this.options.joinType || 'leftJoin';
         sql[method](this.getTable(), this.prepareOn());
@@ -360,7 +394,7 @@ class KnormRelations {
                 parsedRow[as] = data;
               }
             } else {
-              if (!Array.isArray(parsedRow[as])) {
+              if (!isArray(parsedRow[as])) {
                 parsedRow[as] = [];
               }
               parsedRow[as].push(data);