DEV Community: TJF

Class-based enums in Typescript: Are they worth the trouble?

TJF — Mon, 05 Oct 2020 16:33:31 +0000

One of Javascript’s most glaring omissions is first-class support for enums. Anyone who’s spent time in other languages knows the value of these simple structures, so it’s no surprise that one of Typescript’s few language additions is the enum. But Typescript’s implementation is quite basic — under the hood, they’re just objects, and this presents two significant pain points.

Problem 1: Iteration over Typescript enums requires converting to Array

This might seem like a nitpick since ES6 gave us Object.values — but if we consider the most common use cases for enums, there’s a constant need for iteration. Converting every time we need to populate a list or dropdown is a nuisance, but there’s a hidden cost: the resulting type is no longer an enum, but a string. This quickly leads to situations where string values taken directly from an enum won’t be accepted anywhere we expect an enum.

enum Priority {
  'HIGH',
  'MEDIUM',
  'LOW',
}

const logError = (priority: Priority) => { ... }
const priorities = Object.values(Priority)

// Error: Type 'string' is not assignable to type 'Priority'
logError(priorities[0])

Even if we try to annotate upstream, the problem persists.

// Error: Type 'string' is not assignable to type 'Priority'
const priorities = Object.values<Priority>(Priority)
const priorities: Priority[] = Object.values(Priority)

Our only option is to cast or assert, which defeats the purpose of working with strong types and creates unhelpful noise in our code.

Problem 2: Typescript enums can’t be extended

Enums in Python or Java are classes, which allows for custom attributes and methods directly on the enum. Some code philosophers argue this goes against the ethos of enums, which are meant to be static lists and nothing more. In my experience, however, enums don’t live in isolation from changes in the application, and they’re rarely static. Consider a few common requirements that any application might present:

Define a static sort order for iteration/display
Custom toString for localization or business logic
Deprecating values without deleting
Static subsets of values

Class-based enums make it possible colocate these features with the enum itself. Classes may have fallen out of vogue in the shift to functional-reactive styles over the last few years, but this is a situation where classes could offer the more declarative approach. How might we accomplish this in Typescript?

Writing a class-based enum in Typescript

Let’s start with the code, and then walk through its features.

export class Priority {
  static asArray: Priority[] = []

  // Values
  static readonly CRITICAL = new Priority('CRITICAL')
  static readonly HIGH = new Priority('HIGH')
  static readonly MODERATE = new Priority('MODERATE')
  static readonly MEDIUM = new Priority('MEDIUM', true)
  static readonly LOW = new Priority('LOW')

  // Subsets
  static readonly GENERATES_WARNINGS = [
    Priority.CRITICAL,
    Priority.HIGH,
  ];

  static readonly ACTIVE = Priority.asArray
    .filter(({ deprecated }) => !deprecated)

  constructor(
    public readonly value: string,
    public readonly deprecated = false,
  ) {
    Priority.asArray.push(this)
  }

  valueOf() {
    return this.value
  }

  toString() {
    return someLocalizationFunction(this.valueOf())
  }

  get order() {
    return Priority.asArray.indexOf(this)
  }
}

First, we define the static collection asArray, as this needs to be instantiated before any values can be added. Next, we create our Priority enums. Take note that MEDIUM uses a second argument of false to designate itself as deprecated. If we look ahead to the constructor, we see that deprecated is defaulted to false for other enums, and each new Priority is getting added to the static asArray collection. After the individual values are created, we can create arbitrary subsets of values manually or by using other properties of the enum.

Lastly, we have our accessors. Using valueOf() and toString() provides a consistent interface with ECMAScript’s objects and strings. For our order getter, we’re able to rely on the definition order of the values themselves (represented in asArray), which provides a simple mechanism to define sort order.

This gives us everything we need to start using our new enum class just like we would a Typescript enum:

const logError = (priority: Priority) => { ... }

const logCritical = logError(Priority.CRITICAL)
const logAll = Priority.asArray.map(logError)
const logWarnings = Priority.GENERATES_WARNINGS.map(logError)

This looks great! We’ve solved for many common use cases and preserved type safety. But has this been worth all the effort?

Class-based enums have significant drawbacks

There are some issues with our implementation.

As soon we start creating more enums, we’ll find ourselves attempting to factor out the common operations — but this proves to be challenging. We could make a base Enum class and move some functions like toString() and valueOf(). However, all of our static members are specific to each enum, and can’t be abstracted away. Type definitions also can’t moved to the base class, as we would need to use generics — but generics cannot be applied to static members. The end result is that even with some clever abstraction, there will still be a lot of duplicated code with each new enum.

Another problem is that these enums require instantiation. If we’re ingesting raw data from an external source — say, some JSON with a property we want to annotate:

interface PrioritizedError {
  error: {
    priority: Priority
  }
}

const errorData: PrioritizedError = {
  error: {
    priority: 'CRITICAL' // Invalid type
  }
}

We can’t annotate errorData with our PrioritizedError interface as-is. We would first have to transform this data to ensure that error.priority gets instantiated with our Priority enum.

// Data we received from an API
const originalData = {
  error: {
    priority: 'CRITICAL'
  }
}

// The transformed data now carries our enum
const transformedData = {
  error: {
    priority: Priority[originalData.error.priority]
  }
}

This creates a gap between the original data and the data used by the application. We face the reverse issue anywhere we might be sending data to an external source, requiring another transformation back into string format. This introduces additional layers in a pipeline that might otherwise have been seamless. Every time we touch data is another opportunity for bugs and corruption.

This transformation issue isn’t just isolated to file read/writes or API requests. Third-party libraries won’t accept our enums, so we may have to transform back-and-forth within individual components. It’s these handoffs that are particularly dangerous, as external dependencies might not warn us when we’ve failed to provide data in the expected format.

So, are class-based enums worth the effort? As with most things, I think the answer is a rock-solid “it depends”.

These implementations are certainly not optimal — I’m sure there’s plenty that could be improved on, leveraging some more advanced features in Typescript. Some of these improvements might properly address scalability / DRY issues. Still, the decision mostly comes down to your application’s needs.

If you find that some of your enums tend to come with tightly-coupled business logic or you need a structure that flexibly supports additional properties and metadata, this may be a useful pattern. But if you just want easy iteration and don’t need any custom methods, class enums are probably overkill. I would exercise particular caution in situations where it becomes necessary to add new transformations.

A short & terrible history of CSS: Does it ever get better?

TJF — Tue, 29 Sep 2020 15:42:52 +0000

If you fell into a coma in 2005 and woke up today (yikes), what would you need to learn to catch up with modern CSS?

The first stop would have to be flexbox and grid — arguably the most important new features of the language. Well-implemented with a strong conceptual backbone and a consistent vocabulary, they (mostly) take the guesswork out of layout. We still can’t do proper masonry layouts and it’s hard to remember the difference between align-items and align-content, but at least we’ve left float behind.

HTML5 arrived with semantic elements, promising improved accessibility and machine readability. But more questions than answers resulted. Vague element names rooted in the world of print media were added: aside, section, and details appeared without a clear purpose in the application development landscape. Many of these elements brought a host of new default browser styling, completely undocumented. CSS resets emerged to cleanse the palate and bring consistency.

Media queries and relative units deserve mention for enabling responsive design amidst the switch to mobile, but the honor is dubious. Breakpoints and font-based scaling are crude tools in the fight to support a vast range of devices that come in every shape, size, and pixel density. Browsers have stepped in to help with device simulators, while frameworks like Bootstrap give folks a reasonable starting point — at the cost of injecting huge stylesheets that are difficult to customize or override. Collectively, humanity has probably lost centuries in the time spent struggling to make minor tweaks to Bootstrap forms.

On the build side, SASS and LESS have made it possible for CSS to support larger websites and applications, pretty much entirely by the virtues of nested selectors and reusable variables. Combined with hot reloading from tools like webpack and in-place editing with autocomplete through browser dev tools, the development flow for debugging and experimentation requires far less context-switching than it once did.

But the advanced features in preprocessors enable fragile anti-patterns that are difficult to debug and even harder to read. There are no established frameworks for managing stylesheets in large applications — inconsistent spaghetti is inevitable. Linters can offset some of these maintainability issues, but the global scope is inexorable. One typo in one rule can mangle any application’s display, and no test will be the wiser.

Thus, we find ourselves at the end of the timeline with CSS Modules and CSS-in-JS. These solve the scoping problem — a huge, necessary scalability win — but introduce new tribulations for reusability. Legibility in the DOM suffers as generated class names obfuscate intent. Performance drops as two decades of browser optimizations for rendering cascading stylesheets goes out the window. Separation of concerns dissolves as each component file now hosts a hundred lines of border-blah styles before the code even begins.

Congratulations! We’re all caught up on fifteen years of CSS. In total, we got two excellent specs for layout and a handful of tools that all fight each other. This a bit hyperbolic, of course (who could forget the indispensable page marks spec?), but we’ve mostly traded one set of problems for another. Just as we left behind the eternal struggle with Internet Explorer, mobile devices came in to detonate the possibility space.

The language simply hasn’t kept up — but why? CSS renders the entire web! Millions of programmers, designers, and unfortunate interns work with CSS every day. It’s worth our time to make this experience better; our creative capacity is limited by the quality of our tools.

Enough complaining, though. We know CSS is a bad experience — water is blue, the sky is wet. No one is coming to save us. What could we do to change this? Let’s think big. Full-throttle, pie-in-the-sky stuff.

Syntactic sugar. Nested and parent selectors supported in native CSS would be a great start; anything to lessen the need for preprocessors just to get the most basic quality of life improvements.
First-class IDE support. There’s plugins for intellisense and code peeking when writing classes and styles in HTML and JSX, but they’re stopped cold by any number of tools and dependencies that abstract styles away from markup. There’s autocomplete for writing directly in stylesheets, but these don’t provide context or definitions like a fully-featured language might offer. Fluency with CSS shouldn’t demand memorization of its entire vocabulary and logic.
Better specificity resolution. A relentless gotcha through the CSS experience is that collisions in specificity are resolved by using the last defined rule in the stylesheet. There’s nothing wrong with this on its own, except that a) it’s so easy to write selectors with equal specificity and b) order is not easily deterministic. With file concatenation and imported stylesheets from dependencies, we can’t rely on definition order. !important provides an escape hatch, but it’s an excessively nuclear option that breaks the most fundamental concept in CSS. Instead, a decorator applied at the selector or individual property level to give priority at its existing specificity could address this gap. More radically, we could define our own rules for precedence based on the needs of the application.
Customize the cascade. The rules of inheritance are countless, obtuse, and the single greatest source of confusion. Why does text-emphasis inherit but text-decoration does not? I’m sure there’s a valid reason somewhere in the story behind these specs — but as a consumer of this API, I don’t care. I need consistency and predictability. What if we could eliminate the guesswork and dictate inheritance per-property or per-selector?
Validation between styles and components. In React Native, you can get an immediate warning if you try to add text style properties to a non-text component — saving countless hours of fruitless tinkering. Currently, this kind of validation isn’t supported in HTML because any tag can (theoretically) support any property. If we could create and specify a style type for any component, this could prevent us from using invalid properties or values.

It turns out that someone else has already thought of this future: enter the CSS Houdini specifications, which offer direct access to the rendering engine. It enables custom parsing of selectors — a path towards syntactic sugar. It supports custom properties — a mechanism for controlling inheritance and default values. It provides typed object models for properties and values — style validation becomes possible!

When I started writing this piece, I had no idea this spec was under development— and I suspect this is true for many others. This great walkthrough by Tab Atkins currently has 32 views. This talk by Sam Richards has 900. Sure, some people are aware and excited — but the overwhelming perception I see among developers is that CSS as a whole is just legacy baggage, an atrophied limb of web development waiting to fall off.

I know better than to believe an incomplete spec — one that’s still in proposal and working draft phase after several years — is going to provide relief any time soon. Done properly, however, CSS Houdini could elevate the work of front-end design and UX development into something that is both more predictable and more expressive. After decades of spaghetti specifications and unreliable tooling, this is something worth being excited about in the ecosystem of web design.

Migrating to Typescript: Keeping it smooth & steady

TJF — Tue, 22 Sep 2020 22:05:12 +0000

In the process of transitioning two mature frontend codebases (totalling ~5k files / 300k lines) from Javascript to Typescript, I learned a bit about the process that might be helpful to anyone considering this change in their stack. Much of this advice is not really specific to Typescript, and could possibly be generalized to any language or framework migration — but I’ll stick to what I know.

1. Write all new code in Typescript — sometimes

Don’t create extra work for your team down the road by pushing more code to be migrated later — as soon as Typescript has been introduced into your stack, every pull request going forward should be written in TS. But how strict should this be? It’s easy enough to write new files and components in TS, but what about changes to existing files? If a pull request changes just one line in a file, should the whole file be converted?

Requiring devs to migrate every changed file can be a morale and productivity killer. Even the smallest bug fixes become chores, and PRs for new features are impossible to review as the diff often interprets migrated files as being new. On the other hand, if the migration isn’t required, the work might never get done. This is particularly true for older files that aren’t edited often. Find the balance that makes sense for your team and keeps the migration moving forward.

2. Convert common files and generic components first

You’ll get the most immediate benefit from Typescript’s features by targeting the files most likely to be imported in any new feature work. If these shared components aren’t converted, you’re building up tech debt in all of your new TS files. Get ahead of this and enjoy the autocomplete and instant errors on all your new files.

Use the most accurate type available for all the properties of the API on these core components. It can be challenging to find the exact type for functions, callbacks, and events (especially for React events, DOM properties, or third-party dependencies), but it will save you trouble downstream in your consumers. Going slowly to get the core components right will save you time overall.

3. Communicate with your team about upcoming migrations

Migrations can sometimes create huge diffs that lead to nightmarish merge conflicts if multiple devs are working in the same file. Don’t set yourself up for pointless hours of frustrating and buggy conflict resolutions. Check in with your team before starting a migration. If there’s significant activity in that area of the code, consider postponing the work or basing your branch from theirs.

4. Resist the urge to refactor

When migrating any large codebase, you’ll inevitably find yourself opening ancient files with terrible debt. Gross, look at all these deprecated patterns and inefficiencies. Oh, you could totally write this in a third of the lines. No one’s using this function any more, right? Snip-snip.

It’s hubris. Don’t do it. You’re going to create regressions. Be good to yourself and your team. Don’t stress QA out.

5. Avoid maintaining parallel versions of the same component

Sometimes, migrating a complex or highly-used component is just too fraught to risk an in-place conversion — in such situations, the only choice might be to duplicate, convert, and gradually swap out the old for the new throughout your codebase. But as long as both versions exist, there will be confusion about which one to use; the old one will get imported by habit or copy-paste; bug fixes and enhancements will need to be applied to both; behavior may even drift over time.

Minimize the amount of time spent in this situation — when adding a duplicate TS component, prioritize this area of migration. Name your files and components clearly to avoid confusion when importing.

6. Account for migrations in estimations and planning

When providing time or point estimates for future work, add another 20% if you plan on migrating the code first. Plan out your migrations; if you know that major work is upcoming in one area, get the migration done early. Don’t leave it as an invisible or unexpected cost.

7. Leave a comment whenever you use `ts-ignore` or `any`

Some of your third-party dependencies are going to give you incorrect type definitions that leave you scratching your head for days. An obscure corner case with generic tuples will send you down a Stack Overflow wormhole for 5 hours. The greatest good is to keep moving forward and leave good comments whenever you’re forced into a hack.

8. Don’t let it linger

One of the possible migration routes for Typescript is to progressively increase its strictness; turning off these rules can be helpful while getting started, but delaying this for long will hold your team back from the full benefits of the language. It can be a high cost initially as you get the necessary dependencies migrated so even a single component can be fully typed, but it’s better than facing a massive diff on the horizon once you do enable it.

There will be boom and bust periods in the speed of change, but mid-migration tech debt is exhausting to deal with. You can never remember which component has been converted already or not. You still can’t trust the IDE to catch some of the biggest mistakes in your code. Why did we even start this stupid transition in the first place?

But the virtues of a strongly typed language grow exponentially as more of the codebase is converted. The first time you refactor a core component and the compiler immediately tells you down to the line and column where the fixes are needed, it’s all worth it. Most other languages have had this experience for decades, of course, but not Javascript.

Good luck! It’s a lot of work, but it will eventually pay off.