## Node values

The type for node values.

The type for node metadata.

The type for contents keys.

The type for steps between nodes.

The type for either (node) keys or (contents) keys combined with their metadata.

The type of hashes of values.

`of_list l`

is the node `n`

such that `list n = l`

.

```
val list :
?offset:int ->
?length:int ->
?cache:bool ->
t ->
(step * value) list
```

`list t`

is the contents of `t`

. `offset`

and `length`

are used to paginate results.

`val of_seq : (unit -> (step * value) Stdlib__Seq.node) -> t`

`of_seq s`

is the node `n`

such that `seq n = s`

.

```
val seq :
?offset:int ->
?length:int ->
?cache:bool ->
t ->
unit ->
(step * value) Stdlib__Seq.node
```

`seq t`

is the contents of `t`

. `offset`

and `length`

are used to paginate results.

See caching for an explanation of the `cache`

parameter

`empty ()`

is the empty node.

`is_empty t`

is true iff `t`

is `empty`

.

`length t`

is the number of entries in `t`

.

`val hash_exn : ?force:bool -> t -> hash`

`hash_exn t`

is the hash of `t`

.

Another way of computing it is `Hash.Typed(Hash)(Node).hash t`

which computes the pre-hash of `t`

before hashing it using `Hash`

. `hash_exn`

might be faster because the it may be optimised (e.g. it may use caching).

`hash_exn t`

is `hash_exn ~force:true t`

which is not expected to raise an exception. `hash_exn ~force:false t`

will raise `Not_found`

if the hash requires IOs to be computed.

`val find : ?cache:bool -> t -> step -> value option`

`find t s`

is the value associated with `s`

in `t`

.

A node can point to user-defined contents. The edge between the node and the contents is labeled by a `step`

.

See caching for an explanation of the `cache`

parameter

`add t s v`

is the node where `find t v`

is `Some s`

but is similar to `t`

otherwise.

`remove t s`

is the node where `find t s`

is `None`

but is similar to `t`

otherwise.

### caching

`cache`

regulates the caching behaviour regarding the node's internal data which may be lazily loaded from the backend, depending on the node implementation.

`cache`

defaults to `true`

which may greatly reduce the IOs and the runtime but may also increase the memory consumption.

`cache = false`

doesn't replace a call to `clear`

, it only prevents the storing of new data, it doesn't discard the existing one.

## Recursive Nodes

Some `Node`

implementations (like `irmin-pack`

's inodes) can represent a node as a set of nodes. One operation on such "high-level" node corresponds to a sequence of recursive calls to the underlying "lower-level" nodes. Note: theses `effects`

are not in the Lwt monad on purpose (so `Tree.hash`

and `Tree.equal`

are not in the Lwt monad as well).

`type effect := expected_depth:int -> node_key -> t option`

The type for read effects.

`with_handler f`

replace the current effect handler `h`

by `f h`

. `f h`

will be called for all the recursive read effects that are required by recursive operations on nodes. .

`type head := [ `

`| `

``Node of (step * value) list`

`| `

``Inode of int * (int * hash) list`

` ]`

Reveal the shallow internal structure of the node.

Only hashes and not keys are revealed in the ``Inode`

case, this is because these inodes might not be keyed yet.

### merging

`merge`

is the merge function for nodes.

`exception Dangling_hash of {`

`context : string;`

`hash : hash;`

`}`