Compile undici from a built-in implementation

[cramforce]

Summary

scriptc now implements undici itself and compiles that implementation in place of the package's published JavaScript. It does this through a general mechanism that maps an npm package name to a TypeScript module shipped with the compiler. The same registry also lets a project mark optional dependencies as never loaded.

Package shims (packages/compiler/src/frontend/package-shims.ts)

• Implementation entries. A registry entry maps a package name and a supported major version to a module under packages/compiler/shims/. undici 5.x maps to shims/undici/v5.ts and 7.x to shims/undici/v7.ts.
  • The importing package's installed package.json picks the entry. A program with undici 5.12 in one workspace package and 7.30 in another compiles each against its own version.
  • When the package isn't installed, or its major version has no entry, nothing is shimmed and it resolves exactly as before.
• Where the redirect happens.
  • Module edges go through resolveProjectImport (preflight, module order, the CommonJS link). It runs after provenance and tsconfig paths, so a project mapping still wins.
  • resolveNpmImport7, the pipeline's npm-edge walk and the --npm-static package set all skip shimmed packages.
• How the checker sees the shim. This uses the tsgo host's file read, not tsconfig paths, because paths maps every importer to one file. The installed package's index.d.ts reads as export * from "<shim>", so types resolve per importer, the way the real declarations do.
  • Type errors inside shim files don't count as the project's own errors. They are compiler-owned code, much like library declarations under skipLibCheck.
• Unloaded entries. "scriptc": { "packages": { "encoding": "unloaded" } } in the entry's package.json marks a package as never loaded.
  • require("encoding") then throws Node's not-installed MODULE_NOT_FOUND, so try { require("encoding") } catch {} takes its absent branch, and the package never joins the program. This applies decision D6 to node-fetch's encoding.
  • A static import of such a package reports Node's ERR_MODULE_NOT_FOUND.
• Configured stand-ins (for example a no-op dd-trace tracer) are documented in the module header but not implemented. They are an implementation entry whose module the project supplies. A tsconfig paths mapping already does this today.
• Shipping. The shims ship in the compiler package (files) and in native distributions (declarations/shims).

The undici shim (packages/compiler/shims/undici/)

The shim is plain TypeScript over node:net, node:tls and node:events. core/* is shared, and the v5.ts/v7.ts entries subclass Client, Pool and Agent with a version profile, so instanceof and default factories match each version.

• Clients and dispatch.
  • Dispatcher is an EventEmitter with the dispatch(opts, handler) contract. It accepts both the 5.x handler callbacks and 7.x's controller API (onRequestStart and the rest).
  • Client is HTTP/1.1 over one connection: keep-alive reuse with Keep-Alive hints, headersTimeout/bodyTimeout/idle timeouts, a request queue, maxRequestsPerClient, and back-pressure. 7.x uses undici's 499 ms fast timers for headers and body timeouts.
  • Pool creates clients up to connections and exposes stats. 7.x drops clients whose connection failed.
  • Agent keeps one dispatcher per origin, with factory(origin, opts) and connect options. 7.x closes an origin's dispatcher once its connections are gone.
  • 5.x applies interceptors.Client, .Pool and .Agent. 7.x ignores them, as undici 7 does.
• Connector. buildConnector dials over net/tls, honors connect.lookup for TCP, and applies the connect timeout.
• request(). Returns { statusCode, statusText (7.x), headers, trailers, opaque, context, body }. Abort behaves per version: 5.x rejects with RequestAbortedError, 7.x with signal.reason. 5.x supports throwOnError; 7.x rejects it as undici 7 does.
• Body. The response body follows Readable's contract for the members it declares: on/once/pause/resume/destroy, plus text/json/arrayBuffer/bytes/blob/dump. It is built on EventEmitter because scriptc does not compile node:stream subclasses under @types/node.
• Errors. The errors module has undici's classes, names, messages and UND_ERR_* codes, with each version's export set.
• Global dispatcher. setGlobalDispatcher/getGlobalDispatcher are provided.
• fetch. Without a dispatcher it is the native fetch. Through a dispatcher it follows undici's fetch: default headers, redirect follow/manual/error, bad-port blocking, fetch failed errors with a cause, gzip/deflate decoding, and abort. Headers re-exports the native class.
• diagnostics_channel. The shim publishes undici:request:* and undici:client:* with a stable boxed request per request, so WeakMap correlation works.

The rest of undici isn't declared, so using it is a compile-time type error. Known differences are listed in the docs:

• The body can't be piped or used with for await.
• Diagnostics messages omit the socket and connector.
• fetch through a dispatcher returns an empty url and redirected: false, offers only gzip, deflate, and sends only string and byte bodies.
• Pipelining above 1, CONNECT, stream bodies and socketPath are not supported.

Small compiler fixes found on the way

• String(x) and template literals over string | URL unions now compile. The URL arm converts through href.
• A statement-level require() of a missing package now throws with code: "MODULE_NOT_FOUND", as the expression form already did.
• @types/node 20's class-declared NodeJS.Timeout/Immediate now map to the timer handle, as the interface form in @types/node 22+ already did.

Evidence

• Differential npm cases, with a real vendored undici as the Node oracle and the shim as the native side, against a local node:http server: tests/fixtures/npm/cases/undici5 (5.12.0) and undici7 (7.30.0). Byte-identical stdout and exit, plain and sanitized, and stable over repeated runs. They cover:
  • request() with text, json, arrayBuffer, multi-value headers, chunked bodies and the default PUT method.
  • A transport-style Agent subclass with a per-origin Pool factory, a wrapped buildConnector, a client interceptor and pool stats.
  • Keep-alive reuse (connections opened), a Pool connection limit with queued and size stats, Client, and connect.lookup.
  • A subclass overriding dispatch.
  • The diagnostics-channel lifecycle.
  • Errors: connection refused, headers timeout, abort, throwOnError (5.x) and its 7.x refusal, protocol, and a destroyed body.
  • 7.x only: a controller-API handler, and fetch through an agent (POST, manual and followed redirects, refused, abort) and without one.
• unloaded-optional-dependency: a node-fetch-style optional encoding require. tests/harness/package-shims.test.ts compiles it with encoding installed and asserts the output Node prints when it is absent. The same test covers an undici that isn't installed and an unsupported major version.
• packages/compiler/test/undici-shim-types.test.ts:
  • A program written against undici's API type-checks with no diagnostics both against the real 5.12/7.30 declarations and against the shim, under @types/node.
  • Shape checks: shim exports, error classes and option keys are a subset of the real declarations, and response, stats and message records are assignable. The tolerated extras are listed with reasons.
• Corpus 6250-string-of-string-or-url. Corpus 2195-require-missing-package now also prints the error code.
• Zero-cost gate on the final candidate (bench, self, all corpus, two shards): 3188 programs identical, plus one intended difference. The one intended difference is 2195-require-missing-package, from the MODULE_NOT_FOUND code fix (+144 B). Self-compile time +0.4%, within tolerance.
• @types/node 20 timers: tests/harness/node-types-timers.test.ts.
• Other gates. pnpm lint, pnpm format:check, pnpm test:ts7 --baselines-only (4 new order baselines recorded, none changed), the docs gate, the self-host IR build (exit 0, no diagnostics), and the npm, npm-static and frontend unit suites. node24-url-authority fails identically on main in the sandbox.
• Real tree (internal). With Compile esbuild's bundled CommonJS chunks and CommonJS cycles statically #1411, Compile class hierarchies across the CommonJS modules of npm packages #1412 and Serve Temporal's absence, v8, stream/web, dns/promises, EvalError and graceful-fs #1318 merged in, undici no longer compiles from its JavaScript: the shim modules join instead, and the transport-style code compiles against them. The one remaining shim site is fetch through a dispatcher: Headers.forEach has no lowering under @types/node.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
scriptc	Ready	Preview, v0	Oct 20, 2026 5:32pm UTC

[vercel-security-reviewer]

Security review details

[vercel]

Additional findings

1. packages/compiler/shims/undici/core/client.ts:852-857 — When a response stays paused longer than bodyTimeout, resuming it leaves the timeout disabled, so a stalled server can hold the request and connection indefinitely.

   

2. packages/compiler/shims/undici/core/request.ts:135-143 — Diagnostics subscribers calling the declared request.addHeader() method receive a TypeError because the published request view omits that method, breaking tracing-header injection.

   

3. packages/compiler/shims/undici/core/request.ts:230-234 — A Host header containing CRLF bypasses value validation and is written verbatim to the socket, allowing header or request injection in programs using undici 7.x.