experimenting + docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

README.md

@@ -46,10 +46,13 @@ A library of JavaScript type extensions, types and type utilities.
       - [`RegExp.quoteRegExp(..)`](#regexpquoteregexp)
   - [Containers](#containers)
     - [`containers.UniqueKeyMap()` (`Map`)](#containersuniquekeymap-map)
+      - [`<unique-key-map>.set(..)`](#unique-key-mapset)
       - [`<unique-key-map>.reset(..)`](#unique-key-mapreset)
-      - [`<unique-key-map>.uniqueKey(..)`](#unique-key-mapuniquekey)
       - [`<unique-key-map>.rename(..)`](#unique-key-maprename)
+      - [`<unique-key-map>.unorderedRename(..)`](#unique-key-mapunorderedrename)
       - [`<unique-key-map>.keysOf(..)`](#unique-key-mapkeysof)
+      - [`<unique-key-map>.originalKey(..)`](#unique-key-maporiginalkey)
+      - [`<unique-key-map>.uniqueKey(..)`](#unique-key-mapuniquekey)
       - [`<unique-key-map>.__key_pattern__`](#unique-key-map__key_pattern__)
   - [License](#license)
 
@@ -298,14 +301,42 @@ For more info on `Map` see:
 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
 
 
+#### `<unique-key-map>.set(..)`
+
+```
+<unique-key-map>.reset(<key>, <item>)
+    -> <unique-key-map>
+
+<unique-key-map>.reset(<key>, <item>, true)
+    -> <new-key>
+```
+
+Add an `<item>` to `<unique-key-map>`.
+
+If `<key>` already exists then add an index to it to make it unique.
+
+Key updating is done via [`<unique-key-map>.__key_pattern__`](#unique-key-map__key_pattern__).
+
+
 #### `<unique-key-map>.reset(..)`
 
-#### `<unique-key-map>.uniqueKey(..)`
+```
+<unique-key-map>.reset(<key>, <item>)
+    -> <unique-key-map>
+```
+
+Explicitly write an `<item>` under `<key>` as-is, this is like `Map`'s `.set(..)`.
 
 #### `<unique-key-map>.rename(..)`
 
+#### `<unique-key-map>.unorderedRename(..)`
+
 #### `<unique-key-map>.keysOf(..)`
 
+#### `<unique-key-map>.originalKey(..)`
+
+#### `<unique-key-map>.uniqueKey(..)`
+
 #### `<unique-key-map>.__key_pattern__`
 
 

containers.js

@@ -58,6 +58,8 @@ module.UniqueKeyMap = object.Constructor('UniqueKeyMap', Map, {
 	//
 	__unique_key_value__: false,
 
+	__unorderd_writes__: false,
+
 
 	// helpers...
 	//
@@ -152,16 +154,12 @@ module.UniqueKeyMap = object.Constructor('UniqueKeyMap', Map, {
 			s.size == 0
 				&& this.__keys.delete(this.get(key)) }
 		return object.parentCall(UniqueKeyMap.prototype, 'delete', this, key) },
-	// XXX this affects order...
-	rename: function(from, to, return_key=false){
-		var e = this.get(from)
-		this.delete(from)
-		return this.set(to, e, return_key) },
-	// XXX in-place...
-	// XXX rename to .rename(..) 
-	// XXX do not se how can we avoid rewriting the map if we want to 
+	// NOTE: this maintains the item order. This is done by rewriting 
+	// 		items in sequence, this may be slow and trigger lots of write 
+	// 		observer callbacks. to avoid this use .unOrderedRename(..)
+	// XXX do not see how can we avoid rewriting the map if we want to 
 	// 		keep order...
-	_rename: function(from, to, return_key=false){
+	rename: function(from, to, return_key=false){
 		var keys = [...this.keys()]
 		// rename the element...
 		var e = this.get(from)
@@ -173,6 +171,11 @@ module.UniqueKeyMap = object.Constructor('UniqueKeyMap', Map, {
 		return return_key ?
    			n
 			: this },
+	// NOTE: this affects order...
+	unorderedRename: function(from, to, return_key=false){
+		var e = this.get(from)
+		this.delete(from)
+		return this.set(to, e, return_key) },
 })