The first version of Wijmo was written in TypeScript 1.0, and it has always been used in typing to help improve code quality. In the Wijmo 2019 v3 release, we did some extensive refactoring to leverage the latest improvements in TypeScript to improve typing support, so developers get better IntelliSense and compile-time error checking (in addition to the run-time checks we have always used).
Read the full Wijmo v3 release
The typing improvements fall into four main categories:
- Callback type information
- Union type parameters
- Generic CollectionView/ObservableArray
- Generic events
Callback Type Information
Many Wijmo classes have properties that represent callback functions. These used to be declared as "Function," which did not provide any the compiler with any information about the callback's parameters or return type.
To use those callbacks, you had to refer to the documentation.
For example:
Old-style Callback (no type information)
Note: now the tooltip only tells us that it expects a function. There's no information about the parameters or return type. Not very helpful.
In the latest build, we added type information to all callbacks, so now you get this:
New Callbacks (full type information)
This time, the tooltip shows that the callback function is expected to have four parameters, and it shows type information and documentation for each one.
This change applies to all callback functions and properties in Wijmo. And it is backward-compatible.
Union Type Parameters
A few Wijmo methods support parameters of different types.
For example, the FlexGrid.select method allows you to pass in either (a) row and column indices or (b) a CellRange and a Boolean value.
To support these two options, the method used to declare the parameters as type any. This worked, but if the developers used a string as a parameter, the method would throw an exception at run-time. The developer would get no help at design time.
For example:
Old-style multi-type parameters (any type)
In the latest version, we re-worked all these calls to use union types instead, so now you get this:
New-style multi-type parameters (union types)
Now, the tip clearly shows that the first parameter is a number or a CellRange, and the second is a number or a Boolean. The comments for each parameter explain what each option means. And trying to use an invalid type would cause a compile-time error.
This change applies to all multi-type methods in Wijmo. And it is backward-compatible.
Generic CollectionView/ObservableArray
The CollectionView class in Wijmo is responsible for handling data on behalf of all controls. It can store, filter, sort, group, add and remove items, as well as manage currency.
In previous versions, the CollectionView kept items of type any, so if you retrieved the current item for example, you had to explicitly cast it to the type you wanted to use.
For example:
Old-style CollectionView (items of any type)
This code also works with the latest version, but now we added an optional type parameter that allows you to write the same code this way:
New-Style CollectionView (typed items)
Declaring the type of item in the CollectionView is optional, but it can in many cases make your code safer and more readable.
The ObservableArray class has also been updated to use a generic parameter for the item type.
Generic Events
The last type enhancement we added is generic events.
In previous versions, adding event handlers to Wijmo controls required knowledge about the event parameters, which often meant looking at the documentation.
For example: 
Old-style event handlers (no argument type information)
Note how the tooltip only tells you that the event arguments are an instance of the EventArgs class, the base class for all types of event arguments. This is correct, but not very useful.
Using the latest version, you get this instead:
New-style event handlers (with sender and argument type information)
Notice how now you get the sender and argument types automatically. No need to refer to the documentation to figure out the arguments for each event, and no risk of using the wrong argument type.
Build Errors
When we re-built our samples using the new version of Wijmo, a few of them broke and would not compile (in case you are curious, the exact number was 20 broken samples out of 460, or about 4%).
We were concerned at first, but when we looked at the samples, we realized they all had subtle bugs and the compiler was now able to find them for us.
The errors fell into three categories:
- Event handlers with wrong 'sender' type. In these cases, the developer who wrote the sample specified the (wrong) type for the 'sender' parameter. The parameter was not used by the handler, so the sample worked. But it was a bug waiting to happen. The fix was simple, we just fixed the parameter type.
- Delegates with the wrong return type. One of the samples defined a PropertyGroupDescription with an IGroupConverter function that returned dates instead of strings. Since JavaScript automatically converted the dates into strings, the grouping and the sample worked as expected. But the simple fix (calling toString on the dates) made the code clearer and safer.
- Assuming certain types. One of the samples broke because it assumed that the elements in a CollectionView.groupDescriptions collection contained PropertyGroupDescription objects. That was actually true in the sample, but it is not true in general (the collection contains GroupDescription objects, the base class for PropertyGroupDescription). The fix in this case was simply casting the member to PropertyGroupDescription, which made the type assumption explicit and the code clearer/safer.
Fixing these errors took only a few minutes, and the result is a better set of samples with code that is clearer and safer. Best of all, the errors were found at design time, so we could easily pinpoint their location and fix them.
We thought we should mention this because you may run into a similar experience when building your Wijmo apps with improved typing.
We hope your code doesn't have any bugs, but if it does the new Wijmo will help you (and the TypeScript compiler) find them.
Conclusion
The extra type information in Wijmo provides the following benefits:
- More error-checking, which results in fewer bugs.
- More IntelliSense support, which makes development easier, faster, and safer.
- Better/more complete on-line documentation, since the extra type information is automatically picked up by our documentation tools.
- Because the type information is used only at compile time, these benefits com with zero cost in terms of library size/footprint.
The latest version of Wijmo offers several new and exciting features. Richer type-checking is one of my favorites because it applies to the entire library. It leverages the power of the TypeScript compiler to help developers write better code faster, no matter what controls they are using.
