Forem: Marcell Toth

Mapping between identical TypeScript enums without the boilerplate

Marcell Toth — Thu, 14 Apr 2022 13:18:43 +0000

TypeScript's enums are weird. They are the only piece in TS (as far as I'm aware) that doesn't follow the structural / duck typing pattern. If you prefer enums in place of string unions, I'm sure you've encountered the following:

You have two enums which contain the same members, yet TS doesn't realize they are compatible. Now I see three main patterns people utilize to resolve the problem:

The IDC approcach: You cast everywhere. This is the easiest, but it is dangerous, as enum casts let you do pretty much anything.
The purist: The types are different because "they represent different things", so you ignore the similarity and create a mapper function (or object) and use it where needed: This is very safe for sure, but adds a lot of maintenance overhead, and code (bundle) size for nooooot a lot of good reasons.
The middle ground: You create a function but cast inside. This looks better than approach no 1 on paper, as you only cast once, but you really are still prone to the same danger: If the two enums diverge at any point, you won't get a single warning from TS.

Type safety without the boilerplate

I was thinking, can we somehow get the type-safety of approach #2 while also retaining the purity and bundle size of #3? It turns out, we can.

On the JS level this 3rd approach is trivial, your mapper functions are essentially x => x.

So now it's "just" the matter of adding TS constraints to make sure we are only allowed to map between identical enums.

The implementation

The core

My current solution only works with symmetrical (same key and values) enums for simplicity, although it could very well be extended. So let's define what is a symmetrical enum first:



type SymmetricalEnum<TEnum> = {
  [key in keyof TEnum]: key;
};

Then - here is the trick - we can define what the result value of a mapping will be, this is essentially doing the mapping on the TS metalanguage level, with all of its benefits:



type MapperResult<
  TSourceEnumObj,
  TDestEnumObj extends SymmetricalEnum<TSourceEnumObj>,
  TSourceValue extends keyof TSourceEnumObj
> = TDestEnumObj extends { [key in TSourceValue]: infer TResult } ? TResult : never;

We have 3 generic args:

The source enum type, which can be anything (you could add a constraint here if you wanted to).
The destination enum type, which needs to extend the source enum. This is the core of the type-safety logic. If you try to map to an enum which is not a superset of the source this line will yell here.
The type of actual input value given to the mapper function. This is then used in a conditional statement to essentially "pull" the corresponding value from the destination type. If you need to read up on Conditional Types I suggest starting with the documentation.

You can use the above on it's own if you need a mapping on the types-level, see this magic for example:

Incompatible enums are rejected - with a pretty clear error message even:

Creating mapper functions

Now we are ready to create a higher order function that auto-generates mapper functions, utilizing this magic.



const createEnumMapperFunction =
  <TSourceEnumObj, TDestEnumObj extends SymmetricalEnum<TSourceEnumObj>>(from: TSourceEnumObj, to: TDestEnumObj) =>
  <TInput extends keyof TSourceEnumObj>(value: TInput) =>
    value as MapperResult<TSourceEnumObj, TDestEnumObj, TInput>;

You can see it in action here, including one error it caught:

And this is it! Now you can replace all your switch statements with a call to createEnumMapperFunction, or replace your casts with a type safe version like this above. Feel free to tweak it to your needs, like adding support for non-symmetrical enums or other cases.

Final code

For those that have the StackOverflow keyboard

here is the full code, and a TS Playground with examples:



type SymmetricalEnum<TEnum> = {
  [key in keyof TEnum]: key;
};

type MapperResult<
  TSourceEnumObj,
  TDestEnumObj extends SymmetricalEnum<TSourceEnumObj>,
  TSourceValue extends keyof TSourceEnumObj
> = TDestEnumObj extends { [key in TSourceValue]: infer TResult } ? TResult : never;

const createEnumMapperFunction =
  <TSourceEnumObj, TDestEnumObj extends SymmetricalEnum<TSourceEnumObj>>(from: TSourceEnumObj, to: TDestEnumObj) =>
  <TInput extends keyof TSourceEnumObj>(value: TInput) =>
    value as MapperResult<TSourceEnumObj, TDestEnumObj, TInput>;

I hope you find this useful some day. Let me know in the comments if you did, and if you have built an improved version I'd also love to know.

Using accessibility guidelines to improve test quality and robustness

Marcell Toth — Sat, 28 Nov 2020 15:15:13 +0000

There's not a lot of talk about Web Accessibility around here. It is viewed as an uninteresting topic, dealt with on an as-needed basis. But it shouldn't be this way!

Let me give you an intro to WAI-ARIA from an angle you probably have never seen before: How to utilize accessibility guidelines to drastically improve your unit tests?

What do Unit Testing and Accessibility have in common? Much more than you would think!

Unit Testing

Let's begin with some (opinionated) Do-s & Don't-s on Unit Testing. I am assuming you are already familiar, this list is not meant to be complete or perfect.

Test the behavior of components. Don't test implementation details
Be resistant to non-user-visible changes in HTML / React structure. Assert from the users' perspective.
Focus on the semantics, don't break if visuals or the copy changes.
Use the app like a regular user would. Don't query artificial constructs (like CSS selectors or ids). Trigger events a user would trigger themselves.

Accessibility

Now what about some guidelines for accessibility?

Write semantic HTML that screen-readers can understand. Don't rely on CSS to convey structure.
Non-user-visible changes in HTML structure should not change screen-reader output either.
Focus first on the core value/functionality provided for your user, styling & fluff comes second.
Your site by should be discoverable by screen-reader the same way it is for regular users. Don't treat headless user-agents as second-class citizens.

Unit Testing + Accessibility = 💞

Now back to the question I asked before:

What do Unit Testing and Accessibility have in common?

Let's put the two lists side by side:

Testing	Accessibility
Test the behavior of components. Don't test implementation details	Write semantic HTML that screen-readers can understand. Don't rely on CSS to convey structure.
Be resistant to non-user-visible changes in HTML / React structure.	Assert from the users' perspective. Non-user-visible changes in HTML structure should not change screen-reader output either.
Focus on the semantics, don't break if visuals or the copy changes.	Focus first on the core value/functionality provided for your user, styling & fluff comes second.
Use the app like a regular user would. Don't query artificial constructs (like CSS selectors or `id`s). Trigger events a user would trigger themselves.	Your site by should be discoverable by screen-reader the same way it is for regular users. Don't treat headless user-agents as second-class citizens.

At this point, looking back at both lists one can start to see the common pattern:

Describe your semantics well in HTML.
Treat headless agents as first-class citizens.

To put it in another way, screen-readers and test environments are very much alike: They are headless user-agents interpreting your DOM structure without putting much if any effort into calculating layout, styling and visuals in general.

Enough talk, let's see some code

Let's start with a simple example, non-semantic vs semantic HTML. I'm sure most of you are familiar with this one already, but let's see the testing implications.

Let's start with this HTML:

<div class="nav">
  <div class="nav-item">
    <strong>First Item</strong>
  </div>
  <div class="nav-item">
    <strong>Second Item</strong>
  </div>
</div>

Let's say in a test we would like to retrieve the first navigation element. We can do that with a simple CSS query like querySelector('.nav > :first-child'), or a text-based selector (most testing frameworks should include one) getByText('First Item').

While both of them work at the moment, both are fragile as they break the constraints we set out earlier:

The first one depends on exact CSS classes, if someone renames .nav to .navigation, the test breaks.
It also depends on the exact CSS structure, adding another div in-between - like grouping the items - or adding a logo before the items will break it as well.
The second one is somewhat better, but depends on the exact words of the copy, which you don't usually want to test.

Let's rewrite this to be more textbook-like semantic HTML:

<nav>
  <ul>
    <li>First Item</li>
    <li>Second Item</li>
  </ul>
</nav>

At this point your CSS query becomes querySelector('nav li:fist-of-type') which is much more robust, it is ignorant of grouping the items or adding a logo. (Unless of course you add the logo as another li which is the wrong thing to do).

Even better would be to query by WAI-ARIA role, which we'll briefly discuss below: getAllByRole(getByRole('navigation'), 'listitem')[0]. This does almost exactly what our plain English requirements said: Retrieves the navigation menu, and within that menu, the first list item.

Roles

In WAI-ARIA, every HTML element can have something called a role. This is either set implicitly, e.g. nav tags have the navigation role by default, or explicitly by applying the role="some-role" attribute.

Let's imagine you are testing some JavaScript that shows this tooltip on some condition. Your goal is to assert that the tooltip is visible.

<div class="text-center w-96">
  Tooltip content
</div>

The simple solution would be to append a data-testid="some-tooltip" and the div then write the assertion as expect(screen.getByTestId('some-tooltip')).toBeVisible(), or similar in another testing framework. But now you are querying an artificial construct - a test-id -, and you've given yourself another string to maintain, which doesn't even add any value from the perspective of someone writing (or reading) the HTML.

What should we do instead? Think about what our goal is. This is a tooltip. We need to assert a tooltip is visible. Then let's do just that: WAI-ARIA has a role called tooltip that is defined as:

A contextual popup that displays a description for an element.

Instead of the test-id, you can add role="tooltip" to the div, then your assertion becomes expect(screen.getByRole('tooltip')).toBeVisible(), which is almost exactly the business-requirement.

I bet if you show this to a business person who has zero JavaScript knowledge they would still understand it.

And this is the power of using roles and possibly other ARIA attributes for testing!

Of course the full WAI-ARIA spec is much more in depth, with many other aspects (attributes, states, etc.) being just as useful for testing. Describing those is beyond the scope of this introductory article, but I encourage you to at least go through the MDN intro on WAI-ARIA to get an overview of the tools available to you.

Thank you for reading, happy testing!

Resources

MDN - Accessibility overview
MDN - HTML accessibility
MDN - Intro to WAI-ARIA
W3 - Definition of Roles

How to build GraphQL APIs with ASP.NET Core & HotChocolate - Part 1 - Setup

Marcell Toth — Sat, 08 Aug 2020 17:55:52 +0000

Getting started with GraphQL as a .NET developer is much simpler than you would think. Let me show you why.

Coming from a REST or MVC background GraphQL looks scary.

I know.

It is very different from what we are used to, especially in the .NET (Core) ecosystem.

There's no (built-in) template. With traditional RESTful APIs (or MVC apps for that matter) you select your template and you get a ready-to-run solution right away. Not with GraphQL. This makes it look like GraphQL on ASP.NET Core is complicated and a pain to get started with.

I am here to show you, it is not.

In this article I will show you how to:

Set up HotChocolate and GraphiQL for your ASP.NET Core application.
Define types from your GraphQL schema using C#.
Create your resolvers to wire up real data to those types. (Part 2)
Implement pagination. (Part 2)

Who is this article for?

This series of articles focuses on authoring GraphQL APIs using the ASP.NET Core platform.

I am going to assume you have already acquired a solid understanding of the fundamental principles of GraphQL itself. If not, I would suggest heading over to https://graphql.org/ and going through the documentation first.

We will not go into advanced topics - such as directives, fragments, custom scalars, etc, not even mutations - but you are expected to understand the basics of the type system, queries, lists, nullability, and enums.

The API you are going to build by the end of this article

I don't like overly simplified tutorials, they usually miss out on the most important architectural problems.

Instead, here we are going to pretend we're in charge of building a real-world API of an airline travel company: The dataset consists of airlines, airports, and routes between them. The dataset that we are going to use is a full-scale real-world snapshot of said data.

I built a NuGet package that contains all our data, so we don't have to worry about a database now, we can instead focus on the important part: GraphQL.

I strongly believe APIs should be built design-first so that's what we are going to do.

Let's pretend this is the schema our architects built and was given to us for implementation:

type Query{
    routes(offset: Int, limit: Int): [Route!]!
    airlines(offset: Int, limit: Int): [Airline!]!
}

type Route{
    airline: Airline!
    source: Airport!
    destination: Airport!
    codeshare: Boolean!
    stops: Int!
}

type Airline{
    id: ID!
    name: String!
    iata: String
    origin: Country!
    destinations: [Airport!]!
    routes: [Route!]!
}

type Airport{
    id: ID!
    name: String!
    city: String!
    country: Country!
    iata: String
    timezone: Float!
    airlines: [Airline!]!
    routes: [Route!]!
}

type Country{
    name: String!
    isoCode: String!
    dafifCode: String!
}

schema{
    query: Query
}

We have the schema, we have the "database", so let's get started.

Project setup (very simple)

I promised you this is going to be very simple. So here it is:

We are going to start with an Empty ASP.NET Core 3.1 project template. We can even get rid of the UseEndpoints call, so our method looks like this:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment()) app.UseDeveloperExceptionPage();

        app.UseRouting();
    }
}

Can't get much simpler, right?

Adding HotChocolate from NuGet

As you might have noticed, ASP.NET Core does not include GraphQL support by default. This isn't going to stop us though, there are two great GraphQL server implementations for ASP.NET Core: graphql-dotnet and HotChocolate. I am not going to talk about the differences here, but my choice is HotChocolate which we're going to use for this tutorial. Having said that, all I am going to show you here could just as well be achieved with graphql-dotnet.

Let's install 3 HotChocolate NuGet packages:

HotChocolate - contains the core GraphQL server logic
HotChocolate.AspNetCore - contains the AspNetCore bindings
HotChocolate.AspNetCore.GraphiQL - this one is optional, contains graphiql an amazing GraphQL playground we can use to test-drive our server.

Configuring the GraphQL middleware

Let's add these two lines at the end of Configure:

      app.UseGraphiQL();
      app.UseGraphQL();

This wires up both HotChocolate and GraphiQL to our application.

Configuring your GraphQL schema

If you tried to run the above, it crashes on startup with some cryptic error message. That is because we haven't told HotChocolate what schema we'd like to use for our endpoint. So let's do that.

Step 1: the schema file

A wonderful feature of HotChocolate is that it can read our schema from the .graphql file directly, without us having to transform it into C# syntax.

To do that, we have to add the schema file to our project (I am going to call it "schema.graphql") and make sure to set the CopyToOutputDirectory property on it, so it gets placed right next to our output dll.

Step 2: `ConfigureServices`

Now that we have our file in the project let's tell HotChocolate to load it. This is done inside ConfigureServices, like so:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGraphQL(
            SchemaBuilder.New()
                .AddDocumentFromFile("./schema.graphql")
                .Create()
        );
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment()) app.UseDeveloperExceptionPage();

        app.UseRouting();

        app.UseGraphiQL();
        app.UseGraphQL();
    }
}

If you run your app again, you should now be facing a new error message:

This is great. It means the schema is recognized and HotChocolate doesn't know how to serve it yet - because we haven't written the logic for it yet. It is like a series of NotImplementedExceptions.

The setup part is complete here.

Our goal for the next part of this article will be to add all backing Type and Resolver classes for all these GraphQL types until all the error messages are gone.

Conclusion

In just a few minutes, you set up a GraphQL server configuration in your ASP.NET Core application.

Thank you for reading this first part of the article, feel free to share if you liked it.

In the second part of the series, we will cover implementing the actual GraphQL types for this airline example: Query, Route, Airport, et cetera.

In the meanwhile, you can check out the Github Repository containing the final source code of our sample API.