Crate xs 

cross-stream (xs) is an embeddable, local-first event stream store for event sourcing in Rust applications.

The xs binary exposes this as a CLI and an HTTP/socket API, but this crate is the library you embed directly. It was built to back a Tauri clipboard manager: one append-only stream of events, durable on disk, with live subscriptions that drive the UI.

The package is cross-stream; the crate is imported as xs:

[dependencies]
cross-stream = "0.13"

Model

• A Store is an append-only log of Frames, ordered by time-sortable scru128 Scru128Ids. It is Clone, and clones share the same underlying database, so hand copies to wherever you need them.
• A Frame is metadata: a topic, optional JSON meta, an optional content hash, and a TTL. Payload bytes live in a content-addressed store (CAS); the frame references them by hash. Small structured data can ride along in meta; larger blobs go in the CAS.
• Store::append writes a frame and broadcasts it to live readers.
• Store::read replays history and, with FollowOption::On, keeps streaming new appends as they happen.

Quick start

use xs::{Store, Frame, ReadOptions, FollowOption};

// Open (or create) a store backed by a directory on disk.
let store = Store::new("./clipboard-store".into())?;

// Write the payload to the CAS, then append a frame that references it.
let hash = store.cas_insert("hello clipboard").await?;
store.append(
    Frame::builder("clip.add")
        .hash(hash)
        .meta(serde_json::json!({ "source": "keyboard" }))
        .build(),
)?;

// Replay history, then follow live appends to drive a UI.
let mut rx = store
    .read(ReadOptions::builder().follow(FollowOption::On).build())
    .await;
while let Some(frame) = rx.recv().await {
    println!("{} {}", frame.id, frame.topic);
}

Where to look

• store is the embedding surface: Store, Frame, ReadOptions, FollowOption, TTL.
• error holds the shared Error type and the NotFound marker.
• The remaining modules (api, client, listener, processor, nu) implement the server, the client, and the scripting runtime that the xs binary is built from.

Re-exports

pub use error::Error;

pub use store::FollowOption;

pub use store::Frame;

pub use store::ReadOptions;

pub use store::Store;

pub use store::StoreError;

pub use store::TTL;

Modules

api

HTTP and unix-socket server: serve a Store over the wire.

client

Client for talking to a running xs server.

error

Shared error types: the boxed Error and NotFound. Shared error types used across the crate.

listener

Connection listeners (unix socket, TCP, TLS, iroh) used by the server.

nu

Embedded Nushell runtime used to evaluate handler and generator scripts.

processor

Background processors that run Nushell handlers against the stream.

scru128

Helpers for inspecting and constructing scru128 IDs.

store

The event stream store: the core embedding API. The event stream store.

trace

Tracing/log setup helpers.

Structs

Scru128Id

Time-sortable, 128-bit unique identifier used to order Frames.