
Learning how to code in [Rust](https://www.rust-lang.org/) can feel like a daunting task. While it is a very powerful language it is not precisely known for being a simple language.

The same concepts that make Rust such a great language are the same that may cause problems for newcomers: [ownership](https://doc.rust-lang.org/book/ch04-00-understanding-ownership.html), [lifetimes](https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html), among others.

It is not that these concepts are inherently difficult, it's just that they provide safety checks that other languages don't; these safety checks can become an obstacle to people who is familiar with other, more forgiving, languages.

This is why, when someone is writing their first lines of Rust and tries to do simple tasks like passing an object to a function, the compiler will stop them with errors.

Rust compiler relies heavily on static code analysis to find memory errors. While other languages like C or Java allow developers to write code that may result in undesired states (e.g. `NullPointerException` and stack overflows) -which then need to be handled during runtime with error handling and exceptions-, Rust will not allow such code to compile.

In this post, we will focus on common problems that any beginner will find when they start their journey into the world of Rust.

## Trying to modify immutable variables

In the following example, we create an instance of a `struct` called `Book`, and we try to assign a different value to its `title` property:

```rust
struct Book {
    title: String
}

fn main() {
    let book = Book {
        title: String::from("The Rust Programming Language")
    };

    book.title = String::from("Another book")
}
```

If we try to compile this code, we will get the following error:

```bash
error[E0594]: cannot assign to `book.title`, as `book` is not declared as mutable
```

### Solution

This first problem is easy to spot. By default, all Rust variables are declared as immutable (read-only/constant). The goal of this decision is for developers to be explicit when they expect a variable to change values.

If we want to make `book` mutable, we must declare it as `rust^let mut book`:

```rust
struct Book {
    title: String
}

fn main() {
    let mut book = Book {
        title: String::from("The Rust Programming Language")
    };

    book.title = String::from("Another book")
}
```

Another flavor of this same error can be found in the following example:

```rust
let x = 1;
x = 2;
```

```bash
error[E0384]: cannot assign twice to immutable variable `x`
```

The same solution applies: Use `let mut x = 1` to allow future assignments to `x`.

## Trying to use a "moved" variable

Following the previous example, we now define two functions that receive an instance of `Book` and try to do something with it (e.g. printing its title):

```rust
fn print_book(book: Book) {
    println!("Book: {}", book.title);
}

fn do_something_else(book: Book) {
    println!("Again: {}", book.title);
}

fn main() {
    let book = Book {
        title: String::from("The Rust Programming Language")
    };

    print_book(book);
    do_something_else(book);
}
```

If we try to compile this code, we will find the following error:

```bash
error[E0382]: use of moved value: `book`
  --> src/main.rs:19:23
   |
14 |     let book = Book {
   |         ---- move occurs because `book` has type `Book`,
   |               which does not implement the `Copy` trait
...
18 |     print_book(book);
   |                ---- value moved here
19 |     do_something_else(book);
   |                       ^^^^ value used here after move
```

### Solutions

This problem is caused by Rust's [ownership rules around data references](https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html#ways-variables-and-data-interact-move).

Rust has no garbage collector like Java, nor it requires developers to manually "destroy" variable references to free the allocated memory. Instead, [it uses ownership to define when to clear the memory referred by a variable](https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html#memory-and-allocation): When execution reaches the end of a function, all variables owned by that function will go out of scope and their memory will be released.

When the program starts, the `main` function has ownership of the `book` variable. Then, when we call `print_book(book)`, the function `print_book` now owns `book`. When execution reaches the end of `print_book`, `book` will be out of scope and its data is cleared.

There are multiple solutions to this:

- Change `print_book` to return ownership of `book` to `main`.
- Change `print_book` to receive a _borrowed reference_ of book.

#### Solution 1: Returning ownership

The following code will compile correctly:

```rust
fn print_book(book: Book) -> Book {
    println!("Book: {}", book.title);
    book
}

fn do_something_else(book: Book) {
    println!("Again: {}", book.title);
}

fn main() {
    let mut book = Book {
        title: String::from("The Rust Programming Language")
    };

    book = print_book(book);
    do_something_else(book);
}
```

Notice that we changed `book`'s declaration to make it mutable, so we can re-assign its value. Also, we updated `print_book` to return `Book` once it's done with it.

I'm not a big fan of this approach, as I find it verbose and difficult to deal with if `print_book` is expected to return something else.

#### Solution 2: Use a borrowed reference

The following code will compile correctly:

```rust
fn print_book(book: &Book) {
    println!("Book: {}", book.title);
}

fn do_something_else(book: Book) {
    println!("Again: {}", book.title);
}

fn main() {
    let book = Book {
        title: String::from("The Rust Programming Language")
    };

    print_book(&book);
    do_something_else(book);
}
```

Notice we updated `print_book` to receive an instance of `&Book`, which is an _immutable_ reference to an instance of `Book`. This is called **borrowing**. We also changed `print_book(book)` to `print_book(&book)`, to send a reference of `book` to the function.

Now, `print_book` never gets ownership of `book`: It will receive the read-only reference. When execution reaches the end of `print_book`, `book` will not go out of scope, as `main` still owns it.

Just keep in mind that, in this example, `do_something_else` **does** get ownership of `book`, which is perfectly legal.

Another solution is to follow the compiler's advice and implement the `Copy` trait for `Book`, which then would create copies of `book` when passed to other functions. But then we would be using different instances of `book`, which has some downsides:

- Extra memory allocation. If `book` is large and we copy it every time we pass it to a function, we are needlessly consuming memory.
- Doesn't play well with mutations. If one of the functions is expected to change `book`'s contents, then we must return the copy so the next functions can have access to `book`'s updated values. This results in the same flow as returning ownership, but with extra steps.

## Trying to borrow as both mutable and immutable in the same scope

Now, we will modify the book's title using a new function, and print it with another one. The following code will compile correctly:

```rust
fn rename_book(book: &mut Book) {
    book.title = String::from("Something else");
}

fn print_title(book: &Book) {
    println!("Book: {}", book.title);
}

fn main() {
    let mut book = Book {
        title: String::from("The Rust Programming Language")
    };

    rename_book(&mut book);
    print_title(&book);
}
```

However, you will find that doing the following -which seems like it's practically doing the same thing- does not compile:

```rust
fn rename_book(book: &mut Book) {
    book.title = String::from("Something else");
}

fn print_title(book: &Book) {
    println!("Book: {}", book.title);
}

fn main() {
    let mut book = Book {
        title: String::from("The Rust Programming Language")
    };

    let mut book1 = &mut book;
    let book2 = &book;

    rename_book(&mut book1);
    print_title(&book2);
}
```

```bash
error[E0502]: cannot borrow `book` as immutable because it is also borrowed as mutable
  --> src/main.rs:20:17
   |
19 |     let mut book1 = &mut book;
   |                     --------- mutable borrow occurs here
20 |     let book2 = &book;
   |                 ^^^^^ immutable borrow occurs here
21 |
22 |     rename_book(&mut book1);
   |                 ---------- mutable borrow later used here
```

Aren't we also borrowing as both mutable and immutable in the first example? Not really.

### Solution

Rust will not allow us to create mutable and immutable references of an object _in the same scope_.

In the first example, the actual borrow happens once execution reaches each function `rename_book` and `print_title`, so there is only one borrowed reference at a time.

While the most obvious solution to this problem would be to use the first example where everything compiles correctly, let us explore a more contrived solution, which will shed some light on the ownership rules:

```rust
fn main() {
    let mut book = Book {
        title: String::from("The Rust Programming Language")
    };

    {
        let mut book1 = &mut book;
        rename_book(&mut book1);
    }

    let book2 = &book;
    print_title(&book2);
}
```

This little workaround makes our code compilable again. When we wrap the borrowed instance of `book1` and `rename_book` with a block `{}`, we are creating a new scope for them. Any variable declared inside the block will go out of scope once execution reaches the block's end. Then, by the time execution reaches `let book2`, `book1` will not exist anymore and we will only have a single borrow.

## Trying to keep a reference to a struct value

Coming from other languages, it's not uncommon for us to try to keep a reference for an object's attribute:

```rust
fn main() {
    let mut book = Book {
        title: String::from("The Rust Programming Language")
    };

    let title = book.title;

    rename_book(&mut book);

    println!("Title: {}", title);
}
```

While this is correct in other languages, Rust will complain:

```bash
error[E0382]: borrow of partially moved value: `book`
  --> src/main.rs:20:17
   |
18 |     let title = book.title;
   |                 ---------- value partially moved here
19 |
20 |     rename_book(&mut book);
   |                 ^^^^^^^^^ value borrowed here after partial move
```

### Solution

When we do `let title = book.title`, we are passing ownership of the `title` attribute from `book` to the `main` function, which means we cannot use `book` in `rename_book`. We could give `title`'s ownership back to `book`, but that would prevent us from using the `title` variable by itself.

To fix this problem, we could _clone_ the title as `let title = book.title.clone()`. However, this approach only works if one, `title` implements the `Clone` trait (which strings do by default), and two, whatever we use `title` for doesn't expect to get the actual value of `book.title`:

```rust
fn rename_book(book: &mut Book) {
    book.title = String::from("Something else");
}

fn print_title(book: &Book) {
    println!("Title: {}", book.title);
}

fn main() {
    let mut book = Book {
        title: String::from("The Rust Programming Language")
    };

    let title = book.title.clone();

    rename_book(&mut book);

    println!("Title: {}", title);
    print_title(&book);
}
```

```bash
Title: The Rust Programming Language
Title: Something else
```

If we wanted to keep a real reference to `book.title`, we must borrow a reference to it, being careful of not creating immutable and mutable borrows in the same scope:

```rust
fn main() {
    let mut book = Book {
        title: String::from("The Rust Programming Language")
    };

    {
        rename_book(&mut book);
    }

    let title = &book.title;

    println!("Title: {}", title);
    print_title(&book);
}
```

```bash
Title: Something else
Title: Something else
```

Of course, this is a very self-contained example that will not work in other cases. For instance, what if we want to keep a reference to `book.title` -independent from `book`- and return it from a function?

```rust
fn create_book() -> (Book, &String) {
    let book = Book {
        title: String::from("The Rust Programming Language")
    };

    return (book, &book.title);
}

fn main() {
    let (mut book, title) = create_book();
    rename_book(&mut book);
    println!("{}", &title);
}
```

The first problem we will find is the following:

```bash
error[E0106]: missing lifetime specifier
  --> src/main.rs:16:28
   |
16 | fn create_book() -> (Book, &String) {
   |                            ^ expected named lifetime parameter
   |
   = help: this function's return type contains a borrowed value,
    but there is no value for it to be borrowed from
help: consider using the `'static` lifetime
```

We will not go in-depth on the topic of lifetimes, but what Rust is saying is that, since we're returning a borrowed reference to a `String`, the developer needs to add a lifetime to the return type declaration to let Rust know how long is that reference expected to live.

We can try -_spoiler-alert_, unsuccessfully- to follow Rust's compiler advice and annotate `&String` with a `'static` lifetime:

```rust
fn create_book() -> (Book, &'static String) {
    let book = Book {
        title: String::from("The Rust Programming Language")
    };

    return (book, &book.title);
}
```

```bash
error[E0382]: borrow of moved value: `book`
  --> src/main.rs:21:19
   |
17 |     let book = Book {
   |         ---- move occurs because `book` has type `Book`, which does not implement the `Copy` trait
...
21 |     return (book, &book.title);
   |             ----  ^^^^^^^^^^^ value borrowed here after move
   |             |
   |             value moved here
```

By the end of the `create_book` function, `book` is moved out of the function, and ownership is passed to the caller (`main()`); because of this, we cannot borrow `book.title` (this is the same problem we found in the first example of this post).

Even if we try to store the book title's borrowed reference, we cannot just return a borrowed reference to `book.title`:

```rust
fn create_book() -> (Book, &'static String) {
    let book = Book {
        title: String::from("The Rust Programming Language")
    };

    let title = &book.title;

    return (book, title);
}
```

```bash
error[E0515]: cannot return value referencing local data `book.title`
  --> src/main.rs:23:12
   |
21 |     let title = &book.title;
   |                 ----------- `book.title` is borrowed here
22 |
23 |     return (book, title);
   |            ^^^^^^^^^^^^^ returns a value referencing data owned by the current function
```

Even if it _looks_ like we're passing the ownership of `title` to `main()`, in reality, we are trying to return a reference to a variable owned by `create_book`; such variable will also go out of scope at the end of `create_book`.

What options do we have here?

### Using Rc to create immutable references

Basic ownership rules work well in simpler applications. However, larger, more complex code will inevitably require getting multiple references to a single object and passing it across functions. For those cases, `std::rc::Rc` -[Reference Counter](https://doc.rust-lang.org/std/rc/struct.Rc.html)- is a handy tool.

Reference counters allow us to create multiple immutable references to a single object. These references can be safely passed from one function to another:

```rust
use std::rc::Rc;

struct Book {
    title: Rc<String>
}

fn create_book() -> (Book, Rc<String>) {
    let book = Book {
        title: Rc::new(String::from("The Rust Programming Language"))
    };

    let title = Rc::clone(&book.title);

    return (book, title);
}

fn main() {
    let (book, title) = create_book();

    println!("{}", book.title);
    println!("{}", title);
}
```

```bash
The Rust Programming Language
The Rust Programming Language
```

Under the hood, `Rc` keeps a count of the number of references that have been created. Once all references go out of scope, the object they were pointing at will be removed from memory. In a way, `Rc` works as a very simplified Garbage Collector.

This example is a bit misleading, as it looks like we're cloning `book.title`'s value, when we're cloning a _reference_ to it. This difference is clearer if we update `book.title`'s value.

### Using Rc and RefCell to create mutable references

Reference counting by default is immutable. If we want to update `book.title` we must introduce [`RefCell`](https://doc.rust-lang.org/std/cell/struct.RefCell.html) to make `title` a mutable reference:

```rust
use std::rc::Rc;
use std::cell::RefCell;

struct Book {
    title: Rc<RefCell<String>>
}

fn create_book() -> (Book, Rc<RefCell<String>>) {
    let book = Book {
        title: Rc::new(RefCell::new(String::from("The Rust Programming Language")))
    };

    let title = Rc::clone(&book.title);

    return (book, title);
}

fn rename_book(book: &Book) {
    book.title.replace(String::from("Something else"));
}

fn main() {
    let (book, title) = create_book();

    rename_book(&book);
    println!("{}", book.title.borrow());
    println!("{}", title.borrow());
}
```

This code will print:

```bash
Something else
Something else
```

With this example, we demonstrate two points:

- The `Rc::clone(&book.title)` returns a clone of the reference to `book.title`, not a clone of `book.title`'s value. Otherwise, `println!("{}", title.borrow())` would print the old value `"The Rust Programming Language"`.
- Using an `Rc<RefCell<String>>` variable type for `book.title` allows us to create copies of its reference _and_ mutate its value.

### A warning on Rc and RefCell

While `Rc` and `RefCell` allow us to create a more complex workflow, they also increase the complexity within your application. Just from the ergonomics point of view, having to pass around variables with `<Rc<RefCell<T>>` gets very verbose quickly.

Also, using reference counters when it's not needed increases the risk of memory leaks: If we keep a reference copy for too long, the underlying memory it points to may not be released. In cases where we implement things like HTTP servers using Rust, we might accumulate reference copies to objects that are not used, increasing the amount of consumed memory. This is a common problem in languages like Java, where keeping references to unused variables also lead to memory leaks that the Garbage Collector cannot fix.

When possible, we must avoid overusing these tools and try to work with the basic rules of ownership.

With this last example, we reached the end of this post. However, in future posts we will explore more potential difficulties that beginners find when learning Rust.

## Conclusion

Rust ownership and mutability rules are completely different from the way other languages enforce memory safety. While these tools can make it difficult for newcomers to ramp up in their learning journey, they are the reason why Rust is so safe and lightweight.

Not only Ownership allows Rust to operate without tools like Garbage Collectors, but it also forces developers to think deeper into how memory is allocated, used and released in their applications. Languages like `C` and `C++` offer this level of control too, but without the safeguards that Rust's compiler enforces.

While it seems like the Rust compiler throws _too many_ errors, it is for our own good. It's better to catch these problems during compilation than to try to debug them on execution time, many times in production environments.


Learn how to solve some common problems when starting learning Rust

Common Rust problems for beginners: Ownership & mutability

In this second part of the series, we discuss how to create a custom builder to generate SQL code out of Dart classes.

Code-gen in Dart & Flutter: How to create a builder to generate SQL code


import Image from 'src/components/image'
import process from './process-small.png'

Hosting your own blog is the kind of thing that every software developer wants to do. It's usually cheaper, you have control over your data, and you have the option to monetize it.

Whether you're a web developer or not, writing HTML can be cumbersome if you want to post fairly often. Most of the time you will want to focus on the content of your post, not on the code quality of the web page you're building to host it.

Here, Markdown is a great tool to speed up your blog posting capabilities.

## Markdown

Markdown defines a set of rules that indicate what kind of formatting text should have. The following are some of the most basic rules:

<table className="post-table">
  <thead>
    <tr>
      <td>Element</td>
      <td>Markdown Syntax</td>
      <td>Example</td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Heading</td>
      <td>
        <div># H1</div>
        <div>## H2</div>
        <div>### H3</div>
      </td>
      <td>
        <div
          style={{ fontSize: '2em', fontWeight: '500', marginBottom: '0.25em' }}
        >
          {'H1'}
        </div>
        <div
          style={{
            fontSize: '1.5em',
            fontWeight: '500',
            marginBottom: '0.25em',
          }}
        >
          {'H2'}
        </div>
        <div
          style={{ fontSize: '1em', fontWeight: '500', marginBottom: '0.25em' }}
        >
          {'H3'}
        </div>
      </td>
    </tr>
    <tr>
      <td>Bold</td>
      <td>\**bold text**</td>
      <td>**bold text**</td>
    </tr>
    <tr>
      <td>Italic</td>
      <td>\*italicized text*</td>
      <td>*italicized text*</td>
    </tr>
    <tr>
      <td>Blockquote</td> <td>\> blockquote</td>
      <td>*(Adds a quote container)*</td>
    </tr>
    <tr>
      <td>Ordered List</td>
      <td>
        <div>1. First item</div>
        <div>2. Second item</div>
        <div>3. Third item</div>
      </td>
      <td>
        <ol>
          <li>First item</li>
          <li>Second item</li>
          <li>Third item</li>
        </ol>
      </td>
    </tr>
    <tr>
      <td>Unordered List</td>
      <td>
        <div>- First item</div>
        <div>- Second item</div>
        <div>- Third item</div>
      </td>
      <td>
        <ul>
          <li>First item</li>
          <li>Second item</li>
          <li>Third item</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>Code</td>
      <td> \`code\`</td>
      <td> `code` </td>
    </tr>
    <tr>
      <td>Horizontal Rule</td>
      <td> \---</td>
      <td>
        <hr />
      </td>
    </tr>
    <tr>
      <td>Link</td>
      <td style={{ width: '217px' }}>\[title](https://www.example.com)</td>
      <td>[title](https://www.example.com)</td>
    </tr>
    <tr>
      <td>Image</td>
      <td> \!\[alt text](image.jpg)</td>
      <td>*(displays `image.jpg`)*</td>
    </tr>
  </tbody>
</table>

Markdown makes it easy to write formatted text. For instance, the following snippet of Markdown:

```markdown
# Welcome to my blog!

Start with the [first article](/blog/2022/9/markdown-to-html)
```

Gets formatted like follows:

---

<div style={{ fontSize: '2em', fontWeight: '500', marginBottom: '0.25em' }}>
  {'Welcome to my blog!'}
</div>

Start with the [first article](/blog/2022/9/markdown-to-html)

---

Many tools exist to build blogs from Markdown. [Jekyll](https://jekyllrb.com/) is a popular choice to build static websites out of Markdown.

However, when you are writing a technical blog, you will start noticing the limitations of working with out-of-the-box solutions. The point I hit these limits was with **code formatting**.

### Limitation: Code formatting

Markdown has two ways of highlighting code. The block element:

````markdown
```
public class App {
  public static void main(String[] args) { ... }
}
```
````

And the inline element

```
`System.out.println("Hello")`
```

[PrismJS](https://prismjs.com/) and [Highlight.js](https://highlightjs.org/) are two JavaScript libraries to highlight code keywords for multiple programming languages.

With PrismJS, setting a language for formatting is as easy as introducing the library (along with the CSS for a given theme) and then adding the language name to the code block declaration. For the example above, we get the following result:

````
```java
public class App {
  public static void main(String[] args) { ... }
}
```
````

```java
public class App {
  public static void main(String[] args) { ... }
}
```

But, what happens with the inline code? Markdown rules won't allow us to do something like

```
`System.out.println("Hello")`java
```

If we wanted to add custom CSS classes to Markdown-generated components, we find that Markdown doesn't specify the syntax to do so. Tools like Jekyll do allow for use of HTML elements inside Markdown, but it starts defeating a bit the purpose of using Markdown to speed-up writing.

If we want to extend Markdown syntax, we must modify the way Markdown is converted to HTML.

## Getting our hands dirty: Introducing Unified

[Unified](https://github.com/unifiedjs/unified) is a framework to process Markdown. It's a plugin-based tool that allows you to inspect and modify the way Markdown is converted to other formats like HTML.

Its general structure looks like this:

```js
import { unified } from 'unified'

const result = await unified()
  .use(...) // add a plug-in
  .process(await read('./example.md'))
```

Unified relies on two toolsets **remark** and **rehype**:

- [remark](https://github.com/remarkjs/remark): "remark is a tool that transforms markdown with plugins. These plugins can inspect and change your markup. You can use remark on the server, the client, CLIs, deno, etc."
- [rehype](https://github.com/rehypejs/rehype): "rehype is a tool that transforms HTML with plugins. These plugins can inspect and change the HTML. You can use rehype on the server, the client, CLIs, deno, etc."

With a combination of plugins from these two toolsets, we can fully customize the way we parse Markdown into HTML.

Some common plugins are:

- [remark-parse](https://www.npmjs.com/package/remark-parse): remark plugin to add support for parsing markdown input.
- [remark-rehype](https://github.com/remarkjs/remark-rehype): remark plugin that turns markdown into HTML to support rehype.
- [rehype-document](https://github.com/rehypejs/rehype-document): rehype plugin to wrap a fragment in a document.
- [rehype-format](https://github.com/rehypejs/rehype-format): rehype plugin to format (pretty-print) an HTML document.
- [rehype-stri.webpy](https://www.npmjs.com/package/rehype-stri.webpy): rehype plugin to add support for serializing HTML (to string).

Putting all these plugins together, the example looks like this:

```js
import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStri.webpy from 'rehype-stri.webpy'
import { read } from 'to-vfile'

const result = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument)
  .use(rehypeFormat)
  .use(rehypeStri.webpy)
  .process(await read('./test/example.md'))
```

Where `result` is a `VFile` -a virtual representation of the HTML file- that can be easily saved as an HTML file.

### Analyzing the transformation process

The following image represents the process the Markdown file follows to become HTML:

<Image src={process} alt="Transformation process of Markdown to HTML" />

The following is a step-by-step description of the process:

1. The Markdown file contents are read and placed into a `VFile`.
2. `remark` parses and process the Markdown text, and converts it into an [abstract syntax tree (AST)](https://github.com/unifiedjs/unified#syntax-tree). This tree is composed of [unist](https://github.com/syntax-tree/unist) nodes, which follow the [Markdown Abstract Syntax Tree (mdast)](https://github.com/syntax-tree/mdast) structure.
3. `remark-rehype` translates the `mdast` structure into a [Hypertext Abstract Syntax Tree (hast)](https://github.com/syntax-tree/hast) structure, also composed of `unist` nodes.
4. `rehype` process and transforms the `hast` structure into HTML.

Unified allows us to build plugins and process both the `mdast` and `hast` structures.

## mdast and hast

Before we try to customize the transformation process, let us look at how `mdast` and `hast` are represented.

In `mdast`, each node represents an abstract element. For instance, the _paragraph_ or `p` element is represented as follows:

```json
{
  "type": "paragraph",
  "children": [{ "type": "text", "value": "Alpha bravo charlie." }]
}
```

That same node has the following representation in `hast` as follows:

```json
{
  "type": "element",
  "tagName": "p",
  "properties": {},
  "children": [{ "type": "text", "value": "Alpha bravo charlie." }]
}
```

Notice that `mdast` has a different level of abstraction than `hast`: `hast` represents HTML elements, where "paragraph" is defined with the tag name `p`.

We can look at the same difference for `code`. The following markdown...

````
```
foo()
```
````

...becomes the following `mdast`:

```json
{
  "type": "code",
  "lang": null,
  "meta": null,
  "value": "foo()"
}
```

...and the following `hast`:

```json
{
  "type": "element",
  "tagName": "pre",
  "properties": {},
  "children": [
    {
      "type": "element",
      "tagName": "code",
      "properties": {},
      "children": [
        {
          "type": "text",
          "value": "foo()\n"
        }
      ]
    }
  ]
}
```

And the inline version \`bar()\` becomes the `mdast`:

```json
{
  "type": "inlineCode",
  "value": "bar()"
}
```

...and the `hast`:

```json
{
  "type": "element",
  "tagName": "code",
  "properties": {},
  "children": [
    {
      "type": "text",
      "value": "bar()"
    }
  ]
}
```

Notice that the block version of `code` wraps the `<code/>` HTML element in `<pre/>`, to preserve alignment and whitespaces. The inline version, however, just creates a `<code/>` element.

The block version allows us to add a value to the `lang` property. The following Mardown:

````
```js
foo();
```
````

...gets parsed as follows:

```json
{
  "type": "code",
  "lang": "js",
  "meta": null,
  "value": "foo();"
}
```

and:

```json
{
  "type": "element",
  "tagName": "pre",
  "properties": {},
  "children": [
    {
      "type": "element",
      "tagName": "code",
      "properties": {
        "className": ["language-js"]
      },
      "children": [
        {
          "type": "text",
          "value": "foo();\n"
        }
      ]
    }
  ]
}
```

The Markdown parser follows the [HTML5 specification](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element) for `<code/>` to define the language used in that block: Using the `lang` attribute with a value of `language-[LANG]`.

As we can see, we can use CSS to find `<code/>` blocks with class names for a given language (e.g. `language-js`) and process them accordingly.

In fact, PrismJS looks for `<code class="language-[LANG]></code/>` blocks to tokenize the text content and highlight keywords.

While the HTML5 specification allows for the use of `lang` in `<code/>` elements _not_ wrapped in `<pre/>` elements, there is no defined way in the Markdown syntax to set that attribute.

### Adding "lang" to inline code

We will extend the Rehype process to interpret inline code blocks like follows:

```md
`highlighted^const inline = "code";`
```

We will split the contents of the code block in two: Text before a separator `^` and the text after that:

```js
const [part1, part2] = ['markdown', 'const inline = "code";']
```

Then, we will use the first part as the `code`'s class name, and the second part as its contents.

The following code snippet is an extract of the Rehype plugin [rehype-inline-code-classname](https://www.npmjs.com/package/rehype-inline-code-classname) I published to NPM to allow setting a class name to inline code blocks:

```typescript
import { Element, Root, Text } from 'hast'
import { Transformer } from 'unified'
import { visit } from 'unist-util-visit'

export function rehypeInlineCodeClassNamePlugin(
  options?: Options
): void | Transformer<Root, Root> {
  const separator = options?.separator ?? '^'
  const trailing = options?.trailing ?? false

  return function (root) {
    function extract(value: String) {
      const [_, part1, part2] =
        value.match(new RegExp(`(.+)\\${separator}(.+)`)) ?? []

      return trailing
        ? { className: part2, content: part1 }
        : { className: part1, content: part2 }
    }

    visit(
      root,
      'element',
      function visitor(node: Element, i: number | null, parent: any) {
        if (node.tagName !== 'code') return
        if (!parent || parent.tagName === 'pre') return

        const [{ value, ...rest }] = node.children as Text[]
        if (value.includes(separator) && value.length > 2) {
          const { className, content } = extract(value)
          node.children = [{ value: content, ...rest }] as Text[]
          node.properties = {
            className: className,
          }
        }
      }
    )

    return root
  }
}
export type Options =
  | {
      separator: string
      trailing: boolean
    }
  | void
  | undefined
```

#### Working with AST: _visit_

In this plugin, we use the function `visit` from [unist-util-visit](https://www.npmjs.com/package/unist-util-visit) to navigate the `hast` tree and find all nodes:

```typescript
visit(root, 'element',
      function visitor(node: Element, i: number | null, parent: any) {
        //..
      }
```

Notice that `visit` receives three parameters:

- The root node of the `hast`.
- The type of node we want to visit. In our example, it will iterate through all nodes of type `element`.
- A function that will receive references to the `node`, and index `i` and the node's `parent`.

From here, we can modify the `hast` in any way we need to: Remove, add or update nodes.

#### Processing all "code" elements

We filter out all the nodes that don't have a `tagName` of `code`, and all `tagName:code` nodes that have a `tagName:pre` node as a parent, as those are block-type code elements:

```typescript
if (node.tagName !== 'code') return
if (!parent || parent.tagName === 'pre') return
```

We get the node's `value` attribute and check if it contains the expected separator `markdown^^` (and the code element actually has enough characters for having left and right substrings):

```typescript
const [{ value, ...rest }] = node.children as Text[]
if (value.includes(separator) && value.length > 2) {
  //...
}
```

If the value can be parsed with the separator, then we extract both substrings using a `RegExp`:

```typescript
const [_, part1, part2] =
  value.match(new RegExp(`(.+)\\${separator}(.+)`)) ?? []
```

The plugin allows a configuration object to define a custom separator and whether we want to set the class name at the end of the block like follows:

```markdown
`const inline = "code";^highlighted`
```

Depending on the configuration, we set `className` and `content` with `part1` and `part2`; then we update the `hast` node as follows:

```typescript
const { className, content } = extract(value)
node.children = [{ value: content, ...rest }] as Text[]
node.properties = {
  className: className,
}
```

We reset the node's `children` attribute with the actual content of the code block, and we set the `className` property to the substring we extracted using the separator.

### Using the plugin

To include our plugin, we just need to add it to the chain of plugins after `remark-rehype`, as we're working with a `hast`:

```js
import { myRehypePlugin } from '../src/plugin/index.ts'

const result = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(myRehypePlugin) // our rehype plugin
  .use(rehypeDocument)
  .use(rehypeFormat)
  .use(rehypeStri.webpy)
  .process(await read('./test/example.md'))
```

We now can set any class name we need for inline code blocks:

```markdown
`language-java^foo()`
```

will become:

```html
<code class="markdown">^</code>
```

### Revisiting code formatting

Since we now can set class names to our inline code blocks, we can use CSS and JavaScript to further format and style these elements:

```css
code[class*='language-'] {
  background-color: #f2f5ff;
  padding: 0.1em;
  border-radius: 0.3em;
  white-space: normal;
}
```

Unfortunately, the changes we have done are not enough to operate with plugins like [rehype-prism](https://github.com/mapbox/rehype-prism), as those assume `<code/>` blocks are wrapped by `<pre/>` elements. To highlight keywords in our code, we must use a tool to tokenize and highlight keywords, which is exactly what `PrismJS` does.

In a future blog entry, we will extend this example to use [refractor](https://www.npmjs.com/package/refractor?activeTab=readme) to create a custom `rehype` plugin which extends `rehype-prism`'s capabilities, and allows us to highlight keywords in inline code blocks.

### Conclusion

Unified offers an ecosystem of plugins that allow us to extend and customize the way Markdown is converted to HTML.

Creating a `rehype` or `remark` plugin requires us to handle abstract syntax trees, but `unist` tools like `unist-util-visit` offer helper functions that reduce the level of complexity of these tasks.

Frameworks like [NextJS](https://nextjs.org/blog/markdown) integrate nicely with Unified/remark plugins, allowing to convert Markdown files to HTML which can be easily rendered in the application. They even offer integration with [MDX](https://mdxjs.com/), a superset of Markdown that allows the use of React components _inside_ Markdown files.

However, Unified can be used to generate static HTML pages directly, allowing us to keep updated our self-hosted blogs.

#### On hosting

Free hosting for self-managed blogs exist out there. A good example is [Github Pages](https://pages.github.com/), which integrates pretty nicely with tools like Jekyll. But we can just use HTML files created through Unified.


Hosting your own blog is easier on Markdown!

Converting and customizing Markdown files to HTML with Unified, remark & rehype


import Image from 'src/components/image'

If you have worked on Flutter projects (or you're a Java developer), you may be familiar with the Mockito library.

[Mockito](https://pub.dev/packages/mockito) allows developers to create mock objects from existing classes, stub their methods and verify or assert their behavior during tests.

If you have used Mockito for Flutter or Dart projects, you will find the following in their documentation:

<blockquote>
  To use Mockito's generated mock classes, add a build_runner dependency in your
  package's pubspec.yaml file, under dev_dependencies; something like
  build_runner: ^1.11.0.
</blockquote>

Some of the code examples will show how to mock an existing class like `Cat` as follows:

```dart
@GenerateMocks([ Cat ])
```

Then it expects you to run the following command:

```bash
flutter pub run build_runner build
```

The `build_runner build` command creates a file called `*.mocks.dart`. What exactly is happening here?

## Reflection (and the lack of it)

[Flutter's FAQ](https://docs.flutter.dev/resources/faq) contains the following question:

<blockquote cite="https://docs.flutter.dev/resources/faq">
  ***Does Flutter come with a reflection / mirrors system?***

No. Dart includes dart:mirrors, which provides type reflection. But since Flutter
apps are pre-compiled for production, and binary size is always a concern with
mobile apps, this library is unavailable for Flutter apps.

Using static analysis we can strip out anything that isn’t used (“tree shaking”)... This guarantee is only secure if Dart can identify the code path at compile time. To date, we’ve found other approaches for specific needs that offer a better trade-off, such as code generation.

</blockquote>

According to Wikipedia, **Reflection** is:

<blockquote cite="https://en.wikipedia.org/wiki/Reflective_programming">
  In computer science, reflective programming or reflection is the ability of a
  process to examine, introspect, and modify its own structure and behavior
</blockquote>

In other languages like Java, libraries like Mockito use reflection to get information at run-time about the classes they are modifying. For instance, a Java function can get all the available methods for a class with the following code:

```java
Class c = Class.forName("java.lang.String");
Method m[] = c.getDeclaredMethods();
```

In this example, the function gets an array containing all the functions that are part of the `java.lang.String` class.

We can see how this could be practical for libraries like Mockito: It can find all the methods of a given class and provide stub implementations based on their return and parameter types. All in runtime.

A common approach is to mark classes with [annotations](https://docs.oracle.com/javase/tutorial/java/annotations/), then find those classes through reflection and do something with them:

- Create mock implementations.
- Instantiate singletons for the class.
- Create and inject instances of other classes into the constructor (like the Spring framework does).
- Decorate classes to provide behavior like JSON serialization or String representations, and so on.

A good example on how reflection is leveraged is the Java snippet we included in the previous post ["Easy parallelism and multi-threading with Java's CompletableFuture"](https://pedromarquez.dev/blog/2022/8/java-futures) (updated to remove generic classes for clarity):

```java
private static <Book> List<Book> parseJSON(String textResponse) {
    final ObjectMapper objectMapper = new ObjectMapper();
    List<T> objects = new ArrayList<>();
    try {
      objects =
        objectMapper.readValue(textResponse, new TypeReference<List<Book>>() {});
    } catch (JsonMappingException e) {
      // TODO: Do something with the error
    } catch (JsonProcessingException e) {
      // TODO: Do something with the error
      e.printStackTrace();
    }
    return objects;
  }
```

In this code example, the [Jackson](https://github.com/FasterXML/jackson) mapper uses reflection to find out the type of class it should use to de-serialize the JSON string:

```java
List<T> objects = objectMapper.readValue(textResponse, new TypeReference<List<Book>>() {});
```

The parameter `java^new TypeReference<List<Book>>() {}` creates a class reference that lets Jackson's`ObjectMapper`know that it should parse the JSON and create an instance of`List<Book>`.

However, we cannot do this kind of JSON de-serialization in Flutter. Without reflection, we need to consider other approaches for these same tasks. For instance, the package [`json_serializable`](https://github.com/google/json_serializable.dart) uses source code generation for decorating classes with methods to serialize and de-serialize JSON strings.

## Source code generation

When we don't have access to metadata about classes in run-time, one alternative is to do this introspection at compile time.

While Flutter limits reflection at run-time, tools like [source_get](https://pub.dev/packages/source_gen) rely on two low-level Dart packages:

- [build](https://pub.dev/packages/build): _"Defines the basic pieces of how a build happens and how they interact."_
- [analyzer](https://pub.dev/packages/analyzer): _"This package provides a library that performs static analysis of Dart code. It is useful for tool integration and embedding."_

Build provides an interface to implement **builders**: classes that provide an entry point to the compilation process, allowing us to create files as a result of our source code.

The analyzer package provides tools to retrieve information about our classes: The methods and variables they contain and the annotations they use, among others.

The tool [`build_runner`](https://pub.dev/packages/build_runner) (which is mentioned in Mockito's documentation) uses these two low-level packages to generate source code.

## High-level process: json_serializable

At a high level, the `json_serializable` package performs the following steps:

- Have developers annotate classes with `@JsonSerializable`. The annotated class must conform to [a set of guidelines](https://pub.dev/packages/json_serializable) for the process to work correctly.
- Have developers run the `build_runner` tool to generate the code that allows these classes to serialize and de-serialize JSON strings.

At a lower level, what the source code generation process is doing is the following:

- Developers execute the `build_runner` tool and, in turn, `build_runner` executes `json_serializable` builder classes.
  - The builder uses the `build` to define what files it will read from the source code, and what files it will generate.
  - The builder uses `analyzer` to find all classes annotated with `@JsonSerializable`.
  - The builder uses `analyzer` to find all the attributes and constructors for the serializable classes.
  - The builder creates Dart classes for serializing and deserializing JSON strings into the attributes it found with `analyzer`.
  - The builder cleans and puts these new classes in the same package as the annotated classes as `.g.dart` files.
    - These `.g.dart` files are [parts](https://dart.dev/guides/language/effective-dart/usage), which allow you to split a class into multiple files.

Following the example from `json_serializable`'s docs, we annotate the following class contained in `example.dart`:

```dart
@JsonSerializable()
class Person {
  /// The generated code assumes these values exist in JSON.
  final String firstName, lastName;

  /// The generated code below handles if the corresponding JSON value doesn't
  /// exist or is empty.
  final DateTime? dateOfBirth;

  Person({required this.firstName, required this.lastName, this.dateOfBirth});

  /// Connect the generated [_$PersonFromJson] function to the `fromJson`
  /// factory.
  factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);

  /// Connect the generated [_$PersonToJson] function to the `toJson` method.
  Map<String, dynamic> toJson() => _$PersonToJson(this);
}
```

After running `build_runner`, the following file `example.g.dart` is created:

```dart
part of 'example.dart';

Person _$PersonFromJson(Map<String, dynamic> json) => Person(
      firstName: json['firstName'] as String,
      lastName: json['lastName'] as String,
      dateOfBirth: json['dateOfBirth'] == null
          ? null
          : DateTime.parse(json['dateOfBirth'] as String),
    );

Map<String, dynamic> _$PersonToJson(Person instance) => <String, dynamic>{
      'firstName': instance.firstName,
      'lastName': instance.lastName,
      'dateOfBirth': instance.dateOfBirth?.toIso8601String(),
    };
```

All we have to do is import `example.g.dart` into `example.dart` and we will have access to the private functions `dart^_$PersonFromJson` and `dart^_$PersonToJson`.

## Advantages and disadvantages

The lack of reflection forces developers to be explicit about the types and use cases they need to support. However, we can still rely on [generics](https://dart.dev/guides/language/language-tour#why-use-generics) to create reusable code.

Generating source code reduces the number of manual work developers need to do for repetitive tasks. Without `source_gen` and `json_serializable`, we would have to manually create `toJson` and `fromJson` functions listing every attribute for each class. There are alternatives for this too, using generics and inheritence. However, it still requires a good amount of manual work.

While generating source code reduces this manual work, it introduces a layer of complexity to our project: Now we have a big chunk of source code that will not be available for inspection until we run the `build` tool. We can always check-in the generated code into version control, helpings better track changes done by re-running the `build` tool.

But the main disadvantage is the added complexity. Source code generators depend on the code having very specific conditions (e.g. having public constructors, follow name conventions) which may cause the build process to fail when not met. It's easy to find ourselves spending hours of our day just to figure out that the builder wasn't configured correctly.

## What's next

In the next blog post, we will create a simple plugin to build source code for Flutter projects. We will start deep-diving into the build process and how to create reusable modules that can be imported by other projects, just like `json_serializable` or `mockito` do.


Dart libraries like Mockito make heavy use of source-code generation.

Code-gen in Dart & Flutter: Reflection and code gen


import book from './book.jpeg'
import Image from 'src/components/image'

"Backend Developer in 30 Days" is now available on <a href="https://www.amazon.com/dp/9355513216/ref=cm_sw_r_apa_i_V19CYDR26B3R3ST9QMPP_0">Amazon</a> and [bpbonline.com](https://bpbonline.com/products/backend-developer-in-30-days?variant=42073104187592)!!

In this book, I tried to capture what I would have loved to know a decade ago when I was a junior developer: A holistic view of the most critical areas of back-end development, from defining and building APIs to continuously releasing an application.

<a href="https://www.amazon.com/dp/9355513216/ref=cm_sw_r_apa_i_V19CYDR26B3R3ST9QMPP_0">
  <Image
    src={book}
    width={1000 * 0.3}
    height={1233 * 0.3}
    alt="The book cover. It displays the title and a cute porcupine."
  />
</a>

I wrote this book in the middle of a pandemic and a master's degree; so I'm delighted to release this book after all that effort.

A big thank you to BPB for their patience, trust, and support while I wrote this book.

The following is the book description:

<blockquote>
This book connects ideas on API design, data modeling, practical testing, application security, and system design, among other critical areas of backend development.

Build stronger support system to power your enterprise applications

### Key Features

- Figure out the most important elements of backend and application development.
- Know how to construct large-scale, distributed applications using industry best practices and software architecture principles.
- Provides a career map for becoming a successful backend developer, including advice on skills and tools.

### Description

In today's world, becoming an experienced backend developer is a difficult job that requires a lot of work. There are an excessive number of stacks and technologies to master, and new ones often gain popularity. Nonetheless, they share the same fundamental concepts: data storage, security, performance, testing, etc.

This book aims to teach and train you to become a successful backend developer with a solid skill set in developing and implementing the real engine of a successful enterprise application.

Implementation topics like setting up a web server, designing and developing APIs, creating and running automated tests, and working with various types of databases are all addressed in detail.

The book prepares developers to maintain the safety and security of their applications through the use of procedures that avoid application and data breaches. While you learn about every part of backend development, the book teaches you how to deal with errors and find and fix problems.

By the end of the book, you will have a firm grasp on the fundamental principles that underpin backend programming, including application architectures, design patterns, essential development activities, and help for debugging.

### What you will learn

- Gain knowledge to build the momentum of a solid backend developer and choose areas to investigate in depth.
- Learn to integrate backend development as the top tech businesses do.
- Comprehend the distinction between SQL and NoSQL, containers, APIs, and web servers.
- Design large-scale systems step-by-step.
- Grow from junior backend developer to senior developer, including the required skills and responsibilities.

### Who this book is for

This book would greatly benefit readers who are new to backend operations for web and mobile apps, such as junior software developers, web developers, application developers, and frontend and backend coders. Basic programming skills will help you practice this book's learnings.

### Table of Contents

1. Building Multi-User Apps
2. The Client-Server Architecture
3. Designing APIs
4. End-to-end Data Management
5. Automating Application Testing
6. Securing Applications
7. Handling Errors
8. Adopting Frameworks
9. Deploying Applications
10. Creating High-performance Apps
11. Designing a System
12. Bootstrap Your Career Path

</blockquote>

If you have any feedback about the book, don't hesitate to send me an email to <a href="mailto:pedro.f.marquez.soto@gmail.com">pedro.f.marquez.soto@gmail.com</a>

_Note: If you're buying from Mexico, it's easier to order the book from BP online (the link is below), as they don't charge for delivery._


My first book is now for sale! You can find it in Amazon or in bpbonline.com (links in bio).

New book: "Backend Developer in 30 Days"


import Image from "src/components/image";

Modern applications (especially those based on [microservices](https://microservices.io/) architectures) heavily rely on fetching data from
remote servers. However, if not done correctly, the overhead added by these requests can seriously
reduce your application's performance.

In this blog post, we will explore ways to parallelize these requests using
Java's CompletableFuture.

## Background

Long lost are the old days when Java developers had to use the `Thread` or `Runnable` classes
for simple tasks like making requests to remote servers.

In Java 8, the Concurrency API was updated to include `CompletableFuture`, a class that does a great
job abstracting out the complexity of running tasks in multiple Threads.
This interface, in addition to [lambda](https://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html) functions,
makes up for a very intuitive way of running tasks in parallel in separate threads.

For instance, imagine we want to make two requests to a REST API hosted on a remote server:
One to fetch a list of _books_ and one to fetch a list of _authors_:

```bash
.../api/authors
# Returns:
[
  {
    "firstName": "Pedro",
    "lastName": "Marquez-Soto"
  }
]
.../api/books
# Returns:
[
  {
    "type": "Book",
    "name": "Amazing book"
  }
]
```

Unfortunately, these endpoints are extremely slow: The books endpoint takes 2.5 seconds to complete
and the authors endpoint takes 1.5 seconds.

## Making HTTP requests in Java

A simple way to make HTTP requests to remote servers is through the `java.net.http.HttpClient` class:

The following code snippet displays an example of making a `GET` request to the address stored in the string variable `url`:

```java
var client = HttpClient.newHttpClient();

// create a request
var request = HttpRequest
    .newBuilder(URI.create(url))
    .header("accept", "application/json")
    .build();

// use the client to send the request
final var response = client.send(request, BodyHandlers.ofString());
```

The variable response will contain the string representation of the server response.

Now, we can parse the JSON string into a class object using Jackson's [ObjectMapper](https://fasterxml.github.io/jackson-databind/javadoc/2.7/com/fasterxml/jackson/databind/ObjectMapper.html) as follows:

```java
private static <T> List<T> parseJSON(String textResponse) {
    final ObjectMapper objectMapper = new ObjectMapper();
    List<T> objects = new ArrayList<>();
    try {
      objects =
        objectMapper.readValue(textResponse, new TypeReference<List<T>>() {});
    } catch (JsonMappingException e) {
      // TODO: Do something with the error
    } catch (JsonProcessingException e) {
      // TODO: Do something with the error
      e.printStackTrace();
    }
    return objects;
  }
```

Notice that this function is using a generic type, so we can reuse this function to parse JSON strings
into many different classes:

```java
List<Book> books = App.<Book>parseJSON();
List<Author> books = App.<Author>parseJSON();
```

The classes `Book` and `Author` are plain Java objects with empty constructors, getters, and setters:

```java
public class Author {

  private String firstName;
  private String lastName;

  public Author() {}

  public String getFirstName() {
    return firstName;
  }
  // the rest of getters and setters
}
```

Putting it all together, we can create a function to request the data from each endpoint:

```java
private static <T> List<T> fetchSync(String url) {
    var client = HttpClient.newHttpClient();

    var request = HttpRequest
        .newBuilder(URI.create(url))
        .header("accept", "application/json")
        .build();

    // you may need to handle the checked exception in "send"
    final var response = client.send(request, BodyHandlers.ofString());
    return App.<T>parseJSON(response.body());
}
```

And we can use this function to make the two requests we need. Also, we will measure the time
it takes for both requests to complete:

```java
long start = System.nanoTime();
// Fetch the data:
List<Book> bookList = fetchSync("https://[your-api-here]/api/books");
List<Book> authorList = fetchSync("https://[your-api-here]/api/authors");

System.out.println(
    "Sync calls processed in " +
    Duration.ofNanos(System.nanoTime() - start).toSeconds() +
    " sec\n\n"
    );
```

If we execute this code (and the REST APIs are also up and running), we would see a message like follows:

```text
Sync calls processed in 4 sec
```

The time both requests took to complete is consistent with the knowledge we have about the endpoints' performance:

```bash
[Books_API_request] = 2.5 sec
[Authors_API_request] = 1.5 sec
[Books_API_request] + [Authors_API_request] = 4 sec
```

Here, we are making _sequential and blocking_, requests. The second request for
`authorList` will not start until the first request for `bookList` completes. However, both requests are not dependent on each other:
We could do both simultaneously and still receive the same results.

## Multi-threading with CompletableFuture

The `java.net.http.HttpClient` has a non-blocking version of its `send` method: [sendAsync](<https://docs.oracle.com/en/java/javase/12/docs/api/java.net.http/java/net/http/HttpClient.html#sendAsync(java.net.http.HttpRequest,java.net.http.HttpResponse.BodyHandler)>).

```java
public abstract <T> CompletableFuture<HttpResponse<T>> sendAsync​(
  HttpRequest request,
  HttpResponse.BodyHandler<T> responseBodyHandler)
```

Instead of returning a string response directly, this method returns a `CompletableFuture`.
The [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) class is a
wrapper for the result of an operation that may or may not have finished yet.

When using the synchronous method `HttpResponse.send`, once execution reaches `client.send(...)`, the main application thread will pause and block every other action until the server returns a response (or the request fails). However, `HttpResponse.sendAsync` will not block execution; it will immediately return the `CompletableFuture` instance and continue execution to the next line.

The request may or may not have been completed, so`CompletableFuture` could be in a _loading_ state. If we want to do something with the result once the request completes, we can register a listener function to the Future with `Future.thenApply`:

```java
CompletableFuture<String> response = client
  .sendAsync(request, BodyHandlers.ofString())
  .thenApply((httpResponse) -> httpResponse.body());

// of using the static method representation:

CompletableFuture<String> response = client
  .sendAsync(request, BodyHandlers.ofString())
  .thenApply(HttpResponse::body);

```

The method `thenApply` works similarly to Java Stream's [map](https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html#map-java.util.function.Function-): Chain a function that will be executed with the result of the previous operation as a parameter; that function then transforms the data and returns something else (in our example, the function transforms the `HttpResponse` to a `String`).

While this may be confusing, let us continue with our example to make things more transparent.

The following function is an asynchronous version of the `fetchSync` function we wrote before:

```java
private static <T> CompletableFuture<List<T>> fetchAsync(String url) {
    // create a client
    var client = HttpClient.newHttpClient();

    // create a request
    var request = HttpRequest
      .newBuilder(URI.create(url))
      .header("accept", "application/json")
      .build();

    // use the client to send the request
    final var response = client
      .sendAsync(request, BodyHandlers.ofString())
      .thenApply(HttpResponse::body)
      .thenApply(App::<T>parseJSON);

    // the response:
    return response;
  }
```

This function then can be called as follows:

```java
CompletableFuture<List<Book>> booksFuture = fetchAsync(
  "https://[your-api-here]/api/books"
);
CompletableFuture<List<Author>> authorsFuture = fetchAsync(
  "https://[your-api-here]/api/authors"
);
```

Here, Java automatically detects the types of the `booksFuture` and `authorsFuture` variables and passes the correct class type to the generic function.

If we were to execute these functions as they are, we would see no results at all. This is because the application won't wait for the server responses to complete. To block execution and wait for a `CompletableFuture` to finish, we can use the following code:

```java
CompletableFuture<List<Book>> booksFuture = fetchAsync(
  "https://[your-api-here]/api/books"
);
CompletableFuture<List<Author>> authorsFuture = fetchAsync(
  "https://[your-api-here]/api/authors"
);
booksFuture.get();
authorsFuture.get();
```

We now measure the time this code snippet takes. The following is the measurement result:

```text
Async calls processed in 2 sec
```

Both requests took 2 seconds. That is half the time it took to make both requests with blocking requests!

Let us convert the time to milliseconds to better assess what is happening here:

```bash
# Making just the book request:
Calls processed in 2503 sec
# Making just the author request:
Calls processed in 1505 sec

# Both as synchronous calls:
Calls processed in 4343 sec

# Both as asynchronous calls:
Calls processed in 2504 sec
```

When we run both requests in parallel, we can see that the total time it takes to complete both tasks is equal to the time it takes to complete the longest of them (in this case, the books request, which takes 2.5 seconds).

This is a significant improvement over the synchronous/blocking calls, whose total time equals the sum of the time it takes to make each request one after the other.

## Long operations

Java's `CompletableFuture` is not just a good way to handle network requests. Any function that may take a long time is a good candidate for being handled through Futures: Reading and writing files, and memory-intensive operations.

For instance, we can simulate a long-running operation with the following function:

```java
static CompletableFuture<String> longRunningOperation() {
    return CompletableFuture.supplyAsync(
      () -> {
        sleep(5000);
        return "Success";
      }
    );
  }

  static void sleep(long milliseconds) {
    try {
      Thread.sleep(milliseconds);
    } catch (InterruptedException e) {
      // TODO Auto-generated catch block
      e.printStackTrace();
    }
  }

  // ....

  var futureResult = longRunningOperation();
  System.out.println("Getting result of long running operation:");
  System.out.println(futureResult.get());

  /*
  > "Getting result of long running operation:"
  > "Success"
  */
```

The method `CompletableFuture.supplyAsync` gets a thread from ` ForkJoinPool#commonPool()`, and executes the lambda function in that thread.

## Conclusion

`CompletableFuture` is a robust tool that should be in any Java developer's toolset.

It provides a native way to schedule work in parallel threads, which is particularly useful for making network requests to remote servers. Its API provides many practical methods to orchestrate asynchronous calls better, giving developers control to improve their application's performance.

Other languages have interfaces similar to `CompletableFuture`. For instance, JavaScript has [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), which is a concept almost identical to Java's Futures.

If we don't need to share resources between threads, Java Futures and the Concurrency API can be a simpler alternative to classic classes and interfaces like `Thread` and `Runnable`. However, For more low-level tasks requiring synchronization and memory handling across all threads, `Thread` is still a powerful tool.


In this post, we improve application performance by making multiple parallel requests to a REST API

Easy parallelism and multi-threading with Java's CompletableFuture

import Image from "src/components/image";
import CodePen from "src/components/codepen";
import image1 from "./image1.png";
import image2 from "./image2.png";

In this post, we will explore CSS variables and the `prefers-color-scheme` media query, and we will build a small example of how to implement dark-mode in a website without using any external libraries and with little to no use of JavaScript.

## Overview

In recent years, “dark mode” has become widely popular. Ever since the beginning of the Internet,
web developers have looked for ways to customize their users' experiences with different color palettes;
most of the time leading to custom solutions that relied heavily on JavaScript and working around CSS’s rules.

Modern CSS, however, now includes features that allow developers to override easily override styles
across a website or web application.

## CSS Variables

With many years in the making, browser support for CSS variables expanded around 2016.
Now, [newer versions](https://caniuse.com/css-variables) of most modern browsers support them.

It’s important to notice that these variables are supported by vanilla CSS; there is no need to
use a pre-processor like Sass or Less.

As their name indicates, CSS variables allow us to store values once and use them across our stylesheet.

The following example creates two variables in a `body` block and one in a `h1`: `body-color`,
`font-color` and `h1-color`.

```css
body {
  --body-color: black;
  --font-color: white;
  background-color: var(--body-color);
  color: var(--font-color);
}

h1 {
  --h1-color: gold;
  color: var(--h1-color);
}
```

Notice that variables are prefixed with `--`. That is how CSS recognizes that they are variables.

Then, within those same blocks, we apply CSS rules like `background-color` and `color`, and we get
the variables’ values by passing them to the function `var()`.

While this example may seem over-simplistic, you can see the potential: We can take those variables
and put them in a global scope:

```css
:root {
  --body-color: black;
  --font-color: white;
  --h1-color: gold;
}

body {
  background-color: var(--body-color);
  color: var(--font-color);
}

h1 {
  color: var(--h1-color);
}
```

Notice that we moved the variable definitions to a block named `:root`. This pseudo-class matches the `<html>` tag.
This means that, from here, all CSS rules on the page will have access to these variables.

<Image
  className="post-image"
  src={image1}
  scale={0.4}
  alt="A web page with a black background, gold-colored title and white font text"
/>

### Some benefits

CSS variables allow us to centralize and standardize values for CSS rules across our web page.
You can encapsulate specific values in reusable variables.

Most websites use a palette of 3 or 4 colors: primary, secondary, and accent colors.
We can create a variable for each, and refer to those variables directly in every other CSS rule.
If you want to change the palette, just change the variable definitions; no need to update each rule in
every stylesheet.

## Overriding CSS variables.

CSS variables follow the same rules as the rest of CSS; thus, variables can be overridden:

```html
<h2>This is gold</h2>
<h2 class="page1">This is green</h2>
```

```css
:root {
  --h1-color: gold;
}

h2.page1 {
  --h1-color: green;
}

h2 {
  color: var(--h1-color);
}
```

Since we can override CSS rules by adding specificity to the selector, we can also override the
variable definitions in `:root`:

```css
:root {
  --body-color: white;
  --font-color: black;
  --h1-color: gold;
}

// we only override the variables we need:
[data-dark-mode] {
  --body-color: black;
  --font-color: white;
}
```

Now the `:root` block contains the variable definitions for “light-mode”, and the
block `[data-dark-mode]` overrides the `body-color` and `font-color` variables.

This means that, if the element `<html>` has the attribute `data-dark-mode`, the page
will have a black background and white font, instead of the default white background and black font:

```html

<html>
  

  
  <html data-dark-mode></html>
</html>
```

The attribute `data-dark-mode` is no reserved word. This attribute can be
anything like `data-dark-theme` or `data-cool-dark-mode-on`.

Just remember to prefix the attribute with `data-`, as this is a custom attribute.

### Switching between dark and light modes

If we want to allow users to switch between light and dark modes, we will need a couple of
JavaScript lines. First, create a button:

```html
<button id="dark-mode-toggle">Toggle dark mode</button>
```

Then, add an event listener for the “click” event of that button. Inside that event listener,
get a reference to the `html` element, and use the `toggleAttribute` method:

```js
document
  .querySelector("#dark-mode-toggle")
  .addEventListener("click", function () {
    document.querySelector("html").toggleAttribute("data-dark-mode");
  });
```

And that’s it! When the user clicks the button, the attribute `data-dark-mode` will be toggled
on and off the `<html>` element, overriding the styles.

## The “prefers-color-scheme” media query

Users now can configure their operative systems (Android, iOS, MacOS, and so on) to use
dark-mode everywhere, when possible. Browsers can detect this setting through media queries,
specifically, the `prefers-color-scheme` media query:

```css
@media (prefers-color-scheme: light) {
  // detect OS-configured light-mode and apply rules
}

@media (prefers-color-scheme: dark) {
  // detect OS-configured dark-mode and apply rules
}
```

Using these media queries, we can set the page to always be in dark-mode if the user configured
this option in their device:

```css
:root {
  --body-color: white;
  --font-color: black;
  --h1-color: gold;
}

[data-dark-mode] {
  --body-color: black;
  --font-color: white;
}

@media (prefers-color-scheme: dark) {
  :root {
    --body-color: black;
    --font-color: white;
  }
}
```

Optionally, we can remove the dark-mode toggle button if the option is already set at the OS level:

```css
// ...
@media (prefers-color-scheme: dark) {
  :root {
    --body-color: black;
    --font-color: white;
  }
  #dark-mode-toggle {
    display: none;
  }
}
```

The best part of this media query is that it removes the need of using JavaScript to apply dark-mode to the
page. But, as always, make sure that the browsers your expect to target [support the media query](https://caniuse.com/?search=prefers-color-scheme).

An easy way to test `prefers-color-scheme` is through Chrome's Rendering tools:

<Image
  className="post-image"
  src={image2}
  scale={0.5}
  alt="Chrome's rendering tools showing a dropdown to emulate prefers-color-scheme"
/>

## Codepen

<CodePen
  height="300"
  defaultTab="css,result"
  slugHash="RwMjmPm"
  user="pfernandom"
/>

## Conclusion

CSS variables are extremely useful to standardize our stylesheets and make them configurable.

In this post we implemented dark-mode in a very simple web page, but the benefits of CSS variables and
the `prefers-color-scheme` media query are more apparent once we apply them in a real application with tons
of CSS rules.

Native CSS variables make it really easy to build themes for a web app, including 'dark mode'

Building a dark-mode theme with CSS variables


import Image from "src/components/image";
import appstate1 from "./appstate1.webp";
import appstate2 from "./appstate2.webp";
import { ThemeContext } from "src/pages/_document";

Managing state in a client app is always a tricky (and opinionated) topic.
Web developers are familiar with tools like Redux or MobX. These tools follow very specific patterns that are not always easy to learn or understand by new developers.

These same tools exist in the Flutter world, but recently I've been exploring an alternative that may seem consistently easier. We can manage app state with `rxdart` and `get_it`.

## Some background

At any given moment, an application will have _state_. If we think of an app like Instagram, the state can be
the list of posts and stories the application renders. State can also be your app preferences, the contents of the
story you're about to post, the list of notifications and the number of un-read messages.

In general, state is data.

Let's think of notifications. When a user sends you a message, many components in the application need to reflect this change of state: The little red dot that tells you have un-red messages must be rendered, the list of messages must be updated, and so on.

At a lower level, state is a collection of variables. In Flutter, we extend the `StatefulWidget` class when we want to create a widget that will contain state:

```dart
import 'package:flutter/material.dart';

class Update {
  Update({required this.description});

  String description;
}

class MyStatefulWidget extends StatefulWidget {
  @override
  State<StatefulWidget> createState() => MyStatefulWidgetState();
}

class MyStatefulWidgetState extends State<MyStatefulWidget> {
  List<Update> updates = [];

  @override
  Widget build(BuildContext context) {
    print("Updates: $updates");
    return Column(
      children: [
        ElevatedButton(
          onPressed: () {
            fetchUpdates().then((newUpdates) {
              setState(() {
                updates = newUpdates;
              });
            });
          },
          child: const Text("Fetch notifications"),
        ),
        Flexible(
          child: ListView.builder(
            itemCount: updates.length,
            itemBuilder: (BuildContext context, int index) {
              return ListTile(
                title: Text(updates[index].description),
              );
            },
          ),
        )
      ],
    );
  }
}

```

The `MyStatefulWidgetState` widget renders the following view:

<Image
  className="post-image"
  src={appstate1}
  alt={"User clicks in the button and a list of notifications is rendered"}
/>

In this example, when the user clicks the `Fetch notifications` button, the function `fetchUpdates()` is called. This function returns a Future object, and once the request completes successfully, we set the list of updates in the variable `updates`.

The variable `updates` is state within this widget.

Calling `setState` when we set the new value of the variable `updates` will re-render this widget _only_. If this widget contains other widgets (e.g. the `ElevatedButton` and the `ListView`), those widgets will be re-rendered as well.

Now, we want to add an icon to the top bar to indicate the user that new notifications have been fetched. The following widget will render that notification icon:

```dart
import 'package:flutter/material.dart';

class NotificationIcon extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    var notificationsCount = 0;
    return Stack(
        children: <Widget>[
        const Icon(Icons.notifications),
        Positioned(
            right: 0,
            child: Container(
            padding: EdgeInsets.all(1),
            decoration: BoxDecoration(
                color: Colors.red,
                borderRadius: BorderRadius.circular(6),
            ),
            constraints: const BoxConstraints(
                minWidth: 12,
                minHeight: 12,
            ),
            child: Text(
                '$notificationsCount',
                style: const TextStyle(
                color: Colors.white,
                fontSize: 8,
                ),
                textAlign: TextAlign.center,
            ),
            ),
        )
        ],
    );
  }
}
```

How can we notify the `NotificationIcon` widget that `MyStatefulWidget` has fetched a new list of notifications?

## Some options...

We could re-render our component to include `NotificationIcon` in `MyStatefulWidget`. The problem with this approach is that we may need to also include other, unrelated widgets.

Another approach is to use [Inherited Widgets](https://api.flutter.dev/flutter/widgets/InheritedWidget-class.html). However, this approach may require us to modify other widgets than these two, which is not always possible.

How can we notify to independent widgets of state changes?

Enter state management.

## State management through streams

Data streams are analog to queues: One part of the application will publish data to a stream and other parts of the application can subscribe that stream and consume the data it produces.

We can rely on streams to communicate state changes across independent components.

A popular implementation of streams for Flutter apps is [rxdart](https://pub.dev/packages/rxdart).

We can add them to our project with the following command:

```shell
flutter pub add rxdart
```

## Creating a stream

Then, we can create a service to create a stream:

```dart
import 'package:rxdart/rxdart.dart';

import 'MyStatefulWidget.dart';

class NotificationsService {
  final BehaviorSubject<List<Update>> notificationSubject = BehaviorSubject.seeded([]);

  ValueStream get stream$ => notificationSubject.stream;

  updateNotifications(List<Update> updates) {
    notificationSubject.add(updates);
  }
}
```

Before we can use this service, we need a way for widgets to access a shared instance of the stream. For this, we will use [get_it](https://pub.dev/packages/get_it):

```shell
flutter pub add get_it
```

## Registering a service

This tools is a **service locator**: It allows us to create singleton instances of objects and share it across the application without having to pass them as paramaters.

We can create an instance of `NotificationService` when the app starts as follows:

```dart
void main() {
  GetIt getIt = GetIt.I;
  getIt.registerSingleton<NotificationsService>(NotificationsService());
  runApp(const MyApp());
}
```

Now, anywhere in our app, we can get this singleton instance with the following code:

```dart
GetIt getIt = GetIt.I;
var service = getIt.get<NotificationsService>();
```

We update `MyStatefulWidgetState` to get the service, and send the new updates to the stream:

```dart
fetchUpdates().then((newUpdates) {
    GetIt getIt = GetIt.I;
    var service = getIt.get<NotificationsService>();
    service.updateNotifications(newUpdates);
    ...
```

## Subscribing to the stream

Now, we will update `NotificationIcon` to subscribe to the stream and listen for new updates.

For this, we will use `StreamBuilder`, which accepts a stream and re-renders its contents when the stream produces new results.

The following code shows the updated version of `NotificationIcon`:

```dart
import 'package:flutter/material.dart';
import 'package:get_it/get_it.dart';

import 'MyStatefulWidget.dart';
import 'NotificationsService.dart';

class NotificationIcon extends StatelessWidget {
  late NotificationsService service;

  NotificationIcon() {
    GetIt getIt = GetIt.I;
    service = getIt.get<NotificationsService>();
  }

  @override
  Widget build(BuildContext context) {
    return StreamBuilder(
      stream: service.stream$,
      builder: (BuildContext context, AsyncSnapshot<dynamic> snapshot) {
        if (!snapshot.hasData || snapshot.data == null) {
          return const CircularProgressIndicator();
        }

        List<Update> updates = snapshot.data;

        if (updates.isEmpty) {
          return Container();
        }
        var notificationsCount = updates.length;

        return Stack(
          children: <Widget>[
            const Icon(Icons.notifications),
            Positioned(
              right: 0,
              child: Container(
                padding: EdgeInsets.all(1),
                decoration: BoxDecoration(
                  color: Colors.red,
                  borderRadius: BorderRadius.circular(6),
                ),
                constraints: const BoxConstraints(
                  minWidth: 12,
                  minHeight: 12,
                ),
                child: Text(
                  '$notificationsCount',
                  style: const TextStyle(
                    color: Colors.white,
                    fontSize: 8,
                  ),
                  textAlign: TextAlign.center,
                ),
              ),
            )
          ],
        );
      },
    );
  }
}

```

Focus on the important part here:

```dart
 return StreamBuilder(
      stream: service.stream$,
      builder: (BuildContext context, AsyncSnapshot<dynamic> snapshot) {
        if (!snapshot.hasData || snapshot.data == null) {
          return const CircularProgressIndicator();
        }

        List<Update> updates = snapshot.data;

        if (updates.isEmpty) {
          return Container();
        }
        var notificationsCount = updates.length;
        // ... render the notification icon
```

Since the stream may be empty, we need to handle the case where the widget has not received any updates. The class `AsyncSnapshot` has multiple methods that allow us to check the stream state and act accordingly.

Now, when the user clicks in the button, the new updates will be sent to the stream and all widgets listening to it will re-render:

<Image
  className="post-image"
  src={appstate2}
  alt={
    "User clicks in the button, a list of notifications is rendered and the notification icon is rendered as well."
  }
/>

We could take this example even further and make `MyStatefulWidgetState` a stateless widget, getting its state directly from the same stream. Feel free to take this extra step and practice this state management approach.

## Pros and cons

Some of the advantages of this state management approach are:

- It is simple. Multiple, independent widgets can be notified of state changes without changing their parent widgets, and without passing any extra props.
- It allows us to use more stateless widgets. Stateless widgets have a more predictable behavior, and require less boilerplate code.
- It reduces unnecessary re-rendering. If we were to pass app state as properties through the widget tree, all intermediate widgets will be re-rendered when state changes. With this approach, only the widgets that need to re-render do so.
- Less conventions. There is no defined API to follow. No reducers or mappers. While conventions are useful for large projects, smaller apps can benefit of the flexibility this approach provides.

On the other side, the disadvantages are:

- It may be _too_ flexible. This approach opens the door to a lack of structure in the project. More structure is better for large teams and large code bases.
- If not used responsibly, `get_it` can lead to a bunch of global state. Developers can abuse the magic of this service locator and add state that doesn't need to be stored.

## Conclusion

State management is hard. Because of these, developers have created many tools to store state and communicate state changes. Some of those tools will fit better to your specific project needs.

Using streams along with a service locator is a simple yet effective way to handle global state.


Managing state in a Flutter app using data streams and a service locator

Managing state in Flutter apps with data streaming


I was using JavaScript for completing some Leetcode challenges and I got some pretty weird behavior.

I tried to create a matrix (a two-dimension array, or array of arrays), initialize it with `false` and then use it in some backtracking problem. I did something like this:

```javascript
// Initialize a 3x4 matrix with "false" values.
const matrix = Array(3).fill(Array(4).fill(false))

// some stri.webpy to capture the actual values at this point of the execution
console.log(JSON.stri.webpy(matrix))

// set middle value to true
matrix[1][1] = true

console.log(JSON.stri.webpy(matrix))
```

And my console prints this:

```javascript
;[
  [false, false, false, false],
  [false, false, false, false],
  [false, false, false, false],
][
  ([false, true, false, false],
  [false, true, false, false],
  [false, true, false, false])
]
```

Wait, what? If I only set the value at 1,1 to **true**, why am I getting changed values in the whole column?

Well, this is because the parameter passed to `Array.fill()` is not really a callback. It only gets evaluated once, and its used for filling all the elements in the array.

So, in this case, we have only two arrays. The array `A` (`Array(3)`), which has 3 elements, and array `B` (`Array(4)`) which has 4 elements.

`Array(4)` creates array `B`, and `B` is passed as parameter to the `Array(3).fill(B)`.

To be clearer, this is what we are actually doing, broken into more steps:

```javascript
const B = Array(4).fill(false)
const A = Array(3).fill(B)
const matrix = A
```

As we can see, we're filling `A` with the same reference of `B`, three times. Any changes to `B` will be reflected in each element of `A`.

## How do we fix it?

Try this instead:

```javascript
const matrix = Array(3)
  .fill()
  .map((el) => Array(4).fill(false))
```

This will create array `A`, and then use the `map` function to call `Array(4).fill(false)` once per each element of `A`, generating new arrays for each one.

Looking back at why the problem happened, it seems pretty obvious. However, when I was puzzled when it first happened, and I couldn't find any example of anyone else doing the same.

Hope this helps other people.

PS. Happy birthday, USA!


Weird behavior while using Array.fill to create a 2D array

Weird behavior for matrix created with Array.fill()


import Image from 'src/components/image'
import heroImage from './demo.webp'

An Express server showcasing how HTML Chunking behaves, including blocking resources for Critical Rendering Path

## Why?

I've read from multiple sources about HTML streaming (chunking) as a way to increase perceived page load performance, but it was very difficult for me to visualize it without an example.

Most examples I've seen don't exactly show what happens if one chunk takes considerably more time to be streamed than the previous, or what happens with multiple chunks with varying latencies.

### Critical rendering Path

Another thing that was difficult to visualize to me were concepts like "blocking resources" like CSS and JS files; especially because HTML can be rendered in chunks one would think that CSS and JS can be chunked too.

This project adds blocking CSS and JS scripts which finish loading after a timeout, specifically to verify what happens when we also stream blocking resources (_spoiler alert, they still block rendering of the HTML_)

## How

Node's Express allows writing chunks into a response stream using [Node streams](https://nodejs.org/api/stream.html#stream_writable_write_chunk_encoding_callback), via its `response.write(chunk)` method.

Using that method, we can simulate streaming multiple chunks with different latencies:

```js
app.get('/', function (req, res) {
  res.write('<html>')
  res.write('<h1 class="my-text">Hello</h1>')

  setTimeout(function () {
    res.write('<div>I took too long to load, like 5 seconds!</div>')
    res.write('</html>')
    res.end()
  }, 5000)
})
```

Here, we stream first the openning tag `<html>` and the `<h1>` tag, then we wait for 5 seconds and we stream the rest of the document.

In a real-world application, instead of a timeout we can do some costly operation like querying a DB. The browser will render the `<h1>` element and as more chunks are streamed, more parts of the page will be rendered.
In this way, we can get content to the user as fast as possible, without having to wait for those costly operations to finish before even sending the first byte of response.

### Scripts and stylesheets

Using the same chunking technique, we can return JS and CSS files:

```js
app.get('/styles.css', function (req, res) {
  res.write('h1 { background-color:blue; }')
  res.write('.my-text { background-color:yellow; }')
  setTimeout(function () {
    res.write(' body { background-color: grey; }')
    res.end()
  }, 4000)
})

app.get('/script.js', function (req, res) {
  res.write('console.log("hello");')
  setTimeout(function () {
    res.write('console.log("world");')
    res.end()
  }, 4000)
})
```

Unlike the chunked HTML, the browser will not execute/render each chunk as it gets it. It has to wait for the whole file to finish loading before it can continuing rendering the HTML which is declared after these `<link>` and `<script>` tags. So, even if we stream these resources, they will still block rendering.
For example, once the browser gets to the `<script>` tag for the `script.js` file we defined above, both `hello` and `world` will be printed in console at the same time, after the 4 seconds delay.

Why is the browser not processing these files as they get streamed? This is out of the scope of this text, but from a high point of view is because **the browser cannot correctly calculate styles or execute scripts without knowing the whole content of the file**.
Take as an example a JavaScript file. Thanks to [hoisting](https://www.w3schools.com/js/js_hoisting.asp), declarations of JavaScript functions can be bellow their invocations:

```js
main()

function main() {
  console.log('Go main!')
}
```

So, even if the browser browser is able to read the first line with `main()`, how would it know what to execute if it doesn't have the function declaration yet?.

### Fixing blocking resources

There are multiple ways to remove blocking CSS and JS, like inlining critical CSS and JS. It won't change the blocking behavior of the `<script>` and `<link>` tags, but it will reduce the overhead of extra network requests and (hopefully) it will be smaller in content than the full, non-critical resources.

- [https://developers.google.com/speed/docs/insights/BlockingJS](https://developers.google.com/speed/docs/insights/BlockingJS)

## Demo

<Image src={heroImage} alt="Gif showing the server running" />


Pedro's Tech Blog