@perspective-dev/viewer 4.0.0

package/src/rust/utils/hooks/use_async_callback.rs

@@ -0,0 +1,53 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use wasm_bindgen::__rt::IntoJsResult;
+use wasm_bindgen_futures::future_to_promise;
+use yew::prelude::*;
+
+use crate::renderer::*;
+use crate::session::*;
+use crate::*;
+
+#[derive(Clone, Properties, PartialEq)]
+pub struct StatusIndicatorProps {
+    pub session: Session,
+    pub renderer: Renderer,
+    pub children: Children,
+}
+
+/// Just like `use_callback`, except convenient for an async cresult body.
+#[hook]
+pub fn use_async_callback<IN, OUT, F, D>(deps: D, f: F) -> Callback<IN, ()>
+where
+    IN: Clone + 'static,
+    OUT: IntoJsResult + 'static,
+    F: AsyncFn(IN, &D) -> OUT + 'static,
+    D: Clone + PartialEq + 'static,
+{
+    let deps = std::rc::Rc::new(deps);
+    let f = std::rc::Rc::new(f);
+    (*use_memo(deps, move |deps| {
+        let deps = deps.clone();
+        let ff = move |value: IN| {
+            let value = value.clone();
+            let f = f.clone();
+            let deps = deps.clone();
+            let _ = future_to_promise(async move {
+                f(value, &deps).await.into_js_result()?;
+                Ok(JsValue::UNDEFINED)
+            });
+        };
+        Callback::from(ff)
+    }))
+    .clone()
+}

package/src/rust/utils/mod.rs

@@ -0,0 +1,114 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! A catch all for project-wide macros and general-purpose functions that are
+//! not directly related to Perspective.
+//!
+//! Modules below `crate::utils` strive to be single-responsibility, but some
+//! reference other `crate::utils` modules when it helps reduce boiler-plate.
+
+mod browser;
+
+mod custom_element;
+mod datetime;
+mod debounce;
+mod hooks;
+mod number_format;
+mod pubsub;
+mod scope;
+mod tee;
+mod wasm_abi;
+mod weak_scope;
+
+#[cfg(test)]
+mod tests;
+
+pub use browser::*;
+pub use custom_element::*;
+pub use datetime::*;
+pub use debounce::*;
+pub use hooks::*;
+pub use number_format::*;
+pub use perspective_client::clone;
+pub use pubsub::*;
+pub use scope::*;
+pub use tee::*;
+pub use weak_scope::*;
+
+#[macro_export]
+macro_rules! maybe {
+    ($($exp:stmt);*) => {{
+        let x = ({
+            #[inline(always)]
+            || {
+                $($exp)*
+            }
+        })();
+        x
+    }};
+}
+
+#[macro_export]
+macro_rules! js_log_maybe {
+    ($($exp:tt)+) => {{
+        let x = ({
+            #[inline(always)]
+            || {
+                {
+                    $($exp)+
+                };
+                Ok(())
+            }
+        })();
+        x.unwrap_or_else(|e| web_sys::console::warn_1(&e))
+    }};
+}
+
+#[macro_export]
+macro_rules! max {
+    ($x:expr) => ($x);
+    ($x:expr, $($z:expr),+ $(,)?) => {{
+        let x = $x;
+        let y = max!($($z),*);
+        if x > y {
+            x
+        } else {
+            y
+        }
+    }}
+}
+
+#[macro_export]
+macro_rules! min {
+    ($x:expr) => ($x);
+    ($x:expr, $($z:expr),+ $(,)?) => {{
+        let x = $x;
+        let y = min!($($z),*);
+        if x < y {
+            x
+        } else {
+            y
+        }
+    }}
+}
+
+#[macro_export]
+macro_rules! js_log {
+    ($x:expr) => {{
+        const DEBUG_ONLY_WARNING: &str = $x;
+        web_sys::console::log_1(&wasm_bindgen::JsValue::from($x));
+    }};
+    ($x:expr $(, $y:expr)*) => {{
+        const DEBUG_ONLY_WARNING: &str = $x;
+        web_sys::console::log_1(&format!($x, $($y),*).into());
+    }};
+}

package/src/rust/utils/number_format.rs

@@ -0,0 +1,48 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use std::sync::LazyLock;
+
+use js_sys::Intl;
+use perspective_js::json;
+use perspective_js::utils::global::navigator;
+use wasm_bindgen::JsValue;
+
+pub trait ToFormattedString {
+    fn to_formatted_string(&self) -> String;
+}
+
+struct UnsafeNumberFormat(Intl::NumberFormat);
+
+unsafe impl Send for UnsafeNumberFormat {}
+unsafe impl Sync for UnsafeNumberFormat {}
+
+static NUMBER_FORMAT: LazyLock<UnsafeNumberFormat> = LazyLock::new(|| {
+    let locale = navigator().languages();
+    let opts = json!({});
+    let number_format = Intl::NumberFormat::new(&locale, &opts);
+    UnsafeNumberFormat(number_format)
+});
+
+impl UnsafeNumberFormat {}
+
+impl ToFormattedString for u32 {
+    fn to_formatted_string(&self) -> String {
+        NUMBER_FORMAT
+            .0
+            .format()
+            .call1(&NUMBER_FORMAT.0, &JsValue::from_f64(*self as f64))
+            .unwrap()
+            .as_string()
+            .unwrap()
+    }
+}

package/src/rust/utils/pubsub.rs

@@ -0,0 +1,222 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use std::cell::{Cell, RefCell};
+use std::collections::HashMap;
+use std::rc::{Rc, Weak};
+
+use derivative::Derivative;
+use futures::channel::oneshot::*;
+use yew::prelude::*;
+
+/// An internal `HashSet` variant which supports unconstrained `T` e.g.
+/// without `Hash`, via returning a unique `usize` index for each insert
+/// which can be used for a reciprocal `remove(x: usize)`.
+#[derive(Derivative)]
+#[derivative(Default(bound = ""))]
+struct IndexedSet<T> {
+    set: HashMap<usize, T>,
+    gen_: usize,
+}
+
+impl<T> IndexedSet<T> {
+    fn insert(&mut self, v: T) -> usize {
+        let key = self.gen_;
+        self.set.insert(key, v);
+        self.gen_ += 1;
+        key
+    }
+
+    fn remove(&mut self, key: usize) {
+        self.set.remove(&key);
+    }
+
+    fn iter(&self) -> impl Iterator<Item = &T> {
+        self.set.values()
+    }
+
+    fn drain(&mut self) -> impl Iterator<Item = T> {
+        let mut x = Box::default();
+        std::mem::swap(&mut self.set, &mut x);
+        x.into_values()
+    }
+}
+
+type ListenerSet<T> = IndexedSet<Box<dyn Fn(T) + 'static>>;
+type ListenerOnceSet<T> = IndexedSet<Box<dyn FnOnce(T) + 'static>>;
+
+#[derive(Derivative)]
+#[derivative(Default(bound = ""))]
+pub struct PubSubInternal<T: Clone> {
+    deleted: Cell<bool>,
+    listeners: RefCell<ListenerSet<T>>,
+    once_listeners: RefCell<ListenerOnceSet<T>>,
+}
+
+impl<T: Clone> PubSubInternal<T> {
+    fn emit(&self, val: T) {
+        if self.deleted.get() {
+            tracing::warn!("`Callback` invoked after `PubSub` dropped");
+        }
+
+        for listener in self.listeners.borrow().iter() {
+            listener(val.clone());
+        }
+
+        for listener in self.once_listeners.borrow_mut().drain() {
+            listener(val.clone());
+        }
+    }
+}
+
+/// A pub/sub struct which allows many listeners to subscribe to many
+/// publishers, without leaking callbacks as listeners are dropped.
+///
+/// Unlike `mpsc` etc., `PubSub` has no internal queue and is completely
+/// synchronous.
+#[derive(Derivative)]
+#[derivative(Default(bound = ""))]
+pub struct PubSub<T: Clone>(Rc<PubSubInternal<T>>);
+
+unsafe impl<T: Clone> Send for PubSub<T> {}
+unsafe impl<T: Clone> Sync for PubSub<T> {}
+
+pub trait AddListener<T> {
+    /// Register a listener to this `PubSub<_>`, which will be automatically
+    /// deregistered when the return `Subscription` is dropped.
+    ///
+    /// # Arguments
+    /// - `f` The callback, presumably a function-like type.
+    fn add_listener(&self, f: T) -> Subscription;
+}
+
+impl<T: Clone + 'static> PubSub<T> {
+    /// Emit a value to all listeners.
+    ///
+    /// # Arguments
+    /// - `val` The value to emit.
+    pub fn emit(&self, val: T) {
+        self.0.emit(val);
+    }
+
+    /// Get this `PubSub<_>`'s `.emit_all()` method as a `Callback<T>`.
+    pub fn callback(&self) -> Callback<T> {
+        let internal = self.0.clone();
+        Callback::from(move |val: T| internal.emit(val))
+    }
+
+    pub fn as_boxfn(&self) -> Box<dyn Fn(T) + Send + Sync + 'static> {
+        let internal = PubSub(self.0.clone());
+        Box::new(move |val: T| internal.emit(val))
+    }
+
+    /// Await this `PubSub<_>`'s next call to `emit_all()`, once.
+    pub async fn listen_once(&self) -> Result<T, Canceled> {
+        let (sender, receiver) = channel::<T>();
+        let f = move |x| sender.send(x).unwrap_or(());
+        self.0.once_listeners.borrow_mut().insert(Box::new(f));
+        receiver.await
+    }
+
+    /// Create a `Subscriber` from this `PubSub`, which is the reciprocal of
+    /// `PubSub::callback` (a struct which only allows sending), a struct which
+    /// only allows receiving via `Subscriber::add_listener`.
+    pub fn subscriber(&self) -> Subscriber<T> {
+        Subscriber(Rc::<PubSubInternal<T>>::downgrade(&self.0))
+    }
+}
+
+impl<T: Clone> Drop for PubSub<T> {
+    fn drop(&mut self) {
+        self.0.deleted.set(true);
+    }
+}
+
+impl<T: Clone + 'static> AddListener<Callback<T>> for PubSub<T> {
+    fn add_listener(&self, f: Callback<T>) -> Subscription {
+        let internal = self.0.clone();
+        let cb = Box::new(move |x| f.emit(x));
+        let key = self.0.listeners.borrow_mut().insert(cb);
+        Subscription(Box::new(move || {
+            internal.listeners.borrow_mut().remove(key)
+        }))
+    }
+}
+
+impl<T, U> AddListener<U> for PubSub<T>
+where
+    T: Clone + 'static,
+    U: Fn(T) + 'static,
+{
+    fn add_listener(&self, f: U) -> Subscription {
+        let internal = self.0.clone();
+        let key = self.0.listeners.borrow_mut().insert(Box::new(f));
+        Subscription(Box::new(move || {
+            internal.listeners.borrow_mut().remove(key)
+        }))
+    }
+}
+
+/// Like a `PubSub` without `PubSub::emit`; the reciprocal of
+/// `PubSub::callback`. `Subscriber` does not keep the parent `PubSub` alive.
+#[derive(Clone)]
+pub struct Subscriber<T: Clone>(Weak<PubSubInternal<T>>);
+
+impl<T, U> AddListener<U> for Subscriber<T>
+where
+    T: Clone + 'static,
+    U: Fn(T) + 'static,
+{
+    fn add_listener(&self, f: U) -> Subscription {
+        if let Some(internal) = self.0.upgrade() {
+            let key = internal.listeners.borrow_mut().insert(Box::new(f));
+            Subscription(Box::new(move || {
+                internal.listeners.borrow_mut().remove(key)
+            }))
+        } else {
+            Subscription(Box::new(|| {}))
+        }
+    }
+}
+
+impl<T: Clone> Default for Subscriber<T> {
+    fn default() -> Self {
+        Self(Weak::new())
+    }
+}
+
+impl<T: Clone> PartialEq for Subscriber<T> {
+    fn eq(&self, other: &Self) -> bool {
+        match (self.0.upgrade(), other.0.upgrade()) {
+            (Some(x), Some(y)) => std::ptr::eq(
+                &*x as *const PubSubInternal<T>,
+                &*y as *const PubSubInternal<T>,
+            ),
+            (None, None) => true,
+            _ => false,
+        }
+    }
+}
+
+/// Manages the lifetime of a listener registered to a `PubSub<T>` by
+/// deregistering the associated listener when dropped.
+///
+/// The wrapped `Fn` of `Subscriptions` is the deregister closure provided by
+/// the issuing `PubSub<T>`.
+#[must_use]
+pub struct Subscription(Box<dyn Fn()>);
+
+impl Drop for Subscription {
+    fn drop(&mut self) {
+        (*self.0)();
+    }
+}

package/src/rust/utils/scope.rs

@@ -0,0 +1,54 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use extend::ext;
+use futures::channel::oneshot::*;
+use perspective_js::utils::ApiResult;
+use yew::html::Scope;
+use yew::prelude::*;
+
+#[ext]
+pub impl<T> Scope<T>
+where
+    T: Component,
+{
+    /// Send a message with a callback, then suspend until the callback is
+    /// invoked.
+    fn send_message_async<F, U>(&self, f: F) -> Receiver<U>
+    where
+        F: FnOnce(Sender<U>) -> T::Message,
+    {
+        let (sender, receiver) = channel::<U>();
+        self.send_message(f(sender));
+        receiver
+    }
+}
+
+#[ext]
+pub(crate) impl<T> Callback<Sender<T>>
+where
+    T: 'static,
+{
+    /// This is "safe" because `emit()` is not called synchronously.  Normally
+    /// we want this to minimize the async by doing as much work synchronous
+    /// as possible (see `send_message_async()` e.g.), but this method calls
+    /// `Yew` which _never_ wants to be called synchronously.
+    ///
+    /// TODO Need test coverage for this - error behavior is that presize/render
+    /// blocking calls are out-of-order, e.g. toggle config `presize()` call.
+    /// Engineering the test to capture this faulty behavior may be difficult
+    async fn emit_async_safe(&self) -> ApiResult<T> {
+        let (sender, receiver) = channel::<T>();
+        self.emit(sender);
+        Ok(receiver.await?)
+    }
+}

package/src/rust/utils/tee.rs

@@ -0,0 +1,88 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+/// Trait for polymorphic return value via turbofish-const-generic syntax.
+///
+/// The associated type `Output` is a functional dependency of the const generic
+/// parameter `N`, so there's typically no need to specify this parameter when
+/// invoking, which is what we want - this parameter is quite verbose and
+/// repetitive (see below), vs `N` which is a single character.
+pub trait TeeInternal<const N: usize> {
+    type Output: Clone;
+    fn tee_internal(self) -> Self::Output;
+}
+
+pub trait Tee {
+    /// Extension method to add `tee()` method to all `T: Clone`.
+    ///
+    /// This can't be done directly as part of `TeeInternal` because it makes
+    /// specifying the const param at the `tee()` invocation site
+    /// cumbersome: `TeeInternal::<N>::tee(&obj)` as opposed to
+    /// `obj.tee::<N>()`. The constraint `Self: TeeInternal<N>` collapses
+    /// the potential `impl` matches to exactly 1, which makes the call to
+    /// `tee_internal()` unambiguous. This constraint is also allowed to
+    /// contain the generic parameter `N` because it is specified as a
+    /// constraint to the method (as opposed to a constraint on the trait).
+    /// I'm honestly quite surprised this works ...
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let x = "test".tee::<2>();
+    /// assert_eq!(x.0, x.1);
+    /// assert_eq!(x.0, "test");
+    /// ```
+    fn tee<const N: usize>(self) -> <Self as TeeInternal<N>>::Output
+    where
+        Self: TeeInternal<N>;
+}
+
+impl<T: Clone> Tee for T {
+    fn tee<const N: usize>(self) -> <Self as TeeInternal<N>>::Output
+    where
+        Self: TeeInternal<N>,
+    {
+        self.tee_internal()
+    }
+}
+
+macro_rules! gen_tee {
+    ($($x:ty),*) => {
+        impl<T: Clone> TeeInternal<{${count($x)} + 1}> for T {
+            type Output = ($($x),*, T);
+            fn tee_internal(self) -> Self::Output {
+                ($( ${ignore($x)} self.clone() ),*, self)
+            }
+        }
+    };
+}
+
+gen_tee!(T);
+gen_tee!(T, T);
+gen_tee!(T, T, T);
+gen_tee!(T, T, T, T);
+gen_tee!(T, T, T, T, T);
+gen_tee!(T, T, T, T, T, T);
+gen_tee!(T, T, T, T, T, T, T);
+gen_tee!(T, T, T, T, T, T, T, T);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_test1() {
+        let x = "test".tee::<2>();
+        assert_eq!(x.0, x.1);
+        assert_eq!(x.0, "test");
+    }
+}

package/src/rust/utils/tests/mod.rs

@@ -0,0 +1,14 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+mod pubsub;
+mod request_animation_frame;