Reactive isomorphic rust web framework.
Work in progress, this is still a naive early prototype.
Comet is a framework for the web build with Rust+Wasm<3. It takes its inspiration from MeteorJS, Seed-rs, Yew and others.
This crate aims to be an all-in-one all-inclusive battery-included isomorphic reactive framework.
- You keep saying 'Isomorphic', but why ?
In this context, Isomorphic means that you only write one program for both client and server.
One crate. One. For both. Yes.
This means that we rely a lot on macros and code generation, with all the good and the bad this could bring,
but it allows for a great deal of features, close to no boilerplate, and a little quality of life improvement on different aspects.
- Ok, and how is it reactive then ?
It is reactive in many sense, first by its component system, that encapsulate little bits of logic into an HTML templating system,
and which can bind your struct's methods directly to JS events, triggering a render of only the components that changed.
There is also a reactive layer on top of a PostgreSQL database, that permits to watch for some queries to change over time and
to send push notifications over websocket to every client watching for thoses change, triggering a render when needed.
Visit the examples folder.
bash
$> cargo install --git https://github.com/Champii/Comet --locked
You will need to install and run an instance of PostgreSQL.
If not found on your system, Comet will install these following crates using cargo install on the first run:
- wasm-pack
- diesel-cli
bash
$> comet new my_counter && cd my_counter
This newly generated project contains all you need to get started. Your journey starts with src/main.rs.
Conveniently, this generated file is already the simpliest incrementing counter you can think of:
``rust
// This macro takes two arguments:
// - A type for which we will implementComponent
// - And a root HTML element
// We implementComponent` for a simple integer.
component! {
// We use an i32 here, but you can use any stucts/enums/custom type
i32,
// The root of this HTML element is a simple button
// It has a 'click' event registered that will increment our i32 by 1
button @click: { *self += 1 } {
// We display our value inside the button
{ self }
}
}
// This is where all the magic happens // We run the application with an instance of our i32 component that starts with the value 0 comet::run!(0); ```
Setup your database address as an env variable
/!\ Warning: This database will be COMPLETELY WIPED at startup and everytime your models change
This is not ideal but, hey ! This is still a work in progress :p
bash
$> export DATABASE_URL="postgres://your_user:your_password@localhost/your_db"
Actually run your project
bash
$> comet run
This will download and install the tools it needs to build and run your crate.
bash
[✓] Installing wasm-pack
[✓] Installing diesel-cli
[✓] Diesel setup
[✓] Migrating database
[✓] Patching schema
[✓] Building client
[✓] Building server
[✓] Running
-> Listening on 0.0.0.0:8080
Then go go to http://localhost:8080
input fields that react to events```rust struct MyStruct { myvalue: String, myheight: u32, }
component! { MyStruct, // Here #myid defined the id, // and the dot .class1 and .class2 add some classes to the element // The #id must always preceed the classes, if any div #myid.class1.class2 { span { // You can access your context anywhere { self.myvalue } } // Define style properties div [height: { self.myheight }}] { { "Another child" } } } };
```
```rust
struct MyComponent {
show: bool,
value: HashMap
component! { MyComponent, div { div { // Conditional rendering with if // The parenthesis are necessary if (self.show) { { "Visible !" } } button @click: { self.show = !self.show } { { "Toggle" } } } div { // Use a for-like loop. // The parenthesis are necessary around the last part for key, value in (self.value) { div { { key } { value } } } button @click: { self.value.push(42) } { { "Add a number" } } } } } ```
input fields that react to eventsThis is exclusive to input fields for now
The whole component is re-rendered on input's blur event (unfocus).
Each binding should be unique, as in a different variable for each one
```rust struct MyStruct { value: String, }
component! { MyStruct, div { input ={ self.value } {} { self.value } } } ```
```rust struct Child { value: String, }
component! { Child, div { { self.value } } }
struct Parent {
// You need to wrap your components with a Shared
component! { Parent, div { // To include a component, you must wrap it inside a @{ } @{ self.child } } } ```
All the previous examples until now were client-side only. Its time to introduce some persistance.
Deriving with the #[model] macro gives you access to many default DB methods implemented for your types:
- async Self::fetch(i32) -> Result<T, String>;
- async Self::list() -> Result<Vec<T>, String>;
- async self.save() -> Result<(), String>;
- async Self::delete(i32) -> Result<(), String>;
The String error type is meant to change into a real error type soon.
You have a way to add your own database query methods, please read Database queries below.
``rust
// You just have to add this little attribute to your type et voila !
// It will add a fieldid: i32` to the struct, for database storing purpose
// Also, when adding/changing a field to this struct, the db will
// automatically update its schema and generate new diesel bindings
struct Todo { title: String, completed: bool, }
impl Todo { pub async fn toggle(&mut self) { self.completed = !self.completed;
// This will save the model in the db
self.save().await;
}
}
component! { Todo, div { p { { self.id } { self.title } { self.completed } button @click: { self.toggle().await } { { "Toggle" } } } } }
// This will create a new Todo in db every time this program runs comet::run!(Todo::default().create().await.unwrap()); ```
Note: The structs involved in the #[rpc] macro MUST be accessible from the root module (i.e. src/main.rs)
``rust
// If you have other mods that use#[rpc]`, you have to import them explicitly
// in the root (assuming this file is the root). This is a limitation that will not last, hopefully
mod othermod;
use othermod::OtherComponent;
pub struct Counter { pub count: i32, }
// This attribute indicate that all the following methods are to be treated as RPC // These special methods are only executed server side
impl Counter { // The RPC methods MUST be async (at least for now) pub async fn remote_increment(&mut self) { self.count += 1;
self.save().await;
}
}
component! { Counter, button @click: { self.remote_increment().await } { { self.count } } }
comet::run!(Counter::default().create().await.unwrap()); ```
When dealing with Database queries, it is obvious that they should only be executed server side.
The most simple way to define a new one is with the macro #[sql], that uses #[rpc] underneath.
All your models have been augmented with auto-generated diesel bindings, so you can use a familiar syntax. There will be a way to give raw SQL in the near future.
```rust
pub struct Todo { pub title: String, pub completed: bool, }
impl Todo {
pub async fn dbgetall(limit: u16) -> Vec
// You don't have to actually execute the query, all the machinery
// of creating a db connection and feeding it everywhere have been
// abstracted away so you can concentrate on what matters
todos::table.select(todos::all_columns).limit(limit as i64)
}
} ```
Soon there will also be a #[watch] attribute that will trigger the reactive redraw when your model change
Allow for real time value binding for input element without losing focus (might need a real virtual dom for this one)
Separate all the reusable features in different crates: