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: The main trait that defines your application
• Runtime: Manages the application lifecycle and event loop
• Command: Represents asynchronous side effects and runtime directives
• 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.

Modules

command

Commands for performing asynchronous side effects and returning runtime directives.

prelude

Prelude module for convenient imports.

subscription

Subscriptions for handling ongoing event sources.

testing

Deterministic testing support for Applications.

Structs

Command

A command that can be executed to perform side effects and carry runtime directives.

FrameRate

Target frames per second for Runtime.

Runtime

Runtime that schedules and executes TUI application operations.

RuntimeConfig

Construction-time configuration for the runtime: the frame rate and the opt-in load controls (RFC 0006).

Subscription

A subscription represents an ongoing source of messages.

SubscriptionId

A unique identifier for a subscription.

Enums

FrameRateError

Error returned when constructing an invalid FrameRate.

Traits

Application

The main trait for defining TUI applications following The Elm Architecture.

SubscriptionSource

Trait for types that can be used as subscription sources.

Functions

install_panic_hook

Installs a panic hook that restores the terminal before delegating to the previously installed hook.

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.