diff --git a/src/PersistentOrderedMap.mo b/src/PersistentOrderedMap.mo
new file mode 100644
index 00000000..34e116b2
--- /dev/null
+++ b/src/PersistentOrderedMap.mo
@@ -0,0 +1,901 @@
+/// Stable key-value map implemented as a red-black tree with nodes storing key-value pairs.
+///
+/// A red-black tree is a balanced binary search tree ordered by the keys.
+///
+/// The tree data structure internally colors each of its nodes either red or black,
+/// and uses this information to balance the tree during the modifying operations.
+///
+/// Performance:
+/// * Runtime: `O(log(n))` worst case cost per insertion, removal, and retrieval operation.
+/// * Space: `O(n)` for storing the entire tree.
+/// `n` denotes the number of key-value entries (i.e. nodes) stored in the tree.
+///
+/// Note:
+/// * Map operations, such as retrieval, insertion, and removal create `O(log(n))` temporary objects that become garbage.
+///
+/// Credits:
+///
+/// The core of this implementation is derived from:
+///
+/// * Ken Friis Larsen's [RedBlackMap.sml](https://github.com/kfl/mosml/blob/master/src/mosmllib/Redblackmap.sml), which itself is based on:
+/// * Stefan Kahrs, "Red-black trees with types", Journal of Functional Programming, 11(4): 425-432 (2001), [version 1 in web appendix](http://www.cs.ukc.ac.uk/people/staff/smk/redblack/rb.html).
+
+
+import Debug "Debug";
+import I "Iter";
+import List "List";
+import Nat "Nat";
+import O "Order";
+
+// TODO: a faster, more compact and less indirect representation would be:
+// type Map<K, V> = {
+//  #red : (Map<K, V>, K, V, Map<K, V>);
+//  #black : (Map<K, V>, K, V, Map<K, V>);
+//  #leaf
+//};
+// (this inlines the colors into the variant, flattens a tuple, and removes a (now) redundant option, for considerable heap savings.)
+// It would also make sense to maintain the size in a separate root for 0(1) access.
+
+module {
+
+  /// Red-black tree of nodes with key-value entries, ordered by the keys.
+  /// The keys have the generic type `K` and the values the generic type `V`.
+  /// Leaves are considered implicitly black.
+  public type Map<K, V> = {
+    #red : (Map<K, V>, (K, V), Map<K, V>);
+    #black : (Map<K, V>, (K, V), Map<K, V>);
+    #leaf
+  };
+
+  /// Operations on `Map`, that require a comparator.
+  ///
+  /// The object should be created once, then used for all the operations
+  /// with `Map` to ensure that the same comparator is used for every operation.
+  ///
+  /// `MapOps` contains methods that require `compare` internally:
+  /// operations that may reshape a `Map` or should find something.
+  public class MapOps<K>(compare : (K,K) -> O.Order) {
+
+    /// Returns a new map, containing all entries given by the iterator `i`.
+    /// If there are multiple entries with the same key the last one is taken.
+    ///
+    /// Example:
+    /// ```motoko
+    /// import Map "mo:base/PersistentOrderedMap";
+    /// import Nat "mo:base/Nat"
+    /// import Iter "mo:base/Iter"
+    ///
+    /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+    /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+    ///
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(rbMap))));
+    ///
+    /// // [(0, "Zero"), (1, "One"), (2, "Two")]
+    /// ```
+    ///
+    /// Runtime: `O(n * log(n))`.
+    /// Space: `O(n)` retained memory plus garbage, see the note below.
+    /// where `n` denotes the number of key-value entries stored in the tree and
+    /// assuming that the `compare` function implements an `O(1)` comparison.
+    ///
+    /// Note: Creates `O(n * log(n))` temporary objects that will be collected as garbage.
+    public func fromIter<V>(i : I.Iter<(K,V)>) : Map<K, V>
+      = Internal.fromIter(i, compare);
+
+    /// Insert the value `value` with key `key` into map `rbMap`. Overwrites any existing entry with key `key`.
+    /// Returns a modified map.
+    ///
+    /// Example:
+    /// ```motoko
+    /// import Map "mo:base/PersistentOrderedMap";
+    /// import Nat "mo:base/Nat"
+    /// import Iter "mo:base/Iter"
+    ///
+    /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+    /// var rbMap = Map.empty<Nat, Text>();
+    ///
+    /// rbMap := mapOps.put(rbMap, 0, "Zero");
+    /// rbMap := mapOps.put(rbMap, 2, "Two");
+    /// rbMap := mapOps.put(rbMap, 1, "One");
+    ///
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(rbMap))));
+    ///
+    /// // [(0, "Zero"), (1, "One"), (2, "Two")]
+    /// ```
+    ///
+    /// Runtime: `O(log(n))`.
+    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// where `n` denotes the number of key-value entries stored in the tree and
+    /// assuming that the `compare` function implements an `O(1)` comparison.
+    ///
+    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    public func put<V>(rbMap : Map<K, V>, key : K, value : V) : Map<K, V>
+      = Internal.put(rbMap, compare, key, value);
+
+    /// Insert the value `value` with key `key` into `rbMap`. Returns modified map and
+    /// the previous value associated with key `key` or `null` if no such value exists.
+    ///
+    /// Example:
+    /// ```motoko
+    /// import Map "mo:base/PersistentOrderedMap";
+    /// import Nat "mo:base/Nat"
+    /// import Iter "mo:base/Iter"
+    ///
+    /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+    /// let rbMap0 = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+    ///
+    /// let (rbMap1, old1) = mapOps.replace(rbMap0, 0, "Nil");
+    ///
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(rbMap1))));
+    /// Debug.print(debug_show(old1));
+    /// // [(0, "Nil"), (1, "One"), (2, "Two")]
+    /// // ?"Zero"
+    ///
+    /// let (rbMap2, old2) = mapOps.replace(rbMap0, 3, "Three");
+    ///
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(rbMap2))));
+    /// Debug.print(debug_show(old2));
+    /// // [(0, "Zero"), (1, "One"), (2, "Two"), (3, "Three")]
+    /// // null
+    /// ```
+    ///
+    /// Runtime: `O(log(n))`.
+    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// where `n` denotes the number of key-value entries stored in the tree and
+    /// assuming that the `compare` function implements an `O(1)` comparison.
+    ///
+    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    public func replace<V>(rbMap : Map<K, V>, key : K, value : V) : (Map<K,V>, ?V)
+      = Internal.replace(rbMap, compare, key, value);
+
+    /// Creates a new map by applying `f` to each entry in `rbMap`. For each entry
+    /// `(k, v)` in the old map, if `f` evaluates to `null`, the entry is discarded.
+    /// Otherwise, the entry is transformed into a new entry `(k, v2)`, where
+    /// the new value `v2` is the result of applying `f` to `(k, v)`.
+    ///
+    /// Example:
+    /// ```motoko
+    /// import Map "mo:base/PersistentOrderedMap";
+    /// import Nat "mo:base/Nat"
+    /// import Iter "mo:base/Iter";
+    ///
+    /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+    /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+    ///
+    /// func f(key : Nat, val : Text) : ?Text {
+    ///   if(key == 0) {null}
+    ///   else { ?("Twenty " # val)}
+    /// };
+    ///
+    /// let newRbMap = mapOps.mapFilter(rbMap, f);
+    ///
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(newRbMap))));
+    ///
+    /// // [(1, "Twenty One"), (2, "Twenty Two")]
+    /// ```
+    ///
+    /// Runtime: `O(n)`.
+    /// Space: `O(n)` retained memory plus garbage, see the note below.
+    /// where `n` denotes the number of key-value entries stored in the tree and
+    /// assuming that the `compare` function implements an `O(1)` comparison.
+    ///
+    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    public func mapFilter<V1, V2>(rbMap : Map<K, V1>, f : (K, V1) -> ?V2) : Map<K, V2>
+      = Internal.mapFilter(rbMap, compare, f);
+
+    /// Get the value associated with key `key` in the given `rbMap` if present and `null` otherwise.
+    ///
+    /// Example:
+    /// ```motoko
+    /// import Map "mo:base/PersistentOrderedMap";
+    /// import Nat "mo:base/Nat"
+    ///
+    /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+    /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+    ///
+    /// Debug.print(debug_show mapOps.get(rbMap, 1));
+    /// Debug.print(debug_show mapOps.get(rbMap, 42));
+    ///
+    /// // ?"One"
+    /// // null
+    /// ```
+    ///
+    /// Runtime: `O(log(n))`.
+    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// where `n` denotes the number of key-value entries stored in the tree and
+    /// assuming that the `compare` function implements an `O(1)` comparison.
+    ///
+    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    public func get<V>(rbMap : Map<K, V>, key : K) : ?V
+      = Internal.get(rbMap, compare, key);
+
+    /// Deletes the entry with the key `key` from the `rbMap`. Has no effect if `key` is not
+    /// present in the map. Returns modified map.
+    ///
+    /// Example:
+    /// ```motoko
+    /// import Map "mo:base/PersistentOrderedMap";
+    /// import Nat "mo:base/Nat"
+    ///
+    /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+    /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+    ///
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(mapOps.delete(rbMap, 1)))));
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(mapOps.delete(rbMap, 42)))));
+    ///
+    /// // [(0, "Zero"), (2, "Two")]
+    /// // [(0, "Zero"), (1, "One"), (2, "Two")]
+    /// ```
+    ///
+    /// Runtime: `O(log(n))`.
+    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// where `n` denotes the number of key-value entries stored in the tree and
+    /// assuming that the `compare` function implements an `O(1)` comparison.
+    ///
+    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    public func delete<V>(rbMap : Map<K, V>, key : K) : Map<K, V>
+      = Internal.delete(rbMap, compare, key);
+
+    /// Deletes the entry with the key `key`. Returns modified map and the
+    /// previous value associated with key `key` or `null` if no such value exists.
+    ///
+    /// Example:
+    /// ```motoko
+    /// import Map "mo:base/PersistentOrderedMap";
+    /// import Nat "mo:base/Nat"
+    /// import Iter "mo:base/Iter"
+    ///
+    /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+    /// let rbMap0 = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+    ///
+    /// let (rbMap1, old1) = mapOps.remove(rbMap0, 0);
+    ///
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(rbMap1))));
+    /// Debug.print(debug_show(old1));
+    /// // [(1, "One"), (2, "Two")]
+    /// // ?"Zero"
+    ///
+    /// let (rbMap2, old2) = mapOps.remove(rbMap0, 42);
+    ///
+    /// Debug.print(debug_show(Iter.toArray(Map.entries(rbMap2))));
+    /// Debug.print(debug_show(old2));
+    /// // [(0, "Zero"), (1, "One"), (2, "Two")]
+    /// // null
+    /// ```
+    ///
+    /// Runtime: `O(log(n))`.
+    /// Space: `O(1)` retained memory plus garbage, see the note below.
+    /// where `n` denotes the number of key-value entries stored in the tree and
+    /// assuming that the `compare` function implements an `O(1)` comparison.
+    ///
+    /// Note: Creates `O(log(n))` temporary objects that will be collected as garbage.
+    public func remove<V>(rbMap : Map<K, V>, key : K) : (Map<K,V>, ?V)
+      = Internal.remove(rbMap, compare, key);
+
+  };
+
+  /// Create a new empty map.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  ///
+  /// let rbMap = Map.empty<Nat, Text>();
+  ///
+  /// Debug.print(debug_show(Map.size(rbMap)));
+  ///
+  /// // 0
+  /// ```
+  ///
+  /// Cost of empty map creation
+  /// Runtime: `O(1)`.
+  /// Space: `O(1)`
+  public func empty<K, V>() : Map<K, V> = #leaf;
+
+  type IterRep<K, V> = List.List<{ #tr : Map<K, V>; #xy : (K, V) }>;
+
+  public type Direction = { #fwd; #bwd };
+
+  /// Get an iterator for the entries of the `rbMap`, in ascending (`#fwd`) or descending (`#bwd`) order as specified by `direction`.
+  /// The iterator takes a snapshot view of the map and is not affected by concurrent modifications.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  /// import Nat "mo:base/Nat"
+  /// import Iter "mo:base/Iter"
+  ///
+  /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+  /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+  ///
+  /// Debug.print(debug_show(Iter.toArray(Map.iter(rbMap, #fwd))));
+  /// Debug.print(debug_show(Iter.toArray(Map.iter(rbMap, #bwd))));
+  ///
+  /// //  [(0, "Zero"), (1, "One"), (2, "Two")]
+  /// //  [(2, "Two"), (1, "One"), (0, "Zero")]
+  /// ```
+  ///
+  /// Cost of iteration over all elements:
+  /// Runtime: `O(n)`.
+  /// Space: `O(log(n))` retained memory plus garbage, see the note below.
+  /// where `n` denotes the number of key-value entries stored in the map.
+  ///
+  /// Note: Full map iteration creates `O(n)` temporary objects that will be collected as garbage.
+  public func iter<K, V>(rbMap : Map<K, V>, direction : Direction) : I.Iter<(K, V)> {
+    let turnLeftFirst : MapTraverser<K, V>
+     = func (l, xy, r, ts) { ?(#tr(l), ?(#xy(xy), ?(#tr(r), ts))) };
+
+    let turnRightFirst : MapTraverser<K, V>
+     = func (l, xy, r, ts) { ?(#tr(r), ?(#xy(xy), ?(#tr(l), ts))) };
+
+    switch direction {
+      case (#fwd) IterMap(rbMap, turnLeftFirst);
+      case (#bwd) IterMap(rbMap, turnRightFirst)
+    }
+  };
+
+  type MapTraverser<K, V> = (Map<K, V>, (K, V), Map<K, V>, IterRep<K, V>) -> IterRep<K, V>;
+
+  class IterMap<K, V>(rbMap : Map<K, V>, mapTraverser : MapTraverser<K, V>) {
+    var trees : IterRep<K, V> = ?(#tr(rbMap), null);
+    public func next() : ?(K, V) {
+        switch (trees) {
+          case (null) { null };
+          case (?(#tr(#leaf), ts)) {
+            trees := ts;
+            next()
+          };
+          case (?(#xy(xy), ts)) {
+            trees := ts;
+            ?xy
+          };
+          case (?(#tr(#red(l, xy, r) or #black(l, xy, r)), ts)) {
+            trees := mapTraverser(l, xy, r, ts);
+            next()
+          }
+        }
+      }
+  };
+
+  /// Returns an Iterator (`Iter`) over the key-value pairs in the map.
+  /// Iterator provides a single method `next()`, which returns
+  /// pairs in ascending order by keys, or `null` when out of pairs to iterate over.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  /// import Nat "mo:base/Nat"
+  /// import Iter "mo:base/Iter"
+  ///
+  /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+  /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+  ///
+  /// Debug.print(debug_show(Iter.toArray(Map.entries(rbMap))));
+  ///
+  ///
+  /// // [(0, "Zero"), (1, "One"), (2, "Two")]
+  /// ```
+  /// Cost of iteration over all elements:
+  /// Runtime: `O(n)`.
+  /// Space: `O(log(n))` retained memory plus garbage, see the note below.
+  /// where `n` denotes the number of key-value entries stored in the map.
+  ///
+  /// Note: Full map iteration creates `O(n)` temporary objects that will be collected as garbage.
+  public func entries<K, V>(m : Map<K, V>) : I.Iter<(K, V)> = iter(m, #fwd);
+
+  /// Returns an Iterator (`Iter`) over the keys of the map.
+  /// Iterator provides a single method `next()`, which returns
+  /// keys in ascending order, or `null` when out of keys to iterate over.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  /// import Nat "mo:base/Nat"
+  /// import Iter "mo:base/Iter"
+  ///
+  /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+  /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+  ///
+  /// Debug.print(debug_show(Iter.toArray(Map.keys(rbMap))));
+  ///
+  /// // [0, 1, 2]
+  /// ```
+  /// Cost of iteration over all elements:
+  /// Runtime: `O(n)`.
+  /// Space: `O(log(n))` retained memory plus garbage, see the note below.
+  /// where `n` denotes the number of key-value entries stored in the map.
+  ///
+  /// Note: Full map iteration creates `O(n)` temporary objects that will be collected as garbage.
+  public func keys<K, V>(m : Map<K, V>) : I.Iter<K>
+    = I.map(entries(m), func(kv : (K, V)) : K {kv.0});
+
+  /// Returns an Iterator (`Iter`) over the values of the map.
+  /// Iterator provides a single method `next()`, which returns
+  /// values in no specific order, or `null` when out of values to iterate over.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  /// import Nat "mo:base/Nat"
+  /// import Iter "mo:base/Iter"
+  ///
+  /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+  /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+  ///
+  /// Debug.print(debug_show(Iter.toArray(Map.vals(rbMap))));
+  ///
+  /// // ["Zero", "One", "Two"]
+  /// ```
+  /// Cost of iteration over all elements:
+  /// Runtime: `O(n)`.
+  /// Space: `O(log(n))` retained memory plus garbage, see the note below.
+  /// where `n` denotes the number of key-value entries stored in the map.
+  ///
+  /// Note: Full map iteration creates `O(n)` temporary objects that will be collected as garbage.
+  public func vals<K, V>(m : Map<K, V>) : I.Iter<V>
+    = I.map(entries(m), func(kv : (K, V)) : V {kv.1});
+
+  /// Creates a new map by applying `f` to each entry in `rbMap`. Each entry
+  /// `(k, v)` in the old map is transformed into a new entry `(k, v2)`, where
+  /// the new value `v2` is created by applying `f` to `(k, v)`.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  /// import Nat "mo:base/Nat"
+  /// import Iter "mo:base/Iter"
+  ///
+  /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+  /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+  ///
+  /// func f(key : Nat, _val : Text) : Nat = key * 2;
+  ///
+  /// let resMap = Map.map(rbMap, f);
+  ///
+  /// Debug.print(debug_show(Iter.toArray(Map.entries(resMap))));
+  ///
+  /// // [(0, 0), (1, 2), (2, 4)]
+  /// ```
+  ///
+  /// Cost of mapping all the elements:
+  /// Runtime: `O(n)`.
+  /// Space: `O(n)` retained memory
+  /// where `n` denotes the number of key-value entries stored in the map.
+  public func map<K, V1, V2>(rbMap : Map<K, V1>, f : (K, V1) -> V2) : Map<K, V2> {
+    func mapRec(m : Map<K, V1>) : Map<K, V2> {
+      switch m {
+        case (#leaf) { #leaf };
+        case (#red(l, xy, r)) {
+          #red(mapRec l, (xy.0, f xy), mapRec r)
+        };
+        case (#black(l, xy, r)) {
+          #black(mapRec l, (xy.0, f xy), mapRec r)
+        };
+      }
+    };
+    mapRec(rbMap)
+  };
+
+  /// Determine the size of the tree as the number of key-value entries.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  /// import Nat "mo:base/Nat"
+  /// import Iter "mo:base/Iter"
+  ///
+  /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+  /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+  ///
+  /// Debug.print(debug_show(Map.size(rbMap)));
+  ///
+  /// // 3
+  /// ```
+  ///
+  /// Runtime: `O(n)`.
+  /// Space: `O(1)`.
+  /// where `n` denotes the number of key-value entries stored in the tree.
+  public func size<K, V>(t : Map<K, V>) : Nat {
+    switch t {
+      case (#red(l, _, r) or #black(l, _, r)) {
+        size(l) + size(r) + 1
+      };
+      case (#leaf) { 0 }
+    }
+  };
+
+  /// Collapses the elements in `rbMap` into a single value by starting with `base`
+  /// and progressively combining keys and values into `base` with `combine`. Iteration runs
+  /// left to right.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  /// import Nat "mo:base/Nat"
+  /// import Iter "mo:base/Iter"
+  ///
+  /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+  /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+  ///
+  /// func folder(key : Nat, val : Text, accum : (Nat, Text)) : ((Nat, Text))
+  ///   = (key + accum.0, accum.1 # val);
+  ///
+  /// Debug.print(debug_show(Map.foldLeft(rbMap, (0, ""), folder)));
+  ///
+  /// // (3, "ZeroOneTwo")
+  /// ```
+  ///
+  /// Cost of iteration over all elements:
+  /// Runtime: `O(n)`.
+  /// Space: depends on `combine` function plus garbage, see the note below.
+  /// where `n` denotes the number of key-value entries stored in the map.
+  ///
+  /// Note: Full map iteration creates `O(n)` temporary objects that will be collected as garbage.
+  public func foldLeft<Key, Value, Accum>(
+    rbMap : Map<Key, Value>,
+    base : Accum,
+    combine : (Key, Value, Accum) -> Accum
+  ) : Accum
+  {
+    switch (rbMap) {
+      case (#leaf) { base };
+      case (#red(l, (k, v), r) or #black(l, (k, v), r)) {
+        let left = foldLeft(l, base, combine);
+        let middle = combine(k, v, left);
+        foldLeft(r, middle, combine)
+      }
+    }
+  };
+
+  /// Collapses the elements in `rbMap` into a single value by starting with `base`
+  /// and progressively combining keys and values into `base` with `combine`. Iteration runs
+  /// right to left.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Map "mo:base/PersistentOrderedMap";
+  /// import Nat "mo:base/Nat"
+  /// import Iter "mo:base/Iter"
+  ///
+  /// let mapOps = Map.MapOps<Nat>(Nat.compare);
+  /// let rbMap = mapOps.fromIter<Text>(Iter.fromArray([(0, "Zero"), (2, "Two"), (1, "One")]));
+  ///
+  /// func folder(key : Nat, val : Text, accum : (Nat, Text)) : ((Nat, Text))
+  ///   = (key + accum.0, accum.1 # val);
+  ///
+  /// Debug.print(debug_show(Map.foldRight(rbMap, (0, ""), folder)));
+  ///
+  /// // (3, "TwoOneZero")
+  /// ```
+  ///
+  /// Cost of iteration over all elements:
+  /// Runtime: `O(n)`.
+  /// Space: depends on `combine` function plus garbage, see the note below.
+  /// where `n` denotes the number of key-value entries stored in the map.
+  ///
+  /// Note: Full map iteration creates `O(n)` temporary objects that will be collected as garbage.
+  public func foldRight<Key, Value, Accum>(
+    rbMap : Map<Key, Value>,
+    base : Accum,
+    combine : (Key, Value, Accum) -> Accum
+  ) : Accum
+  {
+    switch (rbMap) {
+      case (#leaf) { base };
+      case (#red(l, (k, v), r) or #black(l, (k, v), r)) {
+        let right = foldRight(r, base, combine);
+        let middle = combine(k, v, right);
+        foldRight(l, middle, combine)
+      }
+    }
+  };
+
+
+  public module Internal {
+
+    public func fromIter<K, V>(i : I.Iter<(K,V)>, compare : (K, K) -> O.Order) : Map<K, V>
+    {
+      var map = #leaf : Map<K,V>;
+      for(val in i) {
+        map := put(map, compare, val.0, val.1);
+      };
+      map
+    };
+
+    public func mapFilter<K, V1, V2>(t : Map<K, V1>, compare : (K, K) -> O.Order, f : (K, V1) -> ?V2) : Map<K, V2>{
+      func combine(key : K, value1 : V1, acc : Map<K, V2>) : Map<K, V2> {
+        switch (f(key, value1)){
+          case null { acc };
+          case (?value2) {
+            put(acc, compare, key, value2)
+          }
+        }
+      };
+      foldLeft(t, #leaf, combine)
+    };
+
+    public func get<K, V>(t : Map<K, V>, compare : (K, K) -> O.Order, x : K) : ?V {
+      switch t {
+        case (#red(l, xy, r) or #black(l, xy, r)) {
+          switch (compare(x, xy.0)) {
+            case (#less) { get(l, compare, x) };
+            case (#equal) { ?xy.1 };
+            case (#greater) { get(r, compare, x) }
+          }
+        };
+        case (#leaf) { null }
+      }
+    };
+
+    func redden<K, V>(t : Map<K, V>) : Map<K, V> {
+      switch t {
+        case (#black (l, xy, r)) {
+          (#red (l, xy, r))
+        };
+        case _ {
+          Debug.trap "RBTree.red"
+        }
+      }
+    };
+
+    func lbalance<K,V>(left : Map<K, V>, xy : (K,V), right : Map<K, V>) : Map<K,V> {
+      switch (left, right) {
+        case (#red(#red(l1, xy1, r1), xy2, r2), r) {
+          #red(
+            #black(l1, xy1, r1),
+            xy2,
+            #black(r2, xy, r))
+        };
+        case (#red(l1, xy1, #red(l2, xy2, r2)), r) {
+          #red(
+            #black(l1, xy1, l2),
+            xy2,
+            #black(r2, xy, r))
+        };
+        case _ {
+          #black(left, xy, right)
+        }
+      }
+    };
+
+    func rbalance<K,V>(left : Map<K, V>, xy : (K,V), right : Map<K, V>) : Map<K,V> {
+      switch (left, right) {
+        case (l, #red(l1, xy1, #red(l2, xy2, r2))) {
+          #red(
+            #black(l, xy, l1),
+            xy1,
+            #black(l2, xy2, r2))
+        };
+        case (l, #red(#red(l1, xy1, r1), xy2, r2)) {
+          #red(
+            #black(l, xy, l1),
+            xy1,
+            #black(r1, xy2, r2))
+        };
+        case _ {
+          #black(left, xy, right)
+        };
+      }
+    };
+
+    type ClashResolver<A> = { old : A; new : A } -> A;
+
+    func insertWith<K, V> (
+      m : Map<K, V>,
+      compare : (K, K) -> O.Order,
+      key : K,
+      val : V,
+      onClash : ClashResolver<V>
+    )
+    : Map<K, V>{
+      func ins(tree : Map<K,V>) : Map<K,V> {
+        switch tree {
+          case (#black(left, xy, right)) {
+            switch (compare (key, xy.0)) {
+              case (#less) {
+                lbalance(ins left, xy, right)
+              };
+              case (#greater) {
+                rbalance(left, xy, ins right)
+              };
+              case (#equal) {
+                let newVal = onClash({ new = val; old = xy.1 });
+                #black(left, (key,newVal), right)
+              }
+            }
+          };
+          case (#red(left, xy, right)) {
+            switch (compare (key, xy.0)) {
+              case (#less) {
+                #red(ins left, xy, right)
+              };
+              case (#greater) {
+                #red(left, xy, ins right)
+              };
+              case (#equal) {
+                let newVal = onClash { new = val; old = xy.1 };
+                #red(left, (key,newVal), right)
+              }
+            }
+          };
+          case (#leaf) {
+            #red(#leaf, (key,val), #leaf)
+          }
+        };
+      };
+      switch (ins m) {
+        case (#red(left, xy, right)) {
+          #black(left, xy, right);
+        };
+        case other { other };
+      };
+    };
+
+    public func replace<K, V>(
+      m : Map<K, V>,
+      compare : (K, K) -> O.Order,
+      key : K,
+      val : V
+    )
+    : (Map<K,V>, ?V) {
+      var oldVal : ?V = null;
+      func onClash( clash : { old : V; new : V } ) : V
+      {
+        oldVal := ?clash.old;
+        clash.new
+      };
+      let res = insertWith(m, compare, key, val, onClash);
+      (res, oldVal)
+    };
+
+    public func put<K, V> (
+      m : Map<K, V>,
+      compare : (K, K) -> O.Order,
+      key : K,
+      val : V
+    ) : Map<K, V> = replace(m, compare, key, val).0;
+
+
+    func balLeft<K,V>(left : Map<K, V>, xy : (K,V), right : Map<K, V>) : Map<K,V> {
+      switch (left, right) {
+        case (#red(l1, xy1, r1), r) {
+          #red(
+            #black(l1, xy1, r1),
+            xy,
+            r)
+        };
+        case (_, #black(l2, xy2, r2)) {
+          rbalance(left, xy, #red(l2, xy2, r2))
+        };
+        case (_, #red(#black(l2, xy2, r2), xy3, r3)) {
+          #red(
+            #black(left, xy, l2),
+            xy2,
+            rbalance(r2, xy3, redden r3))
+        };
+        case _ { Debug.trap "balLeft" };
+      }
+    };
+
+    func balRight<K,V>(left : Map<K, V>, xy : (K,V), right : Map<K, V>) : Map<K,V> {
+      switch (left, right) {
+        case (l, #red(l1, xy1, r1)) {
+          #red(
+            l,
+            xy,
+            #black(l1, xy1, r1))
+        };
+        case (#black(l1, xy1, r1), r) {
+          lbalance(#red(l1, xy1, r1), xy, r);
+        };
+        case (#red(l1, xy1, #black(l2, xy2, r2)), r3) {
+          #red(
+            lbalance(redden l1, xy1, l2),
+            xy2,
+            #black(r2, xy, r3))
+        };
+        case _ { Debug.trap "balRight" };
+      }
+    };
+
+    func append<K,V>(left : Map<K, V>, right: Map<K, V>) : Map<K, V> {
+      switch (left, right) {
+        case (#leaf,  _) { right };
+        case (_,  #leaf) { left };
+        case (#red (l1, xy1, r1),
+              #red (l2, xy2, r2)) {
+          switch (append (r1, l2)) {
+            case (#red (l3, xy3, r3)) {
+              #red(
+                #red(l1, xy1, l3),
+                xy3,
+                #red(r3, xy2, r2))
+            };
+            case r1l2 {
+              #red(l1, xy1, #red(r1l2, xy2, r2))
+            }
+          }
+        };
+        case (t1, #red(l2, xy2, r2)) {
+          #red(append(t1, l2), xy2, r2)
+        };
+        case (#red(l1, xy1, r1), t2) {
+          #red(l1, xy1, append(r1, t2))
+        };
+        case (#black(l1, xy1, r1), #black (l2, xy2, r2)) {
+          switch (append (r1, l2)) {
+            case (#red (l3, xy3, r3)) {
+              #red(
+                #black(l1, xy1, l3),
+                xy3,
+                #black(r3, xy2, r2))
+            };
+            case r1l2 {
+              balLeft (
+                l1,
+                xy1,
+                #black(r1l2, xy2, r2)
+              )
+            }
+          }
+        }
+      }
+    };
+
+    public func delete<K, V>(m : Map<K, V>, compare : (K, K) -> O.Order, key : K) : Map<K, V>
+      = remove(m, compare, key).0;
+
+    public func remove<K, V>(tree : Map<K, V>, compare : (K, K) -> O.Order, x : K) : (Map<K,V>, ?V) {
+      var y0 : ?V = null;
+      func delNode(left : Map<K,V>, xy : (K, V), right : Map<K,V>) : Map<K,V> {
+        switch (compare (x, xy.0)) {
+          case (#less) {
+            let newLeft = del left;
+            switch left {
+              case (#black(_, _, _)) {
+                balLeft(newLeft, xy, right)
+              };
+              case _ {
+                #red(newLeft, xy, right)
+              }
+            }
+          };
+          case (#greater) {
+            let newRight = del right;
+            switch right {
+              case (#black(_, _, _)) {
+                balRight(left, xy, newRight)
+              };
+              case _ {
+                #red(left, xy, newRight)
+              }
+            }
+          };
+          case (#equal) {
+            y0 := ?xy.1;
+            append(left, right)
+          };
+        }
+      };
+      func del(tree : Map<K,V>) : Map<K,V> {
+        switch tree {
+          case (#red(left, xy, right)) {
+            delNode(left, xy, right)
+          };
+          case (#black(left, xy, right)) {
+            delNode(left, xy, right)
+          };
+          case (#leaf) {
+            tree
+          }
+        };
+      };
+      switch (del(tree)) {
+        case (#red(left, xy, right)) {
+          (#black(left, xy, right), y0);
+        };
+        case other { (other, y0) };
+      };
+    }
+  }
+}
diff --git a/test/PersistentOrderedMap.prop.test.mo b/test/PersistentOrderedMap.prop.test.mo
new file mode 100644
index 00000000..b2b553cd
--- /dev/null
+++ b/test/PersistentOrderedMap.prop.test.mo
@@ -0,0 +1,240 @@
+// @testmode wasi
+
+import Map "../src/PersistentOrderedMap";
+import Nat "../src/Nat";
+import Iter "../src/Iter";
+import Debug "../src/Debug";
+import Array "../src/Array";
+import Option "../src/Option";
+
+import Suite "mo:matchers/Suite";
+import T "mo:matchers/Testable";
+import M "mo:matchers/Matchers";
+
+import Random2 "mo:base/Random";
+
+let { run; test; suite } = Suite;
+
+class MapMatcher(expected : Map.Map<Nat, Text>) : M.Matcher<Map.Map<Nat, Text>> {
+  public func describeMismatch(actual : Map.Map<Nat, Text>, _description : M.Description) {
+    Debug.print(debug_show (Iter.toArray(Map.entries(actual))) # " should be " # debug_show (Iter.toArray(Map.entries(expected))))
+  };
+
+  public func matches(actual : Map.Map<Nat, Text>) : Bool {
+    Iter.toArray(Map.entries(actual)) == Iter.toArray(Map.entries(expected))
+  }
+};
+
+object Random {
+  var number = 4711;
+  public func next() : Nat {
+    number := (15485863 * number + 5) % 15485867;
+    number
+  };
+
+  public func nextNat(range: (Nat, Nat)): Nat {
+    let n = next();
+    let v = n % (range.1 - range.0 + 1) + range.0;
+    v
+  };
+
+  public func nextEntries(range: (Nat, Nat), size: Nat): [(Nat, Text)] {
+    Array.tabulate<(Nat, Text)>(size, func(_ix) { 
+      let key = nextNat(range); (key, debug_show(key)) } )
+  }
+};
+
+let natMap = Map.MapOps<Nat>(Nat.compare);
+
+func mapGen(samples_number: Nat, size: Nat, range: (Nat, Nat)): Iter.Iter<Map.Map<Nat, Text>> {
+  object {
+    var n = 0;
+    public func next(): ?Map.Map<Nat, Text>  {
+      n += 1;
+      if (n > samples_number) { 
+        null 
+      } else {
+        ?natMap.fromIter<Text>(Random.nextEntries(range, size).vals())
+      }
+    }
+  }
+};
+
+
+func run_all_props(range: (Nat, Nat), size: Nat, map_samples: Nat, query_samples: Nat) {
+  func prop(name: Text, f: Map.Map<Nat, Text> -> Bool): Suite.Suite {
+    var error_msg: Text = "";
+    test(name, do {
+        var error = true;
+        label stop for(map in mapGen(map_samples, size, range)) { 
+          if (not f(map)) {
+            error_msg := "Property \"" # name # "\" failed\n";
+            error_msg #= "\n m: " # debug_show(Iter.toArray(Map.entries(map)));
+            break stop;
+          }
+        };
+        error_msg
+      }, M.describedAs(error_msg, M.equals(T.text(""))))
+  };
+  func prop_with_key(name: Text, f: (Map.Map<Nat, Text>, Nat) -> Bool): Suite.Suite {
+    var error_msg: Text = "";
+    test(name, do {
+        label stop for(map in mapGen(map_samples, size, range)) {
+          for (_query_ix in Iter.range(0, query_samples-1)) {
+            let key = Random.nextNat(range);
+            if (not f(map, key)) {
+              error_msg #= "Property \"" # name # "\" failed";
+              error_msg #= "\n m: " # debug_show(Iter.toArray(Map.entries(map)));
+              error_msg #= "\n k: " # debug_show(key);
+              break stop;
+            }
+          }
+        };
+        error_msg
+      }, M.describedAs(error_msg, M.equals(T.text(""))))
+  };
+  run(
+    suite("Property tests",
+   [ 
+      suite("empty", [
+        test("get(empty(), k) == null", label res : Bool {
+          for (_query_ix in Iter.range(0, query_samples-1)) {
+            let k = Random.nextNat(range);
+            if(natMap.get(Map.empty<Nat, Text>(), k) != null)
+              break res(false);
+          };
+          true;
+        }, M.equals(T.bool(true)))
+      ]),
+
+      suite("get & put", [
+        prop_with_key("get(put(m, k, v), k) == ?v", func (m, k) {
+          natMap.get(natMap.put(m, k, "v"), k) == ?"v"
+        }),
+        prop_with_key("get(put(put(m, k, v1), k, v2), k) == ?v2", func (m, k) {
+          let (v1, v2) = ("V1", "V2");
+          natMap.get(natMap.put(natMap.put(m, k, v1), k, v2), k) == v2
+        }),
+      ]),
+      
+      suite("replace", [
+        prop_with_key("replace(m, k, v).0 == put(m, k, v)", func (m, k) {
+          natMap.replace(m, k, "v").0 == natMap.put(m, k, "v")
+        }),
+        prop_with_key("replace(put(m, k, v1), k, v2).1 == ?v1", func (m, k) {
+          natMap.replace(natMap.put(m, k, "v1"), k, "v2").1 == ?"v1"
+        }),
+        prop_with_key("get(m, k) == null ==> replace(m, k, v).1 == null", func (m, k) {
+          if (natMap.get(m, k) == null) {
+            natMap.replace(m, k, "v").1 == null
+          } else { true }
+        }),
+      ]),
+
+      suite("delete", [
+        prop_with_key("get(m, k) == null ==> delete(m, k) == m", func (m, k) {
+          if (natMap.get(m, k) == null) {
+            MapMatcher(m).matches(natMap.delete(m, k))
+          } else { true }
+        }),
+        prop_with_key("delete(put(m, k, v), k) == m", func (m, k) {
+          if (natMap.get(m, k) == null) {
+            MapMatcher(m).matches(natMap.delete(natMap.put(m, k, "v"), k))
+          } else { true }
+        }),
+        prop_with_key("delete(delete(m, k), k)) == delete(m, k)", func (m, k) {
+          let m1 = natMap.delete(natMap.delete(m, k), k);
+          let m2 = natMap.delete(m, k);
+          MapMatcher(m2).matches(m1)
+        })
+      ]),
+
+      suite("remove", [
+        prop_with_key("remove(m, k).0 == delete(m, k)", func (m, k) {
+          let m1 = natMap.remove(m, k).0;
+          let m2 = natMap.delete(m, k);
+          MapMatcher(m2).matches(m1)
+        }),
+        prop_with_key("remove(put(m, k, v), k).1 == ?v", func (m, k) {
+          natMap.remove(natMap.put(m, k, "v"), k).1 == ?"v" 
+        }),
+        prop_with_key("remove(remove(m, k).0, k).1 == null", func (m, k) {
+          natMap.remove(natMap.remove(m, k).0, k).1 == null
+        }),
+        prop_with_key("put(remove(m, k).0, k, remove(m, k).1) == m", func (m, k) {
+          if (natMap.get(m, k) != null) {
+            MapMatcher(m).matches(natMap.put(natMap.remove(m, k).0, k, Option.get(natMap.remove(m, k).1, "")))
+          } else { true }
+        })
+      ]),
+
+      suite("size", [
+        prop_with_key("size(put(m, k, v)) == size(m) + int(get(m, k) == null)", func (m, k) {
+          Map.size(natMap.put(m, k, "v")) == Map.size(m) + (if (natMap.get(m, k) == null) {1} else {0})
+        }),
+        prop_with_key("size(delete(m, k)) + int(get(m, k) != null) == size(m)", func (m, k) {
+          Map.size(natMap.delete(m, k)) + (if (natMap.get(m, k) != null) {1} else {0}) == Map.size(m)
+        })
+      ]),
+      
+      suite("iter,keys,vals,entries",  [
+        prop("fromIter(iter(m, #fwd)) == m", func (m) {
+          MapMatcher(m).matches(natMap.fromIter(Map.iter(m, #fwd)))
+        }),
+        prop("fromIter(iter(m, #bwd)) == m", func (m) {
+          MapMatcher(m).matches(natMap.fromIter(Map.iter(m, #bwd)))
+        }),
+        prop("iter(m, #fwd) = zip(key(m), vals(m))", func (m) {
+          let k = Map.keys<Nat, Text>(m);
+          let v = Map.vals(m);
+          for (e in Map.iter(m, #fwd)) {
+            if (e.0 != k.next() or e.1 != v.next())
+              return false;
+          };
+          return true;
+        }),
+        prop("entries(m) == iter(m, #fwd)", func (m) {
+          let it = Map.iter(m, #fwd);
+          for (e in Map.entries(m)) {
+            if (it.next() != e)
+              return false;
+          };
+          return true
+        })
+      ]),
+      
+      suite("mapFilter", [
+        prop_with_key("get(mapFilter(m, (!=k)), k) == null", func (m, k) {
+          natMap.get(natMap.mapFilter<Text, Text>(m, 
+          func (ki, vi) { if (ki != k) {?vi} else {null}}), k) == null
+        }),
+        prop_with_key("get(mapFilter(put(m, k, v), (==k)), k) == ?v", func (m, k) {
+          natMap.get(natMap.mapFilter<Text, Text>(natMap.put(m, k, "v"), 
+          func (ki, vi) { if (ki == k) {?vi} else {null}}), k) == ?"v"
+        })
+      ]),
+      
+      suite("map", [
+        prop("map(m, id) == m", func (m) {
+          MapMatcher(m).matches(Map.map<Nat, Text, Text>(m, func (k, v) {v}))
+        })
+      ]),
+      
+      suite("folds", [
+        prop("foldLeft as iter(#fwd)", func (m) {
+          let it = Map.iter(m, #fwd);
+          Map.foldLeft<Nat, Text, Bool>(m, true, func (k, v, acc) {acc and it.next() == ?(k, v)})
+        }),
+        prop("foldRight as iter(#bwd)", func(m) {
+          let it = Map.iter(m, #bwd);
+          Map.foldRight<Nat, Text, Bool>(m, true, func (k, v, acc) {acc and it.next() == ?(k, v)})
+        })
+      ]),
+    ]))   
+};
+
+run_all_props((1, 3), 0, 1, 10);
+run_all_props((1, 5), 5, 100, 100);
+run_all_props((1, 10), 10, 100, 100);
+run_all_props((1, 100), 20, 100, 100);
+run_all_props((1, 1000), 100, 100, 100);
\ No newline at end of file
diff --git a/test/PersistentOrderedMap.test.mo b/test/PersistentOrderedMap.test.mo
new file mode 100644
index 00000000..0e6794c6
--- /dev/null
+++ b/test/PersistentOrderedMap.test.mo
@@ -0,0 +1,541 @@
+// @testmode wasi
+
+import Map "../src/PersistentOrderedMap";
+import Nat "../src/Nat";
+import Iter "../src/Iter";
+import Debug "../src/Debug";
+import Array "../src/Array";
+
+import Suite "mo:matchers/Suite";
+import T "mo:matchers/Testable";
+import M "mo:matchers/Matchers";
+
+let { run; test; suite } = Suite;
+
+let entryTestable = T.tuple2Testable(T.natTestable, T.textTestable);
+
+class MapMatcher(expected : [(Nat, Text)]) : M.Matcher<Map.Map<Nat, Text>> {
+  public func describeMismatch(actual : Map.Map<Nat, Text>, _description : M.Description) {
+    Debug.print(debug_show (Iter.toArray(Map.entries(actual))) # " should be " # debug_show (expected))
+  };
+
+  public func matches(actual : Map.Map<Nat, Text>) : Bool {
+    Iter.toArray(Map.entries(actual)) == expected
+  }
+};
+
+let natMapOps = Map.MapOps<Nat>(Nat.compare);
+
+func checkMap(rbMap : Map.Map<Nat, Text>) {
+  ignore blackDepth(rbMap)
+};
+
+func blackDepth(node : Map.Map<Nat, Text>) : Nat {
+  func checkNode(left : Map.Map<Nat, Text>, key : Nat, right : Map.Map<Nat, Text>) : Nat {
+    checkKey(left, func(x) { x < key });
+    checkKey(right, func(x) { x > key });
+    let leftBlacks = blackDepth(left);
+    let rightBlacks = blackDepth(right);
+    assert (leftBlacks == rightBlacks);
+    leftBlacks
+  };
+  switch node {
+    case (#leaf) 0;
+    case (#red(left, (key, _), right)) {
+      let leftBlacks = checkNode(left, key, right);
+      assert (not isRed(left));
+      assert (not isRed(right));
+      leftBlacks
+    };
+    case (#black(left, (key, _), right)) {
+      checkNode(left, key, right) + 1
+    }
+  }
+};
+
+
+func isRed(node : Map.Map<Nat, Text>) : Bool {
+  switch node {
+    case (#red(_, _, _)) true;
+    case _ false
+  }
+};
+
+func checkKey(node : Map.Map<Nat, Text>, isValid : Nat -> Bool) {
+  switch node {
+    case (#leaf) {};
+    case (#red( _, (key, _), _)) {
+      assert (isValid(key))
+    };
+    case (#black( _, (key, _), _)) {
+      assert (isValid(key))
+    }
+  }
+};
+
+func insert(rbTree : Map.Map<Nat, Text>, key : Nat) : Map.Map<Nat, Text>  {
+  let updatedTree = natMapOps.put(rbTree, key, debug_show (key));
+  checkMap(updatedTree);
+  updatedTree
+};
+
+func getAll(rbTree : Map.Map<Nat, Text>, keys : [Nat]) {
+  for (key in keys.vals()) {
+    let value = natMapOps.get(rbTree, key);
+    assert (value == ?debug_show (key))
+  }
+};
+
+func clear(initialRbMap : Map.Map<Nat, Text>) : Map.Map<Nat, Text> {
+  var rbMap = initialRbMap;
+  for ((key, value) in Map.entries(initialRbMap)) {
+    // stable iteration
+    assert (value == debug_show (key));
+    let (newMap, result) = natMapOps.remove(rbMap, key);
+    rbMap := newMap;
+    assert (result == ?debug_show (key));
+    checkMap(rbMap)
+  };
+  rbMap
+};
+
+func expectedEntries(keys : [Nat]) : [(Nat, Text)] {
+  Array.tabulate<(Nat, Text)>(keys.size(), func(index) { (keys[index], debug_show (keys[index])) })
+};
+
+func concatenateKeys(key : Nat, value : Text, accum : Text) : Text {
+  accum # debug_show(key)
+};
+
+func concatenateValues(key : Nat, value : Text, accum : Text) : Text {
+  accum # value
+};
+
+func multiplyKeyAndConcat(key : Nat, value : Text) : Text {
+  debug_show(key * 2) # value
+};
+
+func ifKeyLessThan(threshold : Nat, f : (Nat, Text) -> Text) : (Nat, Text) -> ?Text
+  = func (key, value) {
+    if(key < threshold)
+      ?f(key, value)
+    else null
+  };
+
+/* --------------------------------------- */
+
+var buildTestMap = func() : Map.Map<Nat, Text> {
+  Map.empty()
+};
+
+run(
+  suite(
+    "empty",
+    [
+      test(
+        "size",
+        Map.size(buildTestMap()),
+        M.equals(T.nat(0))
+      ),
+      test(
+        "iterate forward",
+        Iter.toArray(Map.iter(buildTestMap(), #fwd)),
+        M.equals(T.array<(Nat, Text)>(entryTestable, []))
+      ),
+      test(
+        "iterate backward",
+        Iter.toArray(Map.iter(buildTestMap(), #bwd)),
+        M.equals(T.array<(Nat, Text)>(entryTestable, []))
+      ),
+      test(
+        "entries",
+        Iter.toArray(Map.entries(buildTestMap())),
+        M.equals(T.array<(Nat, Text)>(entryTestable, []))
+      ),
+      test(
+        "keys",
+        Iter.toArray(Map.keys(buildTestMap())),
+        M.equals(T.array<Nat>(T.natTestable, []))
+      ),
+      test(
+        "vals",
+        Iter.toArray(Map.vals(buildTestMap())),
+        M.equals(T.array<Text>(T.textTestable, []))
+      ),
+      test(
+        "empty from iter",
+        natMapOps.fromIter(Iter.fromArray([])),
+        MapMatcher([])
+      ),
+      test(
+        "get absent",
+        natMapOps.get(buildTestMap(), 0),
+        M.equals(T.optional(T.textTestable, null : ?Text))
+      ),
+      test(
+        "remove absent",
+        natMapOps.remove(buildTestMap(), 0).1,
+        M.equals(T.optional(T.textTestable, null : ?Text))
+      ),
+      test(
+        "replace absent/no value",
+        natMapOps.replace(buildTestMap(), 0, "Test").1,
+        M.equals(T.optional(T.textTestable, null : ?Text))
+      ),
+      test(
+        "replace absent/key appeared",
+        natMapOps.replace(buildTestMap(), 0, "Test").0,
+        MapMatcher([(0, "Test")])
+      ),
+      test(
+        "empty right fold keys",
+        Map.foldRight(buildTestMap(), "", concatenateKeys),
+        M.equals(T.text(""))
+      ),
+      test(
+        "empty left fold keys",
+        Map.foldLeft(buildTestMap(), "", concatenateKeys),
+        M.equals(T.text(""))
+      ),
+      test(
+        "empty right fold values",
+        Map.foldRight(buildTestMap(), "", concatenateValues),
+        M.equals(T.text(""))
+      ),
+      test(
+        "empty left fold values",
+        Map.foldLeft(buildTestMap(), "", concatenateValues),
+        M.equals(T.text(""))
+      ),
+      test(
+        "traverse empty map",
+        Map.map(buildTestMap(), multiplyKeyAndConcat),
+        MapMatcher([])
+      ),
+      test(
+        "empty map filter",
+        natMapOps.mapFilter(buildTestMap(), ifKeyLessThan(0, multiplyKeyAndConcat)),
+        MapMatcher([])
+      ),
+    ]
+  )
+);
+
+/* --------------------------------------- */
+
+buildTestMap := func() : Map.Map<Nat, Text> {
+  insert(Map.empty(), 0);
+};
+
+var expected = expectedEntries([0]);
+
+run(
+  suite(
+    "single root",
+    [
+      test(
+        "size",
+        Map.size(buildTestMap()),
+        M.equals(T.nat(1))
+      ),
+      test(
+        "iterate forward",
+        Iter.toArray(Map.iter(buildTestMap(), #fwd)),
+        M.equals(T.array<(Nat, Text)>(entryTestable, expected))
+      ),
+      test(
+        "iterate backward",
+        Iter.toArray(Map.iter(buildTestMap(), #bwd)),
+        M.equals(T.array<(Nat, Text)>(entryTestable, expected))
+      ),
+      test(
+        "entries",
+        Iter.toArray(Map.entries(buildTestMap())),
+        M.equals(T.array<(Nat, Text)>(entryTestable, expected))
+      ),
+      test(
+        "keys",
+        Iter.toArray(Map.keys(buildTestMap())),
+        M.equals(T.array<Nat>(T.natTestable, [0]))
+      ),
+      test(
+        "vals",
+        Iter.toArray(Map.vals(buildTestMap())),
+        M.equals(T.array<Text>(T.textTestable, ["0"]))
+      ),
+      test(
+        "from iter",
+        natMapOps.fromIter(Iter.fromArray(expected)),
+        MapMatcher(expected)
+      ),
+      test(
+        "get",
+        natMapOps.get(buildTestMap(), 0),
+        M.equals(T.optional(T.textTestable, ?"0"))
+      ),
+      test(
+        "replace function result",
+        natMapOps.replace(buildTestMap(), 0, "TEST").1,
+        M.equals(T.optional(T.textTestable, ?"0"))
+      ),
+      test(
+        "replace map result",
+        do {
+          let rbMap = buildTestMap();
+          natMapOps.replace(rbMap, 0, "TEST").0
+        },
+        MapMatcher([(0, "TEST")])
+      ),
+      test(
+        "remove function result",
+        natMapOps.remove(buildTestMap(), 0).1,
+        M.equals(T.optional(T.textTestable, ?"0"))
+      ),
+      test(
+        "remove map result",
+        do {
+          var rbMap = buildTestMap();
+          rbMap := natMapOps.remove(rbMap, 0).0;
+          checkMap(rbMap);
+          rbMap
+        },
+        MapMatcher([])
+      ),
+      test(
+        "right fold keys",
+        Map.foldRight(buildTestMap(), "", concatenateKeys),
+        M.equals(T.text("0"))
+      ),
+      test(
+        "left fold keys",
+        Map.foldLeft(buildTestMap(), "", concatenateKeys),
+        M.equals(T.text("0"))
+      ),
+      test(
+        "right fold values",
+        Map.foldRight(buildTestMap(), "", concatenateValues),
+        M.equals(T.text("0"))
+      ),
+      test(
+        "left fold values",
+        Map.foldLeft(buildTestMap(), "", concatenateValues),
+        M.equals(T.text("0"))
+      ),
+      test(
+        "traverse map",
+        Map.map(buildTestMap(), multiplyKeyAndConcat),
+        MapMatcher([(0, "00")])
+      ),
+      test(
+        "map filter/filter all",
+        natMapOps.mapFilter(buildTestMap(), ifKeyLessThan(0, multiplyKeyAndConcat)),
+        MapMatcher([])
+      ),
+      test(
+        "map filter/no filer",
+        natMapOps.mapFilter(buildTestMap(), ifKeyLessThan(1, multiplyKeyAndConcat)),
+        MapMatcher([(0, "00")])
+      ),
+    ]
+  )
+);
+
+/* --------------------------------------- */
+
+expected := expectedEntries([0, 1, 2]);
+
+func rebalanceTests(buildTestMap : () -> Map.Map<Nat, Text>) : [Suite.Suite] =
+  [
+    test(
+      "size",
+      Map.size(buildTestMap()),
+      M.equals(T.nat(3))
+    ),
+    test(
+      "map match",
+      buildTestMap(),
+      MapMatcher(expected)
+    ),
+    test(
+      "iterate forward",
+      Iter.toArray(Map.iter(buildTestMap(), #fwd)),
+      M.equals(T.array<(Nat, Text)>(entryTestable, expected))
+    ),
+    test(
+      "iterate backward",
+      Iter.toArray(Map.iter(buildTestMap(), #bwd)),
+      M.equals(T.array<(Nat, Text)>(entryTestable, Array.reverse(expected)))
+    ),
+    test(
+      "entries",
+      Iter.toArray(Map.entries(buildTestMap())),
+      M.equals(T.array<(Nat, Text)>(entryTestable, expected))
+    ),
+    test(
+      "keys",
+      Iter.toArray(Map.keys(buildTestMap())),
+      M.equals(T.array<Nat>(T.natTestable, [0, 1, 2]))
+    ),
+    test(
+      "vals",
+      Iter.toArray(Map.vals(buildTestMap())),
+      M.equals(T.array<Text>(T.textTestable, ["0", "1", "2"]))
+    ),
+    test(
+      "from iter",
+      natMapOps.fromIter(Iter.fromArray(expected)),
+      MapMatcher(expected)
+    ),
+    test(
+      "get all",
+      do {
+        let rbMap = buildTestMap();
+        getAll(rbMap, [0, 1, 2]);
+        rbMap
+      },
+      MapMatcher(expected)
+    ),
+    test(
+      "clear",
+      clear(buildTestMap()),
+      MapMatcher([])
+    ),
+    test(
+      "right fold keys",
+      Map.foldRight(buildTestMap(), "", concatenateKeys),
+      M.equals(T.text("210"))
+    ),
+    test(
+      "left fold keys",
+      Map.foldLeft(buildTestMap(), "", concatenateKeys),
+      M.equals(T.text("012"))
+    ),
+    test(
+      "right fold values",
+      Map.foldRight(buildTestMap(), "", concatenateValues),
+      M.equals(T.text("210"))
+    ),
+    test(
+      "left fold values",
+      Map.foldLeft(buildTestMap(), "", concatenateValues),
+      M.equals(T.text("012"))
+    ),
+    test(
+      "traverse map",
+      Map.map(buildTestMap(), multiplyKeyAndConcat),
+      MapMatcher([(0, "00"), (1, "21"), (2, "42")])
+    ),
+    test(
+      "map filter/filter all",
+      natMapOps.mapFilter(buildTestMap(), ifKeyLessThan(0, multiplyKeyAndConcat)),
+      MapMatcher([])
+    ),
+    test(
+      "map filter/filter one",
+      natMapOps.mapFilter(buildTestMap(), ifKeyLessThan(1, multiplyKeyAndConcat)),
+      MapMatcher([(0, "00")])
+    ),
+    test(
+      "map filter/no filer",
+      natMapOps.mapFilter(buildTestMap(), ifKeyLessThan(3, multiplyKeyAndConcat)),
+      MapMatcher([(0, "00"), (1, "21"), (2, "42")])
+    ),
+  ];
+
+buildTestMap := func() : Map.Map<Nat, Text> {
+  var rbMap = Map.empty() : Map.Map<Nat, Text>;
+  rbMap := insert(rbMap, 2);
+  rbMap := insert(rbMap, 1);
+  rbMap := insert(rbMap, 0);
+  rbMap
+};
+
+run(suite("rebalance left, left", rebalanceTests(buildTestMap)));
+
+/* --------------------------------------- */
+
+buildTestMap := func() : Map.Map<Nat, Text> {
+  var rbMap = Map.empty() : Map.Map<Nat, Text>;
+  rbMap := insert(rbMap, 2);
+  rbMap := insert(rbMap, 0);
+  rbMap := insert(rbMap, 1);
+  rbMap
+};
+
+run(suite("rebalance left, right", rebalanceTests(buildTestMap)));
+
+/* --------------------------------------- */
+
+buildTestMap := func() : Map.Map<Nat, Text> {
+  var rbMap = Map.empty() : Map.Map<Nat, Text>;
+  rbMap := insert(rbMap, 0);
+  rbMap := insert(rbMap, 2);
+  rbMap := insert(rbMap, 1);
+  rbMap
+};
+
+run(suite("rebalance right, left", rebalanceTests(buildTestMap)));
+
+/* --------------------------------------- */
+
+buildTestMap := func() : Map.Map<Nat, Text> {
+  var rbMap = Map.empty() : Map.Map<Nat, Text>;
+  rbMap := insert(rbMap, 0);
+  rbMap := insert(rbMap, 1);
+  rbMap := insert(rbMap, 2);
+  rbMap
+};
+
+run(suite("rebalance right, right", rebalanceTests(buildTestMap)));
+
+/* --------------------------------------- */
+
+run(
+  suite(
+    "repeated operations",
+    [
+      test(
+        "repeated insert",
+        do {
+          var rbMap = buildTestMap();
+          assert (natMapOps.get(rbMap, 1) == ?"1");
+          rbMap := natMapOps.put(rbMap, 1, "TEST-1");
+          natMapOps.get(rbMap, 1)
+        },
+        M.equals(T.optional(T.textTestable, ?"TEST-1"))
+      ),
+      test(
+        "repeated replace",
+        do {
+          let rbMap0 = buildTestMap();
+          let (rbMap1, firstResult) = natMapOps.replace(rbMap0, 1, "TEST-1");
+          assert (firstResult == ?"1");
+          let (rbMap2, secondResult) = natMapOps.replace(rbMap1, 1, "1");
+          assert (secondResult == ?"TEST-1");
+          rbMap2
+        },
+        MapMatcher(expected)
+      ),
+      test(
+        "repeated remove",
+        do {
+          var rbMap0 = buildTestMap();
+          let (rbMap1, result) = natMapOps.remove(rbMap0, 1);
+          assert (result == ?"1");
+          checkMap(rbMap1);
+          natMapOps.remove(rbMap1, 1).1
+        },
+        M.equals(T.optional(T.textTestable, null : ?Text))
+      ),
+      test(
+        "repeated delete",
+        do {
+          var rbMap = buildTestMap();
+          rbMap := natMapOps.delete(rbMap, 1);
+          natMapOps.delete(rbMap, 1)
+        },
+        MapMatcher(expectedEntries([0, 2]))
+      )
+    ]
+  )
+);