DEV Community: Nicholas Jamieson

How to Find Projects Using GitHub Stars

Nicholas Jamieson — Tue, 25 Feb 2020 21:05:33 +0000

This article was originally published on my blog.

It's pretty common to refer to a GitHub project's star count. For example, at the moment, React has 144,162 stars, Angular has 58,093 and Vue has 157,325.

Those are some big numbers, but what do they mean? Would you choose a framework based on star counts? I wouldn't. However, I do think GitHub stars are useful and I use them every day. And that's what this post is about.

GitHub has some pseudo-social features that not everyone seems to use. Well, I'm pretty sure that some people don't, because several of the developers I've spoken with recently didn't know about or use these features.

It's possible to follow other people on GitHub: you visit their profile and click the follow button. They are then added to your following list and you're added to their followers list.

Once you have followed some people on Github, things get interesting — and useful — when you visit your dashboard. Your dashboard is what you see if you navigate to github.com/ — when you're logged in, of course.

The middle of the dashboard shows your 'Recent activity': your comments, issues, PRs, reviews, etc. Which is somewhat useful, but I deal with most of that stuff via email notifications. The interesting bit is below that: 'All activity'.

The 'All activity' section shows you some of the things that the people you are following have been up to. The section includes:

repos they've created;
repos they've made public;
repos they've forked;
repos they've pushed to — if you are watching the repo;
repos they've starred; and
people they've followed.

It's interesting to see people's activity — particularly if they've just created a new project — but the most useful inclusion, for me, are the repos that people have starred. It's a great way to find out about new packages. It's often that case the that people you've chosen to follow have similar interests and are solving the same kinds of problems that you are, so repos that they've decided to star are quite likely to be of use — or, at least, of interest — to you. Most of my package discoveries are made this way.

The relationship between followers and stars is presented in another part GitHub's user interface, too. When you click a repo's star count, it navigates to a page that gives you a paginated view of the repo's stargazers — the people who starred it. On that page, there are two tabs that separate said stargazers into the people you know — that is, the people you follow — and everyone else.

For me, this is really useful. When I'm trying to decide which package to use, I'll take a peek to see whether or not someone I know has starred its repo. If one package has no stars from people I know and another has several, it's likely that I'll choose the latter. There are other factors, of course, but this is useful information.

GitHub stars are also useful as bookmarks. It's often the case that I star something because it looks interesting and I anticipate its being useful in the future. Fortunately, the list of starred repos can be filtered, so when I'm looking for some CLI-related package that I can remember starring I can filter the list using 'cli' as the search term.

If you clicked the link in the previous paragraph, you'll have noticed that it's possible to filter someone else's list of starred repos. This can be useful for 'recommendations' and I used this recently when I was trying to find a React context-related package that I'd seen starred on the dashboard — it wasn't in my list of starred repos. I was pretty sure that Tom Crockett had starred it, so I filtered his list using 'context' as the search term and found what I was looking for: react-tracked.

When combined with the features outlined above, I think GitHub stars are useful for discovering and choosing packages. I just don't pay much attention to the total star counts.

Title photo by Daniel Olah on Unsplash.

RxJS: Typing zipWith

Nicholas Jamieson — Mon, 17 Feb 2020 09:05:56 +0000

This article was originally published on my blog.

Much of what we are doing with RxJS, for version 7, is focused on improving the package's types.

RxJS version 6 was released in April 2018 and, at that time, the current version of TypeScript was 2.8. With the bump to version 7, we can update this minimum-supported version of TypeScript and can take advantage of some of TypeScript's more recently-added features to simplify the package's types whilst making them more accurate and more flexible.

This article, we'll look at the types that have been declared for a new operator: zipWith. In particular, we'll look at how they work and at the TypeScript features upon which they rely.

What's zipWith?

zipWith isn't really a new operator; it's the deprecated zip operator renamed.

When RxJS version 6 was released, there were a handful of operators that had the same name as observable creators: concat; combineLatest; merge; race; and zip.

Prior to the introduction of pipe, these operators having the same name wasn't a problem, as operators were attached to Observable.prototype. However, when pipeable operators were introduced, the operators became static functions that had the same name as the creators:

import { zip } from "rxjs"; // the creator
import { zip } from "rxjs/operators"; // the operator

Operators are just functions that take an observable and return an observable, so the operators were deprecated and the recommendation was to use the creators instead, like this:

const answers = of(42).pipe(source => zip(source, of(54)));

Anyway, the above-mentioned operators are being renamed: a With suffix is being added — yielding operator names similar to those in RxJava — and they can be used like this:

const answers = of(42).pipe(zipWith(of(54)));

zipWith isn't really new and it's not especially interesting, but the types in its declaration are representative of the changes that are happening in RxJS version 7, so let's take a look at those.

Some background on RxJS's types

Let's look at two areas in which the package's types were problematic:

union return types; and
functions that take an arbitrary number of arguments.

Let's look at union return types first.

Union return types

We'll use this as our example:

const result = of(Math.random()).pipe(
  concatMap(value =>
    value < 0.05
      ? of("Yikes, rolled a 1!")
      : value < 0.95
      ? of(Math.floor(value * 20) + 1)
      : of("Yay, rolled a 20!")
  )
);

It might look a little contrived, but situations often arise in NgRx and redux-observable in which observable streams of different actions — i.e. different types — are returned from a projection function.

In RxJS version 6.3, the snippet would not have compiled and the following error would have been effected:

Type 'Observable<number> | Observable<string>' is not
assignable to type 'ObservableInput<number>'.

The problem is that the projection function passed to concatMap returns either an Observable<number> or an Observable<string> — depending upon the roll — and it's not possible (or safe) for TypeScript to determine that Observable<number | string> is what should be inferred. Well, not without some help.

In January 2019, Google's Alex Rickabaugh — he's on the Angular team — came up with a solution: the ObservedValueOf type. And it looks like this:

type ObservedValueOf<O> = O extends ObservableInput<infer T>
  ? T
  : never;

It extracts the value type from an ObservableInput. And it can be used like this:

function concatMap<T, O extends ObservableInput<any>>(
  project: (value: T, index: number) => O
): OperatorFunction<T, ObservedValueOf<O>>;

Using ObservedValueOf in the concatMap signature solves the problem and in our snippet, result is inferred to be Observable<number | string>. How it manages to solve the problem isn't immediately obvious, so let's take a closer look.

The O extends ObservableInput<any> type parameter imposes a constraint that the projection function's return value must be an ObservableInput. Observable<number> satisfies this constraint, as an Observable is a valid ObservableInput.

Observable<number> | Observable<string> also satisfies the constraint as both types within the union are ObservableInputs. That means that O is inferred to be Observable<number> | Observable<string> and that's what's passed to ObservedValueOf.

TypeScript's conditional types have an interesting property: they are distributive. That is, the "conditional types are automatically distributed over union types during instantiation."

That means that:

ObservedValueOf<Observable<number> | Observable<string>>

is effectively resolved as:

ObservedValueOf<Observable<number>> | ObservedValueOf<Observable<string>>

which is:

number | string;

And that's how ObservedValueOf solves the problem of projection functions returning union types.

ObservedValueOf was introduced in RxJS 6.4.0 and, unfortunately, it broke a whole bunch of Angular projects. The minimum-supported TypeScript version for RxJS version 6 was always considered to be 2.8 — as that was the latest TypeScript version when RxJS version 6 was released. However, Angular 6.1.0 depended upon RxJS ^6.0.0 and TypeScript ~2.7.2 and that version of TypeScript did not support conditional types — which were introduced in version 2.8.

Because of this breakage, there have not been many subsequent changes to the types in RxJS version 6. Improvements to the package's types are constrained by the minimum-supported TypeScript version of 2.8 and by not being able to make changes to type parameters.

In RxJS version 7, the minimum-supported version of TypeScript will be bumped and numerous type parameters will be repurposed. We'll look at these repurposed type parameters next, when we see how another problem was solved: passing arbitrary numbers of arguments to functions.

Arbitrary numbers of arguments

In September 2019, Ben Lesh added a type to support the passing of an arbitrary number of arguments to functions like concat. Like ObservedValueOf it's a conditional type and it looks like this:

type ObservedValuesFromArray<A> = A extends Array<ObservableInput<infer T>>
  ? T
  : never;

Prior to the introduction of ObservedValuesFromArray, functions like concat had to have numerous overload signatures — a signature for one argument, another for two arguments, etc. There were a limited number of these signatures — typically six — and if the number of arguments passed exceeded the limit, the type information was lost.

With ObservedValuesFromArray, only a single signature is needed and it's type-safe regardless of the number of arguments that are passed. Used with concat looks like this:

function concat<A extends ObservableInput<any>[]>(
  ...observables: A
): Observable<ObservedValuesFromArray<A>>;

It uses TypeScript's support for rest elements in tuple types and when called like this:

const answers = concat(of(42), of("fifty-four"));

A will be inferred to be [Observable<number>, Observable<string>].

The [Observable<number>, Observable<string>] tuple extends the array type Array<number | string>, so ObservedValuesFromArray will infer T to be number | string. And that means that answers will be inferred to be Observable<number | string>.

This is a huge improvement for the package's types. The elimination of overload signatures and the correct type inference — regardless of the number of passed arguments — are significant wins. However, the change is a breaking one, as the type parameter is repurposed. Let's take a closer look at the repurposing.

Prior to the removal of the overload signatures, the single-argument signature looked like this:

function concat<T>(o: ObservableInput<T>): Observable<T>;

So code like this would have been valid (weird and definitely not recommended, but valid nonetheless):

const result = concat<number>([]);

With the removal of the overload signatures, this will break — as the type parameter refers to the arguments' tuple type and not the observable's element type.

Typing zip

The types for zip are similar to those used for concat but there is a difference: zip emits an array containing values received from its source observables. So the inference of an union type from a tuple type is not what's needed. What's needed is a mapped-tuple type.

Taking this into account, ObservedValuesFromArray has been renamed to ObservedValueUnionFromArray:

type ObservedValueUnionFromArray<A> =
  A extends Array<ObservableInput<infer T>>
    ? T
    : never;

And another type — that infers a tuple — has been added:

type ObservedValueTupleFromArray<A> =
  A extends Array<ObservableInput<any>>
    ? { [K in keyof A]: ObservedValueOf<A[K]> }
    : never;

This looks complicated, but what it does is reasonably straightforward: if A is a tuple of ObservableInputs, it maps A to a tuple in which each element has the type of the ObservableInput's value — using Alex's type.

Let's look at an example:

type Example = ObservedValueTupleFromArray<
  [Observable<number>, Observable<string>]
>;

Here, Example will be inferred to be [number, string].

With the mapped-tuple type, zip is similar to concat and no longer requires overload signatures and correctly infers the types for an arbitrary number of arguments:

function zip<A extends ObservableInput<any>[]>(
  ...observables: A
): Observable<ObservedValueTupleFromArray<A>>;

Typing zipWith

The typing for zipWith is similar to that for zip, but there is a small difference: not all of the elements in the zipped array are present in the arguments' tuple. The initial element in the zipped array will be the value received from the source observable to which the zipWith operator is applied.

That is, when it's used like this:

const answers = of(42).pipe(zipWith(of("fifty-four")));

the type of answers needs to be inferred as [number, string], but [string] is what's inferred when ObservedValueTupleFromArray is applied to the arguments tuple.

To get the type that we need, number has to be be added to the head of the tuple.

We can do that using another type:

type Cons<T, A extends any[]> =
  ((arg: T, ...rest: A) => any) extends ((...args: infer U) => any)
    ? U
    : never;

This type is a little tricky. It's a conditional type that uses a relationship between two intermediate function types to infer a tuple type that adds T at the head of A. It works by forming an intermediate function that takes an argument of type T followed by arguments for each of the types in A. U is then inferred from the arguments of the intermediate function, effectively adding T to the head of A.

We can use Cons to add T at the tuple's head, like this:

function zipWith<T, A extends ObservableInput<any>[]>(
  ...observables: A
): OperatorFunction<T, Cons<T, ObservedValueTupleFromArray<A>>>;

And with the zipWith signature declared like this, answers — in the above snippet — is inferred to be Observable<[number, string]>.

What's still to do?

For version 7, the core team will be taking the types that we've looked here and will be applying them to other functions in the package. The goal is to get as much of the API as possible supporting the inference of correct types when an arbitrary number of arguments are passed. And to get rid of all those overload signatures.

Title photo by Ricardo Gomez Angel on Unsplash.

Be Careful with Array Mutators

Nicholas Jamieson — Fri, 27 Dec 2019 08:51:37 +0000

This article was originally published on my blog.

A while ago, I wrote a linting rule to highlight an error that I’d made on a few occasions. Let’s look at the error — and its variations — and then at the rule that prevents it.

The error

If you are used to working with fluent APIs — perhaps with D3 or lodash — it feels natural to write Array-based code like this:

const developers = employees
  .filter(e => e.role === "developer")
  .map(e => e.name)
  .sort();

Which is fine. There’s no error in that code.

However, in situations in which you don’t need to filter or map, you might write something like this:

const sorted = names.sort();

It feels natural, but there’s a potential error in there. And it’s an error that can effect hard-to-find bugs. It’s also an error that’s easy to overlook in code reviews.

The sort method mutates the array. It sorts the array in place and returns a reference to the array itself. It does not return a sorted copy of the array. So the sorted and names variables both reference the same, sorted array. And it means that — unless the array was already sorted — any code using the names variable will be dealing with an array in which the elements that been rearranged.

So why is the code in the first snippet okay? It’s because sort is applied to the array returned by map — a transient array to which there are no references.

The rule

The fundamental problem is the use of the return value when the sort method is applied to an array that is referenced elsewhere in the program.

If the return value is not used, it’s fine — as the intent is clear:

names.sort();

And it’s also fine if the sort method is applied to an array that has no referencing variable:

const names = ["bob", "alice"].sort();

It is a potential problem if the result is assigned to another variable:

const sorted = names.sort();

Or assigned to a property:

const data = {
  names: names.sort(),
};

Or passed as an argument:

console.log(names.sort());

The rule I wrote is named no-assign-mutated-array and is in the tslint-etc package. The source code is here.

It works by searching for method calls — like sort — that mutate arrays and checking to see if they are statements. The search is done using Craig Spence’s awesome tsquery.

If the call is a statement, the return value isn’t used — so there is no potential problem.

If the call is not a statement, the rule determines whether or not the array upon which the call is made is transient and effects a rule failure if it isn’t.

There are several methods on Array.prototype that mutate the array and return a reference to the mutated array — fill, reverse, sort, and splice — and the rule is enforced for all of them.

The future

In the TypeScript roadmap — for January to June 2019 — it was announced that TypeScript will be switching to ESLint — using @typescript-eslint/parser.

So sometime soon, I’ll start converting the rules in tslint-etc and rxjs-tslint-rules from TSLint rules to ESLint rules. Doing that should be … interesting. And I imagine it’ll prompt me to write a few more linting articles.

Title photo by Corinne Kutz on Unsplash.

TIL: Destructuring Property Assignment

Nicholas Jamieson — Sun, 22 Dec 2019 07:37:17 +0000

This article was originally published on my blog.

Until recently, I wasn't aware of the JavaScript syntax for destructuring property assignment.

I knew that I could destructure array elements and object properties in variable declarations, like this:

const [vowel] = ["a", "e", "i", "o", "u"];
console.log(vowel); // a

const { name } = { name: "Alice" };
console.log(name); // Alice

And I knew that I could destructure an array and assign an element to a previously declared variable, like this:

let vowel;
[vowel] = ["a", "e", "i", "o", "u"];
console.log(vowel); // a

But I didn't know how to destructure an object and assign a property to a previously declared variable. I tried this:

let name;
{ name } = { name: "Alice" };

But this error was effected:

SyntaxError: Unexpected token '='

The problem was that the braces surrounding the name variable were parsed as a block. To be parsed as destructuring property assignment, the assignment expression needs to be surrounded by parentheses, like this:

let name;
({ name } = { name: "Alice" });
console.log(name); // Alice

It's worth noting that if you rely upon automatic semicolon insertion, you may need to precede the parentheses with a semicolon to prevent the assignment expression from being used to execute a function on the previous line.

For example, this usage:

let name
console.log("assigning")
({ name } = { name: "Alice" })

Will effect this error:

TypeError: console.log(...) is not a function

Title photo by Florian Klauer on Unsplash.

TIL: String.raw

Nicholas Jamieson — Sat, 21 Dec 2019 03:14:37 +0000

This article was originally published on my blog.

Something that's always annoyed me — because I always seem to mess it up — is having to escape the escape character (\) in some JavaScript string literals.

Well, it turns out there's a feature that means having to do this can be avoided entirely.

Other languages

C# uses the @ character as a verbatim identifier and when it's applied to a string literal, it works like this:

// These strings are equivalent:
const verbatim = @"C:\Windows\system.ini";
const escaped = "C:\\Windows\\system.ini";

This is part of the C# language syntax.

JavaScript

In JavaScript, the mechanism is a little different. It doesn't extend the syntax. Instead, it leverages template literals and their tags.

The String object has a static raw method that is intended to be used as a template-literal tag, like this:

// These strings are equivalent:
const raw = String.raw`C:\Windows\system.ini`;
const escaped = "C:\\Windows\\system.ini";

Having to put backslash-delimited Windows paths in JavaScript literals isn't something that I've ever had to do.

However, I often have to escape escape characters when I'm dynamically creating a regular expression using the RegExp constructor. And in these situations, not having to escape the escape characters makes things much clearer:

const regExp = new RegExp(String.raw`(\b|_)${word}(\b|_)`));

ES2018

It's worth noting that there are differences in how these 'raw' template literals are handled in different JavaScript runtimes.

In ES2016, this template literal will effect an error, because \u is interpreted as a Unicode escape sequence:

const directory = String.raw`C:\images\unsplash`;

In ES2018, this behaviour was changed and — as long as a tag function is applied — no error will be effected.

More template-literal tags

If template-literal tags are something you've not encountered before, you might also want to check out the common-tags package. It has a whole bunch of extremely useful tag functions.

Title photo by Icons8 Team on Unsplash.

TypeScript: Don't Export const enums

Nicholas Jamieson — Sat, 14 Dec 2019 02:34:27 +0000

This article was originally published on my blog.

If you are writing a library and you export a const enum, some developers will not be able to compile their applications if they import your library. Let's look at why.

Non-const enums

When you declare an enum, TypeScript will generate code for it. For example, this TypeScript snippet:

enum Bool {
  True,
  False,
  FileNotFound,
}
let value = Bool.FileNotFound;

will compile to this JavaScript:

var Bool;
(function(Bool) {
  Bool[(Bool["True"] = 0)] = "True";
  Bool[(Bool["False"] = 1)] = "False";
  Bool[(Bool["FileNotFound"] = 2)] = "FileNotFound";
})(Bool || (Bool = {}));
let value = Bool.FileNotFound;

The reasons for this are explained in the documentation. However, some developers don't need the features provided by this style of declaration and don't want the costs involved — they just want to use enums instead of constants.

const enums

When an enum is declared as const, TypeScript doesn't generate code for the declaration. For example, this TypeScript snippet:

const enum Bool {
  True,
  False,
  FileNotFound,
}
let value = Bool.FileNotFound;

will compile to this JavaScript:

let value = 2 /* FileNotFound */;

No code is generated for the enum declaration. Which is great — it's just like using a constant — but there is a problem.

Isolated modules

In the above snippets, TypeScript has access to the const enum declaration, as it's in the same module as the declaration for the value variable.

However, if the const enum declaration is in a different module — and is imported into the module that contains the variable declaration — TypeScript will have to read both modules to determine that Bool.FileNotFound should be replaced with 2.

This is a problem because some developers use a workflow that separates type checking from compilation — with compilation happening on an isolated-module basis:

the compiler reads a TypeScript module;
the module's type information is stripped; and
what's left is the JavaScript module that the compiler writes.

This compilation process does not read imported modules, so it's not possible for it to support the replacement of const enum members — like Bool.FileNotFound — with their values.

The transpileModule function in the TypeScript compiler API performs this type of compilation, as does @babel/plugin-transform-typescript — which is what's used in create-react-app.

TypeScript has an isolatedModules compiler option that performs additional checks to ensure that the compiled code is safe for this type of compilation process. If you are are writing a library, you should enable this option to ensure that you are not exporting const enum declarations and that all TypeScript developers can compile code that imports your library.

Title photo by Waldemar Brandt on Unsplash.