Add support for Repositories / Data Mapper

[ephys]

Issue Creation Checklist

• I understand that my issue will be automatically closed if I don't fill in the requested information
• I have read the contribution guidelines

Feature Description

Describe the feature you'd like to see implemented

This is a feature that would take a long time to implement with our current codebase, but our rewrite to TypeScript is the perfect opportunity to make sure our new design is compatible with a Repository Mode.

The goal of a repository mode would be to eliminate our current limitation that one model can only ever be associated to one Sequelize instance.
(to be 100% honest, that limitation would remain for classes that extend Model because they expose static DB methods, but we could have model classes that do not extend Model).

Here is an example:

// note that this doesn't extend Model
class User {
  @IntPrimaryKey
  declare id: number;
}

// Models are registered just like without repository mode
const sequelize1 = new Sequelize({
  models: [User],
});

// Error! The findAll static method does not exist.
User.findAll();

// You need to get the repository instead:
const userRepository1 = sequelize1.getRepository(User);
const users = userRepository1.findAll(); // success!

// The same model can be used in multiple Sequelize instances.
const sequelize2 = new Sequelize({
  models: [User],
});

const userRepository2 = sequelize2.getRepository(User);
const users = userRepository2.findAll(); // success!

Existing models with their static methods would continue to work just like before, but they cannot be used in multiple Sequelize instances:

class User extends Model {
  @IntPrimaryKey
  declare id: number;
}

// Models are registered just like without repository mode
const sequelize1 = new Sequelize({
  models: [User],
});

// This works!
User.findAll();

// This works too!
const userRepository1 = sequelize1.getRepository(User);
const users = userRepository1.findAll(); // success!

// Error: Model "User" already belongs to a different Sequelize instance. Models that extend the "Model" base class cannot be used in multiple Sequelize instances. You must use plain models and repositories instead.
const sequelize2 = new Sequelize({
  models: [User],
});

Describe why you would like this feature to be added to Sequelize

It would allow using the same models in multiple databases.

How would we implement this

We're migrating model.js to TypeScript, it's the perfect opportunity to move all of it to a new class called ModelRepository.

The Model class would be emptied, with only its public methods remaining. It would have an internal, private, ModelRepository instance, and its public methods would delegate to that ModelRepository.

Once model.js has been completely migrated to ModelRepository, we'll be able to add sequelize.getRepository(model), and register models that don't extend the base Model class.

Is this feature dialect-specific?

• No. This feature is relevant to Sequelize as a whole.
• Yes. This feature only applies to the following dialect(s):

Would you be willing to resolve this issue by submitting a Pull Request?

• Yes, I have the time and I know how to start.
• Yes, I have the time but I will need guidance.
• No, I don't have the time, but my company or I are supporting Sequelize through donations on OpenCollective.
• No, I don't have the time, and I understand that I will need to wait until someone from the community or maintainers is interested in implementing my feature.

---

Indicate your interest in the addition of this feature by adding the 👍 reaction. Comments such as "+1" will be removed.

[klausXR]

How would saving relationships work here, will the setX automatically generated methods be migrated to the repository?

I think its more meaningful to have code that looks like this

const author = await authorRepository.findByPk(1);
const book = new Book("title");

book.author = author;

await bookRepository.save(book)

Updating entities synchronously initially ( no await book.setAuthor methods ) would allow implementation of events that are dispatched at a later point, if the transaction fails or succeeds, when eventually save is called.

Also, for 1:M and M:M relationships, I think it would be more beneficial to have collections to work with instead of relying on the asynchronous methods, for example

const bookToRemove = 15

const author = await authorRepository.findByPk(1, { include: [ Book] )

// Removes it synchronously in memory
author.books.removeByPk(bookToRemove)

// Persists the dirty state
await authorRepository.save(author)

Now, this would be very hard to implement with the current model where these relationships are arrays of models, however, if they are replaced with a custom Collection class instead, it can manage the dirty state of the relationship internally and expose methods to mutate it

Some pseudo code

class Collection<T> {
    private items: T[]

    // Returns the items
    public getItems() {}

    // Removes by a model reference
    public removeByReference(T) {}
    
    // Removes by a primary key
    public removeByPk(pk: number) {}

    // Adds a new model instance to the collection
    public add(T) {}

    // Removes all items from the collection
    public clear() {}

    // Only the passed models will remain associated after save
    public setItems(T[]) {}
}

class Book {
    @BelongsTo(() => Author)
    author: Author
}

class Author {
    @HasMany(() => Book)
    books = new Collection<Book>()
}

I think that this would make the code a lot more readable, concise and not relying on magically generated strings that are hard to get working with TS.

This also allows developers to implement custom business rules to the management of entities that go beyond a single model, for example, one can make a collection private and expose custom methods for its manipulation.

Pseudo-code example below, notice how the lineItems are read-only from outside and the cart object will expose methods for synchronously mutating them, after which the cart can be passed to the repository and be saved.

Collections can also help with a possible implementation of a "recursive save" in the future

class CartLineItem {
    @BelongsTo(() => Product)
    product: Product

    @Column()
    quantity: number
}

class Cart {
    @HasMany(() => CartLineItem)
    private lineItems = new Collection<CartLineItem>()
    
    @BelongsTo(() => User)
    user: User

    public getLineItems() {
        return this.lineItems.getItems()
    }

    public addProduct(product: Product, quantity: number) {
        if (this.lineItems.count > 100) {
            return new Error("No more products can be added to the cart.")
        }

        if (product.quantity < quantity) {
            return new Error("Product has insufficient quantity.")
        }

        if (product.shipsTo(this.user.country) === false) {
            return new Error("Product cannot be shipped to user's country.")
        }

        const lineItem = new CartLineItem()

        lineItem.product = product
        lineItem.quantity = quantity

        this.lineItems.add(lineItem)

        // Dispatched after `save`
        this.scheduleEvent(new CartLineItemAdded(this, lineItem))
    }
}

[ephys]

That's a very good question. All database operations would need to be done through the repository so entities that don't extend the Model class wouldn't include the association methods

I personally really like your suggestion. It looks clean and intuitive.

IMO we could implement this API for entities that extend Model (while still exposing the different association methods they have today)
save not persisting changes made to associations is something I've always found confusing. This change would have an impact on issue #14302

[klausXR]

Do you have some ETAs in mind for when these things could possibly launch in a stable version?

[klausXR]

IMO we could implement this API for entities that extend Model (while still exposing the different association methods they have today)

I think this API is better fit for the repository pattern, because the repository is generic ( getRepository(User) < static class ), but the setter methods are scoped user.setAuthor < called on the instance.

So, you would likely need an additional implementation for the repository such that you have a method similar to getRepository(author).books.add(book).

However, with the collection class or a similar implementation, the repository would be able to read the dirty changes from the model and directly apply them after the base entity is persisted.

It should also be compatible with model.save.