• Hosting quickly 1 - Setting up Terraform, Github, and 1Password
• Hosting quickly 2 - Dioxus to the web on Fly.io
• Hosting quickly 2.5 - Discovering and calling a backend from Dioxus

To get to the point where I can develop my very first application off of Cochrane, I'm adding a database to my setup. Keeping with the free tier, low setup goals here, I'm using Neon. Additionally, I want this to work with local development so we'll add a Docker Compose configuration!

Adding Neon to Terraform

There seem to be two Neon providers (1, 2), which are near feature parity with each other. The first one, by Dmitry Kisler appears to be more active and more used, so let's go with that one.

A tiny bit of config needs to be added to infra/main.tf to get a functioning connection URL to a database:

resource "neon_project" "db_project" {
  name = var.github_name
  branch {
    name = "main"
    database_name = "core"
    role_name = "backend"
  }
}

And when that's working, we can add it to the environment variables for our backend:

resource "fly_machine" "machine_backend" {
  // ...
  env = {
    DATABASE_URL = neon_project.db_project.connection_uri
  }
}

Connecting from our backend

Let's add two new files, backend/src/database.rs and backend/src/config.rs and add it to main.rs with a mod statements. Inside our config.rs, we'll load configuration from file or environment, and in database.rs we'll connect to the actual database.

In config.rs let's define our database configuration:

#[derive(Deserialize, Getters)]
pub struct Config {
    #[getset(get = "pub")]
    database: DatabaseConfig,
}

#[derive(Deserialize)]
pub struct DatabaseConfig {
    username: SecretString,
    password: SecretString,
    port: u16,
    host: String,
    database_name: String,
}

impl DatabaseConfig {
    pub fn as_connect_options(&self) -> PgConnectOptions {
        PgConnectOptions::new()
            .host(&self.host)
            .username(self.username.expose_secret())
            .password(self.password.expose_secret())
            .port(self.port)
            .database(&self.database_name)
    }
}

Two notable things here: the Getters and getset attributes, from the getset crate. This enforces the readonly nature of our Config struct: it should only ever be constructed, never modified. Secondly the SecretStrings in the DatabaseConfig. This comes from secrecy and gives some stronger guarantees around application secrets, including making it harder to accidentally log them.

We'll load our config from environment only for now, using the excellent config crate.

pub fn get_configuration() -> Result<Config, config::ConfigError> {
    let settings = config::Config::builder()
        .add_source(config::Environment::default().separator("__"))
        .build()?;
    settings.try_deserialize::<Config>()
}

Connecting to the database is simple enough, just a few lines of code in database.rs:

pub async fn connect_to_postgres(settings: &DatabaseConfig) -> Result<PgPool, sqlx::Error> {
    let connection = PgPool::connect_with(settings.as_connect_options()).await?;
    Ok(connection)
}

Running a query

Let's add a silly little query for now:

async fn get_data(State(pool): State<PgPool>) -> Json<GetResult> {
    let res = query!("SELECT 5 + 5 AS sum;")
        .fetch_one(&pool)
        .await
        .unwrap();

    Json(GetResult {
        foo: res.sum.unwrap_or_default().to_string(),
    })
}

#[tokio::main]
async fn main() {
    let db_pool = connect_to_postgres(config.database())
        .await
        .unwrap();

    let state = ServerState::new(db_pool);

    // ...

    let app = Router::new()
        .route("/", get(get_data))
        .layer(cors)
        .with_state(state);
}

Passing state to an Axum router is sort of out-of-scope here, so I'll leave that as an exercise to the reader. Or for the reader to look up in the code on Github.

Local development

Right now, to test our connections I have to deploy it. But I'd like to test it before. I can keep running Docker images manually, using justfile commands to string them together. That'll get complicated fast though, so maybe I should consider alternatives.

I'm pretty unfamiliar with making these kind of complex services run in different environments, especially locally. I have some options, like Docker Compose or running Kubernetes locally, potentially with Helm. Some searching quickly shows that lots of people are excited about Docker Compose. Let's go with that!

We'll create an local-dev/ folder, with a justfile and a compose.yaml:

start:
  docker-compose -f compose.yaml up --build

stop:
  docker-compose -f compose.yaml down

The --build flag for the start command is important! Without this, Docker will not try to rebuild your image, even if the filesystem has changed.

version: '3.1'

services:
  backend:
    build:
      context: ../
      dockerfile: backend/Dockerfile
    ports:
      - "8002:3000"
    depends_on:
      - postgres
    environment:
      - DATABASE__HOST=postgres
      - DATABASE__PORT=5432
      - DATABASE__USERNAME=postgres
      - DATABASE__PASSWORD=example
      - DATABASE__DATABASE_NAME=cochrane
  frontend:
    build:
      context: ../
      dockerfile: frontend/Dockerfile
    ports:
      - "8001:8080"
    environment:
      - 'DIOXUS_ENV={ "backend_url": "http://localhost:8002" }'
  postgres:
    image: "postgres:16-alpine"
    restart: always
    ports:
      - "8101:5432"
    environment:
      POSTGRES_PASSWORD: example
      POSTGRES_DB: cochrane

Some special things are worth mentioning! You can see we're setting up the configuration properties here using the environment property on the backend service, and pointing it to our Postgres instance. For each service that we have to build, we also set both a build.context, relative to the compose.yaml itself, and then a build.dockerfile relative to that context.

But, to compile our sqlx queries, we need to have run cargo sqlx prepare. And for that, we need to configure our database. So let's set up a way that we can boot our Postgres machine by itself and run the command against it:

start-service service:
  docker-compose -f compose.yaml up -d {{service}}

stop-service service:
  docker-compose -f compose.yaml down {{service}}

sqlx-prepare: (start-service "postgres")
  cd .. && cargo sqlx prepare --database-url=postgres://postgres:example@localhost:8101/cochrane --workspace

Running up without the -d flag (for "detach") will attach to the Docker container and log its outputs to the terminal. We want it to run in the background in this case.

This way we can boot one specific service, keeping in mind that the backend Docker image will not work without running sqlx prepare first. Then, using the appropriate Postgres URI, sqlx can connect to it and prepare its compilation files.

Now we're ready to run the magical just local-dev/start, and hit our frontend at https://localhost:8001/. It should display {"foo":"10"} on your frontpage. Awesome!

Fine, an actual query

To run a real query against a real database, we'll first want to set up sqlx migrations to actually create that table. Let's run cargo sqlx migrate add init to set up our first migration. Then we add to the justfile:

sqlx-migrate: (start-service "postgres")
  cd .. && cargo sqlx migrate run --database-url=postgres://postgres:example@localhost:8101/cochrane

sqlx-prepare: (start-service "postgres") sqlx-migrate
  # ...

Let's fill our actual migration:

CREATE TABLE test (
  id UUID NOT NULL PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL
)

Now all you need to do is run just local-dev/sqlx-migrate and you'll see it migrating. We've also added sqlx-migrate as a dependency to sqlx-prepare, so running that after creating a new migration will make sure everything's ready for building a database!

Let's use our table from the API:

#[derive(Deserialize)]
struct PostRequest {
    name: String,
}

#[debug_handler]
async fn post_data(
    State(pool): State<PgPool>,
    Path(id): Path<Uuid>,
    Json(request): Json<PostRequest>,
) -> StatusCode {
    query!(
        "INSERT INTO test (id, name) VALUES ($1, $2) ON CONFLICT (id) DO UPDATE SET name = $2",
        id,
        request.name
    )
    .execute(&pool)
    .await
    .unwrap();

    StatusCode::OK
}

I will, again, leave part of this to the reader. Specifically the part where you take this data out (the GET request), and adding this to the router. We now just need to add the usage of this to our frontend...

async fn api_post(url: url::Url, uuid: uuid::Uuid, name: String) -> () {
    let client = reqwest::Client::new();
    client
        .post(url.join(uuid.to_string().as_str()).unwrap())
        .json(&PostRequest { name })
        .send()
        .await
        .map_err(|e| e.to_string())
        .unwrap();

    ()
}

And use it:

    let set_name = move |_| {
        cx.spawn({
            to_owned![backend_url, uuid];

            let new_uuid = uuid::Uuid::new_v4();

            async move {
                api_post(backend_url, new_uuid, "Foo bar".to_string()).await;
                uuid.set(Some(new_uuid));
            }
        })
    };

And before you know it... it works!

Let's recap...

Wow, we did a lot here! We tackled adding a Neon database to our Rust applications and streamlined our development with Docker Compose. With a real database connection, we can finally start building applications with Cochrane. Stay tuned for some first examples of that! 👀

In the upcoming post, I'll add a basic version of running background tasks to Cochrane. Keep coming back!

We should make the backend serve some API that we can hit from the frontend.

We'll turn the root endpoint in the backend into a JSON-returning endpoint:

#[derive(Serialize)]
struct Response {
    name: String,
}

#[debug_handler]
async fn home() -> Json<Response> {
    Json(Response {
        name: "Hello, World!".to_string(),
    })
}

and then use that endpoint from the frontend:

#[derive(Deserialize)]
struct Response {
    name: String,
}

pub async fn get_endpoint() -> Result<String, reqwest::Error> {
    let url = format!("/topstories.json");
    let res = reqwest::get(url).await?.json::<Response>().await?;

    Ok(res.name)
}

fn app(cx: Scope) -> Element {
    let response = use_future(cx, (), |_| get_endpoint());

    match response.value() {
        Some(Ok(name)) => cx.render(rsx! {
            h1 { "{name}" }
        }),
        Some(Err(_)) | None => cx.render(rsx! {
            h1 { "Error!" }
        }),
    }
}

Let the frontend know

There's a very simple reason that this is a separate article: I need to figure out how to make the frontend discover the base URI of the backend API. There are a few options:

1. Compile it in, either from an environment variable or as a hardcoded string.
2. Serve it in configuration, like an /env.json file that can be loaded from the frontend or inserted into a script tag in the HTML.
3. Ensure it's on the same domain, so that the frontend can just call /api.

I'm not a huge fan of compiling it into the code: I'd like to be able to use the same compiled code across different environments. Additional requests, like having an env.json or service discovery, will only slow down the page load. Routing is something I'd like to avoid depending on.

So instead, let's insert any environment variables into the index.html at startup! We'll start by loading it in Dioxus. I'll leave defining the EnvSettings as an exercise to the reader:

fn get_dioxus_env<'a>(cx: &Scope) -> EnvSettings {
    std::env::var("DIOXUS_ENV").unwrap_or_default()
}

For running the frontend locally and through Docker, we'll set it through the Justfile. For the docker-run command, we'll also make sure to forward the backend's port:

run $DIOXUS_ENV='BACKEND_API_URL="https://localhost:3000"': build
    dx serve --features ssr --hot-reload --platform desktop

docker-run: docker-build
    docker run -it -p 8081:8081 -p 8080:8080 -e BACKEND_API_URL=https://localhost:8081 cochrane-frontend:dev

Call the API

To make this as simple as possible, let's create a special component that calls the API and returns either an error or the text response:

#[derive(PartialEq, Props)]
struct QueryingTextProps {
    backend_url: url::Url,
}

#[allow(non_snake_case)]
fn QueryingText(cx: Scope<QueryingTextProps>) -> Element {
    let result = use_future(cx, &cx.props.backend_url, |val| async move {
        let res = call_api(val).await;
        res
    });

    cx.render(match result.value() {
        Some(Ok(s)) => rsx! { p { "{s}" } },
        Some(Err(e)) => rsx! { p { "{e}" } },
        None => rsx! { p { "Loading..." } },
    })
}

Note the call_api function that's undefined, we'll get there. There's some setup code here that's necessary for a Dioxus component: the QueryingTextProps struct to allow passing our API endpoint, the use_future call to actually call the async fn that we'll be defining. Otherwise it's fairly standard!

In fact, the call_api function is super simple. It's just a plain reqwest call. Of course, we could flesh this out by sprinkling in some serde_json and better error types, but this'll do for now:

async fn call_api(url: url::Url) -> Result<String, String> {
    let res = reqwest::get(url).await.map_err(|e| e.to_string())?;
    res.text().await.map_err(|e| e.to_string())
}

All that's left is actually using the component now:

let EnvSettings { backend_url } = get_dioxus_env(&cx);

And then add this to the returned rsx:

rsx! { QueryingText { backend_url: backend_url } },

Voila! It's all hooked up.

Results

I've intentionally left certain elements for the reader to implement. Specifically, the exact definition of EnvSettings and the intricate details of error handling and JSON processing within the call_api function are not covered. Also, getting the environment info from a dotenv file or other configuration would probably improve this.

Anyway, I think it works out to be a nice way of configuring your frontend Docker image without having to rebuild your Rust code for each environment.

Enjoy!

• Hosting quickly 1 - Setting up Terraform, Github, and 1Password

Today, let's build a frontend and backend in Dioxus and Axum, respectively.

The frontend

Let's keep it extra simple and only create an example Dioxus frontend, for now. I want the newest and the hottest I can get, which seems to be Dioxus Fullstack. Let's set that up in a new frontend/ directory.

I'll add the new frontend/ package as a member to our root workspace. For good measure, I've copied the example Dioxus.toml into the frontend/ folder. Finally, we'll create a frontend/justfile with two simple commands:

build:
    dx build --features web

run: build
    dx serve --features ssr --hot-reload --platform desktop

Simply run just frontend/run from the root and... it works! It's almost like magic! Moving on, let's deploy this to Fly.io. To do that, I'll add a Dockerfile:

FROM rust:1.73-buster AS builder

WORKDIR /usr/src/cochrane

RUN rustup target add wasm32-unknown-unknown \
    && cargo install dioxus-cli --version 0.4.1
COPY . .
RUN cd frontend \
    && dx build --features web --platform web --release

FROM caddy:2.7.5-alpine

COPY --from=builder /usr/src/cochrane/frontend/dist /usr/share/caddy

This works ... sort of. We get a response with all the necessary files, but the page doesn't render anything. Dioxus's SSR server by default only listens to 127.0.0.1, so we need to make sure it listens to all addresses:

#[cfg(feature = "ssr")]
fn main() {
    use tracing_subscriber;
    tracing_subscriber::fmt::init();

    LaunchBuilder::new(app)
        .addr(std::net::SocketAddrV4::new(std::net::Ipv4Addr::new(0, 0, 0, 0), 8080))
        .launch();
}

#[cfg(not(feature = "ssr"))]
fn main() {
    LaunchBuilder::new(app).launch();
}

This'll do it.

The backend

Let's set up a simple Axum server with one endpoint. Eventually we might want to add the routes from Dioxus's server functions, but we'll leave that for if I ever want to really use it.

This is super simple and we're purposefully keeping this super simple, so I'll speed through the steps here. We'll add a backend/ folder with its own Cargo.toml, justfile, and Dockerfile. The main.rs will be a straight copy from the example in its docs.

The justfile:

build:
    cargo build

run:
    cargo run

docker-build:
    cd .. && docker build . -f backend/Dockerfile -t cochrane-backend:dev

docker-run: docker-build
    docker run -it -p 8081:3000 cochrane-backend:dev

And the Dockerfile:

FROM rust:1.73-buster AS builder

WORKDIR /usr/src/cochrane

COPY . .
RUN cargo build --release -p backend

CMD ["/usr/src/cochrane/target/release/backend"]

Running just backend/docker-run and hitting localhost:8081 works! All we need to do is add a little magic Hyper incantation to allow the server to shut down nicely. We can lift that from the Hyper docs.

Pushing this to Fly.io

Fly.io has recently deprecated their Terraform provider, but I'm insistent on using Fly.io and Terraform (for now). I'll use a lightly-maintained fork for now. There's a few steps to getting this working. First, I'll have to build the Docker images in Github Actions and push them to the Fly registry. Then we'll need a Terraform configuration for a Fly app and machine

Preparing our Fly apps

We first need to add a Fly app to be able to even push the Docker images. I'll do this through adding this to our Terraform file:

variable "fly_token" {
  type        = string
  description = "A Fly.io API token with access to the right organization"
}

terraform {
  required_providers {
    // ...

    fly = {
      source = "pi3ch/fly"
      version = "0.0.24"
    }
  }
}

provider "fly" {
  fly_api_token = var.fly_token
}

resource "fly_app" "app_backend" {
  name = "${var.github_name}-backend"
}

resource "fly_app" "app_frontend" {
  name = "${var.github_name}-frontend"
}

As well as adding fly_token = "op://cochrane/fly/token" to our terraform.tfvars.tpl. Now we just need to run just --dotenv-filename .just-env infra/apply to actually create the apps.

Building and pushing the Docker image

Let's start! I've created a Fly account, and gotten myself an access token that I can use to publish to the Docker registry. Since Github can load the secrets from the 1Password vault directly, I don't need to add this token as an Actions Secret, just to my vault.

We'll add a second Github Workflow file, let's call it build.yaml, that builds and pushes the Docker images.. That's the easy part, so I'm going to start with authenticating with Fly:

name: Build and deploy

on:
  workflow_dispatch:
  pull_request:
    paths:
      - 'frontend/**.rs'
      - 'frontend/Cargo.toml'
      - 'frontend/Dockerfile'
      - 'backend/**.rs'
      - 'backend/Cargo.toml'
      - 'backend/Dockerfile'

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - name: Get Fly token
        uses: 1password/load-secrets-action@v1
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT }}
          FLY_ACCESS_TOKEN: op://cochrane/fly/token

      - uses: superfly/flyctl-actions/setup-flyctl@master
      - name: Authenticate Fly registry
        run: flyctl auth docker

Then we simply add the Docker build-and-push action steps to the end:

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          push: true
          file: frontend/Dockerfile
          tags: registry.fly.io/cochrane-frontend:latest

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          push: true
          file: backend/Dockerfile
          tags: registry.fly.io/cochrane-backend:latest

Note we don't need Docker's regular username/app syntax here, just the app name.

Configuring our Fly machines

All we need to do to get the app actually running on Fly is create an IP (for the traffic to be routed to) and a machine. The IP is easy:

resource "fly_ip" "ip_backend" {
  app = fly_app.app_backend.name
  type = "v4"
}

The only sort of complicated thing about the machine itself is that you have to set the image to point specifically at Fly's own registry, and you have to configure the ports appropriately:

resource "fly_machine" "machine_backend" {
  app = fly_app.app_backend.name
  image = "registry.fly.io/${var.github_name}-backend:latest"
  region = "iad"
  services = [
    {
      ports = [
        {
          port = 443
          handlers = ["tls", "http"]
        },
        {
          port = 80
          handlers = ["http"]
        }
      ]
      internal_port = 3000
      protocol = "tcp"
    }
  ]
}

After running just --dotenv-filename .just-env infra/apply You have a working service! You can find the IP to hit by running echo "fly_ip.ip_backend" | terraform console -var-file=terraform.tfvars in the infra/ directory, or you can find the app url in your Fly dashboard.

Now copy this over for the frontend and... shock! It's running!

The End

Well... for now. We haven't actually made the frontend and backend talk with each other yet, nor are they doing anything useful. Up next is a quick "intermission" post on the first, and then we're deploying and configuring a Postgres database.

Be sure to subscribe to keep up, and check out cochrane on Github.

Anyway, XState is good for this. However, I don't think it's good enough. Its typegen feels like a dirty fix, it doesn't strongly type its context per state, and its typings are very complicated to use^[1].

So I'm creating tstate, a codegenless, very strictly typed, pure Typescript, composable state machine library. It's based on some of my learnings from using XState quite extensively in production applications, and some of my dreams of what I want libraries to be.

How to use tstate

It's early days. Importantly, I'm still working on getting context to work ergonomically. However, as a minimalist state machine library it actually works. Here's some examples pulled from the tests:

const machine = createStateMachine(
  {
    init: createStateDefinition({
      on: {
        foo: {
          target: "bar",
        },
        bar: {
          target: "init",
        },
      },
    }),
    bar: createStateDefinition({
      on: {
        baz: {
          target: "init",
        },
      },
    }),
  },
  "init"
);

The machine variable is an instance of the machine, in its initial init state. It has a send function that accepts valid events for that state (in this case foo and bar):

const res = machine.send("foo");
expect(res.value).toEqual("bar");

You'll see that .send("foo") returns a new machine instance that's in the target state (bar). This, again, is strictly typed:

const res2 = res.send("baz");
expect(res2.value).toEqual("init");

Type architecture

In the tstate finite state machine, typing is enforced from the inside out, starting at the createStateDefinition function. This function defines a single state and its transitions in your state machine. It looks something like this:

function createStateDefinition<const D extends StateDefinition<…>>(definition: D) {
  return definition;
}

The function takes the cont generic parameter of type StateDefinition. This generic should always be inferred by Typescript, and it'll enforce const typing o our output StateDefinition type so that the next function can use that information to enforce its own typings.

That function is createStateMachine. This is where you define a map of all your state names to their respective StateDefinition objects. Looks (a little) like this:

function createStateMachine<const D extends MachineDefinition<…>>(config: D) {
  // State machine logic here
}

Its MachineDefinition type (again const) shares some generics with StateDefinition. It'll only accept StateDefinitions that use the states listed as keys of the MachineDefinition object. This ensures you cannot define a transition into a non-existent state.

While the first function is basically a simple passthrough that ensures ergonomic strict typing, this second function actually creates an state machine with a current state (the initial state) and a .send method to transition to other states. This method only accepts valid events.

Whereto next?

Up next is context. I'm working on adding strong typing of context next to states. This means that when you've asserted that a machine is in a certain state, you'll also know the shape of the context. I think this is a significant improvement over XState's status quo^[2]. To do this, I also need to build transition actions to mutate from the current context type into the new type.

After that I have a short list of things I want to work on:

• "Nested" states: in reality, this should be connector utilities between separately defined machines. I think it'll be much simpler, possibly at the loss of some ergonomics.
• Utilities for connections with other state machines, like promises, callback functions, and observables.
• Integrations with React and associated.

If you have opinions about these, feel free to hit me up in Github Discussions

Simple machines, little to test

First and foremost: keep your machines small. Nested parallel machines with lots of interdependent states and events are complicated to test not because of any technological reasons, but because the machines themselves are complicated. Small machines will be significantly easier to test.

Instead of nesting parallel machines, see if you can get away with defining the machines separately. You can invoke child machines from the parent and pass messages back and forth. There's a little more work involved, maybe, but your machines will be much more constrained.

Replacing actions and services won't do the job

This might be a controversial take, but I almost never redefine actions or services with .withConfig. I like to test the machine as a whole, including the internal logic of actions and services and, importantly, the way that they affect the machine.

Instead I mock the side effects. Usually, this means jest.mocking the function. I don't like mocking external things though, so I actually ended up providing the functions through the machine's Context^[1]. This makes it super easy to inject mocks that to test specific behaviour.

Looks like this:

const Machine = createMachine({
  schema: {} as {
    context: {
      doAThing: (foo: string) => number;
    };
  },
  // ... ommitted
});

it('does a thing', async () => {
  const doAThingMock = jest.fn<
    // The type parameters aren't absolutely necessary in this example, but
    // they're useful when creating mock implementations.
    ReturnType<ContextFrom<typeof Machine>['doAThing']>,
    Parameters<ContextFrom<typeof Machine>['doAThing']>
  >();

  const service = interpret(Machine.withContext({ doAThing: doAThingMock }));
  service.start();

  await waitFor(service, (state) => state.matches('...'));
  expect(doAThingMock).toHaveBeenLastCalledWith(/* ... */);
});

Builder pattern to the rescue

I'm a sucker for a good XYZBuilder in tests. A good builder allows you to define only the properties relevant for the test, where the others have sane but mostly no-op defaults. I started out creating classes for each machine, but got annoyed at the boilerplate quickly. I tried out builder-pattern but eventually built TSBuilder.

TSBuilder allows easily setting up a type-safe builder. I'm not entirely content with the API yet (especially the typings), but it does the job better than custom classes for now.

const MachineBuilder = TSBuilder<
  ContextFrom<typeof Machine>,
  typeof Machine,
  never
>(
  {
    prop: () => 'defaultValue',
  },
  (ctx) => Machine.withConfig(ctx),
);


const machine = MachineBuilder.withProp('otherValue')[Build]().result;
const service = interpret(machine);

Please open issues and PRs if you don't like things about TSBuilder, I welcome feedback!

ActorRefs

This is new to me and a bit of a work in progress. Sometimes you need to depend on, spawn, or reference other machines. This is extremely useful in connecting multiple independent processes, but quite difficult to test. Primarily you'll want to test one of the machines in isolation. Actually testing the machines altogether will be a bigger and more complex test, and as such you'll want to reduce the amount of tests at this level.

However, replacing machines through createMachineing simpler, dumber versions of the original can be a big hassle. Most of the time I only need the nested machine to respond to a given action or send an event to its parent at a certain point. I ended up directly implementing ActorRefFrom<Machine>:

class MockMachine implements ActorRefFrom<Machine> {
  public readonly id = 'Machine';
  private _state: StateFrom<typeof Machine>['value'] =
    'idle';
  private _context: Context;
  private _listeners: Array<{ func: Listener; id: string }> = [];

  constructor(context: Context) {
    this._context = context;
  }

  getSnapshot() {
    return {
      context: this._context,
      value: this._state,
    } as StateFrom<Machine>;
  }

  unsubscribe(id: string) {
    this._listeners = this._listeners.filter((l) => l.id !== id);
  }

  subscribe(subscriber: Listener | { next: Listener }): Subscription {
    const listener = {
      func: 'next' in subscriber ? subscriber.next : subscriber,
      id: v4(),
    };
    this._listeners.push(listener);

    return {
      unsubscribe: () => {
        this.unsubscribe(listener.id);
      },
    };
  }

  send(
    event:
      | EventFrom<Machine>['type']
      | EventFrom<Machine>,
  ) {
    const parsedEvent = typeof event === 'string' ? { type: event } : event;
    this._listeners.forEach((l) =>
      l.func({
        ...this.getSnapshot(),
        event: parsedEvent as EventFrom<Machine>,
      } as StateFrom<Machine>),
    );
  }

  get state() {
    return this.getSnapshot();
  }

  [Symbol.observable]() {
    return {} as InteropSubscribable<StateFrom<Machine>>;
  }
}

As you can probably tell, I don't actually implement the full behaviour of the ActorRef. It seems to work though, and Typescript believes it. Currently, this isn't generic but it should be easy enough. Pass it the correct types and you can then send certain events from the machine with machine.send({ type: 'ACTION' });. It's similar to XState's empty actor but you get more control over the snapshot.

I do think this could benefit from a generalised library. Maybe I'll build on eventually.

Concluding...

That's it for now. I realize that my specific testing strategies may be controversial. Dependency injection could be replaced with mocking, for one. However, it comes from some amount of experience, and I haven't seen anyone else's approaches to this.

Happy to discuss though, of course!

This is my attempt at recreating it^[1].

The basic idea

There are two core things that Rust's ?-operator allows us to do: early return on errors and (as a result) chain Result types as if they're always Oks. Let's get the first part out of the way: we cannot replicate inline early returns in Typescript.

For the second part, any Javascript aficionado might suggest that this already exists. We already have a ? chaining operator in JS/TS. However, that works only for nullish values, which we actually want to allow.

We can sort of create a new operator though.

The spider "operator"

Attempt number one is based on Javascript's Proxy object, which allows us to override things like getters and setters. We'll build a spider operator 𐳱^[2] that allows us to operate on the potential error state of a Result type:

type MyObj = { bar: { foo: String } };

const ok1 = ok<MyObj, Error>({ bar: { foo: "it's ok" } });
const mappedOk = ok1[𐳱].bar[𐳱].foo.map(() => "it's not ok" as String);

console.assert(𐳱 in mappedOk);
console.assert(mappedOk.unwrapOk() === "it's not ok");

const error1 = err<MyObj, Error>(new Error("hello world"));
const mappedError = error1.mapErr(() => new Error("other world"))[𐳱].bar;

console.assert(𐳱 in mappedError);
console.assert(mappedError.unwrapErr().message === "other world");

I went into this expecting this to be an entirely ridiculous API, but now that I've played with it a little bit it turns out to... not be that crazy, maybe? It differs slightly from Rust: because we cannot do early returns, we have found a slightly nicer way of chaining on properties than simply chaining maps like .map(val => val.prop).map(…).

Let's build it! Obviously, we'll need to define the spider operator^[3]:

const 𐳱 = Symbol.for("SPIDER_OPERATOR");

Then I'll define the Result type that both the ok and err classes will implement:

interface Result<
  // these types need to extend object, or they won't have props to access.
  Ok extends object,
  Err extends object
> {
  map<NewOk extends object>(cb: (e: Ok) => NewOk): Result<NewOk, Err>;
  mapErr<NewErr extends object>(cb: (e: Err) => NewErr): Result<Ok, NewErr>;
  unwrapOk(): Ok | never;
  unwrapErr(): Err | never;
  [𐳱]: {
    // make sure that any accessed prop is wrapped as a result also
    [Prop in keyof Ok]: Ok[Prop] extends object ? Result<Ok[Prop], Err> : never;
  };
}

For this blog, let's define a small part the ok type only. The full version is linked in this Typescript playground.

function ok<Ok extends object, Err extends object>(value: Ok): Result<Ok, Err> {
  return {
    get [𐳱]() {
      return new Proxy(
        value,
        { get: (target, prop) => ok(target[prop]) }
      );
    },
    map<NewOk extends object>(cb: (e: Ok) => NewOk): Result<NewOk, Err> {
      return ok(cb(value));
    },
    // …
  };
}

This is fairly straightforward: the function returns an object with some functions on it. The complicated bit is the get [𐳱]() definition here. There's some special stuff going, so let's break it down into the two maybe complicated bits:

1. We define a getter function for the spider prop (using computed property names):

get [𐳱]() {}

2. We create a Proxy on the actual value, which changes the property getter to wrap the result in a new call to ok(…):

return new Proxy(value, { get: (target, prop) => ok(target[prop]) })

3. A bunch of type magic that I've omitted to get this to work.

This way, any time we try to access a property of this value, the proxy intercepts that and returns a resultified version of the value instead.

What's wrong in this picture?

Lots!

First of all, this whole thing is silly and bad. I'm doing a lot of work here to build some weird silly syntax sugar that isn't even very nice to use.

Second, as I alluded to before, there's a lot of ✨ type magic ✨ that I'm leaving out (including some naughty anys here and there).

Most importantly because Proxy can only work on objects, the Result has to operate on objects for now. That means it cannot work on primitive values, like strings and numbers. You still want to be able to call the spider operator on a string though, since you might want to call something like .toUpperCase() on it. In the (more) real version on the playground I actually call a function to convert primitive values into their object equivalents (like String and Number).

Are there next steps?

This was an experiment! I'm not intending to make something useful out of this. But who knows, maybe I'll continue experimenting!

In the last two posts (1, 2) in this series, I explained why I want Typescript to be more predictable, and some of the most important guidelines I follow to make that happen. Here, I want to dive into a specific library that has helped me significantly improve the predictability of my React components' behaviour: XState.

Why state machines?

There's a pretty common issue that I've seen with React components, where the usage of many different useEffect, useCallback, useState, etc. combined makes for a very unpredictable component: it's very much not obvious what should happen as a result of pressing any button, or any inputs changing. This makes React components very hard to test.

Now one way to resolve this is to be very strict with yourself about decomposing the behavior into separate, bespoke hooks that you can individually test. However, this adds a lot of cognitive overhead and often many refactors.

A state machine can clarify this process by restricting both the states that a component can be in, as well as the ways that it can get to that state. This makes it easier to develop, as there is less cognitive overhead of keeping in mind all the possible hooks that could affect your changes. Instead, you simple modify the state graph at the relevant part and you don't worry about the rest of the states.

XState 101

A state machine^[1] is a simple chart of different states that the machine can be in, and the transitions between those states. Complexer machines will have "submachines" within states. It's pretty straightforward, and the XState docs do a better job of explaining it.

Here's a simple example XState machine:

const machine = createMachine({
  tsTypes: {},
  schema: {} as {
  },
  id: 'trafficLight',
  initial: 'green',
  states: {
    green: {},
  },
});

Predictable XState?

While state machines by their very nature are more predictable than the spaghetti-logic of hooks, there are many ways to make them even stricter. It's important that we make it hard for ourselves to mess up our apps.

The first thing is to strongly type your XState definitions. Using Typescript with XState's typegen is not perfect, but it does a lot to ensure your machines adhere to a certain basic set of rules.

State machines manage to make even complex logic look a lot simpler. It's still important to break up your machines into smaller machines. You'll find yourself building a lot of smaller substates that can split out. I recommend to write your full state graph in one go, but take a moment after to refactor out the submachines.

Rendering out your state machine and running through it in Stately's simulator is also an excellent way of testing your machine has the right states and transitions.

Testing machines

It's important to test your machines. To ensure testable machines, I've resorted to injecting external effects through the machine's context. This way, I can test the machine in isolation by providing mocks in the context. Looks a bit like this:

const fetchMachine = createMachine({
  id: 'fetch',
  initial: 'idle',
  context: {
    fetchService: null
  },
  states: {
    idle: {
      on: {
        FETCH: 'loading'
      }
    },
    loading: {
      invoke: {
        src: (context) => context.fetchService(),
        onDone: {
          target: 'success'
        }
      }
    },
    success: {
      type: 'final'
    }
  }
});

test('fetch machine should reach "success" state', done => {
  // Mock API service
  const mockFetchService = () => Promise.resolve();
  
  // Create a service using the machine with the mock fetch service
  const service = interpret(fetchMachine.withContext({
    fetchService: mockFetchService
  }));
  
  // Listen to state transitions
  service.onTransition(state => {
    if (state.matches('success')) {
      done();
    }
  });

  // Start the service and send the FETCH event
  service.start();
  service.send('FETCH');
});

Beyond XState

XState v5 is also coming soon and promises to bring a bunch of improvements. I'm excited to try out the new stuff.

Additionally, I feel like there's a possibility of a mostly Typescript state graph library. XState feels very heavy to use still, especially when using its type generation and all its various features. I believe there's a possibility to simplify that and to rely mostly on Typescript for enforcing the state machine properties.

While developing RCKIVE, I've done a development against Shopify's GraphQL APIs. I quickly found out that the dealing with GraphQL in Rust could be challenging. Generating Rust serde structs and clients from GraphQL is seamless, but GraphQL's lenient response typing doesn't combine well with Rust's strict typing. Let's illustrate the problem using graphql-client and Shopify's API:

query GetOrders {
  orders(first: 10) {
    edges {
      node {
        id
        displayFulfillmentStatus
        lineItems(first: 10) {
          edges {
            node {
              id
              customAttributes {
                key
                value
              }
            }
          }
        }
      }
    }
  }
}

With the following Rust code:

#[derive(GraphQLQuery)]
#[graphql(
    schema_path = "schema.graphql",
    query_path = "orders_query.graphql",
)]
pub struct OrdersQuery;

That OrdersQuery struct will expand to something like this (heavily edited for readability):

struct GetOrders;
mod get_orders {
    type ID = String;
    pub enum OrderDisplayFulfillmentStatus { ... }

    pub struct ResponseData {
        pub orders: GetOrdersOrders,
    }
    pub struct GetOrdersOrders {
        pub edges: Vec<GetOrdersOrdersEdges>,
    }
    pub struct GetOrdersOrdersEdges {
        pub node: GetOrdersOrdersEdgesNode,
    }
    pub struct GetOrdersOrdersEdgesNode {
        pub id: ID,
        #[serde(rename = "displayFulfillmentStatus")]
        pub display_fulfillment_status: OrderDisplayFulfillmentStatus,
        #[serde(rename = "lineItems")]
        pub line_items: GetOrdersOrdersEdgesNodeLineItems,
    }
    pub struct GetOrdersOrdersEdgesNodeLineItems {
        pub edges: Vec<GetOrdersOrdersEdgesNodeLineItemsEdges>,
    }
    pub struct GetOrdersOrdersEdgesNodeLineItemsEdges {
        pub node: GetOrdersOrdersEdgesNodeLineItemsEdgesNode,
    }
    pub struct GetOrdersOrdersEdgesNodeLineItemsEdgesNode {
        pub id: ID,
        #[serde(rename = "customAttributes")]
        pub custom_attributes: Vec<
            GetOrdersOrdersEdgesNodeLineItemsEdgesNodeCustomAttributes,
        >,
    }
    pub struct GetOrdersOrdersEdgesNodeLineItemsEdgesNodeCustomAttributes {
        pub key: String,
        pub value: Option<String>,
    }
}

Mapping all the way down

To get an attribute from a line item, the resulting queries become deeply nested:

let orders = data.orders.edges;

for order in orders {
    let value = order
        .node
        .line_items
        .edges
        .iter()
        .flat_map(|line_item| &line_item.node.custom_attributes)
        .find_map(|attr| match attr.key.as_str() {
            "custom_attr" => attr.value.clone(),
            _ => None,
        });
}

Now imagine that you want to write a generic function that could work across multiple, similar queries. In Typescript I could easily type the function so that I accept any object that looks has the data I need. This is strict duck typing:

type EdgeNodes<T> = { edges: Array<{ node: T }> };

type HandleXArg = {
    orders: EdgeNodes<{
        line_items: EdgeNodes<{
            custom_attributes: Array<{
                key: string,
                value?: string,
            }>
        }>
    }>
};

function handleX(arg: HandleXArg) {
    // ...
}

However, Rust structs are nominatively typed. I cannot tell the type system to only need specific parts. I could use GraphQL's Fragments, but that would still require me to rewrite my queries if I want to use it in different functions.

substruct

And so I'm building substruct. Let's see some example code first:

#[derive(substructRoot)]
struct User {
    id: String,
    name: String,
    created_at: DateTime<Utc>,
}

#[substruct_child(
    root = User,
    fields(id, name, created_at),
)]
struct FunctionA;

#[substruct_child(
    root = User,
    fields(id, created_at),
)]
struct FunctionB;

#[substruct_use(
    root = User,
    fields(id, created_at),
)]
fn get_name(query: _) {
    println!("{}: {:?}", query.id(), query.created_at())
}

The get_name function now looks almost duck typed!

Under the hood

In the background, we create a getter trait for each field of the root struct. Each child struct then gets implementations for the fields it inherits. Let's look at that first^[1]. We'll start with the root struct:

struct User {
    id: String,
    name: String,
    created_at: DateTime<Utc>,
}

// Getter trait for the `id` field ...
trait __User__Id {
    fn id(&self) -> &String;
}
// ... and its implementation.
impl __User__Id for User {
    fn id(&self) -> &String {
        &self.id
    }
}
// We also create a type alias, we'll get to that later.
type __User__Id__Type = String;

// `name` and `created_at` field traits hidden for brevity.

The child structs reference the field types^[2] and implement the traits. For FunctionA, that looks like this:

// We generate the full struct, referencing the root's field types.
struct FunctionA {
    id: __User__Id__Type,
    name: __User__Name__Type,
    created_at: __User__CreatedAt__Type,
}

// And we implement the getter traits for each field.
impl __User__Id for FunctionA {
    fn id(&self) -> &__User__Id__Type {
        &self.id
    }
}
// Again, imagine the same for `name` and `created_at`...

When modifying a function, substruct then creates a special trait that inherits the getter traits for the required fields. It also immediately implements this trait generically for any type that implements all the getter traits^[3].

trait GetNameInput: __User__Id + __User__CreatedAt {}
impl<T: __User__Id + __User__CreatedAt> GetNameInput for T {}
fn get_name(query: impl GetNameInput) {
    // ...
}

What's next?

Next up would be validating my implementation by integrating it into a GraphQL library. I might fork graphql-client to make this work in there.

To get there, there is one major problem that needs solving. Substruct doesn't yet support the use case I started out with where I want the function to be generic over a deeply nested type. I wonder if leveraging Generic Associated Types (GATs) in Rust could be the solution. This is something I'm eager to experiment with next!

I will add that I'm doing this mostly as an exercise to learn proc macros. Don't expect this to be finished, unless you feel like contributing! However, right now I'm excited to continue developing, and plan to contribute additional documentation to darling (which has been very useful).

This is the second post in a series of blog posts where I explore ways to make Typescript development more predictable. I describe my motivations in-depth in my first post. In this post, I'll focus on a list of concrete techniques to make Typescript development more predictable.

Optional results

Typescript by itself provides a lot of great protections already, but it's not enough to fully satisfy my requirements. The biggest change from regular Typescript development will be transitioning largely to fp-ts paradigms. Its Option<T> type and tooling are a great replacement for a lot of Rust's equivalent tools, and the Either<E, A> type is a good start for an equivalent of Rust's Result<A, E> type.

I don't believe these are necessarily complete solutions: we don't get the ? operator ergonomics here, which means that a lot of function definitions start looking very different. It forces the user to use fp-ts's less intuitive pipes and tasks. There are many alternatives that I'll be looking at, like neverthrow, ts-belt, boxed, true-myth and others. Maybe one of these has better ergonomics.

However, I don't see how anything can add a ? operator. The most signficant improvement we may get is the pipeline operator, which could replace calls to pipe with a more readable syntax.

Read or write?

A commonly hailed paradigm even in current frontend development is immutability. To minimize side-effects, it's become common practice to avoid ever modifying objects. In Rust, this is actually enforced by the type system through mut variables: everything's immutable by default. While we probably can't reproduce that in Typescript, we can get quite far by just making as many things immutable as possible.

Typescript comes with the readonly keyword and some built-in readonly types that we can use on our function definitions. For types coming from outside of our system we can use type-fest's ReadonlyDeep^[1] to restrict it.

However, this does not enforce "immutable by default", and it's quite difficult to do so. There are some open issues on Typescript's Github (and a TC39 proposal) that would make this a lot easier, but for now we'll have to rely on linting. For that, I recommend the functional/prefer-immutable-types^[2] and explicitly ignoring any exceptions.

Ergonomics

One of the big gamechangers of my Typescript work has been ts-pattern. It works almost the same as Rust's match statement, can do exhaustive matching on every type, extractions from patterns, etc. It's great.

Additionally errors in Javascript are awful to work with. But there is a cure, and combining ts-strict-error^[3] with ts-pattern makes for a much nicer experience handling errors.

Guarding the gateways

Many of the errors I've run into (both in Typescript and in other languages) stem from badly defined or badly followed API contracts. Nowadays, I make sure to always validate data at the boundary. Either I use a strictly validated codegen library, or I use something like io-ts for defining and validating the data structure. I use this for APIs without a client library, but also sometimes for flaky external libraries. Just be strict about your typings, and make sure to make everything readonly^[4].

There are almost no Javascript libraries I've seen that properly encode their errors. This makes it extremely difficult to work with the failure cases of external libraries. I am starting to build out a library of convertors for external libraries inside ts-strict-error, but it is so far incomplete and I very much welcome pull requests.

Linting

The last big component of making this work will be static analysis of our code. A lot of lints already exist that we can reuse. I'll list some lints and why I believe you should activate them:

• functional/prefer-immutable-types: as explained before, types should only be mutable when we need them to be mutable, and we should always be explicit about this where we use them.
• @typescript-eslint/explicit-function-return-type: in Rust, all functions must have an explicit return type defined. Automatically inferring types is great, but being explicit at some points helps prevent type inferrence accidents across the board. I find functions to be a perfect boundary for this.
• functional/no-throw-statements: errors should be returned as results (or Either, in fp-ts), never thrown.

Remember that you can explicitly ignore eslint rules with // eslint-disable-line rule-name -- comment and use it whenever needed. I recommend using eslint-comments/require-description to ensure you're always explaining why.

One more thing I'd like to lint for, but can't, is wrapping external calls in fp-ts's either.tryCatch, to map any errors from external libraries into StrictErrors. This would ensure that all errors are explicitly caught and handled at calling time. I might try to write a custom lint for this to try it out.

What's next?

I'm collecting these recommendations in my digital garden for now. While testing out this style guide of sorts, I will also be amending that page. If I ever get to a significantly nicer version, I'll probably write another blog post here.

Additionally, there's another blog post coming up in this series. One major improvement in my frontend development workflow has been state machines. Subscribe for email notifications or to the RSS feed to learn more about developing predictable frontends with XState.js!

Javascript errors are bad. I think we can all agree that new Error("...") doesn't give you something super useful to work with. Extending the Error class is surprisingly difficult. After that, actually dealing with the errors turns into a bit of a guessing game on what type of error actually happened.

The right way

I have one sort of "north star" here, which is the thiserror crate in Rust. It allows you to define errors as enums, with strongly typed metadata and even defining which errors can cause a specific variant. Here's a quick example, taken from their documentation:

#[derive(Error, Debug)]
pub enum DataStoreError {
    Disconnect(#[from] io::Error),
    Redaction(String),
    InvalidHeader {
        expected: String,
        found: String,
    },
    Unknown,
}

This then allows you to use Rust's wonderful match-statement to parse the error later:

match err {
    DataStoreError::Disconnect(cause) => ...,
    DataStoreError::Redaction(key) => ...,
    DataStoreError::InvalidHeader { expected, found } => ...,
    DataStoreError::Unknown => ...,
}

Since match requires exhaustive options, this prevents any errors from staying unhandled. It also makes it super easy for libraries to describe and pass any error case.

So what do I want in Typescript?

So we just saw that there are two parts to this: easily creating categories of connected errors, and matching on those errors. In the end, our error definitions will look something like this:

const Disconnect = createStrictError<
  "Disconnect",
  IoError
>("Disconnect");
const Redaction = createStrictError<"Redaction", undefined, string>(
  "Redaction"
);
const InvalidHeader = createStrictError<
  "InvalidHeader",
  undefined,
  { expected: string; found: string }
>("InvalidHeader");
const Unknown = createStrictError<"Unknown", Error>("Unknown");

const DataStoreError = createStrictError<
  "DataStoreError",
  | InstanceType<typeof Disconnect>
  | InstanceType<typeof Redaction>
  | InstanceType<typeof InvalidHeader>
  | InstanceType<typeof Unknown>
>("DataStoreError");

It's not ideal^[1], but it's easy enough to define strong error types, including typed causes and contexts. Additionally, I want to make sure that it's exhaustively matchable using ts-pattern.

match(err.cause)
  .with({ name: "Disconnect" }, ({ cause }) => (/*...*/))
  .with({ name: "Redaction" }, ({ context: key }) => (/*...*/))
  .with({ name: "InvalidHeader" }, ({ context: { expected, found } }) => (/*...*/))
  .with({ name: "Unknown" }, ({ cause }) => (/*...*/))
  .exhaustive();

How do we build that?

Our new error type needs to carry some type information about the potential causes and contexts, as well as a proper differentiable name property to be matched on. We'll use ts-custom-error to resolve the extends Errors issues we alluded to at the start. Our first step is to create a class that can do all these things. We'll create an abstract class to prevent using this error type directly.

import { CustomError } from "ts-custom-error";

abstract class StrictError<
  const Type extends string,
  const Cause extends Error | undefined = undefined,
  const Context = undefined
> extends CustomError {
  // TODO
}

You'll note I've marked all the type parameters as const, since we (probably?) never want any non-const types defined here. Aside from that it's all pretty basic types and classes. We'll give both Cause and Context an option of being undefined, which we'll assume means you don't want the error to use that.

Now, let's define our properties:

abstract class /* ... */ {
  abstract readonly name: Type;
  readonly cause: Cause;
  readonly context: Context;

  // TODO
}

I think this is pretty self-explanatory. They reference the generic types that the class gets instantiated with, and they're readonly because you should never be allowed to modify an error's properties.

The constructor should be pretty simple also:

class /* ... */ {
  /* ... */

  constructor(
    readonly message: string,
    readonly options: { cause: Cause, context: Context }
  ) {
    super(message, { cause: options.cause });

    this.cause = options.cause;
    this.context = options.context;
  }
}

Now we can create subclasses of this like so:

class Disconnect extends StrictError<"Disconnect", IoError> {
  readonly name = "Disconnect";
}

// and it works!
declare const y: IoError; 
const x = new Disconnect("We disconnected!", { cause: y, context: undefined });

This is still quite explicit. First of all, we need to use the full class syntax, and set the name property manually. Secondly, we can't just omit the context property here even though we know it has to be undefined anyway^[2]. Let's fix those one at a time.

Building a class factory

To create these classes repeatedly, it'll be a lot easier if we build what's often called a "factory", or a creator of classes. We'll build up a function. Please don't mind the weird (but valid) formatting here, I've only done that to separate the components.

function createStrictError

  // 1. Type parameters
  <
    const Type extends string,
    const Cause extends Error | undefined = undefined,
    const Context = undefined
  >

  // 2. Function parameters
  (type: Type)

  // 3. Return type
  : new (
    ...params: ConstructorParameters<typeof StrictError<Type, Cause, Context>>
  ) => StrictError<Type, Cause, Context> {
  // TODO
}

To go through that step-by-step:

1. We simply copy the type parameters from the abstract class, which we'll need to construct the StrictError.
2. We need to pass the Type as a value here. You can see this in the example, where we pass the name as both a type parameter and a function parameter for each new error definition.
3. The return type looks a bit daunting, but because of how classes work in Javascript this is how you return a class in Typescript. You can see it says to return a function that:
   • can be called as a constructor (new);
   • takes the parameters of the StrictError constructor;
   • itself returns something of type StrictError.

And then we simply return a new anonymous class:

function /* ... */ {
  return class extends StrictError<Type, Cause, Context> {
    readonly name = type;
  }
}

Except... not quite. In short, an anonymous class has no name. While instances of this class will have names, if we try to analyze the class itself it'll be nameless. This is fine in most cases, but it's not what I would consider complete. Have a look:

class X { name = "X_" }
console.log(X.name) // "X"
console.log(new X().name) // "X_"

const Y = class extends X { name = "Y_" }
console.log(Y.name) // "Y"
console.log(new Y().name) // "Y_"

const z = () => class extends X { name = "Z_" }
const Z = z();
console.log(Z.name) // ""
console.log(new Z().name) // "Z_"

Note that in the const Y = class scenario, the class does get a name, but in the Z scenario, where the class is created by an anonymous function, it stays unnamed (Z.name is empty!). So we need some special magic to assign the class a name:

function /* ... */ {
  const c = class /* ... */ { /* ... */ }
  Object.defineProperty(c, "name", {
    value: type,
    writable: false,
  });
  return c;
}

Required fields only

In our error instantiation new Disconnect("We disconnected!", { cause: y, context: undefined }), we now have to pass context: undefined to the options object. Let's fix that! What we want is a little more complex than making the fields optional though: when Cause is undefined, the cause property on the second parameter should not exist. Same goes for Context and context. This way, there's no fiddling with undefined types.

First, we'll create a simple object type. When Cause is undefined, we want this object to be empty. Otherwise, we'll want the object to have one required key, from: Cause. This can be done with a conditional operator: Cause extends undefined ? object : { from: Cause }.

By mirroring this type for Context, we now have two objects: one that maybe has a from key and one that maybe has a context key. Now all we need to do is intersect those to create an object that could have either or both the from and context keys, based on the generic type parameters Cause and Context.

Let's fix the constructor:

class /* ... */ {
  /* ... */

  constructor(
    readonly message: string,
    readonly options: 
      (
        Cause extends undefined
          ? object
          : { from: Cause }
      ) &
      (
        Context extends undefined
          ? object :
          { context: Context }
      )
  ) {
    super(message, {
      cause: "from" in options ? options.from : undefined,
    });

    this.cause = ("from" in options ? options.from : undefined) as Cause;
    this.context = (
      "context" in options ? options.context : undefined
    ) as Context;
  }
}

Note that the body of the constructor also changed: we're doing some ternary logic to ensure that all the assignments work as intended.

It's all coming together now...

We now have a working version of the example of the start. Go forth and try it! Feel free to include this in your source code. I've also packaged the above as ts-strict-error, licensed under the MIT license.

I'd love to hear any feedback in Github Discussions or on Twitter. I'm also starting a collection of converters from other libraries to StrictErrors, and very much welcome PRs. The distribution of that is still up for debate: I'd prefer not to distribute it along with the library itself, but I'm not sure that making a separate package for each converter is right either. If you have any ideas, please tell me.

I've spent a lot of time building and maintaining React applications. React, with Typescript, is fine, but I keep coming back to the same realisation: it's not Rust. Over the past few years I've been learning Rust, and it has transformed how I write and think about code. However, as I still have to write React, I've been spending a lot of time trying to emulate the benefits of Rust in Typescript.

This is the first part in a series of posts about a "style guide" of sorts for writing Typescript in a way that feels a lot more like Rust. I focus especially on predictability^[1]: the minimisation of undefined behaviour and other known unknowns in my codebases.

What makes Rust predictable?

In programming we often talk about the happy and unhappy paths. Rust is the first language I've used that requires you to explicitly define both. Not only that, but Rust also focuses on good ergonomics for doing that.

The most common example is error handling. In other languages, we're used to seeing throws and catches, which allow you to implicitly ignore an unhappy path and assume that the parent scope will deal with it. Rust handles that entirely differently: any errors that could happen must be explicitly declared as part of the return type with a Result<T, E>. You can still ignore an error and pass it to your parent, but it requires you to choose to do that.

However, there is another important way that Rust encourages covering all paths exhaustively. Rust recognizes through enums that many variables carry not only their value, but also a state. With the match expression, you can then force yourself to handle each state explicitly. This provides the ergonomics for the programmer to define and traverse complex code paths, without the mental overhead of implicit state management.

This principle can be applied beyond just Rust's syntax into development more generally. State machines allow you to strictly model component behaviour; strong typing makes many of these implicit semantic differences explicit; opting in to explicit exception passing allows you to capture almost all possible errors at compile time.

Why not use Rust?

Wait, you might ask, can't you use Rust in the frontend now? And that's true! I could use something like Yew or Dioxus to write my web applications, and I could continue building in React Native (or Swift and Kotlin separately) and maybe use something like Crux for all the shared business logic.

However, I highly value a mature ecosystem, especially for the frameworks you use. I get the most use out of a framework or tool that I don't have to debug myself. I'd much prefer to use a commonly used framework for something as complex as UI^[2], over a new thing that might break in ways that require a lot of effort on my part to debug.

Next up

I'm lining up two more posts in this series: one that is more of an experimental style guide on how I write Typescript (which will also be available as a living document on my homepage), and another specifically on using state machines in React through XState. Additionally, there's a post adjacent to this topic on making errors in Typescript better.

If any of this interests you, be sure to sign up for email notifications, add my blog to your RSS app or what have you, or follow me on Twitter or Mastodon.

I have recently found myself fully maintaining multiple CI/CD workflows for the first time. It's been exciting setting up the initial workflow, but now it's a huge pain making small changes to it. I'm going to be exploring automated testing of the CI/CD workflows themselves while exploring a few specific types of (reusable) workflows.

I'm calling it relez^[1].

Repository automation

Now, let's talk about what I'm actually trying to tackle here. CI/CD covers a lot of things, and I'm going after a very small, specific portion of it, in a way tailored for a very particular crowd. There's probably a better name already out there (and I'm open to better suggestions), but I'm going to term it "repository automation".

What relez will not cover is the testing and release actions themselves. There are plenty of methods of running tests, builds, and releases, all generic to different degrees. Make, Bazel, doit, npm scripts, etc. all do their job just fine for the purposes of this exploration. relez will cover the questions of when, how, and why those are run.

I'll be (vaguely) defining a Git flow and collection of automations within relez that I've dubbed relez-flows. It's described in-depth in My ideal versioning and releasing workflow^[2], so what I'd like to cover here is the experimentation around testing those flows. relez-flows will initially cover the most complex workflow described there.

Testing that the tests are run

Maybe more importantly, I'd like to enable my own flows experimentation through test automation. A full set of automations quickly becomes as complex as a minor application, and when making even small changes to CI/CD workflows you are effectively testing in production. You can dogfood in a private/less important repo, but that doesn't make the A-Z workflow easier to test.

To tackle this challenge, I'm experimenting with testing relez-flows under the name relez-tests. This set of tests and utility tools will test the Github Workflows and Actions, for now using Bats and Github CLI to run the automation in real repositories. By building them in parallel I have a reason to build the tests, as well as a way to test the flows.

relez's future

I don't really feel a need to define a future for relez, but I'd like to be able to use it in my own repositories as soon as possible. It'll need to make quite a few big steps to make this possible. After finishing the flows, relez will need a method of deployment as well as a method of pushing updates to dependent repositories. relez will need to cover the different versioning workflows to allow using it in my backend repository.

Additionally, it would be nice if this produced something usable by others. If this ends up being useful for myself, I will most likely write more blog posts about it. Potentially, it could also grow into a set of libraries and utilities that could be reused to build other reusable flows.

The dream here is for both relez-flows and relez-tests to be platform-agnostic. At some point, most source management/CI platforms do the same things and it should be possible to deploy the same workflows across them.

In conclusion...

I won't make any promises here on relez's functionality, direction, or even continuation. Currently, it's an experiment that hopefully turns into something useful for myself.

If you're interested in this at all, feel free to come hang out in the repository's discussions tab, star the repo, PR, or message me on Twitter or Mastodon.