Use JSDoc annotations with @typedef's for TypeScript support

[jgaehring]

As a large portion of the JavaScript community seems to be gravitating towards TypeScript adoption, I've considered the possibility of using converting to TS for this codebase. I think this would be a nice level of added documentation, in conjunction with #22 of course, and provide some nice IDE integrations for consumers of this library.

However, I've seen quite a few opinions that for libraries it can be preferable to provide comparable support by using JSDoc annotations with the @typedef annotation. Mainly this is b/c it obviates the need for a compilation step, so both JS and TS consumers can run it from source and compile as they like, using Babel, TSC or what have you.

Good documentation for this here:
https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#typedef-callback-and-param

[jgaehring]

A few links and notes from some preliminary investigation I did tonight....

Gil Tayar's Blog - JSDoc typings: all the benefits of TypeScript, with none of the drawbacks
A really good walkthrough of the basic steps for setting up Typescript specifically for using JSDoc only. Particularly helpful is the section Configuring typescript options correctly. I've basically copy-and-pasted the tsconfig.json from there, although I will probably scale back from strict mode, which reports 211 errors, as opposed to 8 errors with it off.

Carl Rippon - Controlling Type Checking Strictness in TypeScript
For fine-tuning aforesaid strictness.

TypeScript Docs - TypeScript in Your Project
Found it surprisingly hard to find basic info on installing and running the tsc compiler (some older articles say you have to install it globally, but that's no longer true with npx). Most other stuff seems easily searchable in the TypeScript docs.

Joshua's Docs - JSDoc Cheatsheet and Type Safety Tricks
This post has an insane amount of info and helpful resources. I hesitated to include it here at first, thinking it was overkill and most of the useful stuff is covered in the sources above. After actually trying to add some types, however, I realize that some of the "Advanced Usage" sections, like Annotating function signatures / function as a type, could really come in handy, dealing with some of the FP patterns I tend to use. The How to Trigger the JS Type Checker section was also helpful for figuring out tsc, but it was one of the sources that also said it need to be installed globally, which is no longer the case with npx.

Regarding functional programming patterns, I also came across this section, Point-free programming, from the TypeScript docs that was a little dismaying:

Point-free programming — heavy use of currying and function composition — is possible in JavaScript, but can be verbose. In TypeScript, type inference often fails for point-free programs, so you’ll end up specifying type parameters instead of value parameters. The result is so verbose that it’s usually better to avoid point-free programming.

Pretty lousy take, imo, but honestly it may be just as well to spend more time "specifying type parameters instead of value parameters," since I think a huge part of the value of type annotations in our case is in providing better insight into the rather complex data structures we're handling. I'm also reminded how Scott Wlaschin emphasizes that data composition is the other side of the coin of function composition, and every bit as essential to FP.

[jgaehring]

Gonna hold off a little longer on this until I get to the rest of the documentation (#22). I've started a branch with the tsconfig.json and TypeScript as a dev dependency (jgaehring/farmOS.js@879616e), so I can pick this back up then. I think it will be a good approach at that time to start by just annotating the main package exports, then non-strict errors, and probably leave it at that for now.

[jgaehring]

I happened to be looking at AJV and Cambria libraries to see how they define their types for JSON Schema, and I think it would be best to import AJV's definitions to replace the super simple JsonSchema type definitions I'm using currently:

/**
 * @typedef {Object|Boolean} JsonSchema
 * @typedef {Object|Boolean} JsonSchemaDereferenced
 */

The JsonSchemaDereferenced definition may still take a little coercing to get right, but at least the AJV definitions should provide a good starting point. Eventually I'd like to use AJV for validation, too, so it makes sense to use it for type defiitions as well.

Cambria seems to be inferring types from an older npm library, json-schema, which doesn't define its own types. Judging from some of the comments, the conversion seems to be a little rough around the edges, so probably best to avoid.

[jgaehring]

I've added type annotations for all the main exports and their methods. Plenty more that could be done, and it would be nice to add more strictness, but this should suffice for the sake of adding a little better code completion etc in IDE's. Hopefully this will be enough to generate my API reference docs too 🤞.