Crate tears 

Tears - TUI Elm Architecture Runtime System

Tears is a TUI (Text User Interface) framework based on the Elm Architecture (TEA), built on top of ratatui. It provides a clean and type-safe way to build terminal applications using a functional, message-driven architecture.

Architecture

The framework follows the Elm Architecture pattern:

1. Model: Your application state
2. Message: Events that can change the state
3. Update: Function that processes messages and updates the model
4. View: Function that renders the UI based on the current model
5. Subscriptions: External event sources (keyboard, timers, etc.)
6. Commands: Asynchronous operations and runtime directives

Core Components

• application::Application: The main trait that defines your application
• runtime::Runtime: Manages the application lifecycle and event loop
• command::Command: Represents asynchronous side effects and runtime directives
• subscription::Subscription: Represents ongoing event sources
• install_panic_hook: Restores the terminal if the application panics

Example

use ratatui::Frame;
use tears::prelude::*;

#[derive(Debug)]
enum Message { Increment }

struct Counter { count: u32 }

impl Application for Counter {
    type Message = Message;
    type Flags = ();

    fn new(_flags: ()) -> (Self, Command<Message>) {
        (Counter { count: 0 }, Command::none())
    }

    fn update(&mut self, msg: Message) -> Command<Message> {
        match msg {
            Message::Increment => {
                self.count += 1;
                Command::none()
            }
        }
    }

    fn view(&self, frame: &mut Frame<'_>) {
        // Render UI
    }

    fn subscriptions(&self) -> Vec<Subscription<Message>> {
        vec![]
    }
}

Observability

The runtime emits tracing events for its hot paths — message batches, subscription updates, command spawns, renders, and shutdown — under the tears::runtime and tears::subscription targets. Events are inert unless a tracing subscriber is installed, so there is no setup required to ignore them. To see them, install any subscriber (e.g. tracing_subscriber::fmt()) before running the app.

Optional Features

WebSocket Support

[dependencies]
tears = { version = "0.9", features = ["ws", "native-tls"] }

Enables subscription::websocket::WebSocket. Requires a TLS feature for wss://: native-tls, rustls, or rustls-tls-webpki-roots.

HTTP Support

[dependencies]
tears = { version = "0.9", features = ["http"] }

Enables subscription::http with Query and Mutation support.

Re-exports

pub use application::Application;

pub use command::Action;

pub use command::Command;

pub use panic::install_panic_hook;

pub use runtime::Runtime;

pub use subscription::Subscription;

pub use subscription::SubscriptionId;

pub use subscription::SubscriptionSource;

Modules

application

Application trait and core types.

command

Commands for performing asynchronous side effects and returning runtime directives.

panic

Panic handling helpers for restoring the terminal on unwind.

prelude

Prelude module for convenient imports.

runtime

Runtime for executing TUI applications.

subscription

Subscriptions for handling ongoing event sources.

Structs

FrameRate

Target frames per second for Runtime.

Enums

FrameRateError

Error returned when constructing an invalid FrameRate.

Type Aliases

BoxStream

An owned dynamically typed Stream for use in cases where you can’t statically type your result or need to add some indirection.