Solidify :commit syntax in documentation and utilities
There are several places which currently accept these types of forms:
value
{:commit, value}
{:commit, value, options}
{:ignore, value}
{:error, reason}
This has been roughly referred to as "fetch syntax" or "commit syntax", but it's getting more widely used in 5.x for other functions. We should add a section to the docs named something like "Committing Changes", and document all the different formats so we can cross link the documentation.
At the same time, I think we should add an extra one or two forms:
value
{:commit, value}
{:commit, value, options}
{:ignore, value}
{:error, reason}
{:update, value}
{:update, value, options}
This will allow us to differentiate if we want to modify in place, or if we want to do a write. This might be tricky, because some places can't do in-place (i.e. fetch/4) but as long as it's documented then everything should be fine. This will allow us to remove the Cachex.Actions.write_mod/1 mess that I somehow thought was a good idea in the past 🙃
As a note, the new forms are quite verbose. It would be nice that places supporting this had some property to trim things down (context https://github.com/whitfin/cachex/issues/382#issuecomment-3468570692). We can group all the valid cases into :ok (or something) to enable easier success case matching.
To copy over an example for those at a glance:
case Cachex.fetch(cache, key, &function/1) do
{:ignore, value} ->
...
{:commit, value} ->
...
{:error, _reason} ->
...
value ->
...
end
This should also include revisiting how the ! of these functions interact; currently they're unpacked but I'm not entirely sure if that's what we want...