refactor: migrate associations to TypeScript

[ephys]

This PR migrates the 'association' folder to TypeScript.

This PR brings makes very important changes to how associations work in Sequelize:

List of changes

• Association names have been normalized: All associations are named, and their name always corresponds to their value in Model.associations.x.
• Associations are unique: It's not possible to replace an association once defined (breaking change).
• Associations are immutable: Once defined, they cannot be changed (breaking change).
• The way associations are determined when using include has changed (breaking change).
• Includes are now strict.

Changes to how foreign keys are created

Instead of duplicating code across all associations, BelongsTo is the only association capable of adding Foreign Keys. All other associations delegate to BelongsTo:

• HasMany creates its inverse BelongsTo association
• HasOne creates its inverse BelongsTo association
• BelongsToMany creates its inverse BelongsToMany association, both of which create a HasMany association between Through and Source, which creates a BelongsTo

Association names have been normalized

Sequelize 6 would consider these two associations to be different:

Project.belongsTo(User);
Project.belongsTo(User, { as: 'User' });

This worked most of the time, but it was inconsistent internally. Both associations shared the same name and Project.associations.User be equal to the last association to have been defined.
Even more inconsistently, project.getUser and other mixin methods would belong to the first association to have been defined.

After this PR, the above code will throw an error saying that the alias is already in use and to use another one.

Associations are unique

The following code will now throw, because you can't replace an association that has already been defined anymore (your codebase would have been very fragile if you relied on this anyway, it's a very unsafe thing to do):

Project.belongsTo(User);
Project.belongsTo(User);

The way associations are determined when using include has changed

When specifying an include using a model+as, Sequelize 6 would search for an association that was defined with that model & as.

So these failed (on purpose):

Project.belongsTo(User);

Project.findAll({
  include: { model: User, as: 'User' },
});

// ----

Project.belongsTo(User, { as: 'User' });

Project.findAll({
  include: { model: User },
});

these worked:

Project.belongsTo(User);

Project.findAll({
  include: { model: User },
});

// ----

Project.belongsTo(User, { as: 'User' });

Project.findAll({
  include: { model: User, as: 'User' },
});

---

In Sequelize 7, the way it works is that if only one association has been defined with that model as the target, it will use that one, otherwise it will disambiguate using as.

If you're using sequelize-typescript, that is already how it works as they override our system to implement this

That means using as is exactly the same as using association: and I think we should update our documentation to promote the use of association: over the use of model:. i.e. instead of doing this:

Project.findAll({
  include: { model: User, as: 'User' },
});

do this:

Project.findAll({
  include: 'User',
});

Associations are immutable

Before this PR, associations were a bit fuzzy: Defining an association on both sides of the association would attempt to merge and reconcile their options.

A good idea in theory, but these associations are applied as soon as the method is called. This means reconciliation may need to revert changes that were already done on other objects, like renaming a previously added foreign key on a model.

Determining which association was paired with which was also tricky.

With this PR, it's still possible to define association on both sides, but their options must be perfectly compatible. For instance this is not valid:

User.belongsToMany(Countries, { foreignKey: 'user_id' });
Countries.belongsToMany(User);

but this is:

User.belongsToMany(Countries, { foreignKey: 'user_id' });
Countries.belongsToMany(User, { otherKey: 'user_id' });

To make things easier, I've introduced the long requested "inverse" option which lets a user define the association on both sides in one call.

Instead of doing this:

User.belongsToMany(Countries, { as: 'countries' });
User.belongsToMany(Countries, { as: 'citizen' });

users should now do this:

User.belongsToMany(Countries, { as: 'countries', inverse: { as: 'citizen' } });

Closes #5144

Includes are now strict

This PR normalizes Includes, which resolves a series of inconsistencies and should make them more stable.

For instance, Includes are always validated. If no association is found matching that include, an error will be thrown (including nested includes).

PENDING QUESTION: Found an issue with BelongsToMany.

Edit: resolved, see comments

Given a BelongsToMany association from User to Project through User_Project,
and using groupedLimit on the BelongsToMany association,

• This unit test expects the through table to be aliased to User_Project.
• This integration test expects the through table to be aliased to Project.

This needs to be unified, although I'm not sure which choice is best. Right now I've picked the second behavior.

Other breaking changes

• The options 'foreignKeyConstraint' and 'constraints' have been merged in 'foreignKeyConstraints' as they did the same thing.
• The 'timestamps' option in BelongsToManyOptions has been moved to ThroughOptions.timestamps
• The 'uniqueKey' option in BelongsToManyOptions has been merged with ThroughOptions.unique
• HasMany / HasOne don't use 'as' as the foreign key anymore (it wouldn't make sense. You ended up with the class Project.hasMany(User) meant the model User received a foreign key called UserId.
• The foreignKey and otherKey options are unified with ColumnOptions:
  • The 'keyType' option is now 'foreignKey.type'
  • The 'onDelete' option is not 'foreignKey.onDelete'
  • The 'onUpdate' option is not 'foreignKey.onUpdate'
• The default value for onDelete for non-null FKs is unified. It's now always CASCADE. Previously, it was NO ACTION if defined first through belongsTo, and CASCADE if defined first through hasOne or hasMany, leading to unexpected behaviors depending on which method was called first.

Closes #13429
Closes #12782
Closes #11837

What's left to be done

• Merge docs: clean up model docs #14333
• Merge feat: simplify withSchema API #14359
• Merge feat: add isModelStatic, isSameInitialModel #14360
• Add more typing tests
• Check 'inverse' supports all options
• add configuration for fromThroughToSource and fromSourceToThrough
• Add support for inverse in HasMany, HasOne, BelongsToMany
• Add support for inverse in BelongsTo
• Determine the best option for the issue 'Found an issue with BelongsToMany.'

What's next (in follow-up PRs)?

• Consider renaming otherKey to inverse.foreignKey
• Forbid defining an association if the primary key is composite. As this is not supported and breaks silently. (we can add support for this but users should be aware that it will not work).
• Document the breaking changes in the upgrade guide
• Update the documentation to reflect new recommended behaviors (includes, super many-to-many, inverse)
• Document the best practices to avoid errors with associations: Use 'inverse' instead of defining the association twice, beware of creating the same association twice without naming the inverse (this.User.belongsToMany(this.Task) + this.User.belongsToMany(this.Task, {as:'association2'}))
• Improve ORDER BY thanks to the normalization of associations

[ephys]

Conflicts resolved

[WikiRik]

This has been a lot. I mainly have questions to when TODOs will have to be taken care of. Maybe we should provide TODOs with some extra information.
My idea was to add something like;

• TODO needs to be taken care of before the release of v7
• TODO needs to be taken care of after the release of 7.0.0 and is non-breaking
• TODO needs to be taken care of after the release of 7.0.0 and is breaking
• TODO needs to be taken care of after we drop support for version x of whatever (Node/TypeScript/database version)

[WikiRik]

I still have some questions open, but nothing that's blocking this PR. Good work!

[WikiRik]

Woops, it seemed that merging main broke some unit tests. Should have looked at that as well, before approving 😅

[ephys]

I mainly have questions to when TODOs will have to be taken care of

Would it be enough if I mentioned whether the change was a breaking change? As much as I'd like to have some of them fixed before v7, I can't guarantee it with the time I can allocate to this project :/

I can still sort that out before merging :)

[github-actions]

🎉 This PR is included in version 7.0.0-alpha.14 🎉

The release is available on:

• npm package (@release-v7 dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bminer]

Please ignore my prior comment. I misunderstood this change, sorry! I'm going to hide it.