LLM assisted backfilling of nodejs type defs #75608

SimonSchick · 2026-09-23T00:42:19Z

SimonSchick
Sep 23, 2026

Hey, I'm a former/inactive maintainer of the nodejs type defs.

I'm wondering it is permissible to back-fill missing node type definitions with the assistance of claude, specifically I'm not sure if back-filling these counts as make-work (as per https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/CLAUDE.md).

This is specifically about the node typings since they are a rather integral part of the ecosystem and they have notoriously gone out of sync with the actual node and docs on various occasions.

I've previously done this task manually by back-filling the typings from changelogs but this has been a rather.. repetitive task.

Thoughts?

cc @RyanCavanaugh since you authored these rules

Prompt I've played with locally:

This is source of the Node.js type definitions, tens of thousand of projects, libraries and millions of working hours of daily compute depend on them to work, a faulty change can have massive cascading effects.

- STRITCLY adhere to semver, changes that may seem non-breaking may be breaking in subtle and unexpected ways, breaking changes MAY be ok if the current definition is explictly and provably faulty.
- For each change you MUST cite a changelog entry from https://github.com/nodejs/node/blob/main/CHANGELOG.md OR docs from https://nodejs.org/docs/latest/api/.
    - The Node.js docs generally do not use generics/template parameters, when modeling function that use them. Uou must proof them locally, for more involved cases the proof should be included in the PR as a TERSE AND REPRODUCIBLE code block.
- Types for hard-deprecated built-ins may be removed, soft deprecations MUST use `@deprecated`.
- Do not add types for function that are already deprecated.
- Ensure your local runtime matches the type definitions you are using.
- Do NOT generate your own JSDoc, use only description from the official docs UNLESS you are documenting quirks with the definitions, be explicit about these.
- All changes must include tests.
    - For testing refer to the root README.md
- Use technical writing language, do not use idioms or rhetorical devices.

SimonSchick · 2026-09-24T18:22:20Z

SimonSchick
Sep 24, 2026
Author

Possible also @jakebailey since this requires an authoritative answer.

4 replies

jakebailey Sep 24, 2026
Maintainer

cc @Renegade334 since they're basically soloing the types right now (and doing a great job)

My understanding is that we really don't need backfilling of the Node JS types? And their website project started generating even more metadata to automate things?

What stuff are you saying is missing or wrong? I'd be shocked if we were incomplete enough to need any specific effort.

SimonSchick Oct 3, 2026
Author

Hey @jakebailey idk if you saw my reply below (I don't really know how discussions work), any thoughts on this?

jakebailey Oct 6, 2026
Maintainer

I saw it, but ultimately I'm not going to personally be the one bearing the increased load. Every missing thing is likely to be a part of all of the Node packages within the repo, so that's like 4x the review, so I would be pro "send some related fixes in one PR" and not "big AI generated single PR"

SimonSchick Oct 6, 2026
Author

That's reasonable, I'll chunk something down and see where we get with it, I've done manual big backfill PRs in the last and they generally weren't a problem, just want to make sure I'm not active breaking conduct here which it sounds like this will not.

SimonSchick · 2026-09-24T19:17:52Z

SimonSchick
Sep 24, 2026
Author

The missing bits are kind of all over the place and the 'structured' json is still not very structured at least not to a point where they seem to be reliable enough to generate type declarations from (I'm basing this on a quickly glance of the crypto module), it doesn't help that the scripts that I wrote that assisted with importing/checking haven't been updated very much either :(

Here's a small sample of missing items, they are deliberately spread across various modules to assess how complete they are, I did generate these with claude but each missing item was verified through a separate agent to avoid false positive.

Module	Missing declarations
zlib	`ZipFile`, `ZipEntry`, `ZipBuffer`, `createZipArchive`, `createZipArchiveSync`, `zipFiles`, `getMaxZipContentSize`, `setMaxZipContentSize`
crypto	`createMac`, `getMacs`, `Mac` (not exported; returned by `createMac`)
net	`BlockList`: `addCIDR`, `addCIDRs`, `addAddresses`, `removeAddress`, `removeRange`, `removeSubnet`, `removeCIDR`, `clear`, `size`, static `PRIVATE_RANGES`; `BoundSocket#isPipe`; `Server#dropMaxConnection` (settable property, cluster mode only)
perf_hooks	`createSlidingWindowHistogram` (returns a class that is not exported), `importHistogram`; `Histogram`: `export`, `cdf`, `ccdf`, `countAt`, `percentilesAt`, `burnRate`, `linearBuckets`, `logBuckets`, `ksTest`, `mannWhitneyTest`, `welchTest`, `cohensD`, `cliffsD`, `meanCI`, `percentileCI`, `qrde`, `ewmaMean`, `ewmaStddev`, `ewmaErrorRate`, `kurtosis`, `skewness`; `RecordableHistogram`: `recordCorrected`, `subtract`; `PerformanceResourceTiming`: `finalResponseHeadersStart`, `firstInterimResponseStart`, `renderBlockingStatus`, `contentType`, `contentEncoding`
sqlite	`StatementSync#close`, `#stat`, `#resetStats`, `#[Symbol.dispose]`
http2	20 `HTTP2_HEADER_*` constants; `Http2ServerResponse#writeInformation`; `Http2Server#timeout`
util	`debounce`, `throttle`, `markPromiseAsHandled`, `MIMEType.parse`, `MIMEType#toJSON`
fs	`openAsBlobSync`; `constants.UV_FS_O_TEMPORARY`, `UV_FS_O_SHORT_LIVED`, `UV_FS_O_SEQUENTIAL`, `UV_FS_O_RANDOM`; `FileHandle#pullSync`; `FileHandle` `'close'` event
v8	`setHeapProfileNearHeapLimit`; `Serializer#_setTreatArrayBufferViewsAsHostObjects`, `#_getDataCloneError`; `DefaultSerializer#_writeHostObject`; `DefaultDeserializer#_readHostObject`
process	`initgroups`
stream	`isDestroyed`
tty	`ReadStream#rawMode` (set per instance)
vm	`SourceTextModule#createCachedData`
module	`ModuleHooks#[Symbol.dispose]`
ffi	`DynamicLibrary#functions`; `'float32'`/`'float64'` type names
node:test	`entryFile` on `test:stdout`/`test:stderr` events; `counts.failed` on `test:summary`

I'd assume we are probably missing 4-5x this since I explicitly told it not to find everything just a small sample per module.

3 replies

SimonSchick Sep 24, 2026
Author

Please note these are ONLY explicitly MISSING declarations, this did not check for inconsistencies such as missing arguments, wrong arguments, removed APIs, typos etc.

hkleungai Sep 30, 2026

I think each of the missing item here deserve its own PR, before any automation process gets confirmed on @types/node.

SimonSchick Sep 30, 2026
Author

Filing each of these as an individual PR is frankly too much effort both on the filer and the reviewers and has a LOT of overhead in general, I used to do bulk updates manually before LLMs are common, I don't see how this is any different.

SimonSchick · 2026-09-30T06:21:17Z

SimonSchick
Sep 30, 2026
Author

Any guidance, do mind if I proceed?

0 replies

LLM assisted backfilling of nodejs type defs #75608

Uh oh!

Uh oh!

SimonSchick Sep 23, 2026

Replies: 3 comments · 7 replies

Uh oh!

SimonSchick Sep 24, 2026 Author

Uh oh!

jakebailey Sep 24, 2026 Maintainer

Uh oh!

SimonSchick Oct 3, 2026 Author

Uh oh!

jakebailey Oct 6, 2026 Maintainer

Uh oh!

SimonSchick Oct 6, 2026 Author

Uh oh!

Uh oh!

SimonSchick Sep 24, 2026 Author

Uh oh!

SimonSchick Sep 24, 2026 Author

Uh oh!

hkleungai Sep 30, 2026

Uh oh!

SimonSchick Sep 30, 2026 Author

Uh oh!

SimonSchick Sep 30, 2026 Author

SimonSchick
Sep 23, 2026

Replies: 3 comments 7 replies

SimonSchick
Sep 24, 2026
Author

jakebailey Sep 24, 2026
Maintainer

SimonSchick Oct 3, 2026
Author

jakebailey Oct 6, 2026
Maintainer

SimonSchick Oct 6, 2026
Author

SimonSchick
Sep 24, 2026
Author

SimonSchick Sep 24, 2026
Author

SimonSchick Sep 30, 2026
Author

SimonSchick
Sep 30, 2026
Author