Typescript declarations

[ptbrowne]

The idea here is to use the JSDoc comments that we already have in a lot of files of cozy-client (JSDoc is used to generate API docs automatically) to generate typescript declarations and to typecheck cozy-client at transpile time.

Gains:

• More confidence for cozy-client's developer
• DX is improved for cozy-client's users (IDE help)

Example

In:

/**
 * A good dog
 */
class Dog {
  constructor() {
    this.name = 'Hello'
  }
  /**
   * Woofs !
   *
   * @param {String} msg - What to woof
   * @return {void}
   */
  woof(msg) {
    this.name = 0 // PROBLEM Changing string to number
    console.log(msg)
  }
}

const dog = new Dog()
dog.meow() // PROBLEM Absent method
dog.woof() // PROBLEM Missing argument

Out:

/**
 * A good dog
 */
declare class Dog {
    name: string;
    /**
     * Woofs !
     *
     * @param {String} msg - What to woof
     * @return {void}
     */
    woof(msg: string): void;
}
declare const dog: Dog;

It means that before publishing cozy-client, a typecheck pass will be done.

• We continue to use our existing babel transpiler

• Typescript only emits declarations (those declarations are then picked up by IDEs to show contextual helps, see screenshots below)

  • These declarations are generated from JSDoc comments (See 1)
  • These declarations are picked up by my editor (SublimeText) if I
    install the Typescript plugin, see screenshots below

• Checks that intra cozy-client, methods are called with the right parameters etc...

• ⚠️ To be able to typecheck, I had to install redux@4 otherwise we had
  an error, I think we should have the redux update as part of another
  PR. See for the problem TS2315: Type 'Middleware' is not generic reduxjs/redux-thunk#205

• ⚠️ I had to remove some errors (13) with @ts-ignore. I do not think it's problematic.

IDE screenshots

Documentation

These two can be useful before reading the PR:
https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html
https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#param-and-returns

[ptbrowne]

For the redux 3 to 4, since the breaking changes are mostly cosmetic and should not impact us (I haven't seen any error), I believe we could have redux@4 as dev dependency and support redux@3 and 4 in peer deps.

[Crash--]

Incredible work! Once green 👍 ;)