Implement VirtualResolution for resolver-provided modules

[robhogan]

This implements VirtualResolution: a resolver may return {type: 'virtualModule', virtualPath: ?string, source: string | Buffer}, and Metro bundles the source as a module.

Design

What is a virtual module?

A virtual module is a source module like any other - it's a node in the module graph, it may have dependencies, it may have multiple dependants. The difference is it does not exist on disk, so its content and path must come from somewhere else.

In this design, a virtual module's source and virtual path is decided by Metro's resolver - so that takes the resolution specifier, origin module path, and the ResolutionContext APIs as usual and produces the source and (optionally) a virtual module path as outputs.

Visibility in the file map

Virtual modules are not represented in Metro's file map, and therefore not visible through the ResolutionContext APIs like doesFileExist. That's deliberate, and consistent with other bundlers (which follows from their use of real IO for resolution).

An observable consequence of that is that importing a virtual module by its virtual path as if it were a real module will fail, and require.context() won't include it. IMO, that's expected.

If they were represented, one resolution could perform a synchronous doesFileExist on a virtual path, and the result would be sensitive to whether another resolution that creates it has already run. Since traversal order is not deterministic that would make builds non-deterministic.

Nullability of VirtualResolution.virtualPath

This is nullable so that in future a module with no origin/base can be declared - this would be needed for a spec-compliant implementation of a data: URL. It's rejected with an invariant for now because if not nullability would transfer to ResolutionContext.originModulePath, which would be a breaking change. We don't need data: yet anyway, so we can leave that.

Use cases

Worklets

Bundle mode needs each worklet to be a module. Today the Babel plugin writes react-native-worklets/.worklets/<hash>.js from inside the visitor, a resolveRequest maps it back, and a patch makes getOrComputeSha1 return a random SHA-1 for the directory because the file map never saw the file.

No worklet is ever a transform cache hit, and a cache hit on the parent serves a stale generated module. In addition, a race exists where files created at transform time often aren't registered in the file map by the time the resolver looks at the dependencies of the origin module, so multiple refreshes are recommended to get a successful build.

With virtual modules (as the worklets team have requested before - eg #1605), the worklets plugin emits a specifier carrying the module's source (metro:inline;base64,…, next in #2037) and the resolver answers with a virtual module anchored at the importing file. Imports inside the worklet resolve as the importer's would, and the cache behaves as it should.

Verified e2e at https://github.com/robhogan/metro-x-worklets and validated with @tjzel.

Expo virtual modules

Expo CLI already does something like this by patching Metro: an expoVirtualModules map on bundler._depGraph._fileSystem, getSha1 returning the \0-prefixed id, and a wrapped Bundler.transformFile that reads from the map. It serves \0polyfill:*, \0node:*, \0shim:* and \0weak:*.

https://github.com/expo/expo/blob/f7d9310f1252266773c020b3ec7b118e8dde402c/packages/%40expo/cli/src/start/server/metro/metroVirtualModules.ts#L82-L100

Each of those becomes a virtualModule return from resolveRequest, and invalidation comes for free: the environment-variables polyfill's hash changes when an EXPO_PUBLIC_* value does, where today its id is constant. The difference from worklets is identity - a shim wants one module per content, not one per importer, which a fixed originModulePath under the project root gives. A null origin (no base at all, as data: has) is in the type but rejected for now, since resolving such a module's imports needs a ResolutionContext without an origin, and that's a breaking change.

Nothing in Metro produces a virtual module yet. The integration test does so from a custom resolveRequest.

Changelog: [Feature] Resolver: custom resolvers may return {type: 'virtualModule', originModulePath, source} to provide a module's source directly