Add TypeScript definitions with JSDoc

[mtrezza]

New Pull Request Checklist

• I am not disclosing a vulnerability.
• I am creating this PR in reference to an issue.

Issue Description

Currently, Typescript definitions are maintained via DefinitelyTyped which is:

• not compatible when distributing Parse Server / Parse JS SDK concurrently via multiple distributions channels
• a manual effort that should be automated
• simply tedious

Related issue: #7334

Approach

Add typescript compiler to create TS definitions from JSDoc.

Run npm run types to create types in ./types/.

Notes:

• TS definitions in Parse JS SDK have to be addressed in the respective repo.
• TS compiler required refactoring of src/Adapters/Auth/OAuth1Client.js

TODOs before merging

• Add TS compiler run to CI and build / release process
• Adapt TS compiler setting to only generate relevant TS definitions
• Improve quantity and quality of JSDoc annotataions
• Add entry to changelog
• Add changes to documentation (guides, repository pages, in-code descriptions)

[dblythy]

It seems to me that from the type files generated, that this wouldn't provide much benefit from a Parse Server developing perspective.

This is the problem I experienced when I tried to automate the types. Although this will work, it doesn't really add much value / enforce the specific options, such as req.user, req.master, etc.

For example, the automated definition for Parse.Cloud.define:

export function define(functionName: any, handler: any, validationHandler: any): void;

Compare that to the manual current definition:

interface FunctionRequest<T extends Params = Params> {
  installationId?: string;
  master?: boolean;
  params: T;
  user?: User;
}
interface ValidatorField {
  type?: any;
  constant?: boolean;
  default?: any;
   options?: any[]|Function;
  error?: String;
}
interface ValidatorFields {
  [field: string]: ValidatorField;
}
interface Validator {
  requireUser?: boolean;
  requireMaster?: boolean;
  validateMasterKey?: boolean;
  skipWithMasterKey?: boolean;
  requireAnyUserRoles?: String[]|Function;
  requireAllUserRoles?: String[]|Function;
  fields?: ValidatorFields|String[];
  requireUserKeys?: ValidatorFields|String[];
}
function define(name: string, func: (request: FunctionRequest) => any, validator?: Validator|((request: FunctionRequest) => any)): void;

In terms of a user perspective, the two most critical components are obviously that the Parse Server Config in index.js is correctly typed (which again, the types generated for ParseServer constructor allows for any), as well as the usage of Parse.Cloud, Parse.Query, etc.

Which to me, would seem that this repo would need a typescript definition for ParseServer, and the JS SDK would handle all the other types, such as Parse.Cloud.define. Any other typescript definitions would be for the benefit of future contributors, which would be an improvement, but not as critical in terms of user usage.

[mtrezza]

This is just a proof of concept that the generation works based on JSDoc.

Updating the JSDoc would solve this, we can define interface types and get to exactly what the manual types currently are. That is why I think this approach of decoupling flow from TS and only use JSDoc would be an easy way to go, and eventually allow us gradually implement TS in the repo without any interference.

But I am curious to see the flow-to-ts PR and see which one makes more sense.

[dblythy]

Cool, sounds good to me. Does this means that definitions will move away from Flow and instead by TS?

[mtrezza]

Yes, but that is a different topic, see point (3) in the larger discussion. This PR is about point (2) and point (1) which seems unnecessary to me is currently being discussed.

[mtrezza]

Closed in favor of #7337.