V4

README.md

@@ -302,3 +302,29 @@ let save text =
 #### Can I bind to events and use behaviors?
 
 Sure! Check out the [EventBindingsAndBehaviors sample](https://github.com/elmish/Elmish.WPF/tree/master/src/Samples). Note that you have to install the NuGet package `Microsoft.Xaml.Behaviors.Wpf`.
+
+#### How can I control logging?
+
+Elmish.WPF uses `Microsoft.Extensions.Logging`. To see Elmish.WPF output in your favorite logging framework, use `WpfProgram.withLogger` to pass an `ILoggerFactory`:
+
+```f#
+WpfProgram.mkSimple init update bindings
+|> WpfProgram.withLogger yourLoggerFactory
+|> WpfProgram.runWindow window
+```
+
+For example, in Serilog, you need to install Serilog.Extensions.Logging and instantiate `SerilogLoggerFactory`. The samples demonstrate this.
+
+Elmish.WPF logs to these categories:
+
+* `Elmish.WPF.Update`: Logs exceptions (Error level) and messages/models (Trace/Verbose level) during `update`.
+* `Elmish.WPF.Bindings`: Logs events related to bindings. Some logging is done at the Error level (e.g. developer errors such as duplicated binding names, using non-existent bindings in XAML, etc.), but otherwise it’s generally just Trace/Verbose for when you really want to see everything that’s happening (triggering `PropertyChanged`, WPF getting/setting bindings, etc.)
+* `Elmish.WPF.Performance`: Logs the performance of the functions you pass when creating bindings (`get`, `set`, `map`, `equals`, etc.) at the Trace/Verbose level. Use `WpfProgram.withPerformanceLogThreshold` to set the minimum duration to log.
+
+The specific method of controlling what Elmish.WPF logs depends on your logging framework. For Serilog you can use `.MinimumLevel.Override(...)` to specify the minimum log level per category, like this:
+
+```f#
+myLoggerConfiguration
+  .MinimumLevel.Override("Elmish.WPF.Bindings", LogEventLevel.Verbose)
+  ...
+```

RELEASE_NOTES.md

@@ -1,3 +1,22 @@
+#### 4.0.0-beta-1
+
+* **Breaking:** Removed the obsolete binding functions in the `BindingFn` module
+* **Breaking:** Removed the obsolete function `Elmish.WPF.Cmd.showWindow`
+* **Breaking:** Removed all occurrences of the argument `wrapDispatch` from the methods used to create a binding. There is currently no migration path. Please create an issue if this is a negative impact for you.
+* **Breaking:** App initialization is now done using the `WpfProgram` module instead of the `Program` module
+* **Breaking:** Removed `ElmConfig`. For controlling logging, see below. For specifying a binding performance log threshold (corresponding to the old `ElmConfig.MeasureLimitMs` field), use `WpfProgram.withBindingPerformanceLogThreshold`
+* **Breaking:** The method `Binding.oneWaySeq` is implemented by calling the method `Binding.oneWaySeqLazy` with `equals` = `refEq` and `map` = `id`. This is a breaking change when using a mutable data structure for the sequence. Compensate by directly calling `Binding.oneWaySeqLazy` with `equals` = `fun _ _ = false`.
+* **Breaking:** Some calls to `Binding` methods now include an equality constraint. This only is only breaking if the corresponding type included the `NoEquality` attribute.
+* Added binding mapping functions
+  * Added `mapModel`, `mapMsg`, and `mapMsgWithModel` in both the `Binding` and `Bindings` modules
+  * These functions enable common model and message mapping logic to be extracted
+  * See the `SubModelSeq` sample for an excellent use of `mapModel` and `mapMsg`
+* Improved logging:
+  * Now uses `Microsoft.Extensions.Logging` for wide compatibility and easy integration into common log frameworks
+  * Use `WpfProgram.WithLogger` to pass an `ILoggerFactory` for your chosen log framework
+  * Can control specific log categories
+  * See the samples for a demonstration using Serilog
+
 #### 3.5.7
 * Excluded 4.* prereleases from possibilities for version of Elmish dependency
 * Added support for multiple validation errors

TUTORIAL.md

@@ -49,7 +49,9 @@ Table of contents
     - [`subModelSeqSelectedItem`](#submodelseqselecteditem)
     - [`oneWaySeq`](#onewayseq)
   + [Lazy bindings](#lazy-bindings)
-  + [Wrapping dispatch (debouncing/throttling etc.)](#wrapping-dispatch-debouncingthrottling-etc)
+  + [Mapping bindings](#mapping-bindings)
+    - [Example use of `mapModel` and `mapMsg`](#example-use-of-mapModel-and-mapMsg)
+    - [Theory behind `mapModel` and `mapMsg`](#theory-behind-mapModel-and-mapMsg)
 * [Additional resources](#additional-resources)
 
 The MVU (Elm/Elmish) architecture
@@ -730,66 +732,60 @@ Elmish.WPF provides two helpers you can often use as the `equals` parameter: `re
 
 You may pass any function you want for `equals`; it does not have to be one of the above. For example, if you want structural comparison (note the caveat above however), you can pass `(=)`.
 
-### Wrapping dispatch (debouncing/throttling etc.)
+### Mapping Bindings
 
-*Note: This is an advanced optimization that should not be necessary in most cases.*
+Sometimes duplicate mapping code exists across several bindings. The duplicate mappings could be from the parent model to a common child model or it could be the wrapping of a child message in a parent message, which might depend on the parent model. The duplicate mapping code can be extracted and written once using the mapping functions `mapModel`, `mapMsg`, and `mapMsgWithModel`.
 
-Occasionally you may want to limit the frequency of dispatches from a particular binding. You may therefore want to apply some kind of throttling or debouncing (dispatch at most one message every X millisecond, or only dispatch the latest message after there have been no messages for at least X milliseconds).
+#### Example use of `mapModel` and `mapMsg`
 
-To facilitate this, all `twoWay` and `cmd` bindings as well as `subModelSelectedItem` have an optional `wrapDispatch` parameter with the signature `Dispatch<'msg> -> Dispatch<'msg>`.
+Here is a simple example that uses these model and message types.
+```F#
+type ChildModel =
+  { GrandChild1: GrandChild1
+    GrandChild2: GrandChild2 }
 
-This is completely general and allows you to implement all manner of dispatch modifications. There are currently no built-in throttling or debouncing wrappers, but you can write your own. 
+type ChildMsg =
+  | SetGrandChild1 of GrandChild1
+  | SetGrandChild2 of GrandChild2
 
-To show you how you can write them from scratch, here is a throttling wrapper that dispatches the latest message every X milliseconds:
-
-```f#
-let throttle (durationMs: int) (dispatch: Dispatch<'msg>) : Dispatch<'msg> =
-  let locker = obj()
-  let mutable lastMessage = ValueNone
-  let timer = new System.Timers.Timer(Interval = float durationMs)
-  timer.Elapsed.Add (fun _ ->
-    lock locker (fun () ->
-      lastMessage |> ValueOption.iter dispatch
-      lastMessage <- ValueNone
-    )
-  )
-  timer.Start()
-  fun msg ->
-    async {
-      lock locker (fun () ->
-        lastMessage <- ValueSome msg
-      )
-    } |> Async.Start
+type ParentModel =
+  { Child: ChildModel }
+
+type ParentMsg =
+  | ChildMsg of ChildMsg
 ```
 
-Note the use of `Async.Start`. It seems to be required in order to avoid deadlocks, see [#114 (comment)](https://github.com/elmish/Elmish.WPF/issues/114#issuecomment-532481275).
+It is possible to create bindings from the parent to the two grandchild fields, but there is duplicate mapping code.
 
-If you want a more general solution, you can make use of [FSharp.Control.Reactive](http://fsprojects.github.io/FSharp.Control.Reactive/) (which provides an F#-friendly wrapper over [System.Reactive](https://www.nuget.org/packages/System.Reactive), which you can also just use directly). You can write a general helper function to convert any `IObservable` combinator/extension to a dispatch wrapper:
+```F#
+let parentBindings () : Binding<ParentModel, ParentMsg> list = [
+  "GrandChild1" |> Binding.twoWay((fun parent -> parent.Child.GrandChild1), SetGrandChild1 >> ChildMsg)
+  "GrandChild2" |> Binding.twoWay((fun parent -> parent.Child.GrandChild2), SetGrandChild2 >> ChildMsg)
+]
+```
 
-```f#
-open FSharp.Control.Reactive
+The functions `mapModel` and `mapMsg` can remove this duplication.
+```F#
+let childBindings () : Binding<ChildModel, ChildMsg> list = [
+  "GrandChild1" |> Binding.twoWay((fun child -> child.GrandChild1), SetGrandChild1)
+  "GrandChild2" |> Binding.twoWay((fun child -> child.GrandChild2), SetGrandChild2)
+]
 
-let asDispatchWrapper
-    (configure: IObservable<'msg> -> IObservable<'msg>)
-    (dispatch: Dispatch<'msg>)
-    : Dispatch<'msg> =
-  let subject = Subject.broadcast
-  subject |> configure |> Observable.add dispatch
-  fun msg -> async { return subject.OnNext msg } |> Async.Start
+let parentBindings () : Binding<ParentModel, ParentMsg> list =
+  childBindings ()
+  |> Bindings.mapModel (fun parent -> parent.Child)
+  |> Bindings.mapMsg ChildMsg
 ```
 
-Usage:
+#### Benefit for design-time view models
 
-```f#
-"SliderValue" |> Binding.twoWay(
-  (fun m -> float m.SliderValue),
-  int >> SetSliderValue,
-  (Observable.sample (TimeSpan.FromMilliseconds 50.) |> asDispatchWrapper))
-```
+With such duplicate mapping code extracted, it is easier to create a design-time view model for the XAML code containing the bindings to `GrandChild1` and `GrandChild2`.  Specifically, instead of creating the design-time view model from the `parentBindings` bindings, it can now be created from the `childBindings` bindings.  The `SubModelSeq` sample uses this benefit to create a design-time view model for `Counter.xaml`.
 
-Note that since the `binding` function is only called once (or once per sub-model for the sub-model bindings), you can inline the wrapper creation as shown above. (For a “normal” Elmish architecture where `view` is called for each update, you’d have to define it outside).
+#### Theory behind `mapModel` and `mapMsg`
 
-Note also that throttling as demonstrated above may cause suboptimal behavior for two-way bindings due to the value shown in the UI being locked to the value returned by `get`, which isn’t updated until the message is dispatched. For sliders, the slider will “lag” behind the mouse cursor when dragging it, only moving when a message is dispatched and the model updated. For text boxes, throttling will make the cursor jump to the start of the text box while typing, and only some of the characters will be entered.
+A binding in Elmish.WPF is represented by an instance of type `Binding<'model, 'msg>`. It is a profunctor, which means that
+- it is a contravariant functor in `'model` with `mapModel` as the corresponding mapping function for this functor and
+- it is a covariant functor in `'msg` with `mapMsg` as the corresponding mapping function for this functor.
 
 Additional resources
 --------------------