weeklyJS

Types as comments for plain JavaScript

2022-06-24T07:00:13+00:00

Today we’re looking into the potential future of JavaScript by reading up on the types as comments proposal that seeks to introduce type information as part of the core JavaScript language.

Types as comments

Types as comments was proposed by the TC39 technical committee for JavaScript in late 2020. It proposes the addition of syntax for type information as a core, but optional, part of the JavaScript language.

Adding type information syntax to the language enables the potential use of static type checkers to prevent certain classes of bugs. That is to say, static type checking would be possible without having to develop in another statically typed language (such as TypeScript or Flow) that transpiles to JavaScript.

For JavaScript developers, this promises at least two things:

a faster development loop (i.e. without a transpilation step), and
free choice of tooling for type checking.

Why static type checking?

TypeError: Cannot read properties of undefined (reading ‘bar’)

The case for static type checking is not particularly hard.

As JavaScript developers, we probably all know the language’s famously weak and dynamic type system which has no problem with letting funny code like the following pass to the interpreter without throwing errors:

$ node -e 'console.log(3 + [])'
3
$ node -e 'console.log({}.foo)' 
undefined

ℹ️ Examples were run with Node v16.15.1.

ℹ️ Have a look at Programming TypeScript (p.3) for more examples.

Even though the + operator may be overloaded to add strings and arrays, it doesn’t make a lot of sense to do that in the first place. Neither does accessing a custom property foo on a, very obviously, empty object. The developers of JavaScript, in a very questionable attempt to make developer lives easier in the short run, opted to take care of these kinds of problems by

in the first case applying type coercion, and
in the second case by defaulting to the special value undefined that models undefined values.

If you have ever ripped your hairs trying to find the cause of the infamous run time errors like “TypeError: Cannot read properties of undefined (reading ‘bar’)”

$ node -e 'console.log({}.foo.bar)'
[eval]:1
console.log({}.foo.bar)
                   ^

TypeError: Cannot read properties of undefined (reading 'bar')
    at [eval]:1:20
    at Script.runInThisContext (node:vm:129:12)
    at Object.runInThisContext (node:vm:305:38)
    at node:internal/process/execution:76:19
    at [eval]-wrapper:6:22
    at evalScript (node:internal/process/execution:75:60)
    at node:internal/main/eval_string:27:3

you probably understand why, in the long run, you want to catch these kinds of problems before running your code. Preferably even, you want to know this immediately when you type the code into your editor of choice.

TypeScript to the rescue

Part of the appeal of TypeScript is that it adds this additional layer of static—i.e. before runtime—safety to your JavaScript code.

“The main benefit of TypeScript is that it can highlight unexpected behavior in your code, lowering the chance of bugs.”

— TypeScript in 5 Minutes

Let’s now, for example, directly run the above code examples with TypeScript (using ts-node).

$ ts-node -e 'console.log(3 + [])'
[eval].ts:1:13 - error TS2365: Operator '+' cannot be applied to types 'number' and 'never[]'.

1 console.log(3 + [])
              ~~~~~~
$ ts-node -e 'console.log({}.foo.bar)'
[eval].ts:1:16 - error TS2339: Property 'foo' does not exist on type '{}'.

1 console.log({}.foo.bar)
                 ~~~

As we can see, both problems can easily be detected before running the code by applying static type checking. In the first case, TypeScript tells us that we likely wanted a number on the right-hand side of the + operator (and not an array).

In the second case, we are informed that empty objects do not magically come with an arbitrary property called foo.

ℹ️ Admittedly, the phrasing of the first error message is a little bit off because we can actually apply the + operator to number and array types (in our case yielding a number value 3 as shown above). By specification, however, it is only overloaded for number addition and string concatenation. Moreover, it makes very little sense to “add” numbers and arrays, so the right-hand side value probably was intended to be a number as well.

These two properties, i.e.

the plus operator is only used for number addition and string concatenation and
custom properties of objects are not accessed before they are set

are very reasonable constraints for good JavaScript programs. If they don’t hold, we most likely have found some kind of program bug or otherwise bad code. Consequently, it’s extremely helpful that TypeScript can assert (or, disproof) these properties for us before we run the code.

Another great aspect of TypeScript’s type checking is that we, for the most part, don’t actually have to add a lot of type information. In simple cases like the above, TypeScript can simply guess the types via type inference.

Unsurprisingly, a lot of JavaScript developers have come to appreciate TypeScript for these and other reasons and it is considered one of the technologies that are considered safe to adopt by the community. I.e. TypeScript has both a high satisfaction level and is widely used (cf. State of JS: Satisfaction vs Usage).

Making type annotations part of JavaScript

What does it look like?

The syntax of the proposal for types as comments will probably not surprise anyone who has worked with either TypeScript or Flow. It rather seems like the authors aimed to capture the common subset of both. A lot of code written in TypeScript and Flow therefore already conforms to the proposed syntax.

Let’s take a look at some examples to illustrate the similarities.

Type Annotations

A type annotation is written in the form x: T where x is a variable name and T is a type name. We may use type annotations in variable declarations or in function parameters.

// a variable that stores a string
let x: string; 
// a function that takes two string parameters and returns a boolean value
function equals(s: string, t: string): boolean { /* … */ }

Type declarations

Types may be declared using the interface keyword to introduce a new type or using the type keyword to declare aliases.

// An object type with a properties coordinate and radius.
interface Circle {
  coordinate: Point;
  radius: number
}
// A shorter alias for boolean
type bool = boolean;

Classes also implicitly define types.

// Implicitly declares a type Point
class Point {
  x: number;
  y: number
}

Implicitly defined types

JavaScript’s primitive data types have corresponding predefined types (such as number and string).

ℹ️ Curiously, the proposal suggests ignoring anything in between the curly braces of both interface as well as class declarations. This does not make much sense to me at the moment, but will hopefully be cleared up in the upcoming drafts.

Advanced features

Some more complicated type system features such as

type unions (type C = A | B),
generics (type A<T> = T[], interface Box<T> { content: T; })
type and non-null assertions (const point = JSON.parse('{"x": 0, "y": 0}') as Point resp. JSON.parse('{"x": 0, "y": 0}')!.x)

are also proposed to be supported in order to add some more expressiveness.

ℹ️ For the full list of features, take a look at the current draft.

Extensions to the module system

Lastly, an extension to the module system syntax is proposed so that types can be imported and exported as well using import type respectively export type.

Motivation for types as comments in JavaScript

Judging from the widespread adoption of TypeScript, static typing is generally considered useful for JavaScript development. So, the question to address is “why don’t we just not develop in TypeScript if we want to add type information to our JavaScript and/or static type checks to our JavaScript development process?”

One big argument in favor of types as comments in JavaScript compared to TypeScript (or similar languages and tools) is that it gives us the choice of tooling. For example, we could opt for Flow’s type checker instead of TypeScript’s type checker if we preferred that.

ℹ️ Flow would also be able to read the JavaScript code with type information as we will see later on.

Another important argument pro types as comments in JavaScript is that it lets us skip the inevitable JavaScript transpilation step. Compare that to developing in TypeScript, where the usual workflow includes running our code through tsc (the TypeScript compiler) before executing it with node or in the browser. Dropping the transpilation step may significantly improve the speed of our development loop and moreover may require less set-up (such as the tsconfig.json file).

ℹ️ A more elaborate discussion can be found here in this article on the Microsoft dev blog. (Picture above is also taken from the blog.)

Lastly, even if we don’t use type information for static type checking, it could be argued that they are a very good and less verbose replacement for JSDoc style type comments. I.e., this

/**
 * @param a {number}
 * @param b {number}
 */
function add(a, b) {
    return a + b;
}

simply would become this

function add(a: number, b: number) {
  return a + b;
}

What the proposal is not about

When I first read through the proposal it strongly reminded me of the way optional type information was introduced via type hints in Python. I.e. adding type checking is entirely opt-in. You can use it if you want to, but you don’t have to. It is not about introducing a specific type system. And, by extension, neither is it about standardising TypeScript’s type system in the JavaScript specification.

This is a cautious and smart way to proceed on this topic in my opinion, because there is—as mentioned in the proposal—a very high risk that it would break the web. I.e. if web browsers would run type checks on JavaScript code, a lot of websites might break because they run type-wise unsound code.

Summary

The types as comments proposal laid out by the TC39 technical committee for JavaScript suggests adding syntax for optional typing information to JavaScript. With these syntax additions, we may provide type information in JavaScript code similar to comments. This type information may be used to leverage static type checking just as in TypeScript or Flow in order to improve code quality and safety. Having types as comments in JavaScript makes a lot of sense given the popularity of statically typed languages that compile to JavaScript such as TypeScript and Flow. We can make at least three arguments in favor of types as comments: 1. it gives us the choice of the type checker, 2. we can prune the transpilation step from our development loop, and 3. type information is a less verbose replacement for JSDoc-style type comments.

Do you have any questions, suggestions, or comments? Get in touch with the author via mail!

About the Author: Friedrich Kurz

Friedrich has been working for MaibornWolff as a full-time software engineer for 2.5 years. In his current project, he’s helping to build the AWS cloud infrastructure for a client’s web platform. Friedrich considers himself a technology generalist with a broad range of interests rather than a technology specialist. He’s, however, also very interested in functional programming and general methods of writing correct, clean, and maintainable code.

Type-Aware Rules for ESLint

2022-06-17T09:00:00+00:00

In a previous article my colleague Tobias Walle already discussed how Static code analysis in Node.js can be used to improve the quality of your code, specifically with ESLint. Most TypeScript developers are probably already aware of the eslint-plugin which provides a plethora of additional rules specifically for TypeScript.

What is slightly less known is that you can opt in to type-aware rules, albeit at some cost to performance. It is highly recommended to enable this feature unless the size of your code base makes the use of it prohibitively expensive - in which case you might want to defer these checks to a pre-commit hook.

Setting this up is slightly more tricky than your average ESLint-plugin, but the documentation does a great job of guiding you through it. Just make sure you read the troubleshooting section because chances are you will run into issues if you don’t. Or so I am told 🙄.

So what’s the benefit of all of this? Consider the following (admittedly somewhat silly) piece of code, which will pass conventional linting just fine:

async function boom(): Promise<number> {
    throw '💥'
}

boom()

Eagle-eyed developers will quickly spot at least three issues with this (besides the pointlessness of the function 😉):

the function is async even though it does not need to be
the call to boom is not awaited.
the function throws a string literal, not an an Error object

This is where the type-aware rules require-await, no-floating-promises and no-throw-literal, respectively, come to the rescue. Please note that the latter is not enabled by default if your configuration only extends plugin:@typescript-eslint/recommended-requiring-type-checking, you will either have to enable it manually or also use plugin:@typescript-eslint/strict.

About the author: Raphael Pigulla

Raphael has more than ten years of experience in software development and architecture. He specializes in backend development with Node.js and TypeScript. Raphael joined MaibornWolff in 2019.

Deno - adopt or wait?

2022-06-10T05:00:13+00:00

Deno is 4 years old now and is slowly maturing. Among other things, the Node alternative has become known for the really good security principles. Deno is running in a kind of sandbox, just like the browser sandbox. Many developers really like the idea. But how mature is Deno really? Is the effort of changing your runtime worth it if you are already familiar with Node? What’s still missing from the young competitor? Architecture expert Sebastian Springer answers these questions:

What is the most important security feature of Deno?

“The fact that you can manage access permissions to system resources. However, this should be taken with a grain of salt. I can a) leave it out and Deno asks me. Or b) make it explicit via options. Or c) turn off security with an option. If an application needs too many permissions and asks for them, one is quickly tempted to just choose option c).”

What do you have to get used to when you switch from Node to Deno?

“Deno does away with many of Node’s weaknesses and, for example, relies on the ECMAScript module system, supports modern JavaScript and TypeScript out of the box. Unusual is the absence of a package manager, which is reflected in the omission of package.json, package-lock.json and the node_modules directory. For Node developers, this removes familiar structures and perhaps a bit of stability, as the packages now come directly from the Internet.”

Does it make sense to change from Node to Deno in existing projects?

“Personally, I continue to rely on Node in the large projects, the platform is stable, established and has a huge ecosystem to utilize. For small and medium projects, completed services or prototypes, Deno is definitely a very good solution. Even though Deno is already 4 years old, very important developments have taken place only in the last months and years. Like, for example, the collaboration with Node and the community.”

“I know that I need Deno when”

“…I implement small and modern applications, attach importance to additional security in the form of a sandbox. Concrete projects are also a great opportunity to learn the Deno way of doing things.”

What do you miss in Deno?

“What I miss with Deno is the stability of Node. There’s a lot happening under the hood right now, the community is growing and evolving. That’s excellent for me as a developer, I want to try new things. For my big project, sometimes I don’t want that flexibility and modernity.

Deno is evolving in a very interesting direction and getting closer and closer to Node. My hope is that many of these modern concepts will find their way into Node and both platforms will peacefully coexist and challenge each other and make sure that new features find their way into the server-side JavaScript world.”

About the author

Sebastian Springer is a JavaScript developer at MaibornWolff, focussing on the architecture of client- and server-side JavaScript. He is also regularly speaking about JavaScript at national and international conferences and events. MaibornWolff is hiring! If you want to work with Sebastian, this job might be interesting to you: Web Developer (m/f/d) Javascript / Typescript

Angular Changedetection Playground

2022-06-03T05:00:13+00:00

Some colleagues who have not yet dealt much with the topic of ChangeDetection in Angular may find it difficult to imagine what the difference between the default and the OnPush approach is.

When your application gets larger this topic gets more relevant tou you.

Here I would like to compare and show how ChangeDetection can have an effect on the performance of an application.

What is ChangeDetection?

ChangeDetection in Angular is a process which check if components have to rerender.

By Default, each component is permanently checked whether values have changed.

In my main project which grew over the years it is a nearly endless type of processing.

So the idea was, step by step migrate to OnPush.

But what is the difference?

With OnPush it’s up to you to trigger the ChangeDection yourself, using the available tools.

In this articls I hope to give you a better overview of the differences and why it is important to not ignore that topic.

Before to start

what is the difference between markForCheck and detectChanges?

markForCheck

markForCheck should always be used if you have to signal the detector to check that view.

detectChanges

detectChanges should be used to check the view and the children of it.

If you want to check only a small scope of your detection tree, use detach.

Warning: detach components should be done with caution!

Expectation

Default: Angular will rather check the DOM tree too many times than not enough.

OnPush: In Angular it’s your own responsibility to use build-in capabilities like Pipes, Components and the ChangeDetectorRef to define where checks are necessary outside the lifecycle routines.

Setup

Angular ~13

Material ~13

Now I going to use the following two components to build my test angular component tree.

AppComponent - the App Wrapper

DetectionBlockComponent - Components which create recursive Child Components.

Playground

My Component tree looks like:

| App
| - 1
|   - 3
|     - 4
|       - 5
|         - 6
| - 2
|   - 7
|     - 8

Test Process

The following steps I clicked in the appliation:

Open Page
click detectChanges 4
click markForCheck 7
click markForCheck 4
click detectChanges 2
click markForCheck App
click detectChanges App

Test results

app in default detection

We come to the following numbers

Step	check cycles
1	15
2	13
3	12
4	13
5	11
6	10
7	9
total	83

Explaination

the complete tree will be check from the detector on initial.

After the initial check, the app component in default mode will check multiple times itself and the children of it.

When click on detectChanges of a node in the tree, itself and its children will be checked. If you don’t use detach the ChangeDetection will start at the top of the tree and check until the origin of the detection event.

And again, default, app will check their children multiple times.

What happens with markForCheck:

checks 7
checks app
checks 1
checks 2
checks 7
checks 8
double checks app again

app in onpush detection

We come to the following numbers

Step	check cycles
1	11
2	9
3	8
4	9
5	7
6	6
7	5
total	55

Explaination

Wow! Just app component onPush v.s. default performed better by about 45%!

In initial check, ‘1’ and ‘2’ won’t check twice, only app still check multiple times in that setup.

Also additional steps won’t check as often.

App is more stable and won’t check the tree everytime so “aggressive”.

What’s the pitfall here? Mutations in objects without trigger detection by yourself can occure stale views. So be careful how you write component logic. Best practices IMHO are observables with async subscription in the template or call markForCheck after async processes in the component.

detach components after view init

This section is more experimental! In this case, the simple application setup made it possible to receive the same application behavior then before. Larger apps may get more stale and shaky when detach without caution!

When you have call detach the components after intial rendering show the following numbers

Step	check cycles
1	11
2	5
3	4
4	4
5	5
6	4
7	5
total	38

Explaination

Awesome, from 83 to 38 is a lot of circles which we safed!

What’s the reason?

By detaching all components from the ChangeDetection, you take over the full control over the ChangeDetection of them.

For example, after ‘initial’ step the detectChanges of ‘4’ will only effect app, ‘4’ and ‘5’.

‘5’ is the child, ‘4’ itself and app because it’s the root node and have to check how much of the total tree (which nomore exists more or less) has to check like before.

The reason for multiple checks of app is not clear to me, I’ll check it later.

What are the risks with this setup?

Detach can hide changes in the detector circles, so changes in your component won’t notify the renderer and the DOM becomes stale.
You have to do a lot of things manually, like detection and detach(reattach) the component
Child components may not render or act correctly. In my first experiments with MatButton or MatInput it won’t display correct.

My learning while writing this post

detach static “leaf” components can safe performance
From Default to OnPush can be hard but is essential for larger applications

Numbers behind the tests

See here

About the author: Nils Heinemann

Nils has more than five years of experience in software development and architecture. He specializes in frontend development with Angular and TypeScript. Nils joined MaibornWolff in 2018.

Avoid canceled requests when using RxJS combineLatest()

2022-05-27T05:00:13+00:00

If you work with Angular in your project, then you can’t avoid the reactive framework RxJS. This offers a lot of of operators. While some are rarely used, combinedLatest is certainly one of the great favorites of any Angular developer. It is used to combine multiple observable streams. It emits a value as soon as all incoming observables emit at least one value.

Example with backend request

Our example is quite simple. We have two observables: day and month. These are combined with combineLatest. As soon as the combined observable changes, a request is executed against a backend. The request is in a switchMap(). In the UI we have three buttons to change the day, the month and both at the same time (day + month).

  public day$ = new BehaviorSubject(0);
  public dayCount = 0;
  
  public month$ = new BehaviorSubject(0)
  public monthCount = 0;

  public result$ = combineLatest([this.day$, this.month$]).pipe(
    debounceTime(0),
    switchMap( ([day, month]) => this.dataService.apiCall(day, month))
  )

  increaseDay() {
    this.dayCount++;
    this.day$.next(this.dayCount);
  }

  increaseMonth() {
    this.monthCount++;
    this.month$.next(this.monthCount);
  }

  increaseDayAndMonth() {
    this.increaseDay();
    this.increaseMonth();
  }

If you click on the button in the UI to trigger changeDay(), a request is sent to the backend. With increaseMonth() it is the same. So far everything is fine.

But if we now use the method increaseDayAndMonth() to change both at the same time, i.e. day and month, then we see that a canceled request is displayed in our console.

The request is canceled because we use switchMap, which ensures that only the most recent request is active.

So the problem is that in a very short time our incoming observables are changing and therefore triggering the backend request twice in a row.

Solution

To avoid the problem, the debounceTime operator with the value 0 can be used. The value 0 means that 0 milliseconds are waited until the emitted values pass through.

However, it also says that this will only happen at the end of the call stack. This can be considered as a kind of loop, only when the loop has run through, the request is executed. Since within the loop is not only the change of “days”, but also the change of “month”, the request is executed only once.

About the author: Fabian Birke

Fabian joined MaibornWolff GmbH in 2019 and has several years of experience as a full-stack developer. Currently he focuses on the development of dynamic frontend applications.

Handling Conditional Classes in Angular

2022-05-20T13:00:13+00:00

How do you handle conditional classes at a dom element in Angular? There are two main options: class-bindings and ngclass. But which one is better? I tested both to get a definite answer.

ngclass vs class-binding

How to use ngclass?

<div [ngClass]="{
  class0: condition,
  classN: condition
}"></div>

And how would class-binding look like?

<div [class.class0]="condition"
     [class.classN]="condition"
></div>

Test Scenario

Project Structure

app.component.class.html => contains class-binding version of the template

app.component.ngclass.html => contains ngclass version of the template

app.component.css => basic css to provide the demo styles

app.component.ts => align state and callbacks for the buttons to change the alignment

index.html => basic resetted index file

Do it yourself

just clone the repository and execute npm start.

on http://localhost:4200 you can directly interact with the current selected version.

Test Plan

Open the Devtools
Open the angular profiler plugin
switch to “profiler” tab
start recording by click the round button which become red by hover
press
1. top
2. bottom
3. left
4. right
5. center
click “safe profile” to export a json with the detail report

My Result

numbers in seconds

Direction	ngclass	Class-binding
top	0,4999	0,2999
bottom	0,7000	0,4000
left	0,6000	0,4000
right	0,3999	0,3000
Center	0,4000	0,0999

Recommandation

To avoid complexity in your change detection circle you should probably use class-binding instead of ngclass.

For more complex usecases or if you want to bind a object with the typesignature Record<string, boolean> ngclass would be the right way.

About the author: Nils Heinemann

Nils has more than five years of experience in software development and architecture. He specializes in frontend development with Angular and TypeScript. Nils joined MaibornWolff in 2018. If you want to work with Nils, we are looking for Web Developers!

Writing CLI tools with TypeScript

2022-05-06T07:00:13+00:00

There are quite a couple of technology options when it comes to writing a command-line interface (CLI) tool. Most modern languages at the very least provide some kind of out-of-the-box support for command-line argument parsing. In addition, the ecosystems of modern languages also typically contain at least one mature and feature-rich CLI library.

TypeScript is a good choice for writing CLI tools for a couple of reasons including developer-friendliness, static checks, as well as a broad choice of tooling options. As with every TypeScript project, there is however an initial setup hurdle. We’ll have a look at how to set up a TypeScript CLI project with linting, formatting, testing, and packaging to a standalone binary in this post.

To give a few examples, here are some of the libraries and languages I’ve used recently to write CLIs

clap (Rust)
Click (Python)
Picocli (Groovy)
Commander.js (JavaScript)

So, why would we prefer writing a CLI in TypeScript given all these other choices?

Well, TypeScript is an overall good choice for a couple of reasons:

compatibility with JavaScript (TypeScript is a superset of—and by that token compatible with—JavaScript),
popularity (TypeScript was ranked 7th in the 2021 Stack Overflow Developer Survey with JavaScript being 1st),
tooling choice (the Node.js ecosystem provides quite a lot of CLI libraries),
developer friendliness (TypeScript is a scripted language but also has an advanced type system and static type checking which helps writing high-quality code),
performance (since TypeScript code is, in the end, typically run by Node.js, it is in general sufficiently performant thanks to the v8 engine).

Nonetheless, a typically non-trivial part of any TypeScript project is the setup. Writing a CLI with e.g. Python and the Click library requires little more than writing a file with the main function. This higher setup complexity is of course owed to the fact that TypeScript is a superset of JavaScript. To run TypeScript code, you typically transpile it to JavaScript and then execute the JavaScript code with Node.js. (Yes, even ts-node does that.) So, before running a program written in TypeScript, we need to transpile it to JavaScript first. This requires tooling and therefore setup.

Preferably, we also want to have a single, packaged binary as the result of building our project, rather than a script file, to reduce installation overhead on part of the user. To assure a high level of code quality, we also typically want to include code formatting, linting, and tests.

Getting started writing a TypeScript CLI

To hit the ground running, I created a starter project which already contains all required boilerplate and dependencies for running, formatting, linting, testing, and packaging the code to a standalone binary.

ℹ️ The starter project can be found on my GitHub and via npm.

We first clone it and install dependencies.

git clone git@github.com:fkurz/typescript-cliutil-starter.git my-cli
cd my-cli 
npm i

Our starter project uses

the commander package for argument parsing and executing commands,
code linting and formatting with eslint and prettier,
Jest as test runner and assertion library, and
pkg to build a stand-alone binary.

Basic development flow

To illustrate the development flow, we now add an example subcommand yell and test it. yell is similar to the say command (that already exists in the project) but a bit less subtle.

To do this, we add a file src/yell.ts and then add the following code.

// src/yell.ts
import { Command } from "commander";

export default (): Command =>
 new Command()
  .name("yell")
  .description("Say the word passed as the first argument but louder")
  .argument("<word>")
  .action((word: string) => console.log(word.toLocaleUpperCase()));

We also have to register our yell command with the main CLI command in src/cmd.ts, i.e. add an import statement for our subcommand and register it using Commander.addCommand

// src/cmd.ts
// … 
import buildYellCmd from "./yell";
// …
export default (): Command => {
  const command = new Command()
    .option("-g, --greet", `Say ${HELLO}`, false)
    .addCommand(buildSayCmd())
    .addCommand(buildYellCmd())
    .addHelpCommand()
    .showHelpAfterError();

  // …

  return command;
};

Having done that, we can do a quick test run using the dev script defined in package.json. The dev script simply executes our TypeScript code with ts-node.

$ npm run dev -- yell 'hey!'

> @fkurz/typescript-cliutil-starter@1.0.0 dev /private/tmp/my-cli
> ts-node src/main.ts "yell" "hey!"

HEY!

We can also add a test by adding src/yell.test.ts with the following content

import buildCmd from "./cmd";

beforeEach(() => {
  jest.spyOn(process, "exit");
  jest.spyOn(console, "log");
});

describe("Yell subcommand", () => {
  it("Should say 'HEY!' when passed 'hey!'", () => {
    const cmd = buildCmd();
    cmd.parse(["node", "cmd", "yell", "hey!"]);

    expect(console.log).toHaveBeenCalledWith("HEY!");
  });
});

Since our Jest configuration expects JavaScript test files, we first have to transpile our code with the build script using the TypeScript compiler tsc. The transpiled JavaScript source code is put into the dist/ folder.

$ npm run build
> @fkurz/typescript-cliutil-starter@1.0.0 build /private/tmp/my-cli
> tsc --build

We can now run our test suite with Jest using the test script. New test files will automatically get recognized by Jest if they have—as in our case—the suffix *.test.js*.

$ npm run test
> @fkurz/typescript-cliutil-starter@1.0.0 test /private/tmp/my-cli
> jest

...

Test Suites: 3 passed, 3 total
Tests:       8 passed, 8 total
Snapshots:   0 total
Time:        0.41 s, estimated 1 s
Ran all test suites.

As a final step, we can build a native binary by executing npm run package. This script will conveniently bundle all source code and dependencies into a single, stand-alone binary file bin/main using the pkg tool.

$ npm run package

> @fkurz/typescript-cliutil-starter@1.0.0 package /private/tmp/my-cli
> pkg dist/main.js --no-bytecode --public-packages '*' --public --target host --output bin/main

> pkg@5.3.1

The packaged binary is automatically made executable using the postpackage script. Packaging our CLI into a standalone binary has the major advantage that we can now simply run our CLI as a binary from the shell without a Node.js installation and without having to download any dependency whatsoever.

$ ./bin/main yell 'hey!'
HEY!

Summary

TypeScript is a good choice for writing a CLI tool due to various factors.

Not only is TypeScript a developer-friendly language but it also has static checks to assure code quality and its ecosystem offers a wide range of tooling choices for command-line programs.

Additionally, as shown above, developing a CLI utility written in TypeScript does not preclude the option of exporting a stand-alone, native binary if we use a tool like pkg to bundle our program and dependencies into an application binary.

Do you have any questions, suggestions, or comments? Get in touch with the author via mail!

About the Author: Friedrich Kurz

RxJS Best Practices and an Idea

2022-04-29T07:00:13+00:00

There are some best practices in RxJS for several regular use cases. First of all I’ll share my personal recommandations from my long time project, before we go into an idea how to improve them.

Clean flow

Nothing is more important for my colleageues and me than a clean flow of operators in a pipe block:

public userName$ = this.loginService.onLogin$.pipe(
  switchMap((credentials) => this.authService.authenticate(credentials)),
  tap((user) => !user && this.router.navigate(['/login'])),
  filterNotNull(), // custom
  map(({userName}) => userName),
  share({
    resetOnRefCountZero: true,
    connector: () => new ReplaySubject(1)
  })
);

However, is this really clean? Yes, it somehow is, but tap isn’t a great choice in this position, as side effects in a pipe flow should be avoided as much as possible. What would that look like in a “bad” case?

public userName$ = this.loginService.onLogin$.pipe(
  switchMap((credentials) => this.authService.authenticate(credentials).pipe(
    tap((user) => !user && this.router.navigate(['/login'])),
    filterNotNull(), // custom
  )),
  map(({userName}) => userName),
  share({
    resetOnRefCountZero: true,
    connector: () => new ReplaySubject(1)
  })
);

“Bad” is too much of a harsh word for this example, but I hope it gives a rough overview of the problem. Important: in case of errors it could sometimes be necessary to nest some pipes. Keep an eye on that!

Custom operators

Have you ever seen something like this?

....pipe(
  filter((dtoOrNull) => !dtoOrNull),
  map((dto) => dto!.prop)
)
...

Looks familiar, right? Yes, but a simple TypeScript trick and RxJS operator can fix that.

export function filterNotNull<T>(): OperatorFunction<T, Exclude<T, null | undefined>> {
  return value$ =>
    value$.pipe(filter(value => value != null)) as Observable<Exclude<T, null | undefined>>;
}

Why is that casting necessary? filter<T> is a mono type operator function that mean Input = Output type. If you see multiple combinations of operators in several pipes, you can just extract them into one custom pipe. Try it out!

OperatorFunctions from Services

Now, let’s move on from these known best practices to a new idea: this short sample should give a brief overview.

@Injectable()
export class FilterService {
  private termSubject = new BehaviorSubject('');
  
  public currentTerm$ = this.termSubject.asObservable();
  
  public filterFn<T>(matchFn: (item: T, term: string) => boolean)): MonoTypeOperatorFunction<T[]> {
    return source$ => combineLatest({items: source$, term: this.currentTerm$}).pipe(
    	map(({items, term}) => items.filter(item => matchFn(item, term)))
    );
  }
  
  public setFilterTerm(term: string): void {
    this.termSubject.next(term);
  }
}

@Injectable()
export class ListService {
  public listItems$ = this.apiService.listData$.pipe(
    this.filterService.filterFn<ListItem>((item, term) => item.title.contains(term))
  );
  
  constructor(private filterService: FilterService) {}
}

Basically it directly emits the observable at the point where we use the service function in our pipe, we don’t need to combine something anymore or do anything else. Our FilterService can be used in our filter field and every time if the component emit a new term to the service, the listItems$ will update. many other useacses for this are conceivable.

About the author: Nils Heinemann

Static code analysis in Node.js

2022-04-22T07:00:13+00:00

JavaScript is a very powerful language. This has a lot of advantages, but it can also decrease the readability of your code if misused.

Static code analysis can be used to detect common errors in your code and keep the style consistent across your team. In this article I want to share some of the tools that I can recommend.

Typescript

Typescript is a statically typed superset of JavaScript. By attaching the type information to the variables and
functions in your code, it helps finding errors before executing the code. It also boosts your productivity by improving the autocompletion of your editor. The best thing is, most of the time Typescript can infer the type of a variable and you don’t need to declare it. You can even check the types of a normal JavaScript project.

Prettier

Prettier formats your code by a very opinionated rule set. It avoids unnecessary changes caused by different formatting in your git commits. This is especially useful in code reviews, as you don’t get distracted by bloated diffs.

Eslint

Eslint is the de facto standard linter for JavaScript projects. It comes with a large ruleset and is easily extendable with plugins. I would recommend to start with the recommended rules by setting "extends": "eslint:recommended" in the configuration and enable/disable individual rules as needed.

If you want to use Eslint with Typescript, you should install and configure the Typescript Eslint Parser.

The following plugins might be useful to you:

eslint-config-prettier disables all the eslint rules, that might conflict with the prettier formatting.
eslint-plugin-import provides a set of rules to manage the imports in your project. I especially recommend the order rule, which automatically sorts your imports. This also avoids unnecessary diffs in your pull requests.
eslint-plugin-unused-imports. Unused imports can increase your application size and reduce readability. With this plugin you can automatically remove imports with no reference in your code.
The default eslint rules are great, but eslint-plugin-unicorn adds a lot more. For example with the prevent-abbreviations rule, you can ban abbreviations that might reduce clarity of you code. I suggest that you use the recommended configuration of this plugin.
eslint-plugin-promise. Promises and async/await are great and really help to keep your async JavaScript code clean. This plugin detects common pitfalls and bad practices while using Promises and async/await.
eslint-plugin-node extends ESLint with some Node.js specific rules. For example, it can enforce the use of the new promise based fs module with the node/prefer-promises/fs rules.
eslint-plugin-json includes JSON specific rules. This is especially useful, to prevent malformatted json configurations.
Last but not least, the eslint-plugin-eslint-comments detects the abuse of eslint escape comments like /* eslint-disable */. For example it warns you, if the exception is to general or redundant.

Start with the recommended settings of each plugin and enable or disable individual rules based on your project needs. An exception is the eslint-plugin-import. As the individual rules are relatively slow, I would just pick the rules that are worth the performance impact. You can measure the performance impact of each rule by setting the environment variable TIMING=1 (source). I would also recommend setting --cache flag of eslint to improve performance.

That’s it! I hope I could help you to improve the static analysis of your JavaScript project. Do you think I missed something? Please let me know in the comments.

About the Author: Tobias Walle

Tobias works as a full-stack developer at MaibornWolff since 2016. He works regularly with several languages, including Typescript, Kotlin and Rust and loves to deep dive into new technical topics.

Best Practices FP in TypeScript

2022-04-08T09:00:13+00:00

Some of us have a background in functional programming and are now moving into a TypeScript environment.

If you are part of this group, you might be wondering how much FP is possible in TypeScript.

Bad news first: not as much as you might like. However, some things will work. We’ll take a look at function abstraction and currying for compose.

Simple function abstraction

Some anomynous functions can be extracted very simple:

// query dto from api and transform into ui-model
class ApiService {
  public query(filter = ''): Promise<UiModel | null> {
    return fetch(`${url}?filter=${filter}`).then(mapIntoUiModel).catch(() => null);
  }
}

function mapIntoUiModel(response: ResponseData): UiModel {
  return // magic here
}

Also Array transform functions can extract abstract to utils:

export function extractValuesByKey<T, K extends keyof T>(key: K): (item: T) => T[K] {
  return (item) => item[key];
}

// usage: list.map(extractValuesByKey('prop'))

Nothing complicated here, right?

currying for compose

But there is more. In FP it’s sometimes a good practices to build new functions by composing. Compose is based on a simple law:

In Typescript it would look like this:

type ComposeFn = <A, B, C>(
  f: (a: A) => B
) => (g: (b: B) => C) => (a: A) => C;

// g o f => g(f(arg))
export const compose: ComposeFn = <A, B, C>(f: (a: A) => B) => (g: (b: B) => C) => (arg: A) => g(f(arg));

Let’s look at a small example now:

// sort items
function sortFn(items: Model[]): Model[] {
  return items.sort();
}

// filter items
function filterFn(fn: (item: Model) => boolean): (items: Model[]) => Model[] {
  return (items) => items.filter(fn);
}

const filter = filterFn((item) => item.name.startsWith('A'));

// items -> sort -> filter
const filterAndSort = compose(filter)(sortFn);

const items: Model[];

const finalData = filterAndSort(items);

That Functions return functions can also be useful for other use cases, in this example with Cypress:

function baseApiFn(baseUrl: string): (path: string) => string {
  return (path) => `${baseUrl}${path}`;
}

describe('mySuite', () => {
  const baseUrlFn = baseApiFn(Cypress.config().baseUrl);
  
  it('should ...', () => {
    const userApi = baseUrlFn('/user');
    cy.intercept(userApi).as('user');
    // do something
    cy.wait('@user');
  });
  
  it('should ... something other', () => {
    const authApi = baseUrlFn('/token');
    cy.intercept(authApi).as('login');
    // do something
    cy.wait('@login');
  });
  
});

We built a function baseApiFn to manage a preloaded baseUrl value and evaluate the final result on demand.

In a more advanced variant of this we additionally replace path variable:

type ParameterBaseUrlFn = (
  subPath?: string
) => (parameters?: Record<string, string>) => string;

function baseApiFn(baseUrl: string): (path: string) => string {
  return (path) => `${baseUrl}${path}`;
}

export function baseUrlFnWithPathVariables(
  baseUrl: string
): ParameterBaseUrlFn {
  const baseFn = baseApiFn(baseUrl);
  return (subPath) => parameters =>
    Object.entries(parameters ?? {}).reduce((url, [key, value]) => {
      return url.replace(`{${key}}`, value);
    }, baseFn(subPath));
}

This is how you can use currying for compose in TypeScript.

About the author: Nils Heinemann

Nils has more than five years of experience in software development and architecture. He specializes in frontend development with Angular and TypeScript. Nils joined MaibornWolff in 2018.