How to make our CLIs safer with types?

Rate this content
Bookmark

In this talk, we will explore the various issues encountered when building JavaScript CLIs, and demonstrate how TypeScript can address them and help us make our applications safer.

By the end of this talk, you'll understand how to abstract runtime validations type behind easy-to-use interfaces, and have all the tools you need to bring those benefits into your own CLIs at little cost - whether they are open-source projects, or internal tools.

Maël Nison
Maël Nison
29 min
21 Sep, 2023

Comments

Sign in or register to post your comment.

Video Summary and Transcription

This talk explores the challenges of building CLIs and introduces a fully typed CLI framework built with TypeScript. It discusses the complexities and pitfalls of CLI implementation and the benefits of using decorators for metadata and logic. The talk also covers type inference challenges and presents a third way of assigning annotations as decorators. It highlights the integration of Tpanion, Zod, and ClipAnion for type checking and format validation. Finally, it mentions other CLI frameworks like ClipAllian, Common.js, and Oclif that offer similar functionality.

Available in Español

1. Introduction to the Talk

Short description:

Welcome to this talk about making our CLI safer with TypeScript. We will discuss the problems faced when building CLIs, techniques in TypeScript for better inference, and existing frameworks. Let's get started!

Hi everyone, and welcome to this talk about making our CLI safer with TypeScript. My name is Mayr Neonaysan. I work at Datadog as part of the front-end dev team, where we are building all sorts of tools in order to make sure our front-end engineers can be as efficient as they want to be. You can find me on Twitter and GitHub, as Arkalis, and yeah, hope to see you there.

So first, about this talk, we are going to split it into four different parts. First, we are going to talk about what are CLIs, what are the problems that we face when building them. Then we are going to see some techniques that we can use in TypeScript in order to make some better inference on the type of the options. And finally, we are going to go over some of the frameworks that already do that for us before jumping into a conclusion and recapitulating everything that we learned. Does it sound good?

2. Complexities of CLIs and Yarn CLI

Short description:

CLIs are simple and useful for parameterizing actions. However, they can be tricky, like when using npm run eslint ____ version or cp command with arguments at the beginning. Yarn CLI is one of the biggest in the JavaScript ecosystem and has specific behaviors. Commander JS was used initially, but we made run keyword and dash dash token optional, requiring additional implementation.

They are very simple to read on about and very simple to implement usually. We use them in order to parameterize actions, which can be as complicated as a full CLI application like YARN, or something much simpler like a script that you are using inside your build pipeline. The one thing they have in common is that they are typically very simple. Compared to full UI applications, they require very few boiler plates, and that makes them a very good thing to use if you are just trying to make a couple of behaviors configurable.

However, they can also be tricky. For instance, let's take npm run eslint ____ version. If you don't use the ____ token to separate the eslint and the ____ version token, you are going to end up running the version option on npm itself and not eslint. However, if you are running YARN, you don't have to do this ____ token. But in order to do that, as we are going to see later, things start to get more complicated.

The cp command looks simple. However, unlike many commands where the amount of parameters of variadic arguments is at the end of the command, in the case of cp, it's at the beginning of the command. You have slc1, slc2, any number of other sources, but you must have one destination at the end. So the required position of arguments is at the end rather than the beginning. You have the arm command that has the preserve-root option, but it also has the "-no-preserve-root option". And if you're implementing something like this in your scripts, you usually want to declare both options into one, so that you don't have to duplicate them. And finally, let's take the case of the vlc-v. If you look at this command and you don't know anything else about it, you would think that "-v", is actually a boolean flag. But it's not. If you run vlc-vvv, you will not get the same behavior as if you were running vlc-v. Because vvv is actually a counter. It counts the number of times that you're passing it to the command.

Now, let's talk about the Yarn CLI itself. It's very interesting, because the Yarn CLI is one of the biggest CLI interfaces that we all use in the JavaScript ecosystem. Each has more than twenty commands, and each of them accepts options, and we have some very specific behaviors like we previously saw. At first, it started to use Commander JS, which is a CLI framework for JavaScript that supports subcommands, and that's something that is very important for Yarn, because Yarn add, Yarn remove, Yarn upgrade to interact with you, all those kind of things are commands from the main application. However, we decided to eventually make the run keyword optional, so that you could run Yarn eslint instead of Yarn run-eslint, and that wasn't something that Commander JS actually supported out of the box. So we had to implement our own code in order to support that. Then, later on, we decided to also make the dash dash token optional, so that if you run Yarn eslint dash dash version, then the dash dash version is applied on eslint and not on Yarn itself. That's super handy. However, it required to implement something else on top of Commander JS.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

TypeScript and React: Secrets of a Happy Marriage
React Advanced Conference 2022React Advanced Conference 2022
21 min
TypeScript and React: Secrets of a Happy Marriage
Top Content
TypeScript and React are inseparable. What's the secret to their successful union? Quite a lot of surprisingly strange code. Learn why useRef always feels weird, how to wrangle generics in custom hooks, and how union types can transform your components.
React's Most Useful Types
React Day Berlin 2023React Day Berlin 2023
21 min
React's Most Useful Types
Top Content
We don't think of React as shipping its own types. But React's types are a core part of the framework - overseen by the React team, and co-ordinated with React's major releases.In this live coding talk, we'll look at all the types you've been missing out on. How do you get the props type from a component? How do you know what ref a component takes? Should you use React.FC? And what's the deal with JSX.Element?You'll walk away with a bunch of exciting ideas to take to your React applications, and hopefully a new appreciation for the wonders of React and TypeScript working together.
Stop Writing Your Routes
Vue.js London 2023Vue.js London 2023
30 min
Stop Writing Your Routes
The more you keep working on an application, the more complicated its routing becomes, and the easier it is to make a mistake. ""Was the route named users or was it user?"", ""Did it have an id param or was it userId?"". If only TypeScript could tell you what are the possible names and params. If only you didn't have to write a single route anymore and let a plugin do it for you. In this talk we will go through what it took to bring automatically typed routes for Vue Router.
Making Magic: Building a TypeScript-First Framework
TypeScript Congress 2023TypeScript Congress 2023
31 min
Making Magic: Building a TypeScript-First Framework
I'll dive into the internals of Nuxt to describe how we've built a TypeScript-first framework that is deeply integrated with the user's IDE and type checking setup to offer end-to-end full-stack type safety, hints for layouts, middleware and more, typed runtime configuration options and even typed routing. Plus, I'll highlight what I'm most excited about doing in the days to come and how TypeScript makes that possible not just for us but for any library author.
Full-stack & typesafe React (+Native) apps with tRPC.io
React Advanced Conference 2021React Advanced Conference 2021
6 min
Full-stack & typesafe React (+Native) apps with tRPC.io
Top Content
Why are we devs so obsessed with decoupling things that are coupled nature? tRPC is a library that replaces the need for GraphQL or REST for internal APIs. When using it, you simply write backend functions whose input and output shapes are instantly inferred in your frontend without any code generation; making writing API schemas a thing of the past. It's lightweight, not tied to React, HTTP-cacheable, and can be incrementally adopted. In this talk, I'll give a glimpse of the DX you can get from tRPC and how (and why) to get started.
Faster TypeScript builds with --isolatedDeclarations
TypeScript Congress 2023TypeScript Congress 2023
24 min
Faster TypeScript builds with --isolatedDeclarations
Top Content
Type-checking a TypeScript codebase can be slow, especially for monorepos containing lots of projects that each need to use the type checker to generate type declaration files. In this talk, we introduce — for the very first time — a new TypeScript feature we are working on called “Isolated Declarations” that allows DTS files to be generated without using the type checker at all! This opens the door to faster declaration generation in TypeScript itself, as well as in external tools written in other languages such as ESBuild and swc. You'll see how to use this new option, and maybe (just maybe) you’ll be convinced about the benefits of explicit return types! Most importantly, we will show how Isolated Declarations enables parallel builds to spread work across your CPU cores to significantly improve the build speed of your TypeScript projects.

Workshops on related topic

React, TypeScript, and TDD
React Advanced Conference 2021React Advanced Conference 2021
174 min
React, TypeScript, and TDD
Top Content
Featured WorkshopFree
Paul Everitt
Paul Everitt
ReactJS is wildly popular and thus wildly supported. TypeScript is increasingly popular, and thus increasingly supported.

The two together? Not as much. Given that they both change quickly, it's hard to find accurate learning materials.

React+TypeScript, with JetBrains IDEs? That three-part combination is the topic of this series. We'll show a little about a lot. Meaning, the key steps to getting productive, in the IDE, for React projects using TypeScript. Along the way we'll show test-driven development and emphasize tips-and-tricks in the IDE.
Best Practices and Advanced TypeScript Tips for React Developers
React Advanced Conference 2022React Advanced Conference 2022
148 min
Best Practices and Advanced TypeScript Tips for React Developers
Top Content
Featured Workshop
Maurice de Beijer
Maurice de Beijer
Are you a React developer trying to get the most benefits from TypeScript? Then this is the workshop for you.In this interactive workshop, we will start at the basics and examine the pros and cons of different ways you can declare React components using TypeScript. After that we will move to more advanced concepts where we will go beyond the strict setting of TypeScript. You will learn when to use types like any, unknown and never. We will explore the use of type predicates, guards and exhaustive checking. You will learn about the built-in mapped types as well as how to create your own new type map utilities. And we will start programming in the TypeScript type system using conditional types and type inferring.
Deep TypeScript Tips & Tricks
Node Congress 2024Node Congress 2024
83 min
Deep TypeScript Tips & Tricks
Top Content
Workshop
Josh Goldberg
Josh Goldberg
TypeScript has a powerful type system with all sorts of fancy features for representing wild and wacky JavaScript states. But the syntax to do so isn't always straightforward, and the error messages aren't always precise in telling you what's wrong. Let's dive into how many of TypeScript's more powerful features really work, what kinds of real-world problems they solve, and how to wrestle the type system into submission so you can write truly excellent TypeScript code.
Practice TypeScript Techniques Building React Server Components App
TypeScript Congress 2023TypeScript Congress 2023
131 min
Practice TypeScript Techniques Building React Server Components App
Workshop
Maurice de Beijer
Maurice de Beijer
In this hands-on workshop, Maurice will personally guide you through a series of exercises designed to empower you with a deep understanding of React Server Components and the power of TypeScript. Discover how to optimize your applications, improve performance, and unlock new possibilities.
 
During the workshop, you will:
- Maximize code maintainability and scalability with advanced TypeScript practices
- Unleash the performance benefits of React Server Components, surpassing traditional approaches
- Turbocharge your TypeScript with the power of Mapped Types
- Make your TypeScript types more secure with Opaque Types
- Explore the power of Template Literal Types when using Mapped Types
 
Maurice will virtually be by your side, offering comprehensive guidance and answering your questions as you navigate each exercise. By the end of the workshop, you'll have mastered React Server Components, armed with a newfound arsenal of TypeScript knowledge to supercharge your React applications.
 
Don't miss this opportunity to elevate your React expertise to new heights. Join our workshop and unlock the potential of React Server Components with TypeScript. Your apps will thank you.
Advanced TypeScript types for fun and reliability
TypeScript Congress 2022TypeScript Congress 2022
116 min
Advanced TypeScript types for fun and reliability
Workshop
Maurice de Beijer
Maurice de Beijer
If you're looking to get the most out of TypeScript, this workshop is for you! In this interactive workshop, we will explore the use of advanced types to improve the safety and predictability of your TypeScript code. You will learn when to use types like unknown or never. We will explore the use of type predicates, guards and exhaustive checking to make your TypeScript code more reliable both at compile and run-time. You will learn about the built-in mapped types as well as how to create your own new type map utilities. And we will start programming in the TypeScript type system using conditional types and type inferring.
Are you familiar with the basics of TypeScript and want to dive deeper? Then please join me with your laptop in this advanced and interactive workshop to learn all these topics and more.
You can find the slides, with links, here: http://theproblemsolver.nl/docs/ts-advanced-workshop.pdf
And the repository we will be using is here: https://github.com/mauricedb/ts-advanced
Mastering Node.js Test Runner
TestJS Summit 2023TestJS Summit 2023
78 min
Mastering Node.js Test Runner
Workshop
Marco Ippolito
Marco Ippolito
Node.js test runner is modern, fast, and doesn't require additional libraries, but understanding and using it well can be tricky. You will learn how to use Node.js test runner to its full potential. We'll show you how it compares to other tools, how to set it up, and how to run your tests effectively. During the workshop, we'll do exercises to help you get comfortable with filtering, using native assertions, running tests in parallel, using CLI, and more. We'll also talk about working with TypeScript, making custom reports, and code coverage.