What methods/mixins sequelize adds to the models when an association is made?

associations, javascript, orm, prototype, sequelize.js

Solution

Edit: Some time after I wrote this Q&A, I've made improvements to the Sequelize documentation itself, regarding multiple topics, including this one. For those interested, the original Q&A is kept below, but I recommend just reading the new documentation instead:

- Basic Tutorial on Associations

- Advanced Tutorial on Associations

- HasOne API Reference

- HasMany API Reference

- BelongsTo API Reference

- BelongsToMany API Reference

Original Answer

The documentation about associations you linked is a tutorial/guide. There is also the API Reference (edit: warning: this link points to an old version of the documentation), which is another type of documentation, more technical-oriented, which is helpful in this case. You can find it by clicking on the "Reference" link available in the side menu of the links you mentioned (and it took me quite a while to find that - it doesn't even look like a clickable thing IMO).

The parts you're interested here are these (edit: warning: these links points to an old version of the documentation):

- Sequelize docs for BelongsTo type of associations: here

- Sequelize docs for BelongsToMany type of associations: here

- Sequelize docs for HasMany type of associations: here

- Sequelize docs for HasOne type of associations: here

Understanding the API Reference

Since the docs linked above can be very confusing, here is an explanation to assist you to understand the docs.

Let's assume, for example, that we have a belongs to many association between `Person` and `Hypothesis`. Note that their plural forms, `People` and `Hypotheses`, are automatically inferred by Sequelize. This magic is done under the hood by the awesome library called inflection - see How do plurals work in Sequelize? for more details.

// Assuming that the models Person, Hypothesis and Person_Hypothesis are already defined
Person.belongsToMany(Hypothesis, { through: Person_Hypothesis });
Hypothesis.belongsToMany(Person, { through: Person_Hypothesis });

And we want to use the Sequelize docs for BelongsToMany type of associations to learn what methods were automatically added to instances of the Person and Hypothesis models. There, we can find the following table:

To understand what this table means, recall that in the beginning of that page of the docs it says that "In the API reference below, add the name of the association to the method". The most confusing part of this is that it's not so clear when you should add the singular version of the name and when you should add the plural version. But although the docs do not make this clear, I assure you that you can just use common sense to guess. And if you think both versions could make sense (for example, for `add`), be surprised that actually both versions are available. Therefore, from the table above, we can conclude:

Methods added to instances of Person models:

- `addHypothesis()`

- `addHypotheses()`

- `countHypotheses()`

- `createHypothesis()`

- `getHypotheses()`

- `hasHypothesis()`

- `hasHypotheses()`

- `removeHypothesis()`

- `removeHypotheses()`

- `setHypotheses()`

Methods added to instances of Hypothesis models:

- `addPerson()`

- `addPeople()`

- `countPeople()`

- `createPerson()`

- `getPeople()`

- `hasPerson()`

- `hasPeople()`

- `removePerson()`

- `removePeople()`

- `setPeople()`

Another way to figure this out without room for doubt is by checking the Sequelize source code itself, namely here, where we can find:

this.accessors = {
    get: 'get' + plural,
    set: 'set' + plural,
    addMultiple: 'add' + plural,
    add: 'add' + singular,
    create: 'create' + singular,
    remove: 'remove' + singular,
    removeMultiple: 'remove' + plural,
    hasSingle: 'has' + singular,
    hasAll: 'has' + plural,
    count: 'count' + plural
};

Note: although it might seem counter-intuitive, in fact both methods `addPerson()` and `addPeople()` mentioned above work with the same parameters, which can be either a single value or an array. In other words, the methods `add` and `addMultiple` from the source code are actually the same, in the end. The same applies to `remove()` and `removeMultiple()`, and `hasSingle()` and `hasAll()`.

Hopefully with this you can now understand what the Sequelize docs really mean with those tables.

If you prefer to check the source code directly, analogously to what I showed above, these are the relevant lines for the other kinds of associations:

BelongsTo: here

  this.accessors = {
      get: 'get' + singular,
      set: 'set' + singular,
      create: 'create' + singular
  };

HasOne: here

  this.accessors = {
      get: 'get' + singular,
      set: 'set' + singular,
      create: 'create' + singular
  };

HasMany: here

  this.accessors = {
      get: 'get' + plural,
      set: 'set' + plural,
      addMultiple: 'add' + plural,
      add: 'add' + singular,
      create: 'create' + singular,
      remove: 'remove' + singular,
      removeMultiple: 'remove' + plural,
      hasSingle: 'has' + singular,
      hasAll: 'has' + plural,
      count: 'count' + plural
  };

Problem

Original source

Related problems

• How do plurals work in Sequelize?