cloudflare / cloudflare/workerd

✨ Feature request — expose metadata about supported node.js APIs

Open
#2,097 8 comments 1 reaction 1 assignee Claimed by @jasnell View on GitHub
Dominant language
C++
Stars
8.7k
Forks
739
Avg merge
2d 20h
Merged PRs (30d)
174

Description

# The use case

As we improve our Node.js compat story, we'd like to dynamically assemble the Node.js compat layer using a mixture of APIs provided via the runtime as well as via polyfills injected at build time (by wrangler or custom build tooling).

For APIs that are already offered by the runtime, the runtime implementation should be used. Since the runtime node.js coverage is expected to grow a little over time, we'd like the build tooling to know what APIs are provided by a given version of runtime and a given compatibility date.

By being able to consider the compatibility date and corresponding Node.js API coverage at build time, we'll be able to fine-time the build-time polyfill to absolute minimum, and also avoid situations where users could build and successfully run an app locally using a runtime that is on npm already but not yet fully rolled out to prod.

Additionally we'll also be able to introduce new Node APIs into the runtime without it becoming a change with unexpected side effects developers.

# The ask

We'd like the workerd npm package to contain a metadata file in a format that is easy to parse in javascript (ideally json), that contains information about our node.js coverage enabled using the `--nodejs_compat` flag.

The metadata file should group supported node APIs by compat date when they were enabled. The APIs should be listed at the symbol-level granularity.

An example format could look as follows:

`nodejs-compat.json`
```json
{
"2023-05-20": ["buffer#Blob", "assert#AssertionError", "assert#deepEqual", "assert/strict#deepEqual"],
"2024-03-03": ["buffer#Buffer", "path#join"],
}
```

In theory we might want to have a more generic metadata file (e.g. `runtime-compat.json` instead of `nodejs-compat.json`) that lists information about all flags and compat dates which then downstream tooling like wrangler or miniflare could use. I don't have strong opinions about that, as long as such change doesn't expand this scope of this request too much and doesn't result in long delays.

# Maintenance considerations

Ideally this file is autogenerated rather than manually maintained as part of the bazel build before the package is published.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.