Forem: Paolo Longo

TypeScript: a new Frontier for Error Management

Paolo Longo — Tue, 01 Oct 2024 12:22:42 +0000

(Article originally written on Level Up Coding.)

You're working on your TypeScript project. The code is clean and well-architected, you're proud of it. One day, an error pops up. Its stack trace stretches longer than the average npm install, bubbling up through countless layers that failed to handle it. Your code doesn't work, you have no idea where to start fixing it, every attempt feels like a clumsy patch. Your architecture doesn't look so clean anymore. You hate your project. You close your PC and go to enjoy your Friday.

The Error Management Wasteland

JavaScript's error management falls short of the expressive power and developer experience offered by modern languages like Rust, Zig, and Go. Its dynamic nature and lack of guardrails often leave developers navigating uncertainty, without the solid foundations and guarantees that stricter platforms provide.

This crucial pillar of software engineering is poorly reflected in the language's culture and ecosystem, with some of the most popular npm libraries failing to even mention exceptions in their documentation.

This lack of standards fosters in developers the misconception that exceptions rarely occur. As a result, this skewed perspective leads to a lack of interest in establishing such standards within the community, and ultimately riddles most codebases with subtle, hard-to-spot bugs.

Try-Catch: the Costs of Implicitness

The JavaScript try-catch model hides non-obvious implications. Exceptions can occur anywhere, yet anticipating them is surprisingly challenging. This seemingly simple pattern often obscures subtle pitfalls in everyday code:

let value;
try {
  value = mayThrow();
} catch (e) {
  // Handle the exception.
}

The first issue that stands out in the snippet is the scope expansion, with variables needing to be declared outside the try-catch block to maintain a contiguous control flow. This leads to more verbose, harder-to-track code, potentially introducing subtle bugs as the codebase grows in complexity.

The implicit nature of this dynamic error handling increases the cognitive load on the developers, requiring them to mentally track exception sources throughout the codebase. In contrast, explicit error handling models, like for instance the one in Go, compel developers to acknowledge and handle any error.

result, err := mayFail();

This is a huge win in the long term, facilitating smoother and safer maintenance as projects evolve.

Adding to these challenges, TypeScript's catch clause falls short in its ability to track and strictly type the errors that can be thrown, resulting in a loss of type safety at precisely when it's most crucial. JavaScript even allows throwing non-Error values, leaving us with practically no safeguards. Languages like Rust showcase the power and elegance that a stricter model can provide:

match may_fail() {
  Ok(result) => println!("Success"),
  Err(Error::NotFound) => println!("Not found"),
  Err(Error::PermissionDenied) => println!("Permission denied"),
}

Various proposals have been submitted to the TypeScript team, aiming to establish a foundation for a more robust and predictable exception system. However, these proposals have often been blocked by limitations in the underlying JavaScript platform, which lacks the necessary primitives to support such architectural enhancements.

Meanwhile, some proposals to address these shortcomings have also been submitted to TC39 (the committee for ECMAScript standardization), but they remain in the early stages of consideration. As Matt Pocock pointed out, the heat death of the universe is also making steady progress.

// Detect dark theme var iframe = document.getElementById('tweet-1824338426058957098-425'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1824338426058957098&theme=dark" }

Seeking Community Solutions

When a language creates friction for innovation, the developer community often responds with ingenious libraries and user-land solutions. Many of the current proposals in this domain, like the exceptional Neverthrow, draw inspiration from functional programming, offering a suite of abstractions and utilities similar to Rust's Result type to address the problem:

function mayFail(): Result<string> {
  if (condition) {
    return err("failed");
  }

  return ok("value");
}

Another approach that stands out is the one of Effect. This powerful toolkit not only tackles error management head-on but also provides a comprehensive suite of utilities for handling asynchronous operations, resource management, and more:

import { Effect } from "effect";

function divide(a: number, b: number): Effect.Effect<number, Error> {
  return b === 0
    ? Effect.fail(new Error("Cannot divide by zero"))
    : Effect.succeed(a / b);
}

const result = Effect.runSync(divide(1, 2));

Outside the joy of a nerd like myself in digging into tech like this, adopting new technologies demands a careful cost-benefit analysis. The JavaScript ecosystem evolves at a breakneck pace, with libraries emerging and becoming obsolete in rapid succession.

Choosing the wrong abstraction can hold your code hostage, create friction in your development process, and demand blood, sweat, and tears to migrate away from. (Also, adding a new package is likely not gonna help with the 200mb bundle size of your React app.)

Error management is a pervasive concern that touches nearly every part of a codebase. Any abstraction that requires rethinking and rewriting such a vast expanse of code demands an enormous amount of trust—perhaps even faith—in its design.

Crafting a Path Forward

We've explored the limitations of user-land solutions, and life's too short to await commit approvals for new syntax proposals. Could there be a middle ground? What if we could push the boundaries of what's currently available in the language, creating something that aspires to be a new standard or part of the standard library, yet is written entirely in user-land and we can use it right now?

As we delve into this concept, let's consider some key principles that could shape our idea:

Conventions over Abstractions: Minimize abstractions by leveraging existing language features to their fullest.
Minimal API: Strive for simplicity without sacrificing functionality. Conciseness is often an indicator of robust and lasting design.
Compatibility and Integrability: Our solution shouldn't depend on universal adoption, and must seamlessly consume and be consumed by code not written with the same principles in mind.
Intuitive and Ergonomic: The patterns should be self-explanatory, allowing developers to grasp and implement them at a glance, minimizing the risk of misinterpretations that could result in anti-patterns or unexpected behaviors.
Exploit TypeScript: Leverage TypeScript's type system to provide immediate feedback through IDE features like syntax highlighting, error detection, and auto-completion.

Now, let's dive into the heart of the matter by addressing our first key challenge. Let's introduce the term task for functions that may either succeed or encounter an error.

function task() {
  if (condition) {
    throw new Error("failed");
  }

  return "value";
}

We need an error-handling approach that keeps control flow clean, keeps developers constantly aware of potential failures, and maintains type safety throughout. One idea worth exploring is the concept of returning errors instead of throwing them. Let's see how this might look:

function task() {
  if (condition) {
    // return instead of throwing.
    return new Error("failed");
  }

  return "value";
}

By introducing Errors as values and assigning them specific meaning, we enhance the expressivity of a task's return value, which can now represents either successful or failing outcomes. TypeScript’s type system becomes particularly effective here, typing the result as string | Error, and flagging any attempt to use the result without first checking for errors. This ensures safer code practices. Once error checks are performed, type narrowing allows us to work with the success value free from the Error type.

const result: string | Error = task();

// Handle the error.
if (result instanceof Error) {
  return;
}

result;
// ?^ result: string

Managing multiple errors becomes reliable with TypeScript’s type checker, which guides the process through autocompletion and catches mistakes at compile time, ensuring a type-driven and dependable workflow.

function task() {
  if (condition1) return new CustomError1();
  if (condition2) return new CustomError2();
  return "value";
}

// In another file...
const result = task();

if (result instanceof CustomError1) {
  // Handle CustomError1.
} else if (result instanceof CustomError2) {
  // Handle CustomError2.
}

And since we're just working within plain JavaScript, we can seamlessly integrate existing libraries to enhance our error handling. For example, the powerful ts-pattern library synergize beautifully with this approach:

import { match } from "ts-pattern";

match(result)
  .with(P.instanceOf(CustomError1), () => {
    /* Handle CustomError1 */
  })
  .with(P.instanceOf(CustomError2), () => {
    /* Handle CustomError2 */
  })
  .otherwise(() => {
    /* Handle success case */
  });

We now face 2 types of errors: those returned by tasks adopting our convention and those thrown. As established in our guiding principles, we can't assume every function will follow our convention. This assumption is not only necessary to make our pattern useful and usable, but it also reflects the reality of JavaScript code. Even without explicit throws, runtime errors like "cannot read properties of null" can still occur unexpectedly.

Within our convention, we can classify returned errors as "expected" — these are errors we can anticipate, handle, and recover from. On the other hand, thrown errors belong to the "unexpected" category — errors we can't predict or generally recover from. These are best addressed at the highest levels of our program, primarily for logging or general awareness. Similar distinctions are built into the syntax of some other languages. For example, in Rust:

// Recoverable error.
Err("Task failed")

// Unrecoverable error.
panic!("Fatal error")

For third-party APIs whose errors we want to handle, we can wrap them in our own functions that conform to our error handling convention. This approach also gives us the opportunity to add additional context or transform the error into a more meaningful representation for our specific use case. Let's take fetch as an example, to demonstrate also how this pattern seamlessly extends to asynchronous functions:

async function $fetch(input: string, init?: RequestInit) {
  try {
    // Make the request.
    const response = await fetch(input, init);
    // Return the response if it's OK, otherwise an error.
    return response.ok ? response : new ResponseError(response);
  } catch (error) {
    // ?^ DOMException | TypeError | SyntaxError.
    // Any cause from request abortion to a network error.
    return new RequestError(error);
  }
}

When fetch returns a response with a non-2XX status code, it's often considered an unexpected result from the client's perspective, as it falls outside the normal flow. We can wrap such responses in a custom exception type (ResponseError), while keeping other network or parsing issues in their own type (RequestError).

const response: Response | ResponseError | RequestError = await $fetch("/api");

This is an example of how we can wrap third-party APIs to enrich the expressiveness of their error handling. This approach also allows for progressive enhancement — whether you’re incrementally refactoring existing try/catch blocks or just starting to add proper error types in a codebase that’s never even heard of try/catch. (Yes, we know you’re out there.)

Another important aspect to consider is task composition, where we need to extract the results from multiple tasks, process them, and return a new value. In case any task returns an error, we simply stop the execution and propagate it back to the caller. This kind of task composition can look like this:

function task() {
  // Compute the result and exclude the error.
  const result1: number | Error1 = task1();
  if (result1 instanceof Error1) return result1;

  // Compute the result and exclude the error.
  const result2: number | Error2 = task2();
  if (result2 instanceof Error2) return result2;

  const result = result1 + result2;
}

The return type of the task is correctly inferred as number | Error1 | Error2, and type narrowing allow removing the Error types from the return values. It works, but it's not very concise. To address this issue, languages like Zig have a dedicated operator:

pub fn task() !void {
  const value = try mayFail();
  // ...
}

We can achieve something similar in TypeScript with a few simple tricks. Our goal is to create a more concise and readable way of handling errors while maintaining type safety. Let's attempt to define a similar utility function which we'll call $try, it could look something like this:

function task() {
  const result1: number = $try(task1());
  const result2: number = $try(task2());

  return result1 + result2;
}

This code looks definitely cleaner and more straightforward. Internally, the function could be implemented like this:

function $try<T>(result: T): Exclude<T, Error> {
  if (result instanceof Error) throw result;
  return result;
}

The $try function takes a result of type T, checks if it's an Error, and throws it if so. Otherwise, it returns the result, with TypeScript inferring the return type as Exclude<T, Error>.

We've gained a lot in readability and clarity, but we've lost the ability to type expected errors, moving them to the unexpected category. This isn't ideal for many scenarios.

We need a native way to collect the errors types, perform type narrowing, and terminate execution if an error occurs, but we are running short on JavaScript constructs. Fortunately, Generators can come to our rescue. Though often overlooked, they can effectively handle complex control flow problems.

With some clever coding, we can use the yield keyword to extract the return type from our tasks. yield passes control to another process that determines whether to terminate execution based on whether an error is present. We’ll refer to this functionality as $macro, as if it extends the language itself:

// ?^ result: number | Error1 | Error2
const result = $macro(function* ($try) {
  const result1: number = yield* $try(task1());
  const result2: number = yield* $try(task2());

  return result1 + result2;
});

We'll discuss the implementation details later. For now, we've achieved our compact syntax at the cost of introducing an utility. It accepts tasks following our convention and returns a result with the same convention: this ensures the abstraction remains confined to its intended scope, preventing it from leaking into other parts of the codebase — neither in the caller nor the callee.

As it's still possible to have the "vanilla" version with if statements, paying for slightly higher verbosity, we've struck a good balance between conciseness and keeping everything with no abstraction. Moreover, we've got a potential starting point to inspire new syntax or a new part of the standard library, but that's for another post and the ECMAScript committee will have to wait for now.

Wrapping Up

Our journey could end here: we've highlighted the limitations of current error management practices in JavaScript, introduced a convention that cleanly separates expected from unexpected errors, and tied everything together with strong type definitions.

As obvious as it may seems, the real strength of this approach lies in the fact that most JavaScript functions are just a particular case of this convention, that happens to return no expected error. This makes integrating with code written without this convention in mind as intuitive and seamless as possible.

One last enhancement we can introduce is simplifying the handling of unexpected errors, which up to now still requires the use of try/catch. The key is to clearly distinguish between the task result and unexpected errors. Taking inspiration from Go's error-handling pattern, we can achieve this using a utility like:

const [result, err] = $trycatch(task);

This utility adopts a Go-style tuple approach, where the first element is the task's result, and the second contains any unexpected error. Exactly one of these values will be present, while the other will be null.

But we can take it a step further. By leveraging TypeScript's type system, we can ensure that the task's return type remains unknown until the error is explicitly checked and handled. This prevents the accidental use of the result while an error is present:

const [result, err] = $trycatch(() => "succeed!");
// ?^ result: unknown
// ?^ err: Error | null

if (err !== null) {
  return;
}

result;
// ?^ result: string

Due to JavaScript's dynamic nature, any type of value can be thrown. To avoid falsy values that can create and subtle bugs when checking for the presence of an error, err will be an Error object that encapsulates the thrown values and expose them through Error.cause.

To complete out utility, we can extend it to handle asynchronous functions and promises, allowing the same pattern to be applied to asynchronous operations:

// Async functions.
const [result, err] = await $trycatch(async () => { ... });

// Or Promises.
const [result, err] = await $trycatch(new Promise(...));

That's enough for today. I hope you’ve enjoyed the journey and that this work inspires new innovations in the Javascript and Typescript ecosystem.

How to implement the code in the articles, you ask? Well, of course there's a library! Jokes aside, the code is straightforward, but the real value lies in the design and thought process behind it. The repository serves as a foundation for ongoing discussions and improvements. Feel free to contribute or share your thoughts!

See you next time — peace ✌️.

ts-zen / trycatch

Robust and Type-Safe Errors Management Conventions with Typescript

Robust and Type-Safe Errors Management Conventions with Typescript

Philosophy

Haven’t read the blog post yet? You can find it here for a deep dive into the design and reasoning behind this project. Here's a quick snapshot to get you started:

JavaScript’s error management falls short of the expressive power and developer experience offered by modern languages like Rust, Zig, and Go. Language design is hard, and most proposals to the ECMAScript or TypeScript committees are either rejected or move through an extremely slow iteration process.

Most libraries and user-land solutions in this area introduce abstractions that fall into the red/blue function problem, requiring full codebase adoption and resulting in technology lock-in.

The goal of this project is to push the boundaries of error handling in JavaScript, prioritizing conventions over abstractions and leveraging native constructs to their fullest potential. We provide a minimal set of utilities to enhance developer experience, with…

View on GitHub

The Aviator🎮 - Test your coding and logic skills with a web game

Paolo Longo — Sat, 20 Jun 2020 14:58:45 +0000

I've always liked challenges and problem-solving. This is the reason that made me embark on a journey into the world of programming.

It started when I was 15, in the high school computer science course, where I wrote my first "Hello World". Looking back, I can see the most significant stages passed so far, in which I have improved, matured, and in which I can identify a before and after.

Now I study computer engineering at university, and I feel I have reached another important stage of this journey. Stage that I want to represent with a project, to test myself and the skills I have gained.

And so was born The Aviator, a coding game for folks like me who like to test themselves.

4 worlds compose the game. The Aviator, the protagonist of this journey, will have to be instructed through code, to overcome the levels of each world.

As with any journey, the difficulty grows over time. Starting from the first simple challenges, the game ends with a last "impossible" level, which represents that stage to reach to mark the beginning of a new part of the journey.

Do you think you can reach it? Well, if you like challenges, what are you waiting for? Test yourself and challenge friends and colleagues 😎

The game is also available on Github.

paol-imi / the-aviator

🎮 Welcome to the Aviator game!

As a computer engineering student and creator of this project, I would recommend tools like this as educational support👨‍🎓 in schools and universities. With targeted design choices and an advanced code debugging system (with time travel), The Game tries to provide the best developer experience and guide the student's reasoning in each challenge.

Special thanks

The inspiration for the protagonist of the game came to me thanks to this fantastic project, from which I took the name and the sprite of the Aviator.

⚛️ Reparenting is now possible with React

Paolo Longo — Sat, 23 May 2020 17:00:04 +0000

Originally published on Medium

I am designing an app similar to Trello. On the main page, I want some vertical Lists and some Cards that can be dragged from one List to another.

How can I transfer a Card component after dragging? With React it seems quite easy. To change the Parent component of a Child component, the components have to be re-rendered with that Child in its new Parent.

In the same way, I can transfer a <Card> into a new <List>.

I implement a first draft of the code and try it, I take a Card with the mouse and drag it between the various Lists. The transfer takes place, but, unfortunately, the Card component is unmounted, re-mounted, and loses its internal state.

Moreover the feedback from the drag animation isn't so positive. When I perform several drags quickly in succession, the App slows down and for a few moments there is a considerable loss of frames.

In fact, the DOM elements of the Card are recreated from scratch and this is having a negative impact on performance. Also, one of the elements is a scrollable <div> that loses its scroll position, I guess other elements such as <video> and <audio> can have similar problems.

With some effort, I can redesign the App to use Card components without a local state, but in any case I cannot avoid that the DOM elements are recreated.

Is it possible to prevent the component from being re-mounted?

Well, if you are reading this article it is likely that the answer is positive :), but when I asked myself the question for the first time I did not find a definitive answer, probably because it was not there yet. Let's continue with the story.

I start looking for an answer in the React repository on Github, maybe there is something useful in the issues section. I find there is a term for what I'm looking for, and it's Reparenting.

"Reparenting aims to improve both the Developer and the User Experience."

Some open issues confirm that React does not yet provide specific APIs to handle it, my hopes that something like React.transferComponent( ) exists quickly fade away.

An approach I discover is ReactDOM.unstable_renderSubtreeIntoContainer( ), the name looks cool but the unstable tag and the fact that this API has been deprecated are enough to make me look for something else. Searches continue on Medium, Dev, and other platforms, the only possible solution seems to be the use of the Portals. A Tweet by Dan Abramov definitely convinces me to try them.

The portals approach

I open the React documentation in the Portals section. I start reading the guide and doing some tests to get familiar with these APIs.



const element = document.createElement('div');

const PortalComponent = ({children}) => {
  return ReactDOM.createPortal(children, element);
};

I know that I cannot move a component elsewhere in the App or it will be re-mounted, so every Child component must be part of the same Parent.

Should I use a portal for each Child? That way I could decide in which container element to render each of them. But how do I create containers? Do I have to write something like document.createElement('div') 🤨? I could instead use ref to other components. Where do I render those components? Refs are empty initially, should I force a second render? I wanted each Parent to provide a different Context, How can I do that if I am forced to use only one Parent?…

What a mess, the more I try to implement it, the more forced the approach seems to me. It doesn't give me the feeling of being very "reactive", probably because portals have been designed for other purposes:

"Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component." - React docs.

This process is more related to the DOM, at the "React level" the Child is still part of the same Parent, not exactly what I am looking for.

The new solution

Maybe I'm looking for a solution in the wrong place, it is possible that, if it exists, it is more internal to React than I think.

What I know is that React represents my App with a tree of instances, where each instance corresponds to a component. When re-rendering a part of the App, its sub-tree is recreated and compared with the old one, so as to find the changes that have been made and update the DOM.

Due to the way this comparison is implemented, there is no way to make React aware of the transfer of a component. Indeed, If I try to re-render a Card component somewhere else, the result will be the unmounting of the component and the mounting of a new one.

How can I change this behavior? I could try to interact with the internal tree, find the instance of the Card that I want to transfer, and insert it in the new List. In this way, after a re-rendering, both the old and the new tree would have the transferred Card in the same place and the comparison would not cause the re-mount of the component, It might work!

Before starting to design a solution, to avoid running into dead ends I impose some constraints that the final result must respect:

It must not rely on any unstable method
Reparenting must be able to work without redesigning the App
It must respect the philosophy and patterns of React

I have a solid starting point, now I have to understand how these react internals are actually implemented. I find out that starting from version 16, React rolled out a new implementation of that internal instances tree named Fiber. I read some articles about it to get a more complete picture, and when I think I have a fairly broad view on the topic, I start to browse the React source code in search of a solution.

After several days of testing and research, I finally have a first draft of code to try, inside a file named react-reparenting.js. I import it into my App, add a few lines of code, and… It works! The Card is not re-mounted and the goals that I have set for myself have all been respected.

This story can finally have a nice ending, I can continue the development of my App. Maybe, for the next obstacle that I will face, I will find a story like this to read.

The end of the story

This story ends with the publication of the package on Github and with the writing of this article. Before presenting it, I want to share with you what my vision is at the end of this project.

I strongly believe that Reparenting is not only a way of managing these situations, but The way, and I also believe that in the future React will implement it natively.

In my opinion, the reason why this feature has not yet been implemented is that the cases in which it is really necessary are not many. Often the elements to be transferred are stateless and very simple, so it is an acceptable compromise to re-mount them since the difference in performance is almost zero, and there is no state or lifecycle to be interrupted.

I'm not saying that React will implement Reparenting as it has been implemented here, or that the APIs that will be provided will be similar to these, but I hope this package, thanks also to its simplicity, can lay the foundations for the use and diffusion of Reparenting.

"Unmounting one component and mounting another identical one is just a simple compromise that works in most cases. The component should always be transferred, without its lifecycle being interrupted."

You can find the package on Github. On the GitHub page you will also find the documentation and links to various examples on Codesandbox.
Now let's see a simple implementation.

First, let's define the <Child> component, we will use a very simple one.

Now we can use the <Reparentable> component, it has to be the direct parent of the children to reparent. Each <Reparentable> must have a unique id.

Now we can reparent a <Child>. First we have to send its fibers using the sendReparentableChild( ) method, then we just have to re-render the App. The transferred component will not be re-mounted.

That's all. It is also possible to create a custom Parent component and use the <Reparentable> inside it.

Special thanks

During the development of this project, I thought that I would lose my mind managing every use case (context, memo, some edge cases with fibers…). With pleasant surprise React worked in each of these cases without modification, a sign of the amazing work that the React Team has done over the years.

I want also to thank the authors of these amazing articles, without them the work would have been longer and more tedious.