Struct ModuleBuilder 

pub struct ModuleBuilder<S: State> { /* private fields */ }

Fluent builder for constructing a ModuleDefinition.

Example

use hypen_server::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Clone, Default, Serialize, Deserialize)]
struct Counter { count: i32 }

#[derive(Deserialize)]
struct AddPayload { amount: i32 }

let module = ModuleBuilder::new("Counter")
    .state(Counter { count: 0 })
    .ui(r#"Column { Text("Count: @{state.count}") }"#)
    .on_action::<()>("increment", |state, _, _ctx| {
        state.count += 1;
    })
    .on_action::<AddPayload>("add", |state, payload, _ctx| {
        state.count += payload.amount;
    })
    .build();

Implementations

impl<S: State> ModuleBuilder<S>

pub fn new(name: impl Into<String>) -> Self

pub fn state(self, initial: S) -> Self

Set the initial state for this module.

pub fn ui(self, source: impl Into<String>) -> Self

Set the Hypen DSL template as an inline string.

.ui(r#"
    Column {
        Text("Count: @{state.count}")
        Button("@actions.increment") { Text("+") }
    }
"#)

pub fn ui_file(self, path: impl Into<String>) -> Self

Load the Hypen DSL template from a file path.

The file will be read when the module is instantiated.

pub fn on_action<A>( self, name: impl Into<String>, handler: impl Fn(&mut S, A, Option<&GlobalContext>) + Send + Sync + 'static, ) -> Self

where A: DeserializeOwned + 'static,

Register an action handler with a typed payload.

The type parameter A determines how the action payload is deserialized. Use () for actions that don’t carry a payload.

Examples

// No payload — use ()
.on_action::<()>("increment", |state, _, _ctx| {
    state.count += 1;
})

// Typed payload — any Deserialize type
#[derive(Deserialize)]
struct SetValue { value: i32 }

.on_action::<SetValue>("set_value", |state, payload, _ctx| {
    state.count = payload.value;
})

// Raw JSON access
.on_action::<serde_json::Value>("raw", |state, raw, _ctx| {
    if let Some(n) = raw.as_i64() { state.count = n as i32; }
})

pub fn on_created<F>(self, handler: F) -> Self

where F: Fn(&S, Option<&GlobalContext>) + Send + Sync + 'static,

Called when the module is first mounted.

pub fn on_destroyed<F>(self, handler: F) -> Self

where F: Fn(&S, Option<&GlobalContext>) + Send + Sync + 'static,

Called when the module is destroyed/unmounted.

pub fn on_activated<F>(self, handler: F) -> Self

where F: Fn(&S, Option<&GlobalContext>) + Send + Sync + 'static,

Called every time the module becomes the active route.

Unlike on_created (which fires once per instance), on_activated fires on every mount — including when a persisted instance is restored from the [ManagedRouter] cache. Use this for “refresh on entry” work like reading the current path params.

pub fn on_deactivated<F>(self, handler: F) -> Self

where F: Fn(&S, Option<&GlobalContext>) + Send + Sync + 'static,

Called every time the module loses the active route — paired with on_activated. Fires before either on_destroyed (when not persisting) or the persist cache write.

pub fn on_error<F>(self, handler: F) -> Self

where F: Fn(&ErrorContext) -> ErrorResult + Send + Sync + 'static,

Register an error handler for this module.

pub fn on_disconnect<F>(self, handler: F) -> Self

where F: Fn(&S, &SessionInfo) + Send + Sync + 'static,

Called when the last WebSocket connection for a session drops and the session is about to be suspended. The handler receives the current state (read-only) and session information.

pub fn on_reconnect<F>(self, handler: F) -> Self

where F: Fn(&mut S, &SessionInfo, &Value) + Send + Sync + 'static,

Called when a client reconnects to a suspended session within the TTL window. The handler receives a mutable reference to the current (fresh) state, the session info, and the saved-state JSON. If the handler wants to restore the saved state, it should deserialize and write it into state; otherwise the caller will apply the saved state automatically.

pub fn on_expire<F>(self, handler: F) -> Self

where F: Fn(&SessionInfo) + Send + Sync + 'static,

Called when a suspended session’s TTL elapses without a reconnect. The module is destroyed immediately after this handler returns.

pub fn resource(self, name: impl Into<String>, svg: impl Into<String>) -> Self

Register a single SVG resource by name.

.resource("heart", r#"<svg viewBox="0 0 24 24"><path d="M20.84..."/></svg>"#)

pub fn resources(self, map: IndexMap<String, String>) -> Self

Register multiple SVG resources from a map.

pub fn resources_dir(self, path: impl AsRef<Path>) -> Self

Load SVG resources from all .svg files in a directory.

Each file becomes a resource named after its filename (without extension). For example, heart.svg → @resources.heart.

pub fn resources_file(self, path: impl AsRef<Path>) -> Self

Load SVG resources from a JSON file (name → SVG string map).

{ "heart": "<svg>...</svg>", "search": "<svg>...</svg>" }

pub fn persist(self) -> Self

pub fn build(self) -> ModuleDefinition<S>

Consume the builder and produce an immutable ModuleDefinition.