deploy: 9f99bae

khepri.html

@@ -141,6 +141,22 @@ <h3 class="typedecl"><a name="type-data">data()</a></h3>
 <p><code>data() = any()</code></p>
 <p>  Data stored in a tree node's payload.</p>
 
+<h3 class="typedecl"><a name="type-delete_reason">delete_reason()</a></h3>
+<p><code>delete_reason() = explicit | keep_while</code></p>
+<p><p>  The reason why a tree node was removed from the store.</p>
+
+  <ul>
+  <li><code>explicit</code> means that the tree node was removed from the store because a
+  deletion command targeted that tree node or its ancestor. This reason is
+  used when a tree node's path is provided to <a docgen-rel="seemfa" docgen-href="khepri_adv#delete/3" href="khepri_adv.html#delete-3"><code>khepri_adv:delete/3</code></a> for
+  example.</li>
+  <li><code>keep_while</code>: the tree node was removed because the keep-while condition
+  set when the node was created became unsatisfied. Note that adding or
+  updating a tree node can cause a keep-while condition to become unsatisfied,
+  so a put operation may result in a tree node being deleted with this delete
+  reason. See <a docgen-rel="seetype" docgen-href="khepri_condition#keep_while/0" href="khepri_condition.html#type-keep_while"><code>khepri_condition:keep_while()</code></a> and <a docgen-rel="seetype" docgen-href="khepri#put_options/0" href="khepri.html#type-put_options"><code>khepri:put_options()</code></a>.</li>
+  </ul></p>
+
 <h3 class="typedecl"><a name="type-error">error()</a></h3>
 <p><code>error() = <a href="#type-error" docgen-rel="seetype" docgen-href="#error/0">error</a>(any())</code></p>
 <p>  The error tuple returned by a function after a failure.</p>
@@ -218,7 +234,7 @@ <h3 class="typedecl"><a name="type-minimal_ret">minimal_ret()</a></h3>
 <p>  The return value of update functions in the <a docgen-rel="seeerl" docgen-href="khepri" href="khepri.html"><code>khepri</code></a> module.</p>
 
 <h3 class="typedecl"><a name="type-node_props">node_props()</a></h3>
-<p><code>node_props() = #{data =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-data" docgen-rel="seetype" docgen-href="khepri:khepri#data/0">khepri:data()</a>, has_data =&gt; boolean(), sproc =&gt; <a href="/home/runner/work/khepri/horus/doc/horus.html#type-horus_fun" docgen-rel="seetype" docgen-href="horus:horus#horus_fun/0">horus:horus_fun()</a>, is_sproc =&gt; boolean(), payload_version =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-payload_version" docgen-rel="seetype" docgen-href="khepri:khepri#payload_version/0">khepri:payload_version()</a>, child_list_version =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-child_list_version" docgen-rel="seetype" docgen-href="khepri:khepri#child_list_version/0">khepri:child_list_version()</a>, child_list_length =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-child_list_length" docgen-rel="seetype" docgen-href="khepri:khepri#child_list_length/0">khepri:child_list_length()</a>, child_names =&gt; [<a href="/home/runner/work/khepri/khepri/doc/khepri_path.html#type-node_id" docgen-rel="seetype" docgen-href="khepri:khepri_path#node_id/0">khepri_path:node_id()</a>]}</code></p>
+<p><code>node_props() = #{data =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-data" docgen-rel="seetype" docgen-href="khepri:khepri#data/0">khepri:data()</a>, has_data =&gt; boolean(), sproc =&gt; <a href="/home/runner/work/khepri/horus/doc/horus.html#type-horus_fun" docgen-rel="seetype" docgen-href="horus:horus#horus_fun/0">horus:horus_fun()</a>, is_sproc =&gt; boolean(), payload_version =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-payload_version" docgen-rel="seetype" docgen-href="khepri:khepri#payload_version/0">khepri:payload_version()</a>, child_list_version =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-child_list_version" docgen-rel="seetype" docgen-href="khepri:khepri#child_list_version/0">khepri:child_list_version()</a>, child_list_length =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-child_list_length" docgen-rel="seetype" docgen-href="khepri:khepri#child_list_length/0">khepri:child_list_length()</a>, child_names =&gt; [<a href="/home/runner/work/khepri/khepri/doc/khepri_path.html#type-node_id" docgen-rel="seetype" docgen-href="khepri:khepri_path#node_id/0">khepri_path:node_id()</a>], delete_reason =&gt; <a href="/home/runner/work/khepri/khepri/doc/khepri.html#type-delete_reason" docgen-rel="seetype" docgen-href="khepri:khepri#delete_reason/0">khepri:delete_reason()</a>}</code></p>
 <p><p>  Structure used to return properties, payload and child nodes for a specific  
 tree node.</p>
 
@@ -310,7 +326,7 @@ <h3 class="typedecl"><a name="type-store_id">store_id()</a></h3>
   This is the same as the Ra cluster name hosting the Khepri store.</p>
 
 <h3 class="typedecl"><a name="type-tree_options">tree_options()</a></h3>
-<p><code>tree_options() = #{expect_specific_node =&gt; boolean(), props_to_return =&gt; [payload_version | child_list_version | child_list_length | child_names | payload | has_payload | raw_payload], include_root_props =&gt; boolean()}</code></p>
+<p><code>tree_options() = #{expect_specific_node =&gt; boolean(), props_to_return =&gt; [payload_version | child_list_version | child_list_length | child_names | payload | has_payload | raw_payload | delete_reason], include_root_props =&gt; boolean()}</code></p>
 <p><p>  Options used during tree traversal.</p>
 
   <ul>

khepri_adv.html

@@ -309,11 +309,18 @@ <h3 class="function"><a name="put-4">put/4</a></h3>
 in the path pattern is not met, an error is returned and the tree structure  
 is not modified.</p>
 
-  <p>The returned <code>{ok, NodeProps}</code> tuple contains a map with the properties and
-  payload (if any) of the targeted tree node: the payload was the one before
-  the update, other properties like the payload version correspond to the
-  updated node. If the targeted tree node didn't exist, <code>NodeProps</code> will be  
-an empty map.</p>
+  <p>The returned <code>{ok, NodePropsMap}</code> tuple contains a map where keys correspond
+  to the path to a node affected by the put operation. Each key points to a
+  map containing the properties and prior payload (if any) of a tree node
+  created, updated or deleted by the put operation. If the put results in the
+  creation of a tree node this props map will be empty. If the put updates an
+  existing tree node then the props map will contain the payload of the tree
+  node (if any) before the update while the other properties like the payload
+  version correspond to the updated node. The <code>NodePropsMap</code> map might also
+  contain deletions if the put operation leads to an existing tree node's
+  keep-while condition becoming unsatisfied. The props map for any nodes
+  deleted because of an expired keep-while condition will contain a
+  <code>delete_reason</code> key set to <code>keep_while</code>.</p>
 
   The payload must be one of the following form:
   <ul>
@@ -401,11 +408,18 @@ <h3 class="function"><a name="put_many-4">put_many/4</a></h3>
 in the path pattern is not met, an error is returned and the tree structure  
 is not modified.</p>
 
-  <p>The returned <code>{ok, NodePropsMap}</code> tuple contains a map where keys  
-correspond to the path to a tree node matching the path pattern. Each key  
-then points to a map containing the properties and payload (if any) of the  
-targeted tree node: the payload was the one before the update, other  
-properties like the payload version correspond to the updated node.</p>
+  <p>The returned <code>{ok, NodePropsMap}</code> tuple contains a map where keys correspond
+  to the path to a node affected by the put operation. Each key points to a
+  map containing the properties and prior payload (if any) of a tree node
+  created, updated or deleted by the put operation. If the put results in the
+  creation of a tree node this props map will be empty. If the put updates an
+  existing tree node then the props map will contain the payload of the tree
+  node (if any) before the update while the other properties like the payload
+  version correspond to the updated node. The <code>NodePropsMap</code> map might also
+  contain deletions if the put operation leads to an existing tree node's
+  keep-while condition becoming unsatisfied. The props map for any nodes
+  deleted because of an expired keep-while condition will contain a
+  <code>delete_reason</code> key set to <code>keep_while</code>.</p>
 
   The payload must be one of the following form:
   <ul>
@@ -651,17 +665,23 @@ <h3 class="function"><a name="delete-3">delete/3</a></h3>
   one tree node would match at the time. If you want to delete multiple nodes
   at once, use <a docgen-rel="seemfa" docgen-href="#delete_many/3" href="#delete_many-3"><code>delete_many/3</code></a>.</p>
 
-  <p>The returned <code>{ok, NodeProps}</code> tuple contains a map with the properties and
-  payload (if any) of the targeted tree node as they were before the delete.
-  If the targeted tree node didn't exist, <code>NodeProps</code> will be an empty map.</p>
+  <p>The returned <code>{ok, NodePropsMap}</code> tuple contains a map where keys
+  correspond to the path to a deleted tree node. Each key then points to a
+  map containing the properties and payload (if any) of that deleted tree
+  node as they were before the delete. Tree nodes in this map which were
+  the target of the delete command will have a <code>delete_reason</code> key set to
+  <code>explicit</code> in their associated props map. Any tree nodes deleted because
+  their keep-while condition became unsatisfied due to the deletion will have
+  the <code>delete_reason</code> key set to <code>keep_while</code> instead. (See <a docgen-rel="seetype" docgen-href="khepri_condition#keep_while/0" href="khepri_condition.html#type-keep_while"><code>khepri_condition:keep_while()</code></a>.)</p>
 
   <p>When doing an asynchronous update, the <a docgen-rel="seemfa" docgen-href="#handle_async_ret/1" href="#handle_async_ret-1"><code>handle_async_ret/1</code></a>  
 function should be used to handle the message received from Ra.</p>
 
   Example:
   <pre><code>%% Delete the tree node at `/:foo/:bar'.
 {ok, #{data := value,
-       payload_version := 1}} = khepri_adv:delete(StoreId, [foo, bar]).</code></pre>
+       payload_version := 1,
+       delete_reason := explicit}} = khepri_adv:delete(StoreId, [foo, bar]).</code></pre>
  </p>
 <p><b>See also:</b> <a href="#delete_many-3" docgen-rel="seemfa" docgen-href="#delete_many/3">delete_many/3</a>, <a href="khepri.html#delete-3" docgen-rel="seemfa" docgen-href="khepri#delete/3">khepri:delete/3</a>.</p>
 
@@ -716,20 +736,26 @@ <h3 class="function"><a name="delete_many-3">delete_many/3</a></h3>
   <p>The <code>PathPattern</code> can be provided as a native path pattern (a list of tree
   node names and conditions) or as a string. See <a docgen-rel="seemfa" docgen-href="khepri_path#from_string/1" href="khepri_path.html#from_string-1"><code>khepri_path:from_string/1</code></a>.</p>
 
-  <p>The returned <code>{ok, NodePropsMap}</code> tuple contains a map where keys  
-correspond to the path to a deleted tree node. Each key then points to a  
-map containing the properties and payload (if any) of that deleted tree  
-node as they were before the delete.</p>
+  <p>The returned <code>{ok, NodePropsMap}</code> tuple contains a map where keys
+  correspond to the path to a deleted tree node. Each key then points to a
+  map containing the properties and payload (if any) of that deleted tree
+  node as they were before the delete. Tree nodes in this map which were
+  the target of the delete command will have a <code>delete_reason</code> key set to
+  <code>explicit</code> in their associated props map. Any tree nodes deleted because
+  their keep-while condition became unsatisfied due to the deletion will have
+  the <code>delete_reason</code> key set to <code>keep_while</code> instead. (See <a docgen-rel="seetype" docgen-href="khepri_condition#keep_while/0" href="khepri_condition.html#type-keep_while"><code>khepri_condition:keep_while()</code></a>.)</p>
 
   <p>When doing an asynchronous update, the <a docgen-rel="seemfa" docgen-href="#handle_async_ret/1" href="#handle_async_ret-1"><code>handle_async_ret/1</code></a>  
 function should be used to handle the message received from Ra.</p>
 
   Example:
-  <pre><code>%% Delete the tree node at `/:foo/:bar'.
+  <pre><code>%% Delete all tree nodes matching `/*/:bar'.
 {ok, #{[foo, bar] := #{data := value,
-                       payload_version := 1},
-       [baz, bar] := #{payload_version := 1}}} = khepri_adv:delete_many(
-                                                   StoreId, [foo, bar]).</code></pre>
+                       payload_version := 1,
+                       delete_reason := explicit},
+       [baz, bar] := #{payload_version := 1,
+                       delete_reason := explicit}}} =
+khepri_adv:delete_many(StoreId, [?KHEPRI_WILDCARD_STAR, bar]).</code></pre>
  </p>
 <p><b>See also:</b> <a href="#delete-3" docgen-rel="seemfa" docgen-href="#delete/3">delete/3</a>, <a href="khepri.html#delete-3" docgen-rel="seemfa" docgen-href="khepri#delete/3">khepri:delete/3</a>.</p>