Typescript definitions support

[SimonChaumet]

The problem to solve

When developing modules based on the self pattern we often don't see if a function really exists, where it is declared etc.

Proposed solution

Add typescript definition file at root project and

Alternatives

• rewrite apostrophe in typescript or other typed language that transpiles to javascript. This option would cost a lot with few benefits
• use jsdoc. This option is complicated because jsdoc does not handle all the type, however we can combine jsdoc and typescript definitions together.

Additional context

I already started a POC with few definitions

[boutell]

Hi Simon, happy to have this conversation! Can you shed any light on how this would handle a situation where a project-level module extends a core module like @apostrophecms/piece-type? As far as I know there would be no obvious way for the typings to be understood as relevant to that situation.

[boutell]

My thinking is that if you don't get type-checking of inherited methods, it's not accomplishing a lot.

We do have long-term internal plans to try to figure out a fully effective strategy for typescript and Apostrophe but outside input could be very helpful in choosing that strategy.

[SimonChaumet]

I've added the pull request with the draft code

To add module definitions you just need to override the interfaces on module side (in a typescript definition file) :

declare module "apostrophe" {
  interface ApostropheModulesOptions {
    "@apostrophecms/piece-type": {
      someProperty: number
    }
  }

  interface ApostropheModulesApi {
    "@apostrophecms/piece-type": {
      someMethodOnSelf(): void
    }
  }
}

on module side you will need to add the method createModule to allow type inference