docs: Orders comments and changelog update

Author: MartinKavik

CHANGELOG.md

@@ -9,6 +9,16 @@
 - Added support for all `Iterator`s, `Option`, `u32`, `i32`, `usize`, `f64` and references in element creation macros (#365, #128).
 - [BREAKING] `String` implements `UpdateEl<T>`. (References are now required for `String` properties, e.g. `div![&model.title]`.)
 - Fixed `href` detection to ignore `use` elements (#384).
+- Added methods `subscribe`, `subscribe_with_handle`, `perform_cmd_with_handle`, `stream`, `stream_with_handle` and `notify` into `Orders` (#130).
+- Added `cmds::timeout`, `stream::interval`, `stream::window_event`, `subs::UrlChanged` and `subs::UrlRequested` (#131).
+- Added example `subscribe`.
+- Updated example `todomvc` to use subscription `UrlChanged` instead of `routes`.
+- [BREAKING] Futures in `perform_cmd` and `perform_g_cmd` are executed immediately.
+- Added `App` methods `notify` and `notify_with_notification`.
+- [BREAKING] `App` method `process_cmd_and_msg_queue` renamed to `process_effect_queue`.
+- [BREAKING] Url change listeners are always active (even if `routes` is not defined).
+- Added `cmds`, `streams`, `subs`, `CmdHandle`, `SubHandle` and `StreamHandle` into the Seed's prelude.
+- [BREAKING] Removed module `next_tick`.
 
 ## v0.6.0
 - Implemented `UpdateEl` for `Filter` and `FilterMap`.

examples/README.md

@@ -39,7 +39,7 @@ How to perform commands and send messages from `update` function.
 And how to use [gloo](https://github.com/rustwasm/gloo) timers.
 
 ### [Subscribe](subscribe)
-How to create and use subscriptions.
+How to create and use subscriptions, streams, notifications and commands.
 
 ### [TEA component](tea_component)
 How to write a component in The Elm architecture.

examples/orders/src/lib.rs

@@ -3,6 +3,8 @@
 use gloo_timers::future::TimeoutFuture;
 use seed::{prelude::*, *};
 
+// NOTE: See example `subscribe` to learn more about other `Orders` methods.
+
 // ------ ------
 //     Model
 // ------ ------

examples/subscribe/README.md

@@ -1,6 +1,6 @@
 ## Subscribe example
 
-How to create and use subscriptions.
+How to create and use subscriptions, streams, notifications and commands.
 
 ---
 

src/app/cmd_manager.rs

@@ -1,17 +1,22 @@
 use futures::future::{abortable, AbortHandle, Future, FutureExt};
 use wasm_bindgen_futures::spawn_local;
 
+// @TODO: Tighten up access - e.g. replace `pub` with `pub(crate)`. Applicable to the entire code base.
+
 // ------ CmdManager ------
 
 pub struct CmdManager;
 
 impl CmdManager {
     pub fn perform_cmd(cmd: impl Future<Output = ()> + 'static) {
+        // The future is "leaked" into the JS world as a promise.
+        // It's always executed on the next JS tick to prevent stack overflow.
         spawn_local(cmd);
     }
 
     pub fn perform_cmd_with_handle(cmd: impl Future<Output = ()> + 'static) -> CmdHandle {
         let (cmd, handle) = abortable(cmd);
+        // Ignore the error when the future is aborted. I.e. just stop the future execution.
         spawn_local(cmd.map(move |_| ()));
         CmdHandle(handle)
     }

src/app/cmds.rs

@@ -1,8 +1,17 @@
 use futures::future::{Future, FutureExt};
 use gloo_timers::future::TimeoutFuture;
 
+// @TODO add fetch cmd?
+
 // ------ Timeout cmd ------
 
+/// Set timeout in milliseconds.
+///
+/// # Example
+///
+/// ```rust,no_run
+///orders.perform_cmd_with_handle(cmds::timeout(2000, || Msg::OnTimeout));
+/// ```
 pub fn timeout<Ms>(
     ms: u32,
     handler: impl FnOnce() -> Ms + Clone + 'static,

src/app/orders.rs

@@ -3,6 +3,9 @@ use crate::virtual_dom::View;
 use futures::stream::Stream;
 use std::{any::Any, future::Future};
 
+// @TODO: Add links to doc comment once https://github.com/rust-lang/rust/issues/43466 is resolved
+// or use nightly rustdoc. Applicable to the entire code base.
+
 pub mod container;
 pub mod proxy;
 
@@ -37,29 +40,55 @@ pub trait Orders<Ms: 'static, GMs = UndefinedGMsg> {
     /// Don't rerender web page after model update.
     fn skip(&mut self) -> &mut Self;
 
+    /// Notify all subscription handlers which listen for messages with the `message`'s type.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///orders.notify(counter::DoReset);
+    ///orders.notify("Hello!");
+    /// ...
+    ///orders.subscribe(Msg::Reset);  // `Msg::Reset(counter::DoReset)`
+    ///orders.subscribe(|greeting: &'static str| { log!(greeting); Msg::NoOp });
+    /// ```
+    ///
+    /// _Note:_: All notifications are pushed to the queue - i.e. `update` function is NOT called immediately.
     fn notify(&mut self, message: impl Any + Clone) -> &mut Self;
 
-    /// Call function `update` with the given `msg` after model update.
-    /// - You can call this function multiple times - messages will be sent in the same order.
+    /// Invoke function `update` with the given `msg`.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///orders.msg(Msg::Increment);
+    /// ```
+    ///
+    /// _Note:_: All `msg`s are pushed to the queue - i.e. `update` function is NOT called immediately.
     fn send_msg(&mut self, msg: Ms) -> &mut Self;
 
-    /// @TODO
-    /// Schedule given future `cmd` to be executed after model update.
-    /// - Result is send to function `update`.
-    /// - You can call this function multiple times - futures will be scheduled in the same order.
+    /// Execute given future `cmd` and send its output (`Msg`) to `update` function.
     ///
     /// # Example
     ///
     /// ```rust,no_run
-    ///async fn write_emoticon_after_delay() -> Msg {
-    ///    TimeoutFuture::new(2_000).await;
-    ///    Msg::WriteEmoticon
-    ///}
-    ///orders.perform_cmd(write_emoticon_after_delay());
+    ///orders.perform_cmd(cmds::timeout(2000, || Msg::OnTimeout)));
+    ///orders.perform_cmd(async { log!("Hello!"); Msg::NoOp });
     /// ```
+    ///
+    /// _Note:_: Use the alternative `perform_cmd_with_handle` to control `cmd`'s lifetime.
     fn perform_cmd(&mut self, cmd: impl Future<Output = Ms> + 'static) -> &mut Self;
 
-    #[must_use]
+    /// Execute given future `cmd` and send its output (`Msg`) to `update` function.
+    /// - Returns `CmdHandle` that you should save to your `Model`.
+    ///   The `cmd` is aborted on the handle drop.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///let timeout_handle = orders.perform_cmd_with_handle(cmds::timeout(2000, || Msg::OnTimeout)));
+    ///let cmd_handle = orders.perform_cmd_with_handle(async { log!("Hello!"); Msg::NoOp });
+    /// ```
+    #[must_use = "cmd is aborted on its handle drop"]
     fn perform_cmd_with_handle(&mut self, cmd: impl Future<Output = Ms> + 'static) -> CmdHandle;
 
     /// Similar to `send_msg`, but calls function `sink` with the given global message.
@@ -69,6 +98,9 @@ pub trait Orders<Ms: 'static, GMs = UndefinedGMsg> {
     fn perform_g_cmd(&mut self, g_cmd: impl Future<Output = GMs> + 'static) -> &mut Self;
 
     /// Similar to `perform_g_cmd`, but result is send to function `sink`.
+    /// - Returns `CmdHandle` that you should save to your `Model`.
+    ///   `cmd` is aborted on the handle drop.
+    #[must_use = "cmd is aborted on its handle drop"]
     fn perform_g_cmd_with_handle(
         &mut self,
         g_cmd: impl Future<Output = GMs> + 'static,
@@ -103,19 +135,67 @@ pub trait Orders<Ms: 'static, GMs = UndefinedGMsg> {
         callback: impl FnOnce(Option<RenderTimestampDelta>) -> Ms + 'static,
     ) -> &mut Self;
 
+    /// Subscribe for messages with the `handler`s input type.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///orders.subscribe(Msg::Reset);  // `Msg::Reset(counter::DoReset)`
+    ///orders.subscribe(|greeting: &'static str| { log!(greeting); Msg::NoOp });
+    ///orders.subscribe(Msg::UrlChanged)  // `update(... Msg::UrlChanged(subs::UrlChanged(url)) =>`
+    /// ...
+    ///orders.notify(counter::DoReset);
+    ///orders.notify("Hello!");
+    /// ```
+    ///
+    /// _Note:_: Use the alternative `subscribe_with_handle` to control `sub`'s lifetime.
     fn subscribe<SubMs: 'static + Clone>(
         &mut self,
         handler: impl FnOnce(SubMs) -> Ms + Clone + 'static,
     ) -> &mut Self;
 
-    #[must_use]
+    /// Subscribe for messages with the `handler`s input type.
+    /// - Returns `SubHandle` that you should save to your `Model`.
+    ///   The `sub` is cancelled on the handle drop.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///let sub_handle = orders.subscribe_with_handle(Msg::Reset);  // `Msg::Reset(counter::DoReset)`
+    ///orders.subscribe_with_handle(|greeting: &'static str| { log!(greeting); Msg::NoOp });
+    ///let url_changed_handle = orders.subscribe_with_handle(Msg::UrlChanged)  // `update(... Msg::UrlChanged(subs::UrlChanged(url)) =>`
+    /// ...
+    ///orders.notify(counter::DoReset);
+    ///orders.notify("Hello!");
+    /// ```
+    #[must_use = "subscription is cancelled on its handle drop"]
     fn subscribe_with_handle<SubMs: 'static + Clone>(
         &mut self,
         handler: impl FnOnce(SubMs) -> Ms + Clone + 'static,
     ) -> SubHandle;
 
+    /// Stream `Msg`s.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///orders.stream(streams::interval(1000, || Msg::OnTick)));
+    ///orders.stream(streams::window_event(Ev::Resize, |_| Msg::OnResize));
+    /// ```
+    ///
+    /// _Note:_: Use the alternative `stream_with_handle` to control `stream`'s lifetime.
     fn stream(&mut self, stream: impl Stream<Item = Ms> + 'static) -> &mut Self;
 
-    #[must_use]
+    /// Stream `Msg`s.
+    /// - Returns `StreamHandle` that you should save to your `Model`.
+    ///   The `stream` is cancelled on the handle drop.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    ///let timer_handler = orders.stream_with_handle(streams::interval(1000, || Msg::OnTick)));
+    ///let stream_handler = orders.stream_with_handle(streams::window_event(Ev::Resize, |_| Msg::OnResize));
+    /// ```
+    #[must_use = "stream is stopped on its handle drop"]
     fn stream_with_handle(&mut self, stream: impl Stream<Item = Ms> + 'static) -> StreamHandle;
 }

src/app/stream_manager.rs

@@ -8,12 +8,16 @@ pub struct StreamManager;
 
 impl StreamManager {
     pub fn stream(stream: impl Stream<Item = ()> + 'static) {
+        // Convert `Stream` to `Future` and execute it. The stream is "leaked" into the JS world.
         spawn_local(stream.for_each(|_| ready(())));
     }
 
     pub fn stream_with_handle(stream: impl Stream<Item = ()> + 'static) -> StreamHandle {
+        // Convert `Stream` to `Future`.
         let stream = stream.for_each(|_| ready(()));
+        // Create `AbortHandle`.
         let (stream, handle) = abortable(stream);
+        // Ignore the error when the future is aborted. I.e. just stop the stream.
         spawn_local(stream.map(move |_| ()));
         StreamHandle(handle)
     }

src/app/streams.rs

@@ -3,6 +3,13 @@ use gloo_timers::future::IntervalStream;
 
 // ------ Interval stream ------
 
+/// Stream no values on predefined time interval in milliseconds.
+///
+/// # Example
+///
+/// ```rust,no_run
+///orders.stream_with_handle(streams::interval(1000, || Msg::OnTick));
+/// ```
 pub fn interval<Ms>(
     ms: u32,
     handler: impl FnOnce() -> Ms + Clone + 'static,
@@ -12,5 +19,5 @@ pub fn interval<Ms>(
 
 // ------ Window Event stream ------
 
-pub mod window_event;
+mod window_event;
 pub use window_event::window_event;

src/app/streams/window_event.rs

@@ -8,13 +8,29 @@ use wasm_bindgen::closure::Closure;
 use wasm_bindgen::{JsCast, JsValue};
 use web_sys::{Event, EventTarget};
 
+// ------ Window Event stream ------
+
+/// Stream `Window` `web_sys::Event`s.
+///
+/// # Example
+///
+/// ```rust,no_run
+///orders.stream(streams::window_event(Ev::Resize, |_| Msg::OnResize));
+/// ```
 pub fn window_event<Ms>(
     trigger: impl Into<Ev>,
     handler: impl FnOnce(Event) -> Ms + Clone + 'static,
 ) -> impl Stream<Item = Ms> {
     EventStream::new(&window(), trigger.into()).map(move |event| handler.clone()(event))
 }
 
+// ------ EventStream ------
+
+// @TODO Replace `mpsc` with `crossbeam`? (And integrate it into the other Seed parts (e.g. `Listener`, `SubManager`)).
+
+// @TODO Update it to support different `web_sys` events
+// during implementation of https://github.com/seed-rs/seed/issues/331
+
 pub struct EventStream<E> {
     node: EventTarget,
     trigger: Ev,
@@ -31,6 +47,7 @@ where
 
         let (sender, receiver) = unbounded();
 
+        // @TODO replace with `Closure::new` once stable (or use the Seed's temporary one).
         let callback = Closure::wrap(Box::new(move |event: JsValue| {
             sender.unbounded_send(event.dyn_into().unwrap()).unwrap();
         }) as Box<dyn Fn(JsValue)>);

src/app/subs.rs

@@ -7,5 +7,15 @@ pub use url_requested::UrlRequested;
 
 // ------ UrlChanged sub ------
 
+/// Subscribe to url changes.
+/// - Url change is fired also on application start by default.
+///
+/// # Example
+///
+/// ```rust,no_run
+///orders.subscribe(Msg::UrlChanged);
+///...
+///update(... Msg::UrlChanged(subs::UrlChanged(url)) =>
+/// ```
 #[derive(Clone)]
 pub struct UrlChanged(pub Url);

src/app/subs/url_requested.rs

@@ -3,12 +3,31 @@ use std::{cell::Cell, rc::Rc};
 
 pub type PreventDefault = bool;
 
+// ------ UrlRequested sub ------
+
+/// Subscribe to url requests. Requests are fired on a link click.
+///
+/// # Example
+///
+/// ```rust,no_run
+///orders.subscribe(Msg::UrlRequested);
+///...
+///update(... Msg::UrlRequested(subs::UrlRequested(url, url_request))) =>
+/// ```
+/// See `UrlRequest` for more info.
+#[derive(Clone)]
+pub struct UrlRequested(pub Url, pub UrlRequest);
+
+// --- UrlRequestStatus ---
+
 #[derive(Copy, Clone)]
 pub enum UrlRequestStatus {
     Unhandled,
     Handled(PreventDefault),
 }
 
+// --- UrlRequest ---
+
 #[derive(Clone)]
 pub struct UrlRequest(Rc<Cell<UrlRequestStatus>>);
 
@@ -19,22 +38,26 @@ impl Default for UrlRequest {
 }
 
 impl UrlRequest {
+    /// Flag the url request as unhandled.
+    /// - Seed prevents page refresh, pushes the route and fires `UrlChanged` notification.
+    /// - It's the default behaviour.
     pub fn unhandled(self) {
         self.0.set(UrlRequestStatus::Unhandled);
     }
 
+    /// Flag the url request as handled.
+    /// - Seed doesn't intercept or modify the click event and doesn't fire `UrlChanged` notification.
     pub fn handled(self) {
         self.0.set(UrlRequestStatus::Handled(false));
     }
 
-    pub fn handled_and_prevent_default(self) {
+    /// Flag the url request as handled and prevent page refresh.
+    /// - It's almost the same like `handled()` method, but Seed calls `prevent_default` on the click event.
+    pub fn handled_and_prevent_refresh(self) {
         self.0.set(UrlRequestStatus::Handled(true));
     }
 
     pub fn status(self) -> UrlRequestStatus {
         self.0.get()
     }
 }
-
-#[derive(Clone)]
-pub struct UrlRequested(pub Url, pub UrlRequest);