Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

16.7 KB
Raw Blame
use base64::{DecodeError, Engine, engine::general_purpose};
use either::Either;
use serde::{Deserialize, Serialize, de::DeserializeOwned};
use std::{cmp::Ordering, marker::PhantomData, ops::Deref};
use thiserror::Error;

/// struct which encapsulates a single page of cursor based pagination result
#[derive(Debug, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Paginated<T, U> {
    /// the list of items on this page
    pub items: Vec<T>,
    /// the id of the cursor where the next page of items begins
    /// this doesn't exist if we are at the end of results
    pub next_cursor: Option<U>,
}

impl<T, U> Paginated<T, U> {
    /// maps the inner type of the items to a new value using a callback function
    pub fn map<F, V>(self, f: F) -> Paginated<V, U>
    where
        F: FnMut(T) -> V,
    {
        let Paginated { items, next_cursor } = self;

        Paginated {
            items: items.into_iter().map(f).collect(),
            next_cursor,
        }
    }

    /// Decomposes the page into its items and cursor.
    pub fn into_parts(self) -> (Vec<T>, Option<U>) {
        (self.items, self.next_cursor)
    }

    /// Builds a page from an item vector and cursor.
    pub fn from_parts(items: Vec<T>, next_cursor: Option<U>) -> Self {
        Self { items, next_cursor }
    }
}

/// Top level cursor information encodes all the required information for paginating by [Cursor]
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Cursor<Id, C, F> {
    /// the unique id (e.g. i64, uuid, stc) that identifies the last entity
    /// on the previous page
    pub id: Id,
    /// the size of the previous page
    pub limit: usize,
    /// the value of the cursor
    /// this is usually a [CursorVal]
    pub val: C,

    /// the value we are filtering on
    pub filter: F,
}

impl<Id, C, F> Cursor<Id, C, F> {
    /// maps the filter from one type to another
    pub fn map_filter<Fn: FnOnce(F) -> F2, F2>(self, cb: Fn) -> Cursor<Id, C, F2> {
        let Cursor {
            id,
            limit,
            val,
            filter,
        } = self;

        Cursor {
            id,
            limit,
            val,
            filter: cb(filter),
        }
    }
}

/// Type alias for a [Cursor] with a [CursorVal] which is [Sortable]
pub type CursorWithVal<Id, V> = Cursor<Id, CursorVal<V>, ()>;

/// Type alias for a [Cursor] with a [CursorVal] which is [Sortable] and some filter value F
pub type CursorWithValAndFilter<Id, V, F> = Cursor<Id, CursorVal<V>, F>;

/// The value of the [Cursor]. That is, the type of sort we are performing
/// as well as the value of that sort on the last item of the page.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct CursorVal<C: Sortable> {
    /// the type that we are sorting on, must implement [Sortable]
    pub sort_type: C,
    /// the last value of the [Sortable] from the previous page
    pub last_val: C::Value,
}

/// defines type to be sortable, sortable types must have an associated [Sortable::Value]
pub trait Sortable: std::fmt::Debug {
    /// the value which we sort on e.g. Utc timestamp, float, etc
    type Value: std::fmt::Debug + std::cmp::Ord;
}

enum Direction {
    Asc,
    Desc,
}

/// Intermediary struct which holds information about the page we are going to create.
/// The only use for this struct is to call [Paginator::into_page]
pub struct Paginator<Iter, Cb, S, F> {
    iter: Iter,
    limit: usize,
    cb: Cb,
    sort_on: PhantomData<S>,
    filter_on: F,
    ensure_sort: Option<Direction>,
}

impl<Iter, Cb, S> Paginator<Iter, Cb, S, ()> {
    /// define the filter that the cursor is using
    pub fn filter_on<F>(self, filter: F) -> Paginator<Iter, Cb, S, F> {
        let Paginator {
            iter,
            limit,
            cb,
            sort_on,
            filter_on: (),
            ensure_sort,
        } = self;
        Paginator {
            iter,
            limit,
            cb,
            sort_on,
            filter_on: filter,
            ensure_sort,
        }
    }
}

/// The base trait which extends [Iterator] to create a [Paginator] if the trait bounds are met
pub trait Paginate: Iterator + Sized {
    /// turn the iterator into a [Paginator]
    fn paginate<Cb, S>(self, limit: usize, cb: Cb) -> Paginator<Self, Cb, S, ()>
    where
        Cb: FnMut(&<Self as Iterator>::Item) -> CursorVal<S>,
        S: Sortable;
}

/// extension to [Paginate] with the further requirement that the iterator item implements [SortOn] for this sort value T
pub trait PaginateOn<T: Sortable>: Paginate {
    /// wrapper over [Paginate::paginate]
    fn paginate_on(
        self,
        limit: usize,
        sort: T,
    ) -> Paginator<Self, impl FnMut(&<Self as Iterator>::Item) -> CursorVal<T>, T, ()>
    where
        <Self as Iterator>::Item: SortOn<T>;
}

/// the trait used to uniquely identify a record
pub trait Identify {
    /// the type of the records PK
    type Id;

    /// get the records PK
    fn id(&self) -> Self::Id;
}

/// trait which is required to call [PaginateOn]
/// This should be implemented on the item that we iterate over, for the sortable method T that we are trying to paginate on
pub trait SortOn<T: Sortable> {
    /// Given the input sort method T, return a function which produces the [CursorVal] for that T, from an input Self
    fn sort_on(sort: T) -> impl FnMut(&Self) -> CursorVal<T>;
}

impl<T> Paginate for T
where
    T: Iterator,
    T::Item: Identify,
{
    fn paginate<Cb, S>(self, limit: usize, cb: Cb) -> Paginator<Self, Cb, S, ()>
    where
        Cb: FnOnce(&<Self as Iterator>::Item) -> CursorVal<S>,
        S: Sortable,
    {
        Paginator {
            iter: self,
            limit,
            cb,
            sort_on: PhantomData,
            filter_on: (),
            ensure_sort: None,
        }
    }
}

impl<Iter, T: Sortable> PaginateOn<T> for Iter
where
    Iter: Paginate,
{
    fn paginate_on(
        self,
        limit: usize,
        sort: T,
    ) -> Paginator<Self, impl FnMut(&<Self as Iterator>::Item) -> CursorVal<T>, T, ()>
    where
        <Self as Iterator>::Item: SortOn<T>,
    {
        let cb = <<Self as Iterator>::Item as SortOn<T>>::sort_on(sort);
        self.paginate(limit, cb)
    }
}

/// Type alias for a [Paginated] where we still know the underlying type information of the encoded cursor
/// T: The item type that is listed in each page
/// I: The identity type that is associated with this T. e.g. Uuid
/// C: The sort type of this cursor
/// F: The filter type of this cursor
pub type PaginatedCursor<T, I, C, F> = Paginated<T, Base64Str<CursorWithValAndFilter<I, C, F>>>;

/// Type alias for a [Paginated] where the type information of the cursor has been erased. This is identical in memory layout and serialization shape as [PaginatedTypedCursor]
pub type PaginatedOpaqueCursor<T> = Paginated<T, String>;

impl<Iter, Cb, S, F> Paginator<Iter, Cb, S, F>
where
    Iter: Iterator,
    Iter::Item: Identify,
    Cb: FnMut(&Iter::Item) -> CursorVal<S>,
    S: Sortable + Serialize,
    S::Value: Serialize,
    F: Serialize,
    <Iter::Item as Identify>::Id: Serialize,
{
    /// ensures that the output will be sorted.
    /// You should not use this in most cases as the ideal scenario is that the database should
    /// return an already sorted list.
    /// This is an escape hatch for use when stitching multiple database queries together.
    ///
    /// This will sort the entries in ascending order
    pub fn sort_asc(mut self) -> Self {
        self.ensure_sort = Some(Direction::Asc);
        self
    }
    /// ensures that the output will be sorted.
    /// You should not use this in most cases as the ideal scenario is that the database should
    /// return an already sorted list.
    /// This is an escape hatch for use when stitching multiple database queries together.
    ///
    /// This will sort the entries in descending order
    pub fn sort_desc(mut self) -> Self {
        self.ensure_sort = Some(Direction::Desc);
        self
    }
    /// Turn self into a [PaginatedTypedCursor].
    /// This ensures that the page has the correct number of items and encodes the last element of the page into a base64 json encoded representation of the cursor.
    pub fn into_page(self) -> PaginatedCursor<Iter::Item, <Iter::Item as Identify>::Id, S, F> {
        let Paginator {
            iter,
            limit,
            mut cb,
            filter_on,
            ensure_sort,
            ..
        } = self;

        let res = match ensure_sort {
            Some(sort) => {
                let mut res: Vec<_> = iter.collect();
                res.sort_by_key(|r| {
                    let cursor = cb(r);
                    match sort {
                        Direction::Asc => Either::Left(cursor.last_val),
                        Direction::Desc => Either::Right(std::cmp::Reverse(cursor.last_val)),
                    }
                });
                res.truncate(limit);
                res
            }
            None => iter.take(limit).collect(),
        };

        match res.len().cmp(&limit) {
            Ordering::Less => Paginated {
                items: res,
                next_cursor: None,
            },
            Ordering::Equal | Ordering::Greater => Paginated {
                next_cursor: res
                    .last()
                    .map(|last| Cursor {
                        id: last.id(),
                        limit,
                        val: cb(last),
                        filter: filter_on,
                    })
                    .map(Base64Str::encode_json),
                items: res,
            },
        }
    }
}

/// trait for erasing the strong typing of a Cursor
/// This makes the type less specific but maintains the same inner data
pub trait TypeEraseCursor<T> {
    /// Erase the type of self.
    /// This doesn't actually change any data it just makes the type less sepcific
    fn type_erase(self) -> PaginatedOpaqueCursor<T>;
}

impl<T, I, C: Sortable, F> TypeEraseCursor<T> for PaginatedCursor<T, I, C, F> {
    fn type_erase(self) -> PaginatedOpaqueCursor<T> {
        let Self { items, next_cursor } = self;
        PaginatedOpaqueCursor {
            items,
            next_cursor: next_cursor.map(|c| c.type_erase()),
        }
    }
}

impl<T, I, I2, C: Sortable, C2: Sortable, F, F2> TypeEraseCursor<T>
    for Either<PaginatedCursor<T, I, C, F>, PaginatedCursor<T, I2, C2, F2>>
{
    fn type_erase(self) -> PaginatedOpaqueCursor<T> {
        match self {
            Either::Left(l) => l.type_erase(),
            Either::Right(r) => r.type_erase(),
        }
    }
}

fn serialize_json_string<T: Serialize>(val: &T) -> String {
    serde_json::to_string(val).expect("This is infallible")
}

/// Struct which encapsulated some base64 encoded value which is expected to deserialize to some type T
#[derive(Debug, Serialize, Deserialize)]
#[serde(transparent)]
pub struct Base64Str<T> {
    data: String,
    #[serde(skip)]
    target: PhantomData<T>,
}

impl<T> Deref for Base64Str<T> {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        &self.data
    }
}

/// Errors that can occur while working with a [Base64Str]
#[derive(Debug, Error)]
pub enum Base64SerdeErr<E> {
    /// There was an error decoding data from the base64 string
    #[error(transparent)]
    DecodeErr(#[from] DecodeError),
    /// there was an error with serde
    #[error(transparent)]
    SerdeErr(E),
}

impl<T> Base64Str<T>
where
    T: DeserializeOwned,
{
    /// attempt to decode the base64 and then deserialize the raw bytes.
    /// Pass a callback fn that deserializes the data
    pub fn decode<F, E>(self, f: F) -> Result<T, Base64SerdeErr<E>>
    where
        F: FnOnce(Vec<u8>) -> Result<T, E>,
    {
        let bytes = general_purpose::STANDARD.decode(self.data.as_str())?;
        f(bytes).map_err(Base64SerdeErr::SerdeErr)
    }

    /// decode the base64 bytes then deserialize type T from the decoded bytes
    pub fn decode_json(self) -> Result<T, Base64SerdeErr<serde_json::Error>> {
        self.decode(|bytes| serde_json::from_slice(&bytes))
    }
}

impl<T> Base64Str<T> {
    /// Create a new version of self from a string
    pub fn new_from_string(data: String) -> Self {
        Base64Str {
            data,
            target: PhantomData,
        }
    }

    /// Just return the inner string
    pub fn type_erase(self) -> String {
        self.data
    }
}

impl<T> Base64Str<T>
where
    T: Serialize,
{
    /// Serialize the input value to a string using the input callback function.
    /// Then base64 encode that string, creating an instance of Self
    pub fn encode<F>(val: T, s: F) -> Self
    where
        F: FnOnce(&T) -> String,
    {
        let serialized = s(&val);
        let str = general_purpose::STANDARD.encode(serialized);
        Base64Str::new_from_string(str)
    }

    /// Serialize the input value as a json string and then base64 encode, creating an instance of self
    pub fn encode_json(val: T) -> Self {
        Self::encode(val, serialize_json_string)
    }
}

/// A [Query] is either a sort method T
/// Or a [CursorWithVal]
#[derive(Debug)]
pub enum Query<I, T: Sortable, F> {
    /// a Sort method T
    Sort(T, F),
    /// a [CursorWithVal]
    Cursor(CursorWithValAndFilter<I, T, F>),
}

impl<I, T, F> Clone for Query<I, T, F>
where
    T: Sortable + Clone,
    T::Value: Clone,
    I: Clone,
    F: Clone,
{
    fn clone(&self) -> Self {
        match self {
            Query::Sort(s, f) => Query::Sort(s.clone(), f.clone()),
            Query::Cursor(cursor) => Query::Cursor(cursor.clone()),
        }
    }
}

impl<I, T: Sortable, F> Query<I, T, F> {
    /// create an instance of [Query] from optionally a [CursorWithVal], fallling back to T if it does not exist
    pub fn new(maybe_cursor: Option<CursorWithValAndFilter<I, T, F>>, sort: T, filter: F) -> Self {
        match maybe_cursor {
            Some(c) => Self::Cursor(c),
            None => Self::Sort(sort, filter),
        }
    }

    /// returns the inner sort method [Sortable] for this query
    pub fn sort_method(&self) -> &T {
        match self {
            Query::Sort(s, _) => s,
            Query::Cursor(cursor) => &cursor.val.sort_type,
        }
    }

    /// returns a reference to the inner filter type
    pub fn filter(&self) -> &F {
        match self {
            Query::Sort(_, f) => f,
            Query::Cursor(cursor) => &cursor.filter,
        }
    }

    /// maps this filter type into another one via a callback fn.
    /// This is analagous to [Option::map] over just the filter generic type
    pub fn map_filter<Cb, F2>(self, cb: Cb) -> Query<I, T, F2>
    where
        Cb: FnOnce(F) -> F2,
    {
        match self {
            Query::Sort(a, b) => Query::Sort(a, cb(b)),
            Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter,
            }) => Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: cb(filter),
            }),
        }
    }
    /// maps this filter type into another one via a callback fn.
    /// This is analagous to [Option::map] over just the filter generic type
    pub fn try_map_filter<Cb, F2, E>(self, cb: Cb) -> Result<Query<I, T, F2>, E>
    where
        Cb: FnOnce(F) -> Result<F2, E>,
    {
        match self {
            Query::Sort(a, b) => Ok(Query::Sort(a, cb(b)?)),
            Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter,
            }) => Ok(Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: cb(filter)?,
            })),
        }
    }

    /// returns the entity [Uuid] and [Sortable::Value] if they exist
    pub fn vals(&self) -> (Option<&I>, Option<&T::Value>) {
        match self {
            Query::Sort(_, _) => (None, None),
            Query::Cursor(cursor) => (Some(&cursor.id), Some(&cursor.val.last_val)),
        }
    }
}

impl<I, T, F> Query<I, T, Option<F>>
where
    T: Sortable,
{
    /// Factors out an [Option] from the filter, splitting the type into an [Either]
    pub fn split_option(self) -> Either<Query<I, T, ()>, Query<I, T, F>> {
        match self {
            Query::Sort(t, None) => Either::Left(Query::Sort(t, ())),
            Query::Sort(t, Some(f)) => Either::Right(Query::Sort(t, f)),
            Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: None,
            }) => Either::Left(Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: (),
            })),
            Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: Some(f),
            }) => Either::Right(Query::Cursor(Cursor {
                id,
                limit,
                val,
                filter: f,
            })),
        }
    }
}