A fairly common case I'm trying to figure out how to handle, is type annotation in json objects returned by some API.
The spec says:
Apart from primitives, the most common sort of type you’ll encounter is an object type. This refers to any JavaScript value with properties, which is almost all of them! To define an object type, we simply list its properties and their types. For example, here’s a function that takes a point-like object:
// The parameter's type annotation is an object type
function printCoord(pt: { x: number; y: number }) {
console.log("The coordinate's x value is " + pt.x);
console.log("The coordinate's y value is " + pt.y);
}
printCoord({ x: 3, y: 7 });
So we should type every parameter and nested objects? What if I don't know in advance the response body? What if the body is very long and rich in nested objects and arrays of objects?
Which would be the best practice, or the sensible alternatives in the latter case?
As an example, Axios allows you to specify the response type when making the call. This is through the use of typescript generics. You can see an example here.
You can quickly generate Typescript interfaces by pasting your API response into a tool like https://app.quicktype.io/?l=ts it converts your JSON object into typescript interfaces.
Note that if your API responses change, you'll need to ensure that your Interfaces handle all the variations.
Here is another example of specifying return types using the native 'fetch' method: How to use fetch in TypeScript
There is not much to do in the face of this problem.
Some libraries and services have cared to have their client packaged (like twilio) so that it is typed. If that's not the case and you are programming against an API (HTTP most of the time), your first alternative is to program very defensively. That is, not taking for granted that a given property will be present, as if you were using plain Javascript.
Another alternative is to do your best to try and type the responses you get from external services based on their documentation. You can do it by hand, or (and this is what I tend to do to avoid typos, you can use external tools that are able to transform a JSON response into its corresponding type.