DEV Community: Rémi de Juvigny

End-to-end Type Safety with TypeScript and GraphQL

Rémi de Juvigny — Wed, 22 Apr 2020 22:01:48 +0000

In the JavaScript community, static types often get bad press. Configuring the right tools is hard, and a bad architecture can lead to a false sense of confidence. Let's try to fix this.

The problem

Consider this codebase written in TypeScript:

We never even use the any type. It should be type-safe, right? Well, no, at least not yet.

The problem is that our type safety is only as strong as its weakest point. In our case, the loose end is our API. The types from both ends live on their own separate world. So we write types on the frontend based on what we assume the backend will send, and vice versa.

We have multiple sources of truth, and no guarantee that they will keep in sync. It's already annoying for our small project, and can become a huge issue if we have an architecture based on many microservices.

GraphQL to the rescue

Unlike Rest, GraphQL has a type system in its core principles. We can use it to make type-safe API calls. The goal is to use it to propagate our backend types to the frontend.

But we have to make sure there are no holes in our type safety. On both the frontend and the backend, we need a way to convert port the GraphQL schema to TypeScript types. Here's the outline of the architecture:

In our case, we have 3 islands of type safety, but they're not connected to each other. To share our models from one end to the other, we need to build bridges on both sides.

The frontend bridge

Our frontend has access to the GraphQL schema. We need a tool that will introspect it, and map the types to TypeScript. Then we can use the TS types like we normally would.

Apollo built a CLI with this very feature. To help Apollo find your schema, you will first need to create an apollo.config.js file. But the CLI itself also provides many options. After some tweaking, here is the script I added to my last project's package.json:

"scripts": {
  "apollo:types": "rm -rf src/__generated__ && apollo client:codegen --config apollo.config.js --target typescript --outputFlat src/__generated__"
}

We can then type npm run apollo:types when there's a change in our schema or our queries and mutations. We can also keep it running in the background using npm run apollo:types --watch.

Note that the Apollo CLI can also be replaced by other tools:

GraphQL Code Generator generates queries with the types already built-in
gqless provides TypeScript types, and only requires code generation when our schema changes

We have now fixed half of the problem. Let's see the other side!

The backend bridge

The next challenge is to make sure our GraphQL schema is tightly linked to our backend application code, which includes the resolvers and all the business logic. The way we do this depends on our strategy to generate the schema: SDL-first or code-first.

SDL-first

If we write our GraphQL schema by hand, then just like for the frontend, we will need to set up code generation. This is why Prisma built graphqlgen. It will make sure that our resolvers map one-to-one with our schema.

Code-first

Code-first GraphQL development is also a good strategy. The process is reversed, you first write your types by hand in TypeScript, then they are used to generate a GraphQL schema.

Once again, several other tools exist to create code-first GraphQL schemas in Node. But I'll only show the one I have used and loved, TypeGraphQL. It uses decorators to extract a GraphQL schema from your TypeScript classes.

import {
  ObjectType, Field, ID, registerEnumType, Authorized
} from 'type-graphql'

@ObjectType()
class User {
  @Field()
  email: string;

  @Field(type => [Rate])
  ratings: Rate[];

  @Field(type => Float, { nullable: true })
  get averageRating() {
    const sum = this.ratings.reduce((a, b) => a + b, 0);
    return sum / this.ratings.length;
  }
}

Not everyone loves decorators. They're still called an experimental TypeScript feature, and you can see there are a few odd details in the syntax. But what they enable is huge. There's no script running in the background, we write TypeScript types like we're used to – but now we have a GraphQL schema.

This aproach is powerful because it's extensible by design. We can use it hand in hand with a decorator-based ORM, like TypeORM or Typegoose. See what that looks like:

import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
import {
  ObjectType, Field, ID, registerEnumType, Authorized
} from 'type-graphql'

@Entity()
@ObjectType()
class User {
  // Available on both database and schema
  @PrimaryGeneratedColumn()
  @Field(type => ID)
  id: number;

  // Available on both database and schema
  @Column({ unique: true })
  @Field()
  email: string;

  // Available on database but NOT on schema
  @Column()
  passwordHash: string;

  // Available on both database and schema
  @OneToMany(type => Rate, rate => rate.author)
  @Field(type => [Rate])
  ratings: Rate[];

  // Available on schema but NOT database
  @Field(type => Float, { nullable: true })
  get averageRating() {
    const sum = this.ratings.reduce((a, b) => a + b, 0);
    return sum / this.ratings.length;
  }
}

We have now colocated the types required by TypeScript, our database and GraphQL in a single class. To remove a field from GraphQL, or add it to our database, we add or remove a decorator. It's still not 100% type-safe yet, but we greatly reduce the risk of making mistakes by having all the type information grouped together.

Conclusion

Let's see the architecture we ended up with:

I hope you get to love all the benefits that type safety brings. It improves the developer experience by making our tooling smarter. We get autocomplete in our code editor, and linters warn us when we write bugs. Most importantly, just like a good test suite, it gives us more confidence that our code is solid. Enjoy!

Originally posted on my personal blog

5 tips to keep a clean Git history

Rémi de Juvigny — Mon, 13 Apr 2020 22:34:29 +0000

Your project's Git history is a powerful time machine. Here's how to avoid flooding it with useless noise.

Squash your commits

I like committing my changes frequently. It makes me feel safe knowing my changes are saved somewhere, so I commit every time I take a small break. But that means my commits become meaningless. They reflect what my days look like, not what's in my code.

Some changes only make sense when grouped together. But they end up spread out across commits like this:

It's hard giving each one a meaningful name, because they have no individual value. They're just here to let me go back in time if I mess up too much. And that's fine – as long as they don't stay around forever.

To clean up a bunch of redundant commits, you can squash them. That means combining them into a single commit that contains all of their changes. Suddenly your history becomes neat and relevant.

You can squash the commits using the CLI, but the syntax is quite fuzzy (from Stack Overflow):

# Squashes the last 3 commits
git reset --soft HEAD~3 && git commit

The most convenient way to squash commits is during Pull Requests. Both GitHub and GitLab let you combine your commits when you decide to merge your branch.

Using GitHub :

Using GitLab :

Rebase before merging

When you're coding a new feature, it's a good practice to work on a separate branch – often called a feature branch. But by the time your feature is ready, new commits have probably been added to the master branch.

This means Git won't be able to perform a fast-forward merge. Instead, it will have to create a merge commit to reconcile the history of the two branches.

This adds quite a lot of complexity to your history. You get a new weird, auto-generated commit, and your tree becomes two-dimensional, making it hard to read.

Ideally, we would have waited for the commits B and C from our diagram before making our own branch. This would be a terrible workflow, preventing us from working in parallel with our colleagues. But we can simulate this scenario with a simple command.

# from the feature branch
git rebase origin/master

Rebase modifies the history of our branch. It re-applies all of our changes on top of the latest version of master.

After rebasing, when we run git merge master, Git is able to do a fast-forward merge. Now we have a neat, linear and readable Git history. If you're using GitHub pull requests, you can use "Rebase and merge" to make this process automatic.

Stash your unfinished changes

Sometimes I start making changes in my code before realizing that I'm in the wrong branch. The trap would be to checkout to that branch immediately – then our uncommitted changes would be lost! We could also commit these changes before running git checkout, but we would end up having an unwanted commit in the wrong branch.

Git has the perfect command for that use case: git stash. Stashing clears all the changes we've made since our last commit. This gives us a clean state that allows us to update our context, whether we want to switch branches or pull changes. But the changes aren't lost, they are saved in invisible storage. We can think of it as a glorified clipboard, able to store changes across many files.

Then, we just type git stash pop, and our changes are restored.

Amend your last commit

It's usually right after making a commit that my mistakes stand out. Maybe it's a typo, a forgotten console log, or useless commented code. Either way, it's silly can be fixed by a one-line commit.

But then our history feels wrong. It puts our original commit, which may represent a full day of work, on the same level as our tiny hotfix. We're also exposing our mistake to everyone on the project, which sucks.

To avoid this, we can instead modify the history, and add our fix to the last commit. After staging your changes, run this command:

git commit --amend --no-edit

And voilà, we sneakily corrected our mistake. Note that if we already pushed our last commit, we would have to force push our amendment. This is fine if we're working on your own branch, but we should avoid doing it on master.

Visualize your Git tree

When we work with several people on multiple branches, it's easy to get lost. We then make mistakes because we don't have a good understanding of how we got there. To avoid this, we can display a visualization of our Git history. We can do this using the Git CLI:

git log --graph --oneline --all

If we want more comprehensive visual feedback, we can use a Git GUI. For example, here's what Sublime Merge would look like:

We can perform all Git commands using the CLI, but sometimes using an app makes more sense. Some complex actions – like interactive rebases, cherry-picking, or managing stashes – are hard to grasp using only the command line. Having a GUI helps us make less mistakes.

I hope this was helpful. If you want to improve your mental model of advanced Git commands, I recommend reading Lydia Hallie's article. Let me know if you have more tips to share, and happy coding!

How do you introduce yourself to recruiters?

Rémi de Juvigny — Sat, 21 Dec 2019 15:55:11 +0000

The 2019 State of JS survey results were published a few days ago, revealing many precious insights about the industry.

Among the questions asked was an odd one: How do you introduce yourself at parties? Of course, Twitter did its thing and had a good laugh picturing that social situation.

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

But what I find most unfortunate is that the options were limited to the traditional front-end, back-end, web and full-stack developers. As I'll be on the job market soon, I've been thinking about the best way to sell myself on the job market, while staying authentic.

If you could write your own job description, what would it be? How would you introduce yourself to a recruiter?

I've gathered a few titles that I find interesting:

UI developer/engineer
Creative developer
Product developer/engineer
Devops
Software developer/engineer
Software architect

The one that resonates with me is Product Developer. I like to have an impact on what I'm building, not just how I build it.

What about you?