Opinions on the public API?

[dumbbell]

I'm currently revisiting the public API of Khepri because I'm unhappy with the existing one. In particular, the simple vs. advanced APIs were confusing in the end.

Now, I'm leaning towards a unique API provided by the khepri module. khepri_machine becomes an internal module. The experiment is in the revisit-public-api branch (#79).

Changes:

• khepri_machine functions accept both native paths and string-based paths. They take care of converting string-based paths to native ones. Thanks to this, all functions built on top of those primitives can take advantage of string-based paths (they are first-class citizen).
• Functions in khepri return khepri_machine:result() values most of the times (like khepri_machine functions). However, the module provides more functions for specific uses, like fetching the data of a tree node, checking the existence of a tree node, etc. I'm willing to add more functions like these to make it as easy as possible to use Khepri without having to write wrappers for common use cases.
• Functions in khepri_tx mirror the khepri module for transactions.
• Payload wrapping is made automatic: put() accepts wrapped payloads (the #kpayload_*{} records and ?NO_PAYLOAD) or any terms. For the latter, they are wrapped inside #kpayload_sproc{} for anonymous functions, or #kpayload_data{} for everything else. This way, users won't have to mess with the records (making the API simpler) and won't have to recompile if the records evolve.
• The absence of payload is now behind a macro, ?NO_PAYLOAD. Its value is a more obscure atom, $__NO_PAYLOAD__, instead of none to make it easier to auto-detect the type of payload.

Another feature I would like to add, probably in a separate patch, is the wait for a leader election. We have this wrapper in rabbit_khepri in RabbitMQ and it should really be provided by Khepri directly.

The branch is still a work-in-progress. In particular, there is a large work to finish around the documentation.

What do you think? Any specific helpers you would like to see?

[dumbbell]

@the-mikedavis: You spent some time in Khepri already, I would love to have your external opinion!

[the-mikedavis]

Admittedly I haven't spent much time outside of khepri_fun 😅

I'll give the rest of the library a spin and report back. These changes (for #79) sound great though! Moving functionality from khepri_machine into khepri and then reflecting those in khepri_tx seems like it should make it a lot easier to get familiar with the API. Plus I like being able to specify both syntaxes when it comes to the native vs. string paths (especially with #61) and records vs. payloads.

[dumbbell]

There has been nice feedback outside of this discussion (Slack, GitHub issues/pull requests and Erlang forums). I consider the API to be on the right path.