Developer Experience

[justin0mcateer]

First, let me say how impressive the project is already. I realize this is a very new project and there is a very long way to go to maturity. However, what is been done so far is amazing.

I spent a few hours working on a proof of concept for a small application that would need to interact with some REST APIs and perform some encryption functions related to JSON Web Signatures (JWS) and AES decryption. Initial 'hello world' was no problem out of the box. However, once I started getting into creating the cryptography I started running into issues. The technical issues could be worked around, but the developer experience is what I want to discuss here.

My code would compile with type-checking and run to completion without indicating any issue. However, the code was not working as expected. As it turns out, the code I was trying to use (based on our existing code from another project) crypto.subtle, which appears not to be implemented in PerryTS currently, fine whatever. The more challenging issues I faced (as I see them) are as follows:

1. While there is an attempt to re-implement various NodeJS APIs, the implementations are not complete (understandable/expected). However, there is no way to tell what is available without reviewing the Rust source code. Some documentation, or perhaps PerryTS specific TypeScript type definitions would be very helpful here.

2. The compiled code seems to continue running despite functions and properties being dereferenced against undefined. This is surprising, as any JavaScript run-time will throw/panic/etc when attempting property access on an undefined value. The real impact is that it makes it extremely hard to tell where the code is actually going wrong, and the developer is reduced to placing console.log statements after every line of the program.

Concretely, these are the specific suggestions I would make:

1. Produce TypeScript types specific to PerryTS indicating which exactly Classes and Methods are actually implemented.
2. TypeCheck against these specific types to allow run-time problems to be caught at compile time.
3. Produce documentation (perhaps from the type definitions) indicating exactly which NodeJS APIs are currently supported.
4. Have the run-time code panic and produce some usable information when a property is dereferenced against undefined.

[proggeramlug]

Hey @justin0mcateer ,

thank you so much for your detailed report! I appreciate honest feedback like this and need it to improve this project. So by all means, all feedback is always welcome!

What you are describing is real, and the developer experience is the most important aspect of such software. So I will dive into this deeply shortly. I'm just about to release a new version and right after I'll dig into DX and your suggestions in particular. Others have voiced similar things and so this will come as one of the next things.

Anything else you would like to see, I'm always open to hearing it! :)

Best,
Ralph

[proggeramlug]

Issues filed:

• Runtime: throw TypeError on property access against undefined / null #462 — Runtime TypeError on undefined/null property access
• Compile-time error for unimplemented Node / Web APIs #463 — Compile-time error for unimplemented Node/Web APIs (compiler-first, not .d.ts-first)
• Stub registry + first-call runtime diagnostic for no-op stubs #464 — Stub registry + first-call runtime diagnostic
• Generate API support docs (and optional editor .d.ts) from compiler manifest #465 — Generated API docs (+ optional editor .d.ts) from Compile-time error for unimplemented Node / Web APIs #463's manifest