cachex icon indicating copy to clipboard operation
cachex copied to clipboard

Solidify :commit syntax in documentation and utilities

Open whitfin opened this issue 1 month ago • 2 comments

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 🙃

whitfin avatar Nov 11 '25 20:11 whitfin

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

whitfin avatar Nov 11 '25 21:11 whitfin

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...

whitfin avatar Nov 17 '25 04:11 whitfin