... it’s interesting that you can express something like “an array of even length” using a TypeScript interface.
Vanderkam, Dan. Effective TypeScript . O'Reilly Media. Kindle Edition.
Intro
I want to start by saying I think it's really cool how JavaScript arrays can contain elements of different types. And it's even cooler that Dan has a plausible example of when we would want to use this feature and how to type such an array if we do use this feature. So let's dig in.
The example
Say we have a Lisp-like language defined in JSON
12
"red"
["+", 1, 2]
["/", 20, 2]
["case", [">", 20, 10], "red", "blue"]
["rgb", 255, 0, 127]
In this example, each array represents a function call, where the first element is the name of the function, e.g +, and the following elements are parameters to the function.
Our goal is to write type declarations for these inputs to make sure the inputs conform to a well-defined specification.
For motivation, note that the Mapbox library[1] uses a system like this to determine the appearance of map features across many devices, so it's likely we'll come across similar libraries such as Mapbox whose JSON inputs we'll need to type.
For reference, this example is gotten from item 34 of the book, Effective TypeScript.
The process
Quite similar to regular development, Dan suggests adopting a test driven process, and I suggest reading the chapter to see the evolution of passing the test cases, but I want to focus on just the step that caught my interest.
Define test cases
Dan kicks off the process with these test cases, noting the expected outcomes in comments. As the process evolves, we check the output our typescript checker gives us against our expected outcomes.
const tests: Expression2[] = [
10,
"red",
true,
["+", 10, 5],
["case", [">", 20, 10], "red", "blue", "green"],
["**", 2, 31],
["rgb", 255, 128, 64],
["rgb", 255, 0, 127, 0]
];
Vanderkam, Dan. Effective TypeScript . O'Reilly Media. Kindle Edition.
At step 3 of the process we're able to allow strings, numbers, and arrays starting with known function names, with the following type definitions.
type FnName = '+' | '-' | '*' | '/' | '>' | '<' | 'case' | 'rgb';
type CallExpression = [FnName, ...any[]];
type Expression3 = number | string | CallExpression;
const tests: Expression3[] = [
10,
"red",
true,
["+", 10, 5],
["case", [">", 20, 10], "red", "blue", "green"],
["**", 2, 31],
["rgb", 255, 128, 64],
["rgb", 255, 0, 127, 0]
];
But the next step is the most interesting to me:
What if you want to make sure that each function gets the correct number of arguments?
Progressively define more accurate types
Here's the solution with progressively more accurate types, with my inline explanations.
type Expression4 = number | string | CallExpression;
type CallExpression = MathCall | CaseCall | RGBCall;
type MathCall = [
'+' | '-' | '/' | '*' | '>' | '<',
Expression4,
Expression4,
];
interface CaseCall {
0: 'case';
1: Expression4;
2: Expression4;
3: Expression4;
4?: Expression4;
5?: Expression4;
length: 4 | 6 | 8 | 10 | 12 | 14 | 16;
}
type RGBCall = ['rgb', Expression4, Expression4, Expression4];
const tests: Expression4[] = [
10,
"red",
true,
["+", 10, 5],
["case", [">", 20, 10], "red", "blue", "green"],
["**", 2, 31],
["rgb", 255, 128, 64],
["rgb", 255, 0, 127, 0]
];
What I found interesting here is that using recursive types, we can express the idea of a function calling other functions, e.g an addition function call, calling a subtraction operation ["+",["-", 5, 1],4].
And combined with the use of an interface, in this instance, CaseCall, we can express the idea of "an array of even length," using the length property.
I found it a brilliant use of simple operations to "almost" effectively model the complex array types we should expect.
I say almost because, even though the test cases come back positive against our expectations, the difficult to read error messages such as:
// Type '"case"' is not assignable to type '"rgb"'.
suggest that perhaps we should prefer a less accurate type than we've strived for. Dan gives more reasons for this preference in the chapter so again I suggest reading it.
For the record
["case", [">", 20, 10], "red", "blue", "green"],
comes about because this is an array of length 5, and so it cannot be of type CaseCall which only expects even lengths. Therefore the type checker assumes it's of type RGBCall.
Interestingly, when I try to define RGBCall as length 4, the type checker then assumes it's a MathCall
And if I continue along that path and fix MathCall to a length of 3, it concludes the expression cannot be a CallExpression, showing how powerful the length specification is when typing an array.
Conclusion: Prefer incomplete types to inaccurate types
The item containing this lesson concludes that we should avoid such complex types if they result in confusing error messages, and I think it's a really good point to note if you agree with Dan when he says the TypeScript's language services are as much a part of the TypeScript experience as type checking.
Dan also leaves us with the following re: the types from above.
The complexity of this type declaration has also increased the odds that a bug will creep in. For example, Expression4 requires that all math operators take two parameters, but the Mapbox expression spec says that + and * can take more. Also, - can take a single parameter, in which case it negates its input. Expression4 incorrectly flags errors in all of these:
const okExpressions: Expression4[] = [
['-', 12],
['+', 1, 2, 3],
['*', 2, 3, 4],
];
Happy typing 🥳
Links
[1] - Mapbox Library
