Support ESModule natively for config using internal API

[ghostflyby]

details

• uses JSC internal OBJC APIs to utilize native esmodule support in JSC.
• taking the place of require
• introducing a asynchronous evalFromUrl

Some tests just fails with nothing to do with my changes.

demo

2025-12-28.22.37.59.mov

future works

unfortunately, the ESModule only supports ones starting with /, ./ and ../ according to https://github.com/WebKit/WebKit/blob/8615f506db9162ea73173834af9e4b997d92dd93/Source/JavaScriptCore/API/JSAPIGlobalObject.mm#L94

To support custom schemes or modulemap like features for introducing npm, I'll have to use internal cpp based APIs instead of ObjC-based ones.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[Copilot]

Pull request overview

This PR introduces native ESModule support to Hammerspoon 2 by leveraging JavaScriptCore's internal APIs through the InternalESModuleForSwiftJavaScriptCore framework. The implementation adds both synchronous and asynchronous ESModule evaluation capabilities to replace or supplement the existing require mechanism.

Key Changes:

• Added MultiRootFSModuleLoader class implementing ESModuleLoaderDelegate to handle ESModule resolution and loading across multiple filesystem roots
• Introduced synchronous and asynchronous evalFromURL() methods to the JSEngine class for evaluating ESModules
• Integrated ESModule support into the JSEngine initialization with automatic module loader delegation

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

File	Description
JSEngine.swift	Added ESModule import, integrated MultiRootFSModuleLoader, and implemented both sync and async evalFromURL methods with promise handling
MultiRootFSModuleLoader.swift	New module loader implementing ESModuleLoaderDelegate with caching, multi-root resolution, and security checks for file system boundaries
JSEngineProtocol.swift	Updated protocol documentation to clarify async evalFromURL evaluates files as ES modules
MockJSEngine.swift	Extended mock implementation to support both synchronous and asynchronous evalFromURL overloads for testing

Note: Based on my review, I was unable to identify the specific lines changed in the diff context to provide inline comments. However, I've identified several areas that would benefit from attention:

1. Test Coverage: The new MultiRootFSModuleLoader class lacks dedicated unit tests, though the existing integration tests in the test suite may provide some coverage through the JSEngine tests.

2. Return Value Inconsistency: In the async evalFromURL method (JSEngine.swift, around line 138-140), the method returns the promise object itself rather than the resolved value after awaiting it, which may not align with the expected behavior.

3. Empty Delegate Method: The willEvaluateModule method in MultiRootFSModuleLoader (line 123-125) is implemented but empty, which may indicate incomplete functionality.

4. Documentation: While the protocol documentation was updated, additional inline documentation explaining the module resolution algorithm and security boundaries would improve maintainability.

5. Future Work: As noted in the PR description, the current implementation only supports module paths starting with /, ./, or ../, with plans to extend support for custom schemes using C++ APIs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cmsj]

Hmm, this is both interesting and a little terrifying. As someone who isn't deep in the JS world, what would be the benefits of doing this vs require()?

[ghostflyby]

The current require implementation is basically a eval with no module semantics, where problems like re-evaluation and scope pollution arise.

Pros

1. Native IDE support, better coding experience
2. Statically exporting/importing identifiers without unexpected scope pollution
3. Evaluate the same module exactly once even if imported multiple times, suitable for configurations as singleton
4. Top-level await
5. The familiar default choice for JavaScript developers
6. Potential to adopt more JavaScript ecosystems

Cons

1. Internal (although unchanged for long) API used, which is still harder to maintain
2. Implementing custom module resolution rules like node_modules is easier on a require like function based module system.
3. Bundling a JS Bundler might be a simple alternative

[cmsj]

Thanks for the reply. As someone not super familiar with the JS ecosystem, it's somewhat hard for me to evaluate this, but I'll describe where my thoughts are right now:

I'm concerned about taking on subtle, complex code at this stage of the project. I don't really know what the long-term options are going to be for using/installing third party JS code, and I'm not sure if it's a good idea to aim for something like Node compatibility or not.

I think I'd like us to focus on the core functionality and architecture first, so we can match HS1 and start migrating users over.

[ghostflyby]

Whatever early-stage decision on module would be technical debts once prevailing.
Even if this is not merged, is there a chance we get a CommonJS-compliant require from the very beginning stage, whose rule is relatively easy to implement in any JavaScript environment? A require evaluating directly in the global context cannot be identified by language servers.

Module syntax has nothing to do with nodejs, we could support a module system without concerning npm or node:packages.

[alkene5]

What if we just embed esbuild directly? 🤓👆

[cmsj]

@ghostflyby I keep coming back to this PR and re-reading it and struggling to decide what to do...

I'm working on a counter-proposal, a CommonJS module importer that doesn't need any JSC internals, so we can compare and contrast them.

The list of missing functionality for a proper release of HS2 is shrinking by the day, so we do need to figure out what our solution is for both importing third party JS libraries, but also for distributing and importing HS2 spoons.

I'd be very keen to have more discussions about this if you're still interested? As someone who hasn't lived and breathed the JS ecosystem, I would appreciate input from those who have!

[ghostflyby]

Facts in my opinion

1. ESModule is a must for most JavaScript users today.
2. Implementing a ESModule support without internals is impossible.
3. CommonJS with a bundler (bundled or manual) is a proper alternative solution.
4. CommonJS is easy to implement by using a wrapper function

Suggestions

1. Bundle a bundler to support direct eval of ESModule by converting the code silently.

[cmsj]

Here is the CommonJS option:

#145