The Dark Age of React

Tanstack Query (TSQ) is a library that will always have a soft spot in my heart. A framework agnostic tool that has the perfect level of abstraction to solve one problem - async state within a synchronous user interface.

Before TSQ, many engineers struggled with the client needing to accurately maintain a complex global state. Constant challenges included caching previous responses to avoid loading states, data being out of date, or changes made by another user not being reflected until a page refresh occurred. API responses were also commonly cached in Redux, you had to keep track of the request's execution, handle error states and retries, and more. It was a mess.

Redux Flashbacks

But what exactly is the 'client state'? TSQ shifted the landscape, revealing that many things considered 'client state' were actually 'server state.' In many cases, the true state comes from a server's oracle of truth, not a faulty client-side state machine. This simplifies the problem, because now when in doubt you can just ask the server and use the response to render something in a UI.

This realization led to TSQ's revolutionary concept: The Query. A query represents the state of an asynchronous process that yields a result, which is bound to a unique key. It includes features such as SWR caching with background refetching, loading and error states, retries, request deduplication, refetch intervals, invalidation, and more. These are all common properties of asynchronous processes, and TSQ provides a powerful abstraction to manage them. Instead of trying to manage all of the complexity yourself by manually making an API request inside of a useEffect hook, you can just use TSQ's declarative useQuery hook.

Here are some of the benefits of using a Query Manager like Tanstack Query.

TSQ: Query Caching

Every query has a unique key to identify it. This key is used to store the query in the cache, and to retrieve it when needed. Given queries are bound to a unique key, TSQ will also automatically deduplicate requests. This means that if a query is already in flight, the system will not make another request, but instead wait for the existing request to complete. This is a powerful feature that ensures the client is not making unnecessary requests to the server.

One of the powerful features of TSQ is its ability to employ a configurable "Stale While Revalidate" (SWR) strategy for query caching. This approach drastically simplified data fetching, user experience, and ensures the client is always up to date with the latest data.

What is Stale While Revalidate (SWR)?

SWR is a cache invalidation strategy that allows the client to use stale, or slightly outdated, data while simultaneously fetching the latest data from the server. This approach provides an immediate response using cached data, followed by a seamless update once the fresh data is retrieved.

Benenfits of SWR

• Caching: When a query is executed, the result is stored in the cache using it's unique key.
• Background Refetch: If the cached data is considered stale, the system starts fetching the latest data from the server in the background, ensuring that the information displayed to the user is updated as soon as the fresh data is available.
• Less Loading States: When a user requests data that's been previously fetched, the cached (possibly stale) data is immediately displayed. This ensures a responsive user experience, especially on subsequent page loads.
• Seamless Transition: Once the latest data is fetched, the UI automatically updates, replacing the stale data with the latest fresh data.

TSQ: The Best of Dynamic Typing

TSQ makes beautiful tradeoffs between type safety and ergonomics, leveraging a mix of static and dynamic typing made possible by Typescript.

Each Query has an associated key. In TSQ, all keys are arrays.

The Query Cache is just a JavaScript object, where the keys are serialized Query Keys and the values are your Query Data plus meta information.

So in Typescript terms we can use the following type to represent a Query Cache. Keep in mind these are drastically simplified for the sake of this article.

type QueryCache = Map<any[], Query>

type Query  = {
    data: any,
    // Meta information ...
}

Let's look at how this would look for an example query in React + Typescript, where we have a query that shows if a user likes a song or not.

// Query for a Track's Like Status.
const useTrackLikeQuery = (trackId: string): UseQueryResult<boolean, unknown> => {
   return useQuery({
      queryKey: trackLikeQueryKey(trackId),
      queryFn: () => getTrackLike(trackId),
   })
}

// Query Key.
const trackLikeQueryKey = (trackId: string): string[] => ['TrackLike', trackId]

// Query Fetcher.
const getTrackLike = async (trackId: string): Promise<boolean> => {
   //…
}

The Query useTrackLikeQuery returns a UseQueryResult where the data being fetched is of type boolean, and the error type is unknown (one of the tragedies of Javascript).

We can see that the query key is an array of strings, where the first element is a label 'TrackLike' to differentiate this category of queries (e.g. Track likes in the Query Cache), and the second element is the trackId. This query key function guarantees that every query will have a unique slot in the cache.

It's important to note that the Type-safety is inferred from the invocation of useQuery in useTrackLikeQuery. The cache itself, has no notion of the type of data that's being stored.

TSQ: A Common Footgun

If you somehow manage to have non-unique query keys, you can have multiple query value types for the same key, and this can lead to runtime errors.

// Query for a Track.
const useTrackQueryConflict = (trackId: string): UseQueryResult<Track, unknown> => {
   return useQuery({
      // Duplicate Query Key!
      queryKey: trackLikeQueryKey(trackId),
      queryFn: () => getTrack(trackId),
   })
}

type Track = {
    trackId: string,
    trackName: string,
    // ...
}

// Query Fetcher.
const getTrack = async (trackId: string): Promise<Track> => {
   //…
}

Note how we are using the same Query Key function trackLikeQueryKey for both useTrackLikeQuery and useTrackQueryConflict. This is a problem. If we are simultanously using useTrackLikeQuery and useTrackQueryConflict with the same trackId in our React App, we will very likely have a runtime error. This is because in one place we are expecting a boolean, and in another place we are expecting a Track object.

I want to emphasize that once you are aware of this footgun, this is NOT common in practice. It's easy to avoid by ensuring that you make your query keys unique. But it helps you understand the dynamicism of TSQ, and how it's leveraged to make the library so ergonomic.

Porting Tanstack Query to Rust

Now that we've covered how TSQ works, how can we implement an Async Query manager in Leptos, a Rust Web Framework?

The task is non-trivial, given how different Rust and JavaScript are. Rust is a compiled language known for its expressive type system with Algebraic Data Types and Traits, granular memory control, powerful macros, and concurrent programming capabilities. Meanwhile, JavaScript's interpreted, Just-in-time compiled, and dynamically-typed nature offers a simpler, practical approach to development, though it is often unsafe.

It's worth mentioning that TSQ's core implementation is framework agnostic and it provides integration wrappers for React, SolidJS, Vue, and Svelte. I don't have any such constraint, and can leverage Leptos' reactivity directly.

Comparing Leptos and React

1. Rendering and Markup: Both Leptos and React employ declarative rendering with JSX/RSX markup languages.

2. Virtual DOM vs. Reactivity: React uses a virtual DOM, follows specific rules for hooks to guarantee re-render stability. In contrast, Leptos champions fine-grained reactivity using Signals.

3. Full-Stack Development: Leptos is designed to be full-stack and isomorphic, targeting WebAssembly and supporting server-side rendering. React is primarily a front-end library, though frameworks transform it into a full-stack solution. That said, having the Leptos' backend run in Rust makes SSR magnitudes faster and more efficient than any FullStack JS Framework.

4. Maturity: React has been a standard in the JavaScript community since 2013, and Leptos is just a year old.

Dynamic Typing in Rust

Rust's type system is robust, but what if we want some of the flexibility of dynamic typing like in TSQ? Is there a way to have the best of both worlds?

Actually, yes! We can look into the std::any module, which has some neat tools for type reflection. One challenge for implementing a Query Manager in Rust is handling a lot of dynamic entries in one cache, each needing a unique Key and Value combination.

So I came up with a solution: the 'AnyMap' data structure. It's the backbone of Leptos Query, blending Rust's strong typing with the adaptability needed for today's web apps.

type AnyMap = HashMap<TypeKey, Box<dyn Any>>;

type TypeKey = (TypeId, TypeId);

struct CacheEntry<K, V>(HashMap<K, Query<K, V>>);

The outer Map is indexed by a TypeKey, which is a tuple of two TypeIds. The first TypeId is the type of the Query Key, and the second TypeId is the type of the Query Value.

This guarantees that we will always get the correct type of data from the cache, which is a huge win for safety. This approach also lets you use the same key for different value types, which is extremely convenient.

The next thing to notice, is the Box<dyn Any>. This is the magic that lets us store any type of data in the cache. The value is actually of type CacheEntry<K,V>, but we use Box<dyn Any> to store multiple instances of it in the same cache.

When we have a Box<dyn Any>, we can use the downcast functions to get the inner value. This is a runtime operation, but it's safe because we know the type of the inner value. Though there is a cost to runtime reflection and dynamic dispatch associated with Box<dyn Any> and downcasting, the developer ergonomics + safety + efficiency of caching, far outweighs the cost.

Here's the function at the core of the Query Client, showing how we extract the typed inner Map from the cache.

/// The Cache Client to store query data.
/// Exposes utility functions to manage queries.
pub struct QueryClient {
    pub(crate) cx: Scope,
    pub(crate) cache: Rc<RefCell<AnyMap>>,
}

impl QueryClient {

    /// Utility function to find or create a cache entry for the <K,V> combination, and then apply the function to it.
    fn use_or_insert_cache<K, V, R>(
        &self,
        // Function to apply to the cache entry.
        func: impl FnOnce((Scope, &mut HashMap<K, Query<K, V>>)) -> R + 'static,
    ) -> R
    where
        K: 'static,
        V: 'static,
    {
        // borrow the AnyMap!
        let mut cache = self.cache.borrow_mut();

        // Create the TypeKey.
        let type_key: TypeKey = (TypeId::of::<K>(), TypeId::of::<V>());

        // Find or create the cache entry.
        let cache: &mut Box<dyn Any> = match cache.entry(type_key) {
            Entry::Occupied(o) => o.into_mut(),
            Entry::Vacant(v) => {
                let wrapped: CacheEntry<K, V> = CacheEntry(HashMap::new());
                v.insert(Box::new(wrapped))
            }
        };

        // Downcast the cache entry to the correct type.
        let cache: &mut CacheEntry<K, V> = cache
            .downcast_mut::<CacheEntry<K, V>>()
            .expect(
                "Error: Query Cache Type Mismatch. This should not happen. Please file a bug report.",
            );

        // Call the function with the cache entry.
        func((self.cx, &mut cache.0))
    }
}

Leptos Resource - Primitive for Async Tasks

Leptos provides a Resource primitive to integrate async tasks into the synchronous reactive system.

Resources integrate with Suspense and Transition components to simplifiy the loading process and work with server side rendering. Reading the resource from within the <Suspense/> registers that resource with the <Suspense/>, and the fallback will be displayed until the resource is resolved.

Here's a Todo Example using the Resource primitive.

Let's define the following endpoint to get a Todo by ID.

use leptos::*;
use serde::*;

#[derive(Serialize, Deserialize, Clone)]
struct Todo {
    id: String,
    content: String,
}

// Don't do this in a real app! Just for demo purposes.
#[cfg(feature = "ssr")]
static GLOBAL_TODOS: RwLock<Vec<Todo>> = RwLock::new(vec![]);

type TodoResponse = Result<Option<Todo>, ServerFnError>;

#[server(GetTodo, "/api")]
async fn get_todo(id: u32) -> Result<Option<Todo>, ServerFnError> {
    // Mimic a delay.
    tokio::time::sleep(Duration::from_millis(1000)).await;
    let todos = GLOBAL_TODOS.read().unwrap();
    Ok(todos.iter().find(|t| t.id == id).cloned())
}

Now let's use the endpoint in a component. This component will fetch a Todo from the server, and display it using a Resource. If the Todo is not found, it will display "Not Found".

#[component]
fn TodoWithResource(cx: Scope) -> impl IntoView {
    let (todo_id, set_todo_id) = create_signal(cx, 0_u32);

    let todo_resource: Resource<u32, TodoResponse> = create_resource(cx, todo_id, get_todo);

    view! { cx,
        <div>
            <Suspense fallback=move || {
                view! { cx, <p>"Loading..."</p> }
            }>
                {move || {
                    todo_resource
                        .read(cx)
                        .map(|response| {
                            match response.ok().flatten() {
                                Some(todo) => todo.content,
                                None => "Not found".into(),
                            }
                        })
                }}
            </Suspense>
        </div>
    }
}

If we have Resources, why do we need Queries?

Resources don't provide any caching natively. Meaning every time we mount a component, such as our <TodoWithResource/>, we will make a network request to fetch the data.

If you want to have caching, you have to manually lift the resource into a higher scope (closer to base of component tree). And every time the key changes, the resource will be re-fetched, so there's no caching per key, only per resource.

This involves a lot of unnecessary boilerplate, and becomes very tedious if you have many resources.

Here's a simple example:

// Root component for our Leptos Appo
#[component]
fn App(cx: Scope) -> impl IntoView {
    let (todo_id, set_todo_id) = create_signal(cx, 0_u32);
    // Store the resource in a higher scope's context.
    let todo: Resource<u32, TodoResponse> = create_resource(cx, todo_id, get_todo);
    provide_context(cx, todo):

    view!{cx,
        <TodoComponent/>
    }
}

#[component]
fn TodoComponent(cx: Scope) -> impl IntoView {
    let todo_resource: Resource<u32, TodoResponse> = use_context(cx).expect("No Todo Resource Found!");

    view! {cx,
        <div>
            <Suspense fallback=move || {
                view! { cx, <p>"Loading..."</p> }
            }>
                {move || {
                        todo_resource
                        .read(cx)
                        .map(|response| {
                            match response.ok().flatten() {
                                Some(todo) => todo.content,
                                None => "Not found".into(),
                            }
                        })
                }}
            </Suspense>
        </div>
    }
}

Leptos Query

Leptos Query uses Resources internally to be compatible with SSR and Suspense, provides a simpler API, SWR caching and many other niceties out of the box.

Here's an example. We are storing a CacheEntry of <u32, TodoResponse> in the QueryClient's cache.

Given the response will be stored in the cache on a key u32 basis (the todo_id), any subsequent loads for a specific todo will not involved any foreground loading, and will be served from the cache. If the query is considered stale, the query will be re-fetched in the background, and the UI will be updated with the new reponse after it finalizes. Stale time is configurable using QueryOptions.

use leptos_query::*;

#[component]
fn TodoComponentWithQuery(cx: Scope) -> impl IntoView {
    let (todo_id, set_todo_id) = create_signal(cx, 0_u32);

    let QueryResult { data, .. } = leptos_query::use_query(cx, todo_id, get_todo, QueryOptions::default());

    view! {cx,
        <Suspense
            fallback=move || view! { cx, <p>"Loading..."</p> }
        >
            <h2>"Todo"</h2>
            {move || {
                data.get()
                    .map(|a| {
                        match a.ok().flatten() {
                            Some(todo) => todo.content,
                            None => "Not found".into(),
                        }
                    })
            }}
        </Suspense>

    }
}

QueryClient: Interacting with Query Cache directly

The QueryClient lets you interact with the query cache to invalidate queries, observe queries, and make optimistic updates.

Let's beef up our Todo Example a bit.

1. We will add an endpoint and component to load all the todos.
2. Add a form to create a new todo.
3. Add an input to load a specific todo by id.

Starting with the server endpoints.

// Get all todos
#[server(GetTodos, "/api")]
pub async fn get_todos() -> Result<Vec<Todo>, ServerFnError> {
    tokio::time::sleep(Duration::from_millis(1000)).await;
    let todos = GLOBAL_TODOS.read().unwrap();
    Ok(todos.clone())
}

// Add a todo.
#[server(AddTodo, "/api")]
pub async fn add_todo(content: String) -> Result<Todo, ServerFnError> {
    let mut todos = GLOBAL_TODOS.write().unwrap();

    let new_id = todos.last().map(|t| t.id + 1).unwrap_or(0);

    let new_todo = Todo {
        id: new_id as u32,
        content,
    };

    todos.push(new_todo.clone());

    Ok(new_todo)
}

Now let's make a component to load all the todos.

#[component]
fn AllTodos(cx: Scope) -> impl IntoView {
    let QueryResult { data, .. } = use_query(
        cx,
        || (),
        |_| async move { get_todos().await.unwrap_or_default() },
        QueryOptions::default(),
    );

    let todos: Signal<Vec<Todo>> = Signal::derive(cx, move || data.get().unwrap_or_default());

    view! { cx,
        <h2>"All Todos"</h2>
        <Suspense fallback=move || {
            view! { cx, <p>"Loading..."</p> }
        }>
            <ul>
                <Show
                    when=move || !todos.get().is_empty()
                    fallback=|cx| {
                        view! { cx, <p>"No todos"</p> }
                    }
                >
                    <For
                        each=todos
                        key=|todo| todo.id
                        view=move |cx, todo| {
                            view! { cx,
                                <li>
                                    <span>{todo.id}</span>
                                    <span>" "</span>
                                    <span>{todo.content}</span>
                                </li>
                            }
                        }
                    />
                </Show>
            </ul>
        </Suspense>
    }
}

And another component for creating a Todo. Note how we're watching the response of the add_todo action. When the response is successful, we invalidate the query cache for the TodoResponse and Vec<Todo> queries. This will cause any active queries to immediately refetch in the background, updating the cache and the UI.

#[component]
fn AddTodo(cx: Scope) -> impl IntoView {
    let add_todo = create_server_action::<AddTodo>(cx);

    let response = add_todo.value();

    let client = use_query_client(cx);

    create_effect(cx, move |_| {
        // If action is successful.
        if let Some(Ok(todo)) = response.get() {
            let id = todo.id;
            // Invalidate individual TodoResponse.
            client.clone().invalidate_query::<u32, TodoResponse>(id);

            // Invalidate AllTodos.
            client.clone().invalidate_query::<(), Vec<Todo>>(());
        }
    });

    view! { cx,
        <ActionForm action=add_todo>
            <label>"Add a Todo " <input type="text" name="content"/></label>
            <input type="submit" autocomplete="off" value="Add"/>
        </ActionForm>
    }
}

Here's a demo.

Note how two request are initiatied as soon as a Todo is created. One for the TodoResponse and one for the Vec<Todo>. Each of those responses then take a second to complete, and then you get the updated query.

Todo Invalidation Demo

If you really want the maximum speed, you can perform an optimistic update like this, which will immediately update the entry in the cache, and then refetch in the background (confirming the change with the server).

    create_effect(cx, move |_| {
        // If action is successful.
        if let Some(Ok(todo)) = response.get() {
            let id = todo.id;
            // Invalidate individual TodoResponse.
            client.clone().invalidate_query::<u32, TodoResponse>(id);

            // Invalidate AllTodos.
            client.clone().invalidate_query::<(), Vec<Todo>>(());

            // Optimistic update.
            let as_response = Ok(Some(todo));
            client.set_query_data::<u32, TodoResponse>(id, move |_| Some(as_response));
        }
    });

Optimistic Update Demo

It's imporatant to recognize how much legwork you'd have to do to get this behavior without a library like Leptos Query. You'd have to manually manage the cache, and refetch queries.

If you're curious and want to play around with it more, just checkout the example project

Invalidating Multiple Queries

You can invalidate groups of related queries by using QueryClient::invalidate_query_type.

let client = use_query_client(cx);
// Invalidates all queries of type `TodoResponse`, where key is `u32`.
client.invalidate_query_type::<u32, TodoResponse>();

// The queries below will be invalidated.
use_query(cx, || 1, get_todo, QueryOptions::default());
use_query(cx, || 2, get_todo, QueryOptions::default());

And you can also invalidate every query in the cache using QueryClient::invalidate_all_queries.

let client = use_query_client(cx);

client.invalidate_all_queries();

This mimics the behavior of the invalidateQueries method in TSQ. It would use the label of the first entry in the Key Array.

let client = useQueryClient();

// Invalidate every query in the cache.
client.invalidateQueries()
// Invalidate every query with a key that starts with `todo`
client.invalidateQueries({ queryKey: ['todo'] })

Thanks for Reading

Leptos Query is a powerful addition to the Leptos framework, providing a sleek way to manage asynchronous queries. By handling complexities like configurable SWR, background refetching, and query invalidation, it offers a streamlined developer experience that leans on the safety of strong typing and the flexibility of dynamic typing.

As I first sported the mustache, hesitation seeped in. Can I pull it off? Do I really look my best? Donning a mustache goes beyond aesthetics. It required embracing this audacious accessory, adjusting to its weight, and confronting the shift in my reflection.

A mustache is your silent spokesman. The world sees it before they see you. It precedes you into rooms, forging first impressions before a single word is said. Every strand a mute syllable, composing and projecting an implicit language that is distinctively yours.

A mustache is a cry for revolution complying with an office chair. In the stark world of sleek corporate professionalism, where conformity is often a requisite, a mustache dares to deviate. This unassuming sliver of hair carries the weight of an unspoken oath — a conduit to subvert the status quo.

A mustache is a bold statement perched on the brink of tomorrow. It lives at the mercy of your razor. This transient nature of the mustache, so subject to the whims of your desire, calls for an ironclad pledge. It is a delicate dance with the fleeting nature of existence, day after day.

But above all, a mustache is an absurdity. A dash of comedy inked onto the face. How many of history’s stars, from Einstein to Mercury to Nietzsche, have walked an exaggerated life through the underlined humor of a mustache? Even in its seriousness, it beckons laughter. Therein lies its paradoxical charm, the seduction of the mustache.

It wields power to instigate change, yet never takes itself too seriously.

And well it's gone by quickly. I looked at my NextJS personal website and felt compelled to "Rewrite it in Rust", which you're now visiting.

And so I got my hands dirty with the Leptos Web Framework, which we'll get into later.

There's a lot cover so let's get into it.

What I Like About Rust (so far...)

• Expression Based Thinking
• Zero Cost Abstractions
• Mutation in the Type System
• Errors as Values
• I wanna go fast

Expression based thinking

Understanding Expressions Vs. Statements

Diving into the mechanics of Rust, one of the first things you'll notice is its strong emphasis on expressions rather than statements, a clear distinction from many other languages. But what exactly does that mean, and why should you care?

Expressions are best likened to LEGO blocks. Each piece, or in this case, a chunk of code, has its own unique value. Just as LEGO blocks come together to create a spaceship, castle, or whatever your imagination desires, expressions combine and interact to form more complex values.

Conversely, statements could be seen as the action of placing a LEGO block in a specific spot. It's a crucial action to build your model, but it doesn't constitute a structure on its own. In code, statements perform an action like assigning a value or printing a message, but they don't yield a value in themselves.

Expression Orientation in Java Vs. Rust

To put this into perspective, let's take a look at Java. In Java, 'if' statements are, well, just statements. Here's an example:

public void statements() {
    int x = null;
    if (true) {
        x = 3;
    } else {
        x = 10;
    }
    System.out.println(x);
}

In this code snippet, the 'if' statement modifies the state of a variable based on a condition but does not produce any value in and of itself. The value is then printed to the console, which also doesn't produce any value.

Now, let's pivot to Rust, an expression-oriented language. Most constructs in Rust - excluding declarations - such as blocks, ifs, matches, loops, and functions, are expressions.

If expressions behave like ternary operators in other languages. Meaning, they evalate to the value of the executed branch.

let x: i32 = if true { 3 } else { 10 };

Block expressions establish new scopes and evaluate to the last expression in the block. This lets you create clear demarcations without the need for helper functions:

let x = 0;
let y: i32 = {
    // This variable 'x' shadows and takes precedence over the outer 'x'.
    let x = 3;
    x + 1
};
assert_eq!(y, 4);

If the last expression in a block ends with a semicolon, it will evaluate to Unit (()):

let unit_block: () = {
    let number = 0;
    println!("The number is {}", number);
    number;
};

Loop expressions yield the value they 'break' with.

let z: i32 = {
    let mut i = 0;
    loop {
        i += 1;
        if i == 10 {
            break 42;
        }
    }
};

Functions evaluate to a resultant value. If the return keyword is ommitted - the last expression in a function is the return value.

// Implicit return.
fn add_one(x: i32) -> i32 {
    x + 1
}

Here's a function that combines many different type of expressions to calculate the value of a wallet:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

enum Bill {
    Washington,
    Jefferson { year: u32 },
    Lincoln,
    Hamilton,
    Jackson,
    Benjy,
}

struct Wallet {
    coins: Vec<Coin>,
    bills: Vec<Bill>,
}

// Return value in of wallet in cents.
fn wallet_value(wallet: &Wallet) -> u32 {
    let cents = {
        let mut cents = 0;
        for coin in wallet.coins.iter() {
            cents += match coin {
                Coin::Penny => 1,
                Coin::Nickel => 5,
                Coin::Dime => 10,
                Coin::Quarter => 25,
            }
        }
        cents
    };

    let dollars: u32 = wallet
        .bills
        .iter()
        .map(|bill| match bill {
            Bill::Washington => 1,
            Bill::Jefferson { year } => {
                // This is a rare bill!
                if *year < 1900 {
                    100
                } else {
                    2
                }
            }
            Bill::Lincoln => 5,
            Bill::Hamilton => 10,
            Bill::Jackson => 20,
            Bill::Benjy => 100,
        })
        .sum();

    cents + dollars * 100
}

See how composable these expressions are? wallet_value combines blocks, matches, an if expression, an iterator sum, and a for loop, to calculate the value. You can "follow" each branch neatly to see the sequential flow of the program.

Rust's emphasis on expressions over statements is akin to valuing the whole LEGO model over the single step of placing a block. It's this philosophy that contributes to Rust's expressiveness and ergonomics, making it a powerful tool for developers.

Zero Cost Abstractions

In Rust, most abstractions come with no runtime costs regarding execution speed or memory usage.

One shining example of this is the Iterator trait. Rust allows you to chain together multiple iterator methods to perform intricate transformations on data. Even with such high-level abstraction, the resultant code often matches, or even outperforms, the efficiency of manually written, low-level code.

let squares_of_evens: Vec<i32> = {
    (1..)
        .map(|x| x * x)
        .filter(|&x| x % 2 == 0)
        .take(10)
        .collect()
};

Even with its high-level nature, this code matches the performance of a manually written loop

let mut squares_of_evens = Vec::new();
for i in 1.. {
    let square = i * i;
    if square % 2 == 0 {
        squares_of_evens.push(square);
        if squares_of_evens.len() == 10 {
            break;
        }
    }
}

"Virtual-Free" Rust

A typical object-oriented programming concept is the "virtual table" (or vtable), a mechanism employed to support dynamic dispatch. It's how languages like JavaScript, Python, Java, and Scala handle method calls, deciding at runtime which specific version of a method to execute based on the object's actual type.

In contrast, Rust embraces a more efficient approach, sidestepping the need for vtables. It does this through static dispatch, resolving method calls at compile time, instead of waiting until runtime. This leads to faster, more memory-efficient code, as we're not paying the runtime cost of dynamically dispatching method calls.

Take the concept of "virtual methods" in Java using interfaces, for example. These are methods declared in an interface and subsequently implemented by any class using this interface. For instance, if you have an interface, Animal, with a method sound(), and classes Dog and Cat implementing this interface, you are using virtual methods.

public interface Animal {
    void sound();
}

public class Dog implements Animal {
    @Override
    public void sound() {
        System.out.println("Woof!");
    }
}

public class Cat implements Animal {
    @Override
    public void sound() {
        System.out.println("Meow!");
    }
}

public class Main {
    public static void main(String[] args) {
        Animal myDog = new Dog();
        Animal myCat = new Cat();

        myDog.sound(); // Prints "Woof!"
        myCat.sound(); // Prints "Meow!"
    }
}

When you call sound() on an Animal instance, the JVM uses a vtable to determine which version of the method to execute, based on the actual type of the object.

A vtable is essentially an array created by the JVM in memory for each class implementing an interface. Each array entry is a pointer to a method callable by an object of the class. The JVM uses this array to look up method addresses at runtime.

The vtable for our Animal interface might look something like this:

So, when we create a Dog object and call myDog.sound(), the JVM does the following:

1. It accesses the Dog object's vtable in memory.
2. It locates the sound() entry in the vtable and retrieves the corresponding pointer.
3. It uses this pointer to navigate to the memory address where the Dog.sound() method is stored.
4. Finally, it executes the method.

This process involves dereferencing pointers and introduces a runtime cost due to the extra steps needed to decide which method to execute.

In contrast, Rust sidesteps this process. It accomplishes polymorphism through the use of traits and type parameters, thus avoiding the need for a vtable and the accompanying dynamic dispatch. This concept is a cornerstone of what's known as "zero-cost abstractions" in Rust - writing high-level, readable code without the performance penalties commonly associated with such abstractions in other languages.

Mutation in the Type System

Rust's type system embraces mutation as a first-class citizen.

For one, you have to declare variables as mutable with the mut keyword. This code would yield a helpful error, showing an illegal attempt to mutate a Vec that has not been declared as mutable.

let list = vec![1, 2, 3];
list.push(4);

error[E0596]: cannot borrow `list` as mutable, as it is not declared as mutable
--> <SOURCE POSITION>
|
52 |     list.push(4);
|     ^^^^^^^^^^^^ cannot borrow as mutable
|
help: consider changing this to be mutable
|
51 |     let mut list = vec![1, 2, 3];
|         +++

Now when it comes to variables, For some type T you have:

• T: You are the owner of the data.
• &mut T: You have EXCLUSIVE write access to the data.
• & T: You have SHARED read access to the data.

Consider a simple function in Rust that increments a count:

 fn increment_count(count: &mut i32) {
     let value = *count;
     *count = value + 1;
 }

 #[test]
 fn test_inc_count() {
     let mut count = 0;
     let count_ref = &mut count;
     increment_count(count_ref);
     assert_eq!(count, 1)
 }

In this example, the increment_count function takes a mutable reference to an integer (&mut i32). The mutable reference denotes that count can be modified within the function.

Rust forces you to indicate that a reference is mutable when you declare it. This applies to structs, enums, and function parameters. This explicitness provides a lot of safety, and forced documentation.

Fine control over mutability is something that Rust shares with functional languages like Scala. We can draw parallels to a similar function in Scala using a ZIO Ref, a concurrent mutable reference:

 object TestSpec extends ZIOSpecDefault:
     def incrementCount(countRef: Ref[Int]): UIO[Unit] =
         for
             value <- countRef.get
             _     <- countRef.set(value + 1)
         yield ()

     def spec = suite("incrementCount") {
         test("incrementCount should increment the value of the ref by 1") {
             for
                 ref   <- Ref.make(0)
                 _     <- incrementCount(ref)
                 value <- ref.get
             yield assertTrue(value == 1)
         }
     }

In the Scala example, incrementCount is an atomic operation using a ZIO Ref. A Ref allows for safe mutation in a concurrent context. Similiarly to the mut keyword in Rust, when you see the Ref type, it indicates that mutation is bound to take place in the given scope.

Though Rust and Scala have different idioms and philosophies, both provide robust ways to control mutation and ensure safety.

A Ref's concurrent counterpart in Rust would look something like

type Ref<T> = Arc<RwLock<T>>

Errors as Values

When it comes to handling errors, Rust employs an intriguing and unique approach: it treats errors as values, rather than as control flow primitives. This paradigm is inspired by functional programming languages and leverages Rust's robust algebraic data types (ADTs) to create a powerful error handling system.

In many other programming languages such as Java, Python, and C++, errors are usually dealt with exceptions. An exception is a special kind of object created and thrown when an error occurs, effectively interrupting the normal flow of a program. Control is then transferred to the nearest exception handler in the call stack, which is designed to address the specific error.

Rust, on the other hand, opts for a different approach, treating errors as ordinary data that can be returned by functions and passed around. This approach is centered around the use of ADTs, specifically enums, to model potential error states.

There are two primary types used for error handling in Rust:

• Option<T>
  • A value that can exist (Some) or is missing (None)
  • Akin to a type-safe null

enum Option<T> {
    Some(T),
    None,
}

// Find the index of the word in the Vec.
fn find_word(words: Vec<&str>, target: &str) -> Option<usize> {
    words.iter().enumerate().find_map(
        |(index, &word)| {
            if word == target {
                Some(index)
            } else {
                None
            }
        },
    )
}

#[test]
fn find_word_find_cherry() {
    let words = vec!["apple", "banana", "cherry", "date"];

    let result = find_word(words, "cherry");

    assert_eq!(result, Some(2));
}

• Result<T, E>:
  • The result of a computation that may fail.
  • It can either be Ok(T) if the computation was successful, or Err(E) if it failed. E will contain information about what went wrong.

enum Result<E, T> {
    Ok(T)
    Err(E)
}

fn divide(numerator: f64, denominator: f64) -> Result<f64, String> {
    if denominator == 0.0 {
        Err("Cannot divide by zero".to_string())
    } else {
        Ok(numerator / denominator)
    }
}

#[test]
fn cannot_divide_by_zero() {
    let result = divide(5.0, 0.0);

    assert_eq!(result, Err("Cannot divide by zero".to_string()));
}

A key point of this design choice is to make error handling more explicit and deliberate. Unlike exception-based systems, where it can be easy to overlook handling for an error, the Rust compiler enforces the handling of Result and Option types. Note how their implementation is completely transparent, and requires no custom compiler machinery implement thanks to zero-cost abstractions. This enables programmers to model other expressive error types, such as Inclusive-Or errors, with the same efficiency as Error types in the standard library.

By using ADTs and pattern matching, Rust effectively turns error handling from a control flow problem into a data modeling problem.

Performance of Error Handling

When we consider the performance implications of this design, Rust's Errors as Values approach also provides a noticeable advantage. Exception handling in traditional languages incurs a non-trivial runtime cost. When an exception is thrown, the runtime environment needs to unwind the stack until it finds a suitable exception handler.

In contrast, Rust's approach to handling errors incurs minimal performance penalty. This is because there's no need for stack unwinding or searching for exception handlers. Errors are returned just like any other value, and error handling is done via pattern matching, a compile-time mechanism. The "happy path" and the "error path" are treated uniformly in terms of performance.

• Happy path: optimal, error-free, successful execution of a program.

• Error path: execution of a program that encounters an error/exception.

Meaning that when Result is evaluated, the code has an additional check on the discriminant of Result to determine whether it is Ok or Err before continuing.

A caveat is that if exceptions are truly used properly - only for truly exceptional circumstances - then the happy path will not incur any performance penalty. However, this is rarely the case in practice.

So if you have a program that uses exceptions, and the exceptions rarely occur, then exceptions are being put to good use. However, if exceptions are being thrown frequently, then your program could suffer an enormous performance penalty, which Rust opts to avoid.

TLDR: exceptions may allow the happy path to be faster, but at the expense of performance on the error path. There's no free lunch.

Hidden control flow

An understated advantage of Errors as Values over exceptions is predictability and the absence of "hidden" control flow paths. Exceptions can be thrown at many points in a program (and in some languages any value can be thrown), and it can be non-obvious where they should be handled. On the other hand, functions in Rust that can fail have their error types explicitly defined in their signatures, making it clear what errors need to be handled.

I wanna go fast

anyone else?

So we've all heard that Rust is fast, here are some of the reasons why.

Zero-Cost Abstractions

The cornerstone of Rust's performance lies in its mantra of "zero-cost abstractions." The concept is simple: abstractions, which allow us to write clear and concise code, should not come at the cost of runtime performance.

Ownership and Borrowing: The Ultimate Garbage Collector

Garbage collection (GC) is a double-edged sword. On the one hand, it frees developers from manual memory management, preventing a whole class of bugs. On the other hand, GC comes with an overhead, and can introduce unpredictable pauses in a running program.

Rust's unique system of ownership and borrowing eliminates the need for a garbage collector altogether, while still providing the safety guarantees that a GC would. With Rust, memory is managed through a system of ownership with a set of rules that the compiler checks at compile-time. No garbage collector is needed.

By default, objects are stack-allocated, which generally is more efficient than heap allocation. However, Rust also allows explicit heap allocation using constructs like Box. This fine-grained control over memory management allows Rust programs to be incredibly efficient, minimizing runtime overhead and maximizing speed.

Lightweight Concurrency with Async/Await and Tokio

Multithreading and concurrency are critical for modern applications, but managing threads safely is notoriously difficult. Rust's async/await syntax and the Tokio runtime bring the benefits of asynchronous programming to Rust without the usual pitfalls.

Async/await in Rust is a zero-cost abstraction. Unlike in other languages, where async/await can add significant overhead, in Rust the generated code is as efficient as hand-written state machines.

The Tokio runtime further enhances Rust's concurrency story. It's a non-blocking I/O platform for writing asynchronous applications, with a focus on simplicity, speed, and reliability. Tokio makes use of core threads and blocking threads.

As per the docs:

Tokio provides two kinds of threads: Core threads and blocking threads

The core threads are where all asynchronous code runs, and Tokio will by default spawn one for each CPU core

The blocking threads are spawned on demand, can be used to run blocking code that would otherwise block other tasks from running

Together, async/await and Tokio make it possible to write high-performance concurrent code that is still safe and easy to understand.

Power of Optimized Builds

In Rust, you typically develop in "debug" mode, where the compiler prioritizes compilation speed and debug information. However, when you're ready to release your application, you switch to "release" mode, where the compiler takes more time to apply optimizations that make your code run faster.

The difference between the two can be astonishing. Optimized --release builds are often 10 to 100 times faster than debug builds.

Oxidation underway

Like a metal refined by the elements, my journey into Rust has ignited a transformative process. Exploring the realms of Rust's expression-based thinking, zero-cost abstractions, and the empowering mutation in its type system has deepened my understanding of how computers and programs truly operate. Rust has been designed in face of past grievances (e.g. C, C++, Java) and future challenges.

I'm sure I'll write some on Rust's downsides, and want to share my experience building this website using the Leptos Web Framework. See ya then.