Proposal: Rename persistLater to persist

Is your feature request related to a problem? Please describe.

We’ve been getting up to speed on Mikro and are loving it. A bit of confusion came about with the interaction of the following:

• EntityManager.persistLater: Adds the change to the unit of work, does not flush. This was clear.
• EntityManager.persistAndFlush: Adds the change to the unit of work and flushes it immediately. This was also clear.

We got confused with EntityManager.persist though. It can either persistAndFlush or it can persistLater. This felt like a duplication in the API, and given that autoFlush is still hanging around as a setting, feels a bit odd. We were struggling with the difference between persist and persistLater until we looked at the code and saw that it’s just calling one or the other based on the boolean.

Describe the solution you’d like

This would be a breaking change, but I’d propose that we do the following:

1. Remove the current persist implementation.
2. Remove the autoFlush setting.
3. Rename persistLater to persist. Do not have an option to flush with this call as we still have persistAndFlush.
4. Leave persistAndFlush alone.

This would leave us with very clear terminology:

• “persist” always means into the unit of work, and there is no concept of adding it to the unit of work “later”.
• “flush” always means applying what’s in the EntityManager to the database.
• There is a helper method that does both for you in one call if you like.

Describe alternatives you’ve considered

The other clear terminology for me would be to:

1. Remove persist
2. Combine persistAndFlush and flush, and rename to persist. It would then take an optional set of additional entities to add before persisting, and if you just called persist with no arguments it’d be like calling flush is today.
3. Leave persistLater alone.

This would also leave us with very clear terminology:

• “persist” always means into the database, and calling persistLater queues the change up in the unit of work.
• Calling persist can mean “write everything I have queued up” or it can mean “add this change, then write everything I have queued up”.
• “flush” is no longer a concept, as it’s now called “persist”. If you want to use the unit of work, use “persistLater” and call “persist” when you want that to be saved.

Additional context

Docs are pretty clear that this is the behaviour, but it seems odd to have persistLater, persist which is usually persistLater but might not be, and persistAndFlush. I think it’d be better to just have explicit “later” or “now” as the options and settle on a clear terminology for which happens when you call these functions on the Entity Manager.

[B4nan]

This is planned for v4 (already added to ROADMAP.md), will be dropping autoFlush option (it was there just to ease the transition from v2 to v3).

Although I was planning to keep that flush parameter of persist() as for me it is quite handy when I am working with larger chunks (like data imports), where I do flush based on the modulo of iteration index (so let’s say every 100 items). But that can be changed to having the explicit if condition with flush() call. And I guess it will help others to understand how things work better (that flush() is actually what makes the db calls and everything).

So yes, let’s drop current persist() implementation and rename persistLater -> persist.

[B4nan]

In v2 the autoFlush defaulted to true, so that is where all this mess is coming from (and the reason was that v1 was mongo only, so flushing all the time was ok as there were no transactions at the time). I wanted to handle this somehow gracefully, as doing simple true/false change, you would not be able to spot all the problems (as the code would be still valid from the TS point of view).

Ok so maybe I will keep the flush param there, I kinda like it. But will definitely get rid of the autoFlush thing.

Btw we could also have an API like await em.persist(...).flush(), WDYT? persist would always return EM and we would drop the flush param. And this way we could also get rid of persistAndFlush().