Support for union relationships

[calvinbrewer]

For example:

{
  ...
  {
    belongsTo: ['a', 'b', 'c'],
    inverse: 'd',
  }
}

[dylnslck]

This is my proposal. A few more schema-level relations need to be defined:

/**
 * @method hasManyOf
 * @param {(Object|String[])} types
 * @param {String} [inverse='']
 */
hasManyOf(types, inverse = '')

/**
 * @method belongsToOneOf
 * @param {(Object|String[])} types
 * @param {String} [inverse='']
 */
belongsToOneOf(types, inverse = '')

/**
 * @method hasOneOf
 * @param {(Object|String[])} types
 * @param {String} [inverse='']
 */
hasOneOf(types, inverse = '')

If types is an object, each key would be schema type, and each value would be the inverse. On the other hand, a common pattern might be to have the same inverse per type, in which case types would be an array, and the second argument inverse would be the inverse for each type.

A couple of examples:

const userSchema = schema('user', {
  attributes: { /* ... */ },
  relationships: {
    pets: hasManyUnionOf({
      dog: 'owner',
      cat: 'user', 
    }),
  },
});

const userSchema = schema('user', {
  attributes: { /* ... */ },
  relationships: {
    pets: hasManyUnionOf(['dog', 'cat'], 'owner'),
  },
});

RethinkDB document changes are trivial:

// user document
id: '1',
name: 'Bob',
pets: [{
  id: '1',
  _archived: false,
  _related: true,
  _type: 'dog', // add a _type field per relationship
}, {
  id: '1',
  _archived: false,
  _related: true,
  _type: 'cat',
}],
company: {
  id: '1',
  _archived: false,
  _related: true,
  _type: 'company',
}

The only complexity, albeit small, would occur when creating or updating certain relationships. For example, the object passed to Model.create would have to accommodate belongsToUnionOf differently than belongsTo:

For example, assume the office type belongs to a building entity. We know for certain that the type of the building relationship is a 'building':

model('office').create({
  size: 100,
  building: '1',
});

However, assume that the office type can belong to either a building entity or factory entity. The end-user would have to specify:

model('office').create({
  size: 100,
  building: {
    id: '1',
    type: 'building', // or type: 'factory'
  },
});

Let's compile the required internal changes for this.