quokka_templating/

scripting.rs

use std::{
    collections::{HashMap, HashSet},
    marker::PhantomData,
    sync::Arc,
};

use quokka_config::{Config, TryFromConfig};

use crate::Result;

use quokka_state::FromState;

const DEFAULT_SCRIPTS_GROUP: &str = "default";

///
/// With this you register your script sources and global/"merged" scripts for the whole page
///
/// You usually only use it during bundle initialization. There are already handlers for `/scripting/path_to_your_script.js` and `/scripting/script.js`.
///
#[derive(Clone)]
pub struct Scripting {
    sources: Vec<Arc<dyn ScriptSource + Send + Sync + 'static>>,
    merged_scripts: HashMap<String, HashSet<String>>,
}

impl Scripting {
    pub fn try_new() -> Result<Self> {
        Ok(Self {
            sources: Default::default(),
            merged_scripts: Default::default(),
        })
    }

    ///
    /// Registers a script from a rust_embed struct
    ///
    /// # Example
    ///
    /// ```
    /// use quokka_templating::Scripting;
    ///
    /// #[derive(rust_embed::RustEmbed)]
    /// #[folder = "../test_resources/scripts"]
    /// #[include = "*.js"]
    /// struct Scripts;
    ///
    /// let mut scripting = Scripting::try_new().unwrap();
    ///
    /// assert!(scripting.get_script("test.js").is_none());
    ///
    /// scripting.register_embedded_scripts::<Scripts>();
    /// assert_eq!(scripting.get_script("test.js").unwrap(), "console.log(\"Hello World\");\n");
    /// ```
    ///
    pub fn register_embedded_scripts<E: rust_embed::RustEmbed + Send + Sync + 'static>(&mut self) {
        self.sources
            .push(Arc::new(EmbedSource::<E>(Default::default())));
    }

    ///
    /// Adds a script to the `default` group. Same as `Scripting.add_merged_script_group("default", path)`
    ///
    pub fn add_merged_script(&mut self, script: &str) {
        self.add_merged_script_group(DEFAULT_SCRIPTS_GROUP, script);
    }

    ///
    /// Adds a global script.
    ///
    /// The merged scripts are supposed to be loaded on all pages. Adding a big or a
    /// lot of scripts will impact the sites performance and reduce the user experiance.
    /// Use with caution.
    ///
    /// # Note
    ///
    /// The script name has to be a valid import part. Relative paths in the current
    /// directory need to start with a `./`. An alphanumeric "word" will be seen as
    /// an item of an import map [more details here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
    ///
    /// # Example
    ///
    /// ```
    /// use quokka_templating::Scripting;
    ///
    /// #[derive(rust_embed::RustEmbed)]
    /// #[folder = "../test_resources/scripts"]
    /// #[include = "*.js"]
    /// struct Scripts;
    ///
    /// let mut scripting = Scripting::try_new().unwrap();
    ///
    /// assert!(scripting.get_merged_script().is_empty());
    ///
    /// scripting.add_merged_script_group("default", "./test.js");
    /// assert_eq!(scripting.get_merged_script(), "import \"./test.js\";\n");
    /// ```
    ///
    pub fn add_merged_script_group(&mut self, group: &str, script: &str) {
        self.merged_scripts
            .entry(group.to_string())
            .or_default()
            .insert(script.to_string());
    }

    ///
    /// Gets a script by its path
    ///
    /// # Example
    ///
    /// ```
    /// use quokka_templating::Scripting;
    ///
    /// #[derive(rust_embed::RustEmbed)]
    /// #[folder = "../test_resources/scripts"]
    /// #[include = "*.js"]
    /// struct Scripts;
    ///
    /// let mut scripting = Scripting::try_new().unwrap();
    ///
    /// assert!(scripting.get_script("test.js").is_none());
    ///
    /// scripting.register_embedded_scripts::<Scripts>();
    /// assert_eq!(scripting.get_script("test.js").unwrap(), "console.log(\"Hello World\");\n");
    /// ```
    ///
    pub fn get_script(&self, path: &str) -> Option<String> {
        for source in &self.sources {
            if let Some(data) = source.read(path) {
                return Some(data);
            }
        }

        None
    }

    ///
    /// Gets the `default` merged scripts. Same as `Scripting.get_merged_script_group("default")`
    ///
    pub fn get_merged_script(&self) -> String {
        self.get_merged_script_group(DEFAULT_SCRIPTS_GROUP)
    }

    ///
    /// Gets the merged script. Merged scripts are supposed to be used on all sides.
    /// The merged script will rely on ECMAScript imports to get all the required scripts.
    ///
    /// # Example
    ///
    /// ```
    /// use quokka_templating::Scripting;
    ///
    /// #[derive(rust_embed::RustEmbed)]
    /// #[folder = "../test_resources/scripts"]
    /// #[include = "*.js"]
    /// struct Scripts;
    ///
    /// let mut scripting = Scripting::try_new().unwrap();
    ///
    /// assert!(scripting.get_merged_script().is_empty());
    ///
    /// scripting.add_merged_script("test.js");
    /// assert_eq!(scripting.get_merged_script(), "import \"test.js\";\n");
    /// ```
    ///
    pub fn get_merged_script_group(&self, group: &str) -> String {
        use std::fmt::Write;
        let mut out = String::new();

        let Some(scripts) = self.merged_scripts.get(group) else {
            return String::new();
        };

        for script in scripts {
            writeln!(out, "import \"{script}\";").unwrap();
        }

        out
    }
}

trait ScriptSource {
    fn read(&self, path: &str) -> Option<String>;
}

struct EmbedSource<E>(PhantomData<E>);

impl<E: rust_embed::RustEmbed> ScriptSource for EmbedSource<E> {
    fn read(&self, path: &str) -> Option<String> {
        let file = E::get(path)?;

        #[cfg(feature = "script-utf16")]
        return Some(String::from_utf16_lossy(&file.data).to_string());
        #[cfg(not(feature = "script-utf16"))]
        return Some(String::from_utf8_lossy(&file.data).to_string());
    }
}

impl std::fmt::Debug for Scripting {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(
            r#"Scripting {
    sources: Vec<rust_embed::RustEmbed>,
}"#,
        )
    }
}

impl TryFromConfig for Scripting {
    type Error = crate::Error;

    #[tracing::instrument]
    async fn try_from_config(_: &Config) -> crate::Result<Self>
    where
        Self: Sized,
    {
        Self::try_new()
    }
}

impl FromState<Scripting> for Scripting {
    fn from_state(state: &Scripting) -> Self {
        state.clone()
    }
}