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

[proggeramlug]

Hey @justin0mcateer — coming back on this with concrete results. Your post drove a real chunk of work that's now shipping in v0.5.606. Walking through each of your suggestions with the exact commands so you can reproduce.

The short version: all four issues we filed in response to your post (#462, #463, #464, #465) closed, plus a follow-up batch (#510, #511, #512, #513, #525, #526) that turned up while we were stress-testing the DX end-to-end. Net result is that your crypto.subtle repro now errors at compile time, undefined dereferences throw with node-shaped messages and exit 1, the supported API surface is documented and typed, and tsc catches argument-shape mistakes against the manifest's typed signatures.

TL;DR scoreboard

Your ask	Status	Issue(s)
1) PerryTS-specific .d.ts of what's implemented	shipped	#465, #512, #513, #526
2) Typecheck against those types	shipped	#463, #525 (compile-time), #512 (tsc)
3) Documentation of supported APIs	shipped	#465, drift gate v0.5.560
4) Runtime panic on undefined deref	shipped	#462, #510, #511

Concern 1 + 3: Discoverability

perry init now scaffolds a project with the full TS declarations wired in:

$ perry init my-app && cd my-app
  Created perry.toml
  Created src/main.ts
  Created tsconfig.json
  Created .perry/types/ type stubs (ui, thread, i18n, system, media, tui, stdlib)

The generated .perry/types/stdlib/index.d.ts is auto-derived from the compiler's source-of-truth manifest and ships 673 entries across 68 modules in v0.5.606. The same data is rendered as a Markdown reference at docs/src/api/reference.md and exposed via perry --print-api-manifest (json, markdown, or dts):

$ perry --print-api-manifest=markdown | head
# Supported API Reference
...
Total: 673 entries across 68 modules.

A CI drift gate (v0.5.560) re-runs the generator on every push and fails the build if the artifacts go stale, so the published reference stays in sync with the compiler's actual dispatch tables.

For your specific case: the crypto entry lists createHash, randomUUID, sha256, pbkdf2, etc. — and conspicuously does not list subtle, so a reader scanning the page knows up front that Web Crypto isn't there.

Concern 2: Catch unimplemented APIs at compile time

This was the load-bearing one. Your exact crypto.subtle shape now errors before tsc even gets involved:

$ cat src/repro.ts
import * as crypto from 'crypto';
const key = await crypto.subtle.generateKey(...);

$ perry compile src/repro.ts -o out
Error: `crypto.subtle` is not implemented in Perry — see `perry --print-api-manifest` for the supported surface, or set `PERRY_ALLOW_UNIMPLEMENTED=1` to ignore. (#463)

The check (R005 UnimplementedApi) consults the same manifest that drives the docs and the .d.ts. It fires on property reads (#463 phase A), 2-deep calls (#525), and 3-deep static-method calls (crypto.subtle.encrypt(...), #463 phase B). The escape hatch PERRY_ALLOW_UNIMPLEMENTED=1 is there for cases where a followup will fix the manifest but you want to keep moving.

For typecheck-time errors against arg shapes — your suggestion (2) — tsc -p . on a perry init project picks up the typed signatures:

$ cat src/main.ts
import { hash, compare } from 'bcrypt';
const ok   = await hash("hunter2", 10);
const bad  = await hash(12345, 10);        // wrong type
const bad2 = await compare("hunter2");     // wrong arg count

$ tsc --noEmit -p .
src/main.ts(3,24): error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.
src/main.ts(4,20): error TS2554: Expected 2 arguments, but got 1.

(That tsc flow was actually broken on the first try — delete is a JS reserved word and the .d.ts emitter wasn't escaping it for axios.delete(). Filed as #526 and fixed in v0.5.606. The full demo only finalized after that landed.)

Concern 4: Runtime panic on undefined dereference

Pre-fix behavior was the silent-undefined fall-through you described. Now:

$ cat src/undef.ts
function loadConfig(): any { return undefined; }
const cfg = loadConfig();
console.log('before deref');
const port = cfg.server.port;
console.log('after — should never print');

$ perry compile src/undef.ts -o out && ./out
before deref
TypeError: Cannot read properties of undefined (reading 'server')
$ echo $?
1

Node-shaped error message, exits 1 (so CI scripts and process supervisors detect the crash — fixed in v0.5.597 / #511 — previously exited 0), execution stops at the bad line.

Same pattern works on the related case of typo'd method calls on primitives (#510, v0.5.593) — the "I meant .length but typed .lengt()" footgun:

$ ./out_typo
before typo call
TypeError: (string).lengt is not a function
$ echo $?
1

Bonus: stub registry diagnostics (#464)

Some symbols link cleanly on every platform but no-op at runtime on the wrong target — e.g. audioStartRecording is a real implementation on macOS/iOS/Android but a stub on harmonyOS. Pre-#464 this was another silent-failure mode.

$ perry check src/stub_demo.ts --target harmonyos
warning[R004]: `audioStartRecording` from `perry/system` is a no-op stub on this target — harmonyos perry/system FFI: not implemented on this build (tracking: #399)
  --> src/stub_demo.ts:4:35
   |
 4 | import { audioSetOutputFilename, audioStartRecording, ... } from 'perry/system';
   |                                   ^^^^^^^^^^^^^^^^^^^

Plus a runtime first-call warning when execution actually hits a stubbed symbol. PERRY_STUB_DIAG=verbose prints every call, =off silences.

Bonus: unified message format (#525)

When you write code that hits an unimplemented API, the error is the same regardless of which path the AST took to get there:

$ perry compile fs_bogus.ts
Error: `fs.bogusMethod` is not implemented in Perry — see `perry --print-api-manifest` for the supported surface, or set `PERRY_ALLOW_UNIMPLEMENTED=1` to ignore. (#463)

$ perry compile ui_bogus.ts
Error: `perry/ui.bogusWidget` is not implemented in Perry — see `perry --print-api-manifest` for the supported surface, or set `PERRY_ALLOW_UNIMPLEMENTED=1` to ignore. (#463)

$ perry compile crypto_subtle.ts
Error: `crypto.subtle` is not implemented in Perry — see `perry --print-api-manifest` for the supported surface, or set `PERRY_ALLOW_UNIMPLEMENTED=1` to ignore. (#463)

Same shape, same hint, same escape hatch, same (#463) reference. You learn the format once.

Honest gaps still on the list

Want to be straight about what's not yet polished:

• Manifest argument types are partial. ~10% of entries (mostly the older crypto/os/path hand-curated ones) still emit (...args: any[]) => any because the manifest doesn't carry their param types yet. Tracked at issue level — the mechanism is there (you can see it in bcrypt.hash(password: string, ...)), it's a backfill task. New wrappers ship with typed signatures.
• axios.delete after import axios from 'axios' doesn't typecheck because the manifest models the default export as a plain function, not as the callable-namespace shape axios actually has. Separate from DX: generated .d.ts doesn't escape JS reserved words used as method names — tsc -p . fails on fresh perry init #526. Working around it via named imports today.
• Bare-global crypto (no import) falls through the manifest gate at compile time because the gate keys off the import binding. The runtime primitive-receiver TypeError (Runtime: throw TypeError on property access against primitive receivers (number, boolean, raw f64) #510) still catches it, just one stage later. Followup planned.

Try it

If you have a few minutes, the v0.5.606 binary makes the original repro a two-command verification:

$ npm install -g @perryts/perry
$ perry --version
perry 0.5.606
$ cat > test.ts <<EOF
import * as crypto from 'crypto';
await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt']);
EOF
$ perry compile test.ts -o test
Error: `crypto.subtle` is not implemented in Perry — ...

Thanks again for the detailed report — it forced us to think about the DX story end-to-end rather than as scattered ergonomics. If you have time to give v0.5.606 a real workout against your JWS/AES code, I'd love to know what the next round of friction looks like. Always more sanding to do.

Best,
Ralph

[justin0mcateer]

Awesome! Thanks for the thorough response. Will definitely give it another look soon.