Skip to content

Clean up return types #310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dumbbell merged 1 commit into from
Dec 16, 2024
Merged

Clean up return types #310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions src/khepri.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,10 @@
%% exposed by {@link khepri_adv}. The list of returned properties can be
%% configured using the `props_to_return' option (see {@link tree_options()}).

-type node_props_map() :: #{khepri_path:native_path() => khepri:node_props()}.
%% Structure used to return a map of nodes and their associated properties,
%% payload and child nodes.

-type trigger_id() :: atom().
%% An ID to identify a registered trigger.

Expand Down Expand Up @@ -462,7 +466,7 @@
%%
%% `undefined' is returned if a tree node has no payload attached to it.

-type async_ret() :: khepri_adv:many_results() |
-type async_ret() :: khepri_machine:write_ret() |
khepri_tx:tx_fun_result() |
khepri:error({not_leader, ra:server_id()}).
%% The value returned from of a command function which was executed
Expand All @@ -478,7 +482,7 @@
%% commands could not be applied since they were sent to a non-leader member.
%%
%% Note that when commands are successfully applied, the return values are
%% {@link khepri_adv:many_results()} rather than {@link khepri:minimal_ret()},
%% {@link khepri_machine:write_ret()} rather than {@link khepri:minimal_ret()},
%% even if the command was sent using a function from the {@link khepri} API
%% such as {@link khepri:put/4}.
%%
Expand All @@ -494,6 +498,7 @@
child_list_length/0,
delete_reason/0,
node_props/0,
node_props_map/0,
trigger_id/0,

async_option/0,
Expand Down
86 changes: 38 additions & 48 deletions src/khepri_adv.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,23 +48,13 @@
unregister_projections/1, unregister_projections/2,
unregister_projections/3]).

-type node_props_map() :: #{khepri_path:native_path() => khepri:node_props()}.
%% Structure used to return a map of nodes and their associated properties,
%% payload and child nodes.

-type many_results() :: khepri_machine:common_ret().
%% Return value of a query or synchronous command targeting many tree nodes.

-export_type([node_props_map/0,
many_results/0]).

%% -------------------------------------------------------------------
%% get().
%% -------------------------------------------------------------------

-spec get(PathPattern) -> Ret when
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Returns the properties and payload of the tree node pointed to by the
%% given path pattern.
%%
Expand All @@ -83,11 +73,11 @@ get(PathPattern) ->
(StoreId, PathPattern) -> Ret when
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results();
Ret :: khepri_machine:write_ret();
(PathPattern, Options) -> Ret when
PathPattern :: khepri_path:pattern(),
Options :: khepri:query_options() | khepri:tree_options(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Returns the properties and payload of the tree node pointed to by the
%% given path pattern.
%%
Expand All @@ -112,7 +102,7 @@ get(PathPattern, Options) when is_map(Options) ->
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Options :: khepri:query_options() | khepri:tree_options(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Returns the properties and payload of the tree node pointed to by the
%% given path pattern.
%%
Expand Down Expand Up @@ -170,7 +160,7 @@ get(StoreId, PathPattern, Options) ->

-spec get_many(PathPattern) -> Ret when
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Returns properties and payloads of all the tree nodes matching the
%% given path pattern.
%%
Expand All @@ -189,11 +179,11 @@ get_many(PathPattern) ->
(StoreId, PathPattern) -> Ret when
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results();
Ret :: khepri_machine:write_ret();
(PathPattern, Options) -> Ret when
PathPattern :: khepri_path:pattern(),
Options :: khepri:query_options() | khepri:tree_options(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Returns properties and payloads of all the tree nodes matching the
%% given path pattern.
%%
Expand All @@ -218,7 +208,7 @@ get_many(PathPattern, Options) when is_map(Options) ->
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Options :: khepri:query_options() | khepri:tree_options(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Returns properties and payloads of all the tree nodes matching the
%% given path pattern.
%%
Expand Down Expand Up @@ -267,7 +257,7 @@ get_many(StoreId, PathPattern, Options) ->
PathPattern :: khepri_path:pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri:minimal_ret() |
khepri_adv:many_results().
khepri_machine:write_ret().
%% @doc Sets the payload of the tree node pointed to by the given path
%% pattern.
%%
Expand All @@ -287,7 +277,7 @@ put(PathPattern, Data) ->
PathPattern :: khepri_path:pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri:minimal_ret() |
khepri_adv:many_results().
khepri_machine:write_ret().
%% @doc Sets the payload of the tree node pointed to by the given path
%% pattern.
%%
Expand All @@ -307,7 +297,7 @@ put(StoreId, PathPattern, Data) ->
khepri:tree_options() |
khepri:put_options(),
Ret :: khepri:minimal_ret() |
khepri_adv:many_results() |
khepri_machine:write_ret() |
khepri_machine:async_ret().
%% @doc Sets the payload of the tree node pointed to by the given path
%% pattern.
Expand Down Expand Up @@ -406,7 +396,7 @@ put(StoreId, PathPattern, Data, Options) ->
-spec put_many(PathPattern, Data) -> Ret when
PathPattern :: khepri_path:pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Sets the payload of all the tree nodes matching the given path pattern.
%%
%% Calling this function is the same as calling `put_many(StoreId, PathPattern,
Expand All @@ -424,7 +414,7 @@ put_many(PathPattern, Data) ->
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Sets the payload of all the tree nodes matching the given path pattern.
%%
%% Calling this function is the same as calling `put_many(StoreId, PathPattern,
Expand All @@ -442,7 +432,7 @@ put_many(StoreId, PathPattern, Data) ->
Options :: khepri:command_options() |
khepri:tree_options() |
khepri:put_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Sets the payload of all the tree nodes matching the given path pattern.
%%
%% The `PathPattern' can be provided as a native path pattern (a list of tree
Expand Down Expand Up @@ -533,7 +523,7 @@ put_many(StoreId, PathPattern, Data, Options) ->
-spec create(PathPattern, Data) -> Ret when
PathPattern :: khepri_path:pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Creates a tree node with the given payload.
%%
%% Calling this function is the same as calling `create(StoreId, PathPattern,
Expand All @@ -551,7 +541,7 @@ create(PathPattern, Data) ->
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Creates a tree node with the given payload.
%%
%% Calling this function is the same as calling `create(StoreId, PathPattern,
Expand All @@ -569,7 +559,7 @@ create(StoreId, PathPattern, Data) ->
Options :: khepri:command_options() |
khepri:tree_options() |
khepri:put_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Creates a tree node with the given payload.
%%
%% The behavior is the same as {@link put/4} except that if the tree node
Expand Down Expand Up @@ -608,7 +598,7 @@ create(StoreId, PathPattern, Data, Options) ->
-spec update(PathPattern, Data) -> Ret when
PathPattern :: khepri_path:pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Updates an existing tree node with the given payload.
%%
%% Calling this function is the same as calling `update(StoreId, PathPattern,
Expand All @@ -626,7 +616,7 @@ update(PathPattern, Data) ->
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Updates an existing tree node with the given payload.
%%
%% Calling this function is the same as calling `update(StoreId, PathPattern,
Expand All @@ -644,7 +634,7 @@ update(StoreId, PathPattern, Data) ->
Options :: khepri:command_options() |
khepri:tree_options() |
khepri:put_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Updates an existing tree node with the given payload.
%%
%% The behavior is the same as {@link put/4} except that if the tree node
Expand Down Expand Up @@ -685,7 +675,7 @@ update(StoreId, PathPattern, Data, Options) ->
PathPattern :: khepri_path:pattern(),
DataPattern :: ets:match_pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Updates an existing tree node with the given payload only if its data
%% matches the given pattern.
%%
Expand All @@ -705,7 +695,7 @@ compare_and_swap(PathPattern, DataPattern, Data) ->
PathPattern :: khepri_path:pattern(),
DataPattern :: ets:match_pattern(),
Data :: khepri_payload:payload() | khepri:data() | fun(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Updates an existing tree node with the given payload only if its data
%% matches the given pattern.
%%
Expand All @@ -726,7 +716,7 @@ compare_and_swap(StoreId, PathPattern, DataPattern, Data) ->
Options :: khepri:command_options() |
khepri:tree_options() |
khepri:put_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Updates an existing tree node with the given payload only if its data
%% matches the given pattern.
%%
Expand Down Expand Up @@ -770,7 +760,7 @@ compare_and_swap(StoreId, PathPattern, DataPattern, Data, Options) ->
Options :: khepri:command_options() |
khepri:tree_options() |
khepri:put_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Prepares the payload and calls {@link khepri_machine:put/4}.
%%
%% @private
Expand All @@ -785,7 +775,7 @@ do_put(StoreId, PathPattern, Payload, Options) ->

-spec delete(PathPattern) -> Ret when
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Deletes the tree node pointed to by the given path pattern.
%%
%% Calling this function is the same as calling `delete(StoreId, PathPattern)'
Expand All @@ -803,11 +793,11 @@ delete(PathPattern) ->
(StoreId, PathPattern) -> Ret when
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results();
Ret :: khepri_machine:write_ret();
(PathPattern, Options) -> Ret when
PathPattern :: khepri_path:pattern(),
Options :: khepri:command_options() | khepri:tree_options(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Deletes the tree node pointed to by the given path pattern.
%%
%% This function accepts the following two forms:
Expand All @@ -831,7 +821,7 @@ delete(PathPattern, Options) when is_map(Options) ->
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Options :: khepri:command_options() | khepri:tree_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Deletes the tree node pointed to by the given path pattern.
%%
%% The `PathPattern' can be provided as a native path pattern (a list of tree
Expand Down Expand Up @@ -889,7 +879,7 @@ delete(StoreId, PathPattern, Options) ->

-spec delete_many(PathPattern) -> Ret when
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Deletes all tree nodes matching the given path pattern.
%%
%% Calling this function is the same as calling `delete_many(StoreId,
Expand All @@ -907,11 +897,11 @@ delete_many(PathPattern) ->
(StoreId, PathPattern) -> Ret when
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results();
Ret :: khepri_machine:write_ret();
(PathPattern, Options) -> Ret when
PathPattern :: khepri_path:pattern(),
Options :: khepri:command_options() | khepri:tree_options(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().

%% @doc Deletes all tree nodes matching the given path pattern.
%%
Expand All @@ -936,7 +926,7 @@ delete_many(PathPattern, Options) when is_map(Options) ->
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Options :: khepri:command_options() | khepri:tree_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Deletes all tree nodes matching the given path pattern.
%%
%% The `PathPattern' can be provided as a native path pattern (a list of tree
Expand Down Expand Up @@ -988,7 +978,7 @@ delete_many(StoreId, PathPattern, Options) ->

-spec clear_payload(PathPattern) -> Ret when
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Deletes the payload of the tree node pointed to by the given path
%% pattern.
%%
Expand All @@ -1006,7 +996,7 @@ clear_payload(PathPattern) ->
-spec clear_payload(StoreId, PathPattern) -> Ret when
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Deletes the payload of the tree node pointed to by the given path
%% pattern.
%%
Expand All @@ -1024,7 +1014,7 @@ clear_payload(StoreId, PathPattern) ->
Options :: khepri:command_options() |
khepri:tree_options() |
khepri:put_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Deletes the payload of the tree node pointed to by the given path
%% pattern.
%%
Expand Down Expand Up @@ -1057,7 +1047,7 @@ clear_payload(StoreId, PathPattern, Options) ->

-spec clear_many_payloads(PathPattern) -> Ret when
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Deletes the payload of all tree nodes matching the given path pattern.
%%
%% Calling this function is the same as calling `clear_many_payloads(StoreId,
Expand All @@ -1074,7 +1064,7 @@ clear_many_payloads(PathPattern) ->
-spec clear_many_payloads(StoreId, PathPattern) -> Ret when
StoreId :: khepri:store_id(),
PathPattern :: khepri_path:pattern(),
Ret :: khepri_adv:many_results().
Ret :: khepri_machine:write_ret().
%% @doc Deletes the payload of all tree nodes matching the given path pattern.
%%
%% Calling this function is the same as calling `clear_many_payloads(StoreId,
Expand All @@ -1092,7 +1082,7 @@ clear_many_payloads(StoreId, PathPattern) ->
Options :: khepri:command_options() |
khepri:tree_options() |
khepri:put_options(),
Ret :: khepri_adv:many_results() | khepri_machine:async_ret().
Ret :: khepri_machine:write_ret() | khepri_machine:async_ret().
%% @doc Deletes the payload of all tree nodes matching the given path pattern.
%%
%% In other words, the payload is set to {@link khepri_payload:no_payload()}.
Expand Down
Loading