Add lyng.observable ObservableList hooks, flow events, and docs

docs/Collection.md

@@ -11,6 +11,7 @@ Concrete collection classes:
 
 - Mutable: [List], [Set], [Map]
 - Immutable: [ImmutableList], [ImmutableSet], [ImmutableMap]
+- Observable mutable lists (opt-in module): [ObservableList]
 
 | name                   | description                                          |
 |------------------------|------------------------------------------------------|
@@ -27,3 +28,4 @@ See [List], [Set], [Iterable] and [Efficient Iterables in Kotlin Interop](Effici
 [ImmutableList]: ImmutableList.md
 [ImmutableSet]: ImmutableSet.md
 [ImmutableMap]: ImmutableMap.md
+[ObservableList]: ObservableList.md

docs/List.md

@@ -2,6 +2,7 @@
 
 Mutable list of any objects.
 For immutable list values, see [ImmutableList].
+For observable mutable lists and change hooks, see [ObservableList].
 
 It's class in Lyng is `List`:
 
@@ -180,6 +181,50 @@ for `sort()` will be `sort { a, b -> a <=> b }
 
 It inherits from [Iterable] too and thus all iterable methods are applicable to any list.
 
+## Observable list hooks
+
+Observable hooks are provided by module `lyng.observable` and are opt-in:
+
+    import lyng.observable
+
+    val src = [1,2,3]
+    val xs = src.observable()
+    assert(xs is ObservableList<Int>)
+
+    var before = 0
+    var after = 0
+    xs.beforeChange { before++ }
+    xs.onChange { after++ }
+
+    xs += 4
+    xs[0] = 100
+    assertEquals([100,2,3,4], xs)
+    assertEquals(2, before)
+    assertEquals(2, after)
+    >>> void
+
+`beforeChange` runs before mutation commit and may reject it by throwing exception (typically `ChangeRejectionException` from the same module):
+
+    import lyng.observable
+    val xs = [1,2].observable()
+    xs.beforeChange { throw ChangeRejectionException("read only") }
+    assertThrows(ChangeRejectionException) { xs += 3 }
+    assertEquals([1,2], xs)
+    >>> void
+
+`changes()` returns `Flow<ListChange<T>>` of committed events:
+
+    import lyng.observable
+    val xs = [10,20].observable()
+    val it = xs.changes().iterator()
+    xs += 30
+    assert(it.hasNext())
+    val e = it.next()
+    assert(e is ListInsert<Int>)
+    assertEquals([30], (e as ListInsert<Int>).values)
+    it.cancelIteration()
+    >>> void
+
 ## Member inherited from Array
 
 | name             | meaning                        | type  |
@@ -199,3 +244,4 @@ It inherits from [Iterable] too and thus all iterable methods are applicable to
 
 [Iterable]: Iterable.md
 [ImmutableList]: ImmutableList.md
+[ObservableList]: ObservableList.md

docs/ObservableList.md

@@ -0,0 +1,70 @@
+# ObservableList module
+
+`ObservableList` lives in explicit module `lyng.observable`.
+
+Import it first:
+
+    import lyng.observable
+    >>> void
+
+Create from a regular mutable list:
+
+    import lyng.observable
+    val xs = [1,2,3].observable()
+    assert(xs is ObservableList<Int>)
+    assertEquals([1,2,3], xs)
+    >>> void
+
+## Hook flow
+
+Event order is:
+1. `beforeChange(change)` listeners
+2. mutation commit
+3. `onChange(change)` listeners
+4. `changes()` flow emission
+
+Rejection is done by throwing in `beforeChange`.
+
+    import lyng.observable
+    val xs = [1,2].observable()
+    xs.beforeChange {
+        throw ChangeRejectionException("no mutation")
+    }
+    assertThrows(ChangeRejectionException) { xs += 3 }
+    assertEquals([1,2], xs)
+    >>> void
+
+## Subscriptions
+
+`beforeChange` and `onChange` return `Subscription`.
+Call `cancel()` to unsubscribe.
+
+    import lyng.observable
+    val xs = [1].observable()
+    var hits = 0
+    val sub = xs.onChange { hits++ }
+    xs += 2
+    sub.cancel()
+    xs += 3
+    assertEquals(1, hits)
+    >>> void
+
+## Change events
+
+`changes()` returns `Flow<ListChange<T>>` with concrete event classes:
+- `ListInsert`
+- `ListSet`
+- `ListRemove`
+- `ListClear`
+- `ListReorder`
+
+    import lyng.observable
+    val xs = [10,20].observable()
+    val it = xs.changes().iterator()
+    xs[1] = 200
+    val ev = it.next()
+    assert(ev is ListSet<Int>)
+    assertEquals(20, (ev as ListSet<Int>).oldValue)
+    assertEquals(200, ev.newValue)
+    it.cancelIteration()
+    >>> void