@perspective-dev/viewer 4.0.0 → 4.1.0

package/src/rust/session/metadata.rs

@@ -17,7 +17,6 @@ use std::ops::{Deref, DerefMut};
 use perspective_client::config::*;
 use perspective_js::apierror;
 
-use crate::components::viewer::ColumnLocator;
 use crate::*;
 
 struct SessionViewExpressionMetadata {
@@ -46,6 +45,9 @@ impl DerefMut for SessionMetadata {
     }
 }
 
+pub type MetadataRef<'a> = std::cell::Ref<'a, SessionMetadata>;
+pub type MetadataMutRef<'a> = std::cell::RefMut<'a, SessionMetadata>;
+
 /// TODO the multiple `Option` types could probably be merged since they are
 /// populated within an async lock
 #[derive(Default)]
@@ -193,22 +195,6 @@ impl SessionMetadata {
         is_expr.unwrap_or_default()
     }
 
-    /// This function will find a currently existing column. If you want to
-    /// create a new expression column, use ColumnLocator::Expr(None)
-    pub fn get_column_locator(&self, name: Option<String>) -> Option<ColumnLocator> {
-        name.and_then(|name| {
-            self.as_ref().and_then(|meta| {
-                if self.is_column_expression(&name) {
-                    Some(ColumnLocator::Expression(name))
-                } else {
-                    meta.column_names
-                        .iter()
-                        .find_map(|n| (n == &name).then_some(ColumnLocator::Table(name.clone())))
-                }
-            })
-        })
-    }
-
     /// Creates a new column name by appending a numeral corresponding to the
     /// number of columns with that name.
     pub fn make_new_column_name(&self, col: Option<&str>) -> String {

package/src/rust/session/replace_expression_update.rs

@@ -37,8 +37,7 @@ pub impl ViewConfig {
             sort,
             filter,
             aggregates,
-            filter_op: _,
-            group_by_depth: _,
+            ..
         } = self.clone();
 
         let expressions = expressions

package/src/rust/session.rs

@@ -21,47 +21,49 @@ use std::collections::HashSet;
 use std::future::Future;
 use std::ops::Deref;
 use std::rc::Rc;
-use std::sync::Arc;
 
 use perspective_client::config::*;
-use perspective_client::{ClientError, ReconnectCallback, View, ViewWindow};
+use perspective_client::{Client, ClientError, ReconnectCallback, View, ViewWindow};
 use perspective_js::apierror;
 use perspective_js::utils::*;
 use wasm_bindgen::prelude::*;
 use yew::html::ImplicitClone;
 use yew::prelude::*;
 
+pub use self::metadata::MetadataRef;
 use self::metadata::*;
 use self::replace_expression_update::*;
 pub use self::view_subscription::ViewStats;
 use self::view_subscription::*;
-use crate::dragdrop::*;
 use crate::js::plugin::*;
 use crate::utils::*;
 
-/// The `Session` struct is the principal interface to the Perspective engine,
-/// the `Table` and `View` objects for this viewer, and all associated state
-/// including the `ViewConfig`.
-#[derive(Clone, Default)]
-pub struct Session(Arc<SessionHandle>);
-
-impl ImplicitClone for Session {}
-
 /// Immutable state for `Session`.
 #[derive(Default)]
 pub struct SessionHandle {
     session_data: RefCell<SessionData>,
     pub table_updated: PubSub<()>,
     pub table_loaded: PubSub<()>,
+    pub table_errored: PubSub<ApiError>,
+    pub table_unloaded: PubSub<bool>,
     pub view_created: PubSub<()>,
     pub view_config_changed: PubSub<()>,
     pub stats_changed: PubSub<Option<ViewStats>>,
-    pub table_errored: PubSub<ApiError>,
+    pub title_changed: PubSub<Option<String>>,
+}
+
+impl Deref for SessionHandle {
+    type Target = RefCell<SessionData>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.session_data
+    }
 }
 
 /// Mutable state for `Session`.
 #[derive(Default)]
 pub struct SessionData {
+    client: Option<perspective_client::Client>,
     table: Option<perspective_client::Table>,
     metadata: SessionMetadata,
     old_config: Option<ViewConfig>,
@@ -71,11 +73,36 @@ pub struct SessionData {
     is_clean: bool,
     is_paused: bool,
     error: Option<TableErrorState>,
+    title: Option<String>,
 }
 
 #[derive(Clone)]
 pub struct TableErrorState(ApiError, Option<ReconnectCallback>);
 
+/// Options for [`Session::reset`]
+#[derive(Default)]
+pub struct ResetOptions {
+    /// Reset user defined expressions
+    pub expressions: bool,
+
+    /// Reset the [`Table`]
+    pub table: bool,
+
+    /// Reset the [`ViewConfig`]
+    pub config: bool,
+
+    /// Manually reset the [`ViewStats`]
+    pub stats: bool,
+}
+
+/// The `Session` struct is the principal interface to the Perspective engine,
+/// the `Table` and `View` objects for this viewer, and all associated state
+/// including the `ViewConfig`.
+#[derive(Clone)]
+pub struct Session(Rc<SessionHandle>);
+
+impl ImplicitClone for Session {}
+
 impl Deref for Session {
     type Target = SessionHandle;
 
@@ -86,22 +113,18 @@ impl Deref for Session {
 
 impl PartialEq for Session {
     fn eq(&self, other: &Self) -> bool {
-        Arc::ptr_eq(&self.0, &other.0)
+        Rc::ptr_eq(&self.0, &other.0)
     }
 }
 
-impl Deref for SessionHandle {
-    type Target = RefCell<SessionData>;
-
-    fn deref(&self) -> &Self::Target {
-        &self.session_data
+impl Session {
+    /// Uses [`Self::new`] instead of [`Default`] to prevent accidental
+    /// instantiation in props/etc.
+    #[allow(clippy::new_without_default)]
+    pub fn new() -> Self {
+        Self(Rc::default())
     }
-}
 
-pub type MetadataRef<'a> = std::cell::Ref<'a, SessionMetadata>;
-pub type MetadataMutRef<'a> = std::cell::RefMut<'a, SessionMetadata>;
-
-impl Session {
     pub fn metadata(&self) -> MetadataRef<'_> {
         std::cell::Ref::map(self.borrow(), |x| &x.metadata)
     }
@@ -110,40 +133,48 @@ impl Session {
         std::cell::RefMut::map(self.borrow_mut(), |x| &mut x.metadata)
     }
 
-    pub fn invalidate(&self) {
-        self.borrow_mut().error = None;
-        self.borrow_mut().is_clean = false;
-        self.borrow_mut().view_sub = None;
+    pub fn get_title(&self) -> Option<String> {
+        self.borrow().title.clone()
     }
 
-    /// Reset this `Session`'s `View` state, but preserve the `Table`.
-    ///
-    /// # Arguments
-    /// - `reset_expressions` Whether to reset the `expressions` property.
-    pub fn reset(&self, reset_expressions: bool) -> impl Future<Output = ApiResult<()>> + use<> {
-        self.borrow_mut().is_clean = false;
-        let view = self.0.borrow_mut().view_sub.take();
-        self.borrow_mut().view_sub = None;
-        self.borrow_mut().config.reset(reset_expressions);
-        let err = self.get_error();
-        async move {
-            let res = view.delete().await;
-            if let Some(err) = err { Err(err) } else { res }
-        }
+    pub fn set_title(&self, title: Option<String>) {
+        let new_title = title.filter(|x| !x.is_empty());
+        self.borrow_mut().title.clone_from(&new_title);
+        self.title_changed.emit(new_title);
     }
 
     /// Reset this (presumably shared) `Session` to its initial state, returning
     /// a bool indicating whether this `Session` had a table which was
     /// deleted. TODO Table should be an immutable constructor parameter to
     /// `Session`.
-    pub async fn delete(&self) -> ApiResult<()> {
+    pub fn reset(&self, options: ResetOptions) -> impl Future<Output = ApiResult<()>> + use<> {
         self.borrow_mut().is_clean = false;
-        self.borrow_mut().config.reset(true);
-        self.borrow_mut().metadata = SessionMetadata::default();
-        self.borrow_mut().table = None;
-        let view = self.borrow_mut().view_sub.take();
-        view.delete().await?;
-        Ok(())
+        let view = self.0.borrow_mut().view_sub.take();
+        let err = self.get_error();
+        self.borrow_mut().error = None;
+        if options.stats {
+            self.update_stats(ViewStats::default());
+        }
+
+        if options.config {
+            self.borrow_mut().config.reset(options.expressions);
+        }
+
+        if options.table {
+            self.borrow_mut().table = None;
+            self.borrow_mut().metadata = SessionMetadata::default();
+        }
+
+        let table_unloaded = self.table_unloaded.callback();
+        self.borrow_mut().is_clean = false;
+        async move {
+            let res = view.delete().await;
+            if options.table {
+                table_unloaded.emit(true)
+            }
+
+            if let Some(err) = err { Err(err) } else { res }
+        }
     }
 
     pub fn has_table(&self) -> bool {
@@ -154,10 +185,40 @@ impl Session {
         self.borrow().table.clone()
     }
 
+    pub fn set_client(&self, client: Client) -> bool {
+        if Some(&client) != self.borrow().client.as_ref() {
+            self.borrow_mut().client = Some(client);
+            self.borrow_mut().table = None;
+            true
+        } else {
+            false
+        }
+    }
+
+    pub fn get_client(&self) -> Option<Client> {
+        self.borrow().client.clone()
+    }
+
     /// Reset this `Session`'s state with a new `Table`.  Implicitly clears the
     /// `ViewSubscription`, which will need to be re-initialized later via
     /// `create_view()`.
-    pub async fn set_table(&self, table: perspective_client::Table) -> ApiResult<JsValue> {
+    ///
+    /// # Arguments
+    ///
+    /// - `table_name` The name of the `Table` to load, which must exist on the
+    ///   loaded `Client`.
+    ///
+    /// # Returns
+    ///
+    /// `table_name` is unique per `Client`, so if this value has not changed,
+    /// `Session::set_table` does nothing and returns `Ok(false)`.
+    pub async fn set_table(&self, table_name: String) -> ApiResult<bool> {
+        if Some(table_name.as_str()) == self.0.borrow().table.as_ref().map(|x| x.get_name()) {
+            return Ok(false);
+        }
+
+        let client = self.0.borrow().client.clone().into_apierror()?;
+        let table = client.open_table(table_name.clone()).await?;
         match SessionMetadata::from_table(&table).await {
             Ok(metadata) => {
                 let client = table.get_client();
@@ -186,19 +247,31 @@ impl Session {
                 let sub = self.borrow_mut().view_sub.take();
                 self.borrow_mut().metadata = metadata;
                 self.borrow_mut().table = Some(table);
+                self.borrow_mut().is_clean = false;
                 sub.delete().await?;
                 self.table_loaded.emit(());
-                Ok(JsValue::UNDEFINED)
+                Ok(true)
             },
-            Err(err) => self.set_error(false, err).await.map(|_| JsValue::UNDEFINED),
+            Err(err) => self.set_error(false, err).await.map(|_| false),
+        }
+    }
+
+    pub fn update_column_defaults(&self, requirements: &ViewConfigRequirements) {
+        if self.borrow().config.columns.is_empty() {
+            let mut update = ViewConfigUpdate::default();
+            self.set_update_column_defaults(&mut update, requirements);
+            self.borrow_mut().config.apply_update(update);
         }
     }
 
     pub async fn set_error(&self, reset_table: bool, err: ApiError) -> ApiResult<()> {
         let session = self.clone();
         let poll_loop = LocalPollLoop::new(move |()| {
-            session.invalidate();
-            ApiFuture::spawn(session.reset(true));
+            ApiFuture::spawn(session.reset(ResetOptions {
+                config: true,
+                expressions: true,
+                ..ResetOptions::default()
+            }));
             Ok(JsValue::UNDEFINED)
         });
 
@@ -240,7 +313,7 @@ impl Session {
 
     pub async fn await_table(&self) -> ApiResult<()> {
         if self.js_get_table().is_none() {
-            self.table_loaded.listen_once().await?;
+            self.table_loaded.read_next().await?;
             let _ = self.js_get_table().ok_or("No table set")?;
         }
 
@@ -279,6 +352,7 @@ impl Session {
             self.borrow_mut().error = None;
             self.borrow_mut().is_clean = false;
             self.borrow_mut().view_sub = None;
+            self.table_loaded.emit(());
         }
 
         Ok(())
@@ -457,7 +531,7 @@ impl Session {
         self.borrow().stats.clone()
     }
 
-    pub fn get_view_config(&self) -> Ref<ViewConfig> {
+    pub fn get_view_config(&'_ self) -> Ref<'_, ViewConfig> {
         Ref::map(self.borrow(), |x| &x.config)
     }
 
@@ -511,7 +585,7 @@ impl Session {
         use self::column_defaults_update::*;
         config_update.set_update_column_defaults(
             &self.metadata(),
-            &self.borrow().config.columns,
+            &self.all_columns().into_iter().map(Some).collect::<Vec<_>>(),
             requirements,
         )
     }
@@ -534,15 +608,6 @@ impl Session {
         Ok(())
     }
 
-    pub fn reset_stats(&self) {
-        self.update_stats(ViewStats::default());
-    }
-
-    #[cfg(test)]
-    pub fn set_stats(&self, stats: ViewStats) {
-        self.update_stats(stats)
-    }
-
     /// In order to create a new view in this session, the session must first be
     /// validated to create a `ValidSession<'_>` guard.
     pub async fn validate(&self) -> Result<ValidSession<'_>, ApiError> {
@@ -555,8 +620,11 @@ impl Session {
         if let Err(err) = self.validate_view_config().await {
             let session = self.clone();
             let poll_loop = LocalPollLoop::new(move |()| {
-                session.invalidate();
-                ApiFuture::spawn(session.reset(true));
+                ApiFuture::spawn(session.reset(ResetOptions {
+                    config: true,
+                    expressions: true,
+                    ..ResetOptions::default()
+                }));
                 Ok(JsValue::UNDEFINED)
             });
 
@@ -574,7 +642,12 @@ impl Session {
             if let Some(config) = old {
                 self.borrow_mut().config = config;
             } else {
-                self.reset(true).await?;
+                self.reset(ResetOptions {
+                    config: true,
+                    expressions: true,
+                    ..ResetOptions::default()
+                })
+                .await?;
             }
 
             return Err(err);
@@ -604,16 +677,18 @@ impl Session {
         self.stats_changed.emit(Some(stats));
     }
 
-    async fn validate_view_config(&self) -> ApiResult<()> {
-        let mut config = self.borrow().config.clone();
-        let table_columns = self
-            .metadata()
+    fn all_columns(&self) -> Vec<String> {
+        self.metadata()
             .get_table_columns()
             .into_iter()
             .flatten()
             .cloned()
-            .collect::<Vec<String>>();
+            .collect()
+    }
 
+    async fn validate_view_config(&self) -> ApiResult<()> {
+        let mut config = self.borrow().config.clone();
+        let table_columns = self.all_columns();
         let all_columns: HashSet<String> = table_columns.iter().cloned().collect();
         let mut view_columns: HashSet<&str> = HashSet::new();
         let table = self
@@ -711,17 +786,17 @@ impl Session {
 /// A newtype wrapper which only provides `create_view()`
 pub struct ValidSession<'a>(&'a Session, bool);
 
-impl<'a> ValidSession<'a> {
+impl ValidSession<'_> {
     /// Set a new `View` (derived from this `Session`'s `Table`), and create the
     /// `update()` subscription, consuming this `ValidSession<'_>` and returning
     /// the original `&Session`.
-    pub async fn create_view(&self) -> Result<&'a Session, ApiError> {
+    pub async fn create_view(&self) -> Result<Option<View>, ApiError> {
         if !self.0.reset_clean() && !self.0.borrow().is_paused {
             if !self.1 {
                 let config = self.0.borrow().config.clone();
                 if let Some(sub) = &mut self.0.borrow_mut().view_sub.as_mut() {
                     sub.update_view_config(Rc::new(config));
-                    return Ok(self.0);
+                    return Ok(Some(sub.get_view().clone()));
                 }
             }
 
@@ -747,11 +822,16 @@ impl<'a> ValidSession<'a> {
                         .0
                         .metadata()
                         .get_column_aggregates(col.as_str())
-                        .into_apierror()?
-                        .next()
-                        .into_apierror()?;
-
-                    let _ = view_config.aggregates.insert(col.to_string(), agg);
+                        .and_then(|mut aggs| aggs.next())
+                        .into_apierror();
+
+                    match agg {
+                        Err(_) => tracing::warn!(
+                            "No default aggregate for column '{}' found, skipping",
+                            col
+                        ),
+                        Ok(agg) => _ = view_config.aggregates.insert(col.to_string(), agg),
+                    };
                 }
             }
 
@@ -781,7 +861,7 @@ impl<'a> ValidSession<'a> {
             self.0.borrow_mut().view_sub = Some(sub);
         }
 
-        Ok(self.0)
+        Ok(self.0.get_view())
     }
 }
 

package/src/rust/utils/browser/blob.rs

@@ -11,10 +11,13 @@
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 use perspective_js::utils::ApiResult;
+use wasm_bindgen::JsValue;
 
+/// An extension method for converting various [`js_sys`] and [`web_sys`] types
+/// to [`web_sys::Blob`].
 pub trait AsBlob {
-    /// Standardized conversions from common `wasm_bindgen` types to
-    /// `js_sys::Blob`, which is commonly necessary to provide data to a
+    /// Standardized conversions from common [`wasm_bindgen`] types to
+    /// [`web_sys::Blob`], which is commonly necessary to provide data to a
     /// download or clipboard action.
     fn as_blob(&self) -> ApiResult<web_sys::Blob>;
 }
@@ -26,6 +29,17 @@ impl AsBlob for js_sys::ArrayBuffer {
     }
 }
 
+impl AsBlob for JsValue {
+    fn as_blob(&self) -> ApiResult<web_sys::Blob> {
+        let array = std::iter::once(self).collect::<js_sys::Array>();
+        let options = web_sys::BlobPropertyBag::new();
+        options.set_type("text/plain");
+        Ok(web_sys::Blob::new_with_str_sequence_and_options(
+            &array, &options,
+        )?)
+    }
+}
+
 impl AsBlob for js_sys::JsString {
     fn as_blob(&self) -> ApiResult<web_sys::Blob> {
         let array = std::iter::once(self).collect::<js_sys::Array>();

package/src/rust/utils/browser/download.rs

@@ -13,6 +13,7 @@
 use perspective_js::utils::{global, *};
 use wasm_bindgen::JsCast;
 
+/// Given a blob, invoke the Browser's download popup.
 pub fn download(name: &str, value: &web_sys::Blob) -> ApiResult<()> {
     let element: web_sys::HtmlElement = global::document().create_element("a")?.unchecked_into();
     let blob_url = web_sys::Url::create_object_url_with_blob(value)?;

package/src/rust/{components/column_settings_sidebar/mod.rs → utils/browser/dragdrop.rs}

@@ -9,9 +9,18 @@
 // ┃ 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 attributes_tab;
-mod save_settings;
-mod sidebar;
-mod style_tab;
 
-pub use sidebar::*;
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum DragTarget {
+    Active,
+    GroupBy,
+    SplitBy,
+    Sort,
+    Filter,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum DragEffect {
+    Copy,
+    Move(DragTarget),
+}

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

@@ -10,15 +10,19 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+//! Utilities specific to Browser-only JavaScript extensions.
+
 mod blob;
 mod download;
+mod dragdrop;
 mod request_animation_frame;
 mod selection;
 
 #[cfg(test)]
 mod tests;
 
-pub use blob::*;
-pub use download::*;
-pub use request_animation_frame::*;
-pub use selection::*;
+pub use self::blob::*;
+pub use self::download::*;
+pub use self::dragdrop::*;
+pub use self::request_animation_frame::*;
+pub use self::selection::*;

package/src/rust/utils/browser/selection.rs

@@ -19,8 +19,13 @@ use crate::*;
 /// but `Deref` makes them fall through, so it is important that this method
 /// be called on the correct struct type!
 pub trait CaretPosition {
+    /// Select the entired clip
     fn select_all(&self) -> ApiResult<()>;
+
+    /// Set the caret to a specific offset.
     fn set_caret_position(&self, offset: usize) -> ApiResult<()>;
+
+    /// Get the caret's offset (if it has focus)
     fn get_caret_position(&self) -> Option<u32>;
 }
 

package/src/rust/utils/custom_element.rs

@@ -10,20 +10,9 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-use wasm_bindgen::prelude::*;
-
-pub trait CustomElementMetadata {
-    const CUSTOM_ELEMENT_NAME: &'static str;
-    const STATICS: &'static [&'static str] = [].as_slice();
-    const TYPE_NAME: &'static str = std::any::type_name::<Self>();
+//! Utilities for building JavaScript Custom Elements with Rust.
 
-    fn struct_name() -> &'static str {
-        match &Self::TYPE_NAME.rfind(':') {
-            Some(pos) => &Self::TYPE_NAME[pos + 1..],
-            None => Self::TYPE_NAME,
-        }
-    }
-}
+use wasm_bindgen::prelude::*;
 
 #[wasm_bindgen(inline_js = r#"
     export function bootstrap(psp, name, clsname, statics) {
@@ -75,6 +64,32 @@ extern "C" {
     fn js_bootstrap(psp: &JsValue, name: &str, cls: &str, statics: js_sys::Array) -> JsValue;
 }
 
+/// A trait which allows the [`define_web_component`] method to create a
+/// Custom Element (which must by definition inherit from `HTMLElement`) from
+/// a `[wasm_bindgen]` annotated Rust struct (for which this trait is
+/// implemented).
+pub trait CustomElementMetadata {
+    /// The name of the element to register.
+    const CUSTOM_ELEMENT_NAME: &'static str;
+
+    /// [optional] The names of the methods which should be static on the
+    /// element.
+    const STATICS: &'static [&'static str] = [].as_slice();
+
+    /// [optional] The name of the Rust struct.
+    const TYPE_NAME: &'static str = std::any::type_name::<Self>();
+
+    /// [optional] A custom implementation of struct name to class name.
+    #[must_use]
+    fn struct_name() -> &'static str {
+        match &Self::TYPE_NAME.rfind(':') {
+            Some(pos) => &Self::TYPE_NAME[pos + 1..],
+            None => Self::TYPE_NAME,
+        }
+    }
+}
+
+/// Register the Custom Element globally.
 pub fn define_web_component<T: CustomElementMetadata>(module: &JsValue) {
     js_bootstrap(
         module,

package/src/rust/utils/datetime.rs

@@ -10,6 +10,9 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+//! Utility functions for dealing with datetime types.
+//! TODO These methods should use JavaSript `Intl`.
+
 use chrono::{DateTime, FixedOffset, NaiveDateTime, TimeZone, Utc};
 use perspective_js::utils::*;
 use wasm_bindgen::prelude::*;
@@ -27,6 +30,7 @@ fn get_local_tz() -> FixedOffset {
     FixedOffset::west_opt(js_sys::Date::new(&0.into()).get_timezone_offset() as i32 * 60).unwrap()
 }
 
+/// Convert POSIX timestamp to a formatted string.
 pub fn posix_to_utc_str(x: f64) -> ApiResult<String> {
     let tz = get_local_tz();
     if x > 0_f64 {
@@ -42,6 +46,7 @@ pub fn posix_to_utc_str(x: f64) -> ApiResult<String> {
     }
 }
 
+/// Convert a `String` datetime representation to a POSIX timestamp.
 pub fn str_to_utc_posix(val: &str) -> Result<f64, ApiError> {
     let tz = get_local_tz();
     let posix = NaiveDateTime::parse_from_str(val, input_value_format(val)?)?;