@perspective-dev/client 4.0.0

package/src/rust/utils/console_logger.rs

@@ -0,0 +1,236 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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::fmt::{Debug, Write};
+use std::sync::OnceLock;
+
+use tracing::Subscriber;
+use tracing::field::{Field, Visit};
+use tracing_subscriber::Layer;
+use tracing_subscriber::layer::Context;
+use tracing_subscriber::registry::LookupSpan;
+use wasm_bindgen::prelude::*;
+
+use crate::utils::*;
+
+/// A struct to implement the `Visit` visitor pattern trait to process
+/// `tracing::Event`s.
+#[derive(Default)]
+struct LogLineBuffer {
+    value: String,
+    is_tail: bool,
+}
+
+impl Visit for LogLineBuffer {
+    fn record_debug(&mut self, field: &Field, value: &dyn Debug) {
+        if field.name() == "message" {
+            if !self.value.is_empty() {
+                self.value = format!("{:?}\n{}", value, self.value)
+            } else {
+                self.value = format!("{value:?}")
+            }
+        } else {
+            if self.is_tail {
+                writeln!(self.value).unwrap();
+            } else {
+                write!(self.value, " ").unwrap();
+                self.is_tail = true;
+            }
+
+            write!(self.value, "{} = {:?};", field.name(), value).unwrap();
+        }
+    }
+}
+
+#[extend::ext]
+impl tracing::Level {
+    /// Convert a `tracing::Level` to an equivalent 4-arg call to the
+    /// browser console via the `web_sys::console` module.
+    fn web_logger_4(&self) -> fn(&JsValue, &JsValue, &JsValue, &JsValue) {
+        match *self {
+            tracing::Level::TRACE => web_sys::console::trace_4,
+            tracing::Level::DEBUG => web_sys::console::debug_4,
+            tracing::Level::INFO => web_sys::console::info_4,
+            tracing::Level::WARN => web_sys::console::warn_4,
+            tracing::Level::ERROR => web_sys::console::error_4,
+        }
+    }
+
+    fn web_logger_1(&self) -> fn(&JsValue) {
+        match *self {
+            tracing::Level::TRACE => web_sys::console::trace_1,
+            tracing::Level::DEBUG => web_sys::console::debug_1,
+            tracing::Level::INFO => web_sys::console::info_1,
+            tracing::Level::WARN => web_sys::console::warn_1,
+            tracing::Level::ERROR => web_sys::console::error_1,
+        }
+    }
+
+    /// Return a pretty color theme for a `tracing::Level`.
+    fn web_log_color(&self) -> &'static str {
+        match *self {
+            tracing::Level::TRACE => "background: #005F73; color: #000",
+            tracing::Level::DEBUG => "background: #0A9396; color: #000",
+            tracing::Level::INFO => "background: #E9D8A6; color: #000",
+            tracing::Level::WARN => "background: #EE9B00; color: #000",
+            tracing::Level::ERROR => "background: #AE2012; color: #000",
+        }
+    }
+}
+
+static IS_CHROME: OnceLock<bool> = OnceLock::new();
+
+fn detect_chrome() -> bool {
+    if let Some(window) = web_sys::window() {
+        window.get("chrome").is_some()
+    } else {
+        true
+    }
+}
+
+#[extend::ext]
+impl<'a> tracing::Metadata<'a> {
+    /// Log a message in the style of `WasmLogger`.
+    fn console_log(&self, msg: &str) {
+        let level = self.level();
+        let origin = self
+            .module_path()
+            .and_then(|file| self.line().map(|ln| format!("{}:{}", &file[11..], ln)))
+            .unwrap_or_default();
+
+        if *IS_CHROME.get_or_init(detect_chrome) {
+            level.web_logger_4()(
+                &format!("%c {level} %c {origin}%c {msg} ").into(),
+                &level.web_log_color().into(),
+                &"color: gray; font-style: italic".into(),
+                &"color: inherit".into(),
+            );
+        } else {
+            level.web_logger_1()(&format!("{origin} {msg}").into());
+        }
+    }
+}
+
+/// A custom logger modelled afer the `tracing_wasm` crate.
+struct WasmLogger {
+    max_level: tracing::Level,
+}
+
+impl Default for WasmLogger {
+    fn default() -> Self {
+        Self {
+            max_level: tracing::Level::WARN,
+        }
+    }
+}
+
+impl<S: Subscriber + for<'a> LookupSpan<'a>> Layer<S> for WasmLogger {
+    fn on_event(
+        &self,
+        event: &tracing::Event<'_>,
+        _ctx: tracing_subscriber::layer::Context<'_, S>,
+    ) {
+        let mut recorder = LogLineBuffer::default();
+        event.record(&mut recorder);
+        event.metadata().console_log(&recorder.value);
+    }
+
+    fn enabled(&self, metadata: &tracing::Metadata<'_>, _: Context<'_, S>) -> bool {
+        let level = metadata.level();
+        level <= &self.max_level
+    }
+
+    fn on_new_span(
+        &self,
+        attrs: &tracing::span::Attributes<'_>,
+        id: &tracing::Id,
+        ctx: Context<'_, S>,
+    ) {
+        let mut new_debug_record = LogLineBuffer::default();
+        attrs.record(&mut new_debug_record);
+        if let Some(span_ref) = ctx.span(id) {
+            span_ref
+                .extensions_mut()
+                .insert::<LogLineBuffer>(new_debug_record);
+        }
+
+        global::performance()
+            .mark(&format!("t{:x}", id.into_u64()))
+            .unwrap();
+    }
+
+    fn on_record(&self, id: &tracing::Id, values: &tracing::span::Record<'_>, ctx: Context<'_, S>) {
+        if let Some(span_ref) = ctx.span(id) {
+            if let Some(debug_record) = span_ref.extensions_mut().get_mut::<LogLineBuffer>() {
+                values.record(debug_record);
+            }
+        }
+    }
+
+    fn on_close(&self, id: tracing::Id, ctx: Context<'_, S>) {
+        if let Some(span_ref) = ctx.span(&id) {
+            let perf = global::performance();
+            let meta = span_ref.metadata();
+            let mark = format!("t{:x}", id.into_u64());
+            let start = perf
+                .get_entries_by_name_with_entry_type(&mark, "mark")
+                .at(-1)
+                .unchecked_into::<web_sys::PerformanceMark>()
+                .start_time();
+
+            meta.console_log(&format!("{:.0}ms", perf.now() - start));
+            let msg = format!(
+                "\"{}\" {} {}",
+                meta.name(),
+                meta.module_path().unwrap_or_default(),
+                span_ref
+                    .extensions()
+                    .get::<LogLineBuffer>()
+                    .map(|x| &x.value[..])
+                    .unwrap_or_default(),
+            );
+
+            perf.measure_with_start_mark(&msg, &mark).unwrap();
+        }
+    }
+}
+
+/// Configure `WasmLogger` as a global default for tracing.
+///
+/// This operation will conflict with any other library which sets a global
+/// default `tracing::Subscriber`, so it should not be called when `perspective`
+/// is used as a library from a larger app; in this case the app itself should
+/// configure `tracing` explicitly.
+pub fn set_global_logging() {
+    static INIT_LOGGING: OnceLock<()> = OnceLock::new();
+    INIT_LOGGING.get_or_init(|| {
+        if !*IS_CHROME.get_or_init(detect_chrome) {
+            web_sys::console::warn_1(
+                &"Unknown browser detected. Some features may not work, and performance may be \
+                  degraded."
+                    .into(),
+            );
+        }
+
+        use tracing_subscriber::layer::SubscriberExt;
+        let filter = tracing_subscriber::filter::filter_fn(|meta| {
+            meta.module_path()
+                .as_ref()
+                .map(|x| x.starts_with("perspective"))
+                .unwrap_or_default()
+        });
+
+        let layer = WasmLogger::default().with_filter(filter);
+        let subscriber = tracing_subscriber::Registry::default().with(layer);
+        tracing::subscriber::set_global_default(subscriber).unwrap();
+    });
+}

package/src/rust/utils/errors.rs

@@ -0,0 +1,288 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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::fmt::Display;
+use std::rc::Rc;
+use std::string::FromUtf8Error;
+
+use perspective_client::{ClientError, ExprValidationResult};
+use thiserror::*;
+use wasm_bindgen::prelude::*;
+
+#[macro_export]
+macro_rules! apierror {
+    ($msg:expr) => {{
+        use $crate::utils::errors::ApiErrorType::*;
+        let js_err_type = $msg;
+        let err = js_sys::Error::new(js_err_type.to_string().as_str());
+        let js_err = $crate::utils::errors::ApiError(
+            js_err_type,
+            $crate::utils::errors::JsBackTrace(std::rc::Rc::new(err.clone())),
+        );
+        js_err
+    }};
+}
+
+fn format_js_error(value: &JsValue) -> String {
+    if let Some(err) = value.dyn_ref::<js_sys::Error>() {
+        let msg = err.message().as_string().unwrap();
+        if let Ok(x) = js_sys::Reflect::get(value, &"stack".into()) {
+            format!("{}\n{}", msg, x.as_string().unwrap())
+        } else {
+            msg
+        }
+    } else {
+        value
+            .as_string()
+            .unwrap_or_else(|| format!("{value:?}"))
+            .to_string()
+    }
+}
+
+fn format_valid_exprs(recs: &ExprValidationResult) -> String {
+    recs.errors
+        .iter()
+        .map(|x| format!("\"{}\": {}", x.0, x.1.error_message))
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+/// A bespoke error class for chaining a litany of error types with the `?`
+/// operator.  
+#[derive(Clone, Debug, Error)]
+pub enum ApiErrorType {
+    #[error("{}", format_js_error(.0))]
+    JsError(JsValue),
+
+    #[error("{}", format_js_error(.0))]
+    JsRawError(js_sys::Error),
+
+    #[error("Failed to construct table from {0:?}")]
+    TableError(JsValue),
+
+    #[error("{}", format_js_error(.0))]
+    ViewerPluginError(JsValue),
+
+    #[error("{0}")]
+    ExternalError(Rc<Box<dyn std::error::Error>>),
+
+    #[error("{0}")]
+    UnknownError(String),
+
+    #[error("{0}")]
+    ClientError(#[from] ClientError),
+
+    #[error("Cancelled")]
+    CancelledError(#[from] futures::channel::oneshot::Canceled),
+
+    #[error("{0}")]
+    SerdeJsonError(Rc<serde_json::Error>),
+
+    #[error("{0}")]
+    ProstError(#[from] prost::DecodeError),
+
+    #[error("Unknown column \"{1}\" in field `{0}`")]
+    InvalidViewerConfigError(&'static str, String),
+
+    #[error("Invalid `expressions` {}", format_valid_exprs(.0))]
+    InvalidViewerConfigExpressionsError(Rc<ExprValidationResult>),
+
+    #[error("No `Table` attached")]
+    NoTableError,
+
+    #[error(transparent)]
+    SerdeWasmBindgenError(Rc<serde_wasm_bindgen::Error>),
+
+    #[error(transparent)]
+    Utf8Error(#[from] FromUtf8Error),
+
+    #[error(transparent)]
+    StdIoError(Rc<std::io::Error>),
+
+    #[error(transparent)]
+    RmpSerdeEncodeError(Rc<rmp_serde::encode::Error>),
+
+    #[error(transparent)]
+    RmpSerdeDecodeError(Rc<rmp_serde::decode::Error>),
+
+    #[error(transparent)]
+    Base64DecodeError(#[from] base64::DecodeError),
+
+    #[error(transparent)]
+    ChronoParseError(#[from] chrono::ParseError),
+}
+
+#[derive(Clone, Debug, Error)]
+pub struct ApiError(pub ApiErrorType, pub JsBackTrace);
+
+impl ApiError {
+    pub fn new<T: Display>(val: T) -> Self {
+        apierror!(UnknownError(format!("{val}")))
+    }
+
+    /// The error category
+    pub fn kind(&self) -> &'static str {
+        match self.0 {
+            ApiErrorType::JsError(..) => "[JsError]",
+            ApiErrorType::TableError(_) => "[TableError]",
+            ApiErrorType::ExternalError(_) => "[ExternalError]",
+            ApiErrorType::UnknownError(..) => "[UnknownError]",
+            ApiErrorType::ClientError(_) => "[ClientError]",
+            ApiErrorType::CancelledError(_) => "[CancelledError]",
+            ApiErrorType::SerdeJsonError(_) => "[SerdeJsonError]",
+            ApiErrorType::ProstError(_) => "[ProstError]",
+            ApiErrorType::InvalidViewerConfigError(..) => "[InvalidViewerConfigError]",
+            ApiErrorType::InvalidViewerConfigExpressionsError(_) => "[InvalidViewerConfigError]",
+            ApiErrorType::NoTableError => "[NoTableError]",
+            ApiErrorType::SerdeWasmBindgenError(_) => "[SerdeWasmBindgenError]",
+            ApiErrorType::Utf8Error(_) => "[FromUtf8Error]",
+            ApiErrorType::StdIoError(_) => "[StdIoError]",
+            ApiErrorType::RmpSerdeEncodeError(_) => "[RmpSerdeEncodeError]",
+            ApiErrorType::RmpSerdeDecodeError(_) => "[RmpSerdeDecodeError]",
+            ApiErrorType::Base64DecodeError(_) => "[Base64DecodeError]",
+            ApiErrorType::ChronoParseError(_) => "[ChronoParseError]",
+            ApiErrorType::ViewerPluginError(_) => "[ViewerPluginError]",
+            ApiErrorType::JsRawError(_) => "[JsRawError]",
+        }
+    }
+
+    /// The raw internal enum
+    pub fn inner(&self) -> &'_ ApiErrorType {
+        &self.0
+    }
+
+    /// The `Display` for this error
+    pub fn message(&self) -> String {
+        self.0.to_string()
+    }
+
+    /// This error's stacktrace from when it was constructed.
+    pub fn stacktrace(&self) -> String {
+        js_sys::Reflect::get(&self.1.0, &"stack".into())
+            .unwrap()
+            .as_string()
+            .unwrap()
+            .to_string()
+    }
+}
+
+unsafe impl Send for ApiError {}
+unsafe impl Sync for ApiError {}
+
+impl std::fmt::Display for ApiError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+impl<T: Into<ApiErrorType>> From<T> for ApiError {
+    fn from(value: T) -> Self {
+        let value: ApiErrorType = value.into();
+        let err = js_sys::Error::new(value.to_string().as_str());
+        ApiError(value, JsBackTrace(Rc::new(err.clone())))
+    }
+}
+
+impl From<ApiError> for JsValue {
+    fn from(err: ApiError) -> Self {
+        err.1.0.unchecked_ref::<JsValue>().clone()
+    }
+}
+
+impl From<serde_wasm_bindgen::Error> for ApiError {
+    fn from(value: serde_wasm_bindgen::Error) -> Self {
+        ApiErrorType::SerdeWasmBindgenError(Rc::new(value)).into()
+    }
+}
+
+impl From<std::io::Error> for ApiError {
+    fn from(value: std::io::Error) -> Self {
+        ApiErrorType::StdIoError(Rc::new(value)).into()
+    }
+}
+
+impl From<rmp_serde::decode::Error> for ApiError {
+    fn from(value: rmp_serde::decode::Error) -> Self {
+        ApiErrorType::RmpSerdeDecodeError(Rc::new(value)).into()
+    }
+}
+
+impl From<rmp_serde::encode::Error> for ApiError {
+    fn from(value: rmp_serde::encode::Error) -> Self {
+        ApiErrorType::RmpSerdeEncodeError(Rc::new(value)).into()
+    }
+}
+
+impl From<Box<dyn std::error::Error>> for ApiError {
+    fn from(value: Box<dyn std::error::Error>) -> Self {
+        ApiErrorType::ExternalError(Rc::new(value)).into()
+    }
+}
+
+impl From<serde_json::Error> for ApiError {
+    fn from(value: serde_json::Error) -> Self {
+        ApiErrorType::SerdeJsonError(Rc::new(value)).into()
+    }
+}
+
+impl From<JsValue> for ApiError {
+    fn from(err: JsValue) -> Self {
+        if err.is_instance_of::<js_sys::Error>() {
+            ApiErrorType::JsRawError(err.clone().unchecked_into()).into()
+        } else {
+            apierror!(JsError(err))
+        }
+    }
+}
+
+impl From<String> for ApiError {
+    fn from(value: String) -> Self {
+        apierror!(UnknownError(value.to_owned()))
+    }
+}
+
+impl From<&str> for ApiError {
+    fn from(value: &str) -> Self {
+        apierror!(UnknownError(value.to_owned()))
+    }
+}
+
+/// `ToApiError` handles complex cases that can't be into-d
+pub trait ToApiError<T> {
+    fn into_apierror(self) -> ApiResult<T>;
+}
+
+impl<T> ToApiError<T> for Option<T> {
+    fn into_apierror(self) -> ApiResult<T> {
+        self.ok_or_else(|| "Unwrap on None".into())
+    }
+}
+
+impl ToApiError<JsValue> for Result<(), ApiResult<JsValue>> {
+    fn into_apierror(self) -> ApiResult<JsValue> {
+        self.map_or_else(|x| x, |()| Ok(JsValue::UNDEFINED))
+    }
+}
+
+/// A common Rust error handling idiom (see e.g. `anyhow::Result`)
+pub type ApiResult<T> = Result<T, ApiError>;
+
+// Backtrace
+
+#[derive(Clone, Debug)]
+pub struct JsBackTrace(pub Rc<js_sys::Error>);
+
+impl std::fmt::Display for JsBackTrace {
+    fn fmt(&self, _: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        Ok(())
+    }
+}

package/src/rust/utils/futures.rs

@@ -0,0 +1,174 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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::future::Future;
+use std::pin::Pin;
+
+use perspective_client::ClientError;
+// TODO This is risky to rely on, but it is currently impossible to implement
+// this trait locally due to the orphan instance restriction.  Using this trait
+// removes alow of boilerplate required by `async` when casting to `Promise`.
+use wasm_bindgen::__rt::IntoJsResult;
+use wasm_bindgen::convert::{FromWasmAbi, IntoWasmAbi};
+use wasm_bindgen::describe::WasmDescribe;
+use wasm_bindgen::prelude::*;
+use wasm_bindgen_futures::{JsFuture, future_to_promise};
+
+use super::errors::*;
+
+/// A newtype wrapper for a `Future` trait object which supports being
+/// marshalled to a `JsPromise`.
+///
+/// This avoids implementing an API which requires type casting to
+/// and from `JsValue` and the associated loss of type safety.
+#[must_use]
+pub struct ApiFuture<T>(Pin<Box<dyn Future<Output = ApiResult<T>>>>)
+where
+    Result<T, JsValue>: IntoJsResult + 'static;
+
+impl<T> ApiFuture<T>
+where
+    Result<T, JsValue>: IntoJsResult + 'static,
+{
+    /// Constructor for `ApiFuture`.  Note that, like a regular `Future`, the
+    /// `ApiFuture` created does _not_ execute without being further cast to a
+    /// `Promise`, either explicitly or implcitly (when exposed via
+    /// `wasm_bindgen`).
+    pub fn new<U: Future<Output = ApiResult<T>> + 'static>(x: U) -> Self {
+        Self(Box::pin(x))
+    }
+}
+
+impl<T> ApiFuture<T>
+where
+    Result<T, JsValue>: IntoJsResult + 'static,
+{
+    /// Construct an `ApiFuture` and execute it immediately.  The `Promise`
+    /// handle created internally is dropped, but since JavaScript `Promise`
+    /// executes on construction, the async invocation persists.
+    pub fn spawn<U: Future<Output = ApiResult<T>> + 'static>(x: U) {
+        drop(js_sys::Promise::from(Self::new(x)))
+    }
+}
+
+impl<T> Default for ApiFuture<T>
+where
+    Result<T, JsValue>: IntoJsResult + 'static,
+    T: Default,
+{
+    fn default() -> Self {
+        Self::new(async { Ok(Default::default()) })
+    }
+}
+
+impl<T> From<ApiFuture<T>> for JsValue
+where
+    Result<T, Self>: IntoJsResult + 'static,
+{
+    fn from(fut: ApiFuture<T>) -> Self {
+        js_sys::Promise::from(fut).unchecked_into()
+    }
+}
+
+impl<T> From<ApiFuture<T>> for js_sys::Promise
+where
+    Result<T, JsValue>: IntoJsResult + 'static,
+{
+    fn from(fut: ApiFuture<T>) -> Self {
+        future_to_promise(async move {
+            match fut.0.await.ignore_view_delete()? {
+                Some(x) => Ok(x).into_js_result(),
+                None => Ok::<_, JsValue>(()).into_js_result(),
+            }
+        })
+    }
+}
+
+impl<T> WasmDescribe for ApiFuture<T>
+where
+    Result<T, JsValue>: IntoJsResult + 'static,
+{
+    fn describe() {
+        <js_sys::Promise as WasmDescribe>::describe()
+    }
+}
+
+impl<T> IntoWasmAbi for ApiFuture<T>
+where
+    Result<T, JsValue>: IntoJsResult + 'static,
+{
+    type Abi = <js_sys::Promise as IntoWasmAbi>::Abi;
+
+    #[inline]
+    fn into_abi(self) -> Self::Abi {
+        js_sys::Promise::from(self).into_abi()
+    }
+}
+
+impl<T> FromWasmAbi for ApiFuture<T>
+where
+    Result<T, JsValue>: IntoJsResult + 'static,
+    T: From<JsValue> + Into<JsValue>,
+{
+    type Abi = <js_sys::Promise as IntoWasmAbi>::Abi;
+
+    #[inline]
+    unsafe fn from_abi(js: Self::Abi) -> Self {
+        Self::new(async move {
+            let promise = unsafe { js_sys::Promise::from_abi(js) };
+            Ok(JsFuture::from(promise).await?.into())
+        })
+    }
+}
+
+impl<T> Future for ApiFuture<T>
+where
+    Result<T, JsValue>: IntoJsResult + 'static,
+{
+    type Output = ApiResult<T>;
+
+    fn poll(
+        self: Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+    ) -> std::task::Poll<Self::Output> {
+        let mut fut = unsafe { self.map_unchecked_mut(|s| &mut s.0) };
+        fut.as_mut().poll(cx)
+    }
+}
+
+#[extend::ext]
+pub impl<T> Result<T, ApiError> {
+    /// Wraps an error `JsValue` return from a caught JavaScript exception,
+    /// checking for the explicit error type indicating that a
+    /// `JsPerspectiveView` call has been cancelled due to it already being
+    /// deleted.  This is a normal mechanic of the `JsPerspectiveView` to
+    /// cancel a `View` call that is no longer need be the viewer, e.g. when
+    /// the user updates the UI before the previous update has finished
+    /// drawing.  Without using exceptions for this, we'd need to wrap every
+    /// such `JsPerspectiveView` call individually.
+    ///
+    /// When `"View method cancelled"` message is received, this call should
+    /// silently be replaced with `Ok`.  The message itself is returned in this
+    /// case (instead of whatever the `async` returns), which is helpful for
+    /// detecting this condition when debugging.
+    fn ignore_view_delete(self) -> Result<Option<T>, ApiError> {
+        self.map(|x| Some(x)).or_else(|x| match x.inner() {
+            ApiErrorType::ClientError(ClientError::ViewNotFound) => Ok(None),
+            ApiErrorType::JsRawError(..) | ApiErrorType::JsError(..)
+                if format!("{x}").contains("View not found") =>
+            {
+                Ok(None)
+            },
+            x => Err(x.clone().into()),
+        })
+    }
+}