Parse-server: Typescript definitions outdated

[sadortun]

New Issue Checklist

• [x] I am not disclosing a vulnerability.
• [x] I am not just asking a question.
• [x] I have searched through existing issues.
• [x] I can reproduce the issue with the latest version of Parse Server.

Issue Description

Not sure if i'm dooing something wrong, but it seems the typescript definitions doesnt match. For all Cloud methods, validationHandler are missing

ParseCloud.beforeSave = function (parseClass, handler, validationHandler) {
// ...
};

      function beforeSave<T extends Object = Object>(
                arg1: { new (): T } | string,
                func?: (request: BeforeSaveRequest<T>) => Promise<void> | void,
            ): void;

Steps to reproduce

Parse.Cloud.beforeSave('test', async (request) => {
}, {
  fields: {
  },
})

Actual Outcome

 - error TS2554: Expected 1-2 arguments, but got 3.

Expected Outcome

no errors :)

Failing Test Case / Pull Request

• [ ] 🤩 I submitted a PR with a fix and a test case.
• [ ] 🧐 I submitted a PR with a failing test case.

Environment

Server

• Parse Server version: 4.5.0
• Operating system: windows
• Local or remote host (AWS, Azure, Google Cloud, Heroku, Digital Ocean, etc): local

Database

• System (MongoDB or Postgres): mongo
• Database version: eh
• Local or remote host (MongoDB Atlas, mLab, AWS, Azure, Google Cloud, etc): local

Client

• SDK (iOS, Android, JavaScript, PHP, Unity, etc): js
• SDK version: 3.1

Logs

[mtrezza]

Thanks for reporting.

Parse types are managed in @types/parse, so any PR should be submitted there.

However, I wonder if we could auto-generate the type definitions and bundle them with this package or the Parse JS SDK package, instead of manually maintaining the @types/parse repo. If we decide to tackle this (and make many Parse Server developers happy), then this issue should be renamed / changed accordingly, otherwise this issue is to be closed, as types are currently not managed by Parse Platform.

Related: https://github.com/parse-community/parse-server/issues/6727

[sadortun]

Seems like we can already generate definitions from JSDoc annotations blocks

https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html

I'm fairly sure this isnot going to work all at once, but of someone else is interested in helping on this, o think it can be doable.

[mtrezza]

@sadortun Would you want to look into this to find out what we are missing to generate from the annotations?

[sadortun]

@mtrezza I did start to take a look, but my first tests yielded over 1000 errors :) .... I'll try to do a few more tests, but i dont have much time in the upcoming weeks

[sadortun]

@mtrezza I'm not a Typescript Expert, but one question i have for you is why dont we rename all .js files to .ts files ?

Currenly i have a few thousands of theses errors : TS8010: Type annotations can only be used in TypeScript files.

[swittk]

Regarding renaming .js to .ts, I've been wondering that too.

I'd noticed that in many of the files, functions are fully annotated with Flow types. It shouldn't be that hard to simply convert all files to .ts with the function types being the ones already defined there.

But I don't know if there are still people using Flow. If they still do, then changing .js to .ts might break people's workflows.

[sadortun]

I think we should rename files to ts for the next major release.

Meanwhile, I can try to get something working, but I don't want it to go to waste if its not going to be merged.

[mtrezza]

I think using TypeScript would also be a good best practice addition to the example repo, @dblythy?

Switching Parse Server to TypeScript is probably not a bad idea, although there are syntactic differences between Flow and TS, it seems that TS is developing into the de facto standard.

@dplewis @davimacedo What do you think?

[dblythy]

Forgot to mention that this issue will be closed here.

Switching Parse Server to TypeScript is probably not a bad idea

I think converting the Parse Server Example to Typescript would be a good improvement. Parse is appealing to new developers and I think it's important that we introduce them to industry standards where possible.

[sadortun]

@dblythy just for my understanding, did you update the TS typrs by hand or there is a way to regenerate them ?

Could/should we have something In The docs regarding this ?

[dblythy]

I did them all manually @sadortun. I tried to automate it but couldn't get it working with enough depth.

[sadortun]

Thanks a lot @dblythy you're awesome! I'll submit my a PR directly there of I see anything else missing

[mtrezza]

Is anyone interested in looking into how to automate this and make it part of our package so this tedious manual work doesn't have to be done?

This would play nicely with the release automation philosophy that we are currently pursuing.

[dblythy]

I tried with no success, I’m not overly familiar with Typescript.

Also I’m relation to the example repo, perhaps we could have parse-server-typescript-example?

We could also add some full stack examples with /Backend and /Frontend folders organised such as the project @sadortun shared earlier. I’m thinking we could have boilerplate:

-parse-server-mean-example
-parse-server-mern-example
-parse-server-mevn-example

Just to make it a lot easier for modern JS framework devs to get started.

[mtrezza]

Not sure whether we want to maintain multiple repos. I think also within typescript it is possible to have non-types files. The challenge is that every repo requires resources for maintenance. We can always add a list of community maintained example repos that are not maintained by Parse Platform though, just like we do with various adapters.

[sadortun]

@mtrezza

I think also within typescript it is possible to have non-types files.

Yes and no, Typescript can parse .js files containing JavaScript.

Currently .js files includes Type definitions and it breaks TSC.

If you are interested in moving toward Typescript, I can start dooing some tests to see what's possible. But at a minimum that's involve renaming all js to ts.

I think it could be a great Leap forward!

[mtrezza]

But at a minimum that's involve renaming all js to ts.

I think we should explore a transitional approach, otherwise the PR will have a hard time to keep up with changes. Large-scale all-at-once changes rarely work well.

Currently .js files includes Type definitions and it breaks TSC.

Maybe there is comment tag that makes TS ignore that or silence errors on file level?

[dblythy]

Sorry to interrupt - @sadortun you can close this issue as the definitions should now available in 2.18.5

[sadortun]

@dblythy @mtrezza ive been thinking about this for some time and I think we can do better.

DefinitelyTyped repo is good when the main project doesn't support typescript or types are contributed from a separate entity, but I think in the case of Parse we should have types definitions moved back to the intro parse-server and JS SDK repo.

In addition, expecially considering the plan to include a deprecation strategy that will span on multiple branches (stable, beta, next).

Theses types definitions needs to follow the branch and release cycles.

Its natively supported by package.json and Typescript. I don't see any drawback to dooing this. Or any impact on non-typescript users

This will also ensure that new PR that adds or remove features will have matching Typescript definitions. Otherwise, I have no idea how you can synchronize merged PR additions with the type definitions.

As of now, there is still a lot of incorrect/missing Typescript definitions in Parse-server.

Having theses types in this repo would solve so many issues. Otherwise @types/parse will never be in sync with the actual code.

I can submit a PR about this in the next days, and also fix multiple broken definitions.

As of @types/parse you can leave it in this current state, and in the next releases notes add a deprecation notice to mention the definitions are now part of the project.

Have a nice day,
Samuel

[sadortun]

@mtrezza

Maybe there is comment tag that makes TS ignore that or silence errors on file level?

I don't think so, Typescript parser doesn't expect typescript definitions in JS files.

See https://github.com/microsoft/TypeScript/issues/35470

[mtrezza]

DefinitelyTyped repo is good when the main project doesn't support typescript or types are contributed from a separate entity, but I think in the case of Parse we should have types definitions moved back to the intro parse-server and JS SDK repo.

First, hats off to @dblythy for manually updating the TS definitions, it can bring some immediate relief until we automate the TS definitions creation.

I agree, manually adding definitions is not sustainable and inconsistent when Parse Server is concurrently distributed on multiple channels. It's never too much work to do it manually - until it is. Hence we are moving to automated releases now, and I think the logical step is to follow the same philosophy with TS. As @dblythy suggested, you may want to close this specific issue if it is fixed now, and open a new issue that focuses on automating TS definitions.