refactor: compile builtins as function bodies with a fixed binding parameter

Adopts Node's internals idiom: every builtin is compiled via
ScriptCompiler::CompileFunction with the single parameter `binding`, and
natives arrive as properties of one bag object that each file
destructures at the top (const { isRuntimeRunloop } = binding). The
visible IIFE wrappers are gone, top-level return is the way a builtin
hands a value back to C++, and the bytecode cache moves to
CreateCodeCacheForFunction.

The parameter name is fixed and hardcoded in BuiltinLoader, so there is
no per-builtin name to mistype in C++; on the JS side an ESLint gate
(no-undef with `binding` and the reachable native globals declared)
catches typos in the destructures, wired into lint-staged. Conventions
are documented in NativeScript/runtime/js/README.md.

Author: edusperoni

NativeScript/runtime/BuiltinLoader.cpp

@@ -15,10 +15,12 @@ namespace {
 std::mutex builtinCacheMutex;
 std::vector<uint8_t> builtinCache[static_cast<unsigned>(BuiltinId::kCount)];
 
-}  // namespace
+// Every builtin is compiled as a function body receiving this single, fixed
+// parameter (Node's internalBinding idiom): natives arrive as properties of
+// one bag object and each file destructures what it needs.
+constexpr const char* kBindingParamName = "binding";
 
-MaybeLocal<Value> BuiltinLoader::RunBuiltin(Local<Context> context,
-                                            BuiltinId id) {
+MaybeLocal<v8::Function> CompileBuiltin(Local<Context> context, BuiltinId id) {
   Isolate* isolate = v8::Isolate::GetCurrent();
   const BuiltinSource& builtin = GetBuiltinSource(id);
   const unsigned index = static_cast<unsigned>(id);
@@ -43,41 +45,60 @@ MaybeLocal<Value> BuiltinLoader::RunBuiltin(Local<Context> context,
   );
   Local<v8::String> sourceText = tns::ToV8String(
       isolate, builtin.source, static_cast<int>(builtin.length));
+  Local<v8::String> params[] = {tns::ToV8String(isolate, kBindingParamName)};
 
-  Local<Script> script;
+  Local<v8::Function> fn;
   if (!blob.empty()) {
     // The Source owns and deletes the CachedData object; BufferNotOwned keeps
     // the underlying bytes (our copy) out of its hands.
     auto* cachedData = new ScriptCompiler::CachedData(
         blob.data(), static_cast<int>(blob.size()),
         ScriptCompiler::CachedData::BufferNotOwned);
     ScriptCompiler::Source source(sourceText, origin, cachedData);
-    if (ScriptCompiler::Compile(context, &source,
-                                ScriptCompiler::kConsumeCodeCache)
-            .ToLocal(&script) &&
+    if (ScriptCompiler::CompileFunction(context, &source, 1, params, 0, nullptr,
+                                        ScriptCompiler::kConsumeCodeCache)
+            .ToLocal(&fn) &&
         !cachedData->rejected) {
-      return script->Run(context);
+      return fn;
     }
     // Rejected cache (e.g. produced under different flags): fall through and
     // recompile eagerly so the refreshed blob covers inner functions again.
   }
 
   ScriptCompiler::Source source(sourceText, origin);
-  if (!ScriptCompiler::Compile(context, &source, ScriptCompiler::kEagerCompile)
-           .ToLocal(&script)) {
-    return MaybeLocal<Value>();
+  if (!ScriptCompiler::CompileFunction(context, &source, 1, params, 0, nullptr,
+                                       ScriptCompiler::kEagerCompile)
+           .ToLocal(&fn)) {
+    return MaybeLocal<v8::Function>();
   }
 
   std::unique_ptr<ScriptCompiler::CachedData> produced(
-      ScriptCompiler::CreateCodeCache(script->GetUnboundScript()));
+      ScriptCompiler::CreateCodeCacheForFunction(fn));
   if (produced != nullptr && produced->data != nullptr &&
       produced->length > 0) {
     std::lock_guard<std::mutex> lock(builtinCacheMutex);
     builtinCache[index].assign(produced->data,
                                produced->data + produced->length);
   }
 
-  return script->Run(context);
+  return fn;
+}
+
+}  // namespace
+
+MaybeLocal<Value> BuiltinLoader::RunBuiltin(Local<Context> context,
+                                            BuiltinId id,
+                                            Local<Value> binding) {
+  Isolate* isolate = v8::Isolate::GetCurrent();
+
+  Local<v8::Function> fn;
+  if (!CompileBuiltin(context, id).ToLocal(&fn)) {
+    return MaybeLocal<Value>();
+  }
+
+  Local<Value> args[] = {binding.IsEmpty() ? v8::Undefined(isolate).As<Value>()
+                                           : binding};
+  return fn->Call(context, v8::Undefined(isolate), 1, args);
 }
 
 }  // namespace tns

NativeScript/runtime/BuiltinLoader.h

@@ -8,14 +8,17 @@ namespace tns {
 
 class BuiltinLoader {
  public:
-  // Compiles and runs the builtin script identified by id in the given context
-  // and returns its completion value. Scripts carry an "internal/<name>.js"
-  // origin so runtime frames are identifiable in stack traces. Compilation goes
-  // through a process-wide bytecode cache: the first run in the process
-  // compiles eagerly and populates the cache, later isolates (workers) consume
-  // it instead of re-parsing the source.
-  static v8::MaybeLocal<v8::Value> RunBuiltin(v8::Local<v8::Context> context,
-                                              BuiltinId id);
+  // Compiles the builtin identified by id as a function body with the single
+  // fixed parameter `binding` (Node's internalBinding idiom), calls it with
+  // the given bag of natives (or undefined when omitted), and returns its
+  // return value. Scripts carry an "internal/<name>.js" origin so runtime
+  // frames are identifiable in stack traces. Compilation goes through a
+  // process-wide bytecode cache: the first run in the process compiles
+  // eagerly and populates the cache, later isolates (workers) consume it
+  // instead of re-parsing the source.
+  static v8::MaybeLocal<v8::Value> RunBuiltin(
+      v8::Local<v8::Context> context, BuiltinId id,
+      v8::Local<v8::Value> binding = v8::Local<v8::Value>());
 };
 
 }  // namespace tns

NativeScript/runtime/ErrorEvents.cpp

@@ -23,40 +23,42 @@ static void NativeReportFatalCallback(const FunctionCallbackInfo<Value>& info) {
 }
 
 void ErrorEvents::Init(Local<Context> context) {
-  // WHATWG error-events layer, layered on top of the generic event primitives
-  // installed by Events::Init. Plain (module-free) script, strict inside the
-  // IIFE, ES5-ish so it never depends on other runtime extensions. The IIFE is
-  // invoked with two arguments — the internal EventTarget backing the global
-  // (so native dispatch survives app code overwriting globalThis.dispatchEvent)
-  // and the native nativeReportFatal(error, stack) function that runs the
-  // terminal tail — and returns three closures bound to that backing store.
-  // ErrorEvent/PromiseRejectionEvent subclass the Event captured off globalThis
-  // at init time, which runs before any user code.
+  // WHATWG error-events layer (internal/error-events.js), layered on top of
+  // the generic event primitives installed by Events::Init. The builtin
+  // receives — via its binding bag — the internal EventTarget backing the
+  // global (so native dispatch survives app code overwriting
+  // globalThis.dispatchEvent) and the native nativeReportFatal(error, stack)
+  // function that runs the terminal tail, and returns three closures bound to
+  // that backing store. ErrorEvent/PromiseRejectionEvent subclass the Event
+  // captured off globalThis at init time, which runs before any user code.
   Isolate* isolate = v8::Isolate::GetCurrent();
 
   auto cache = Caches::Get(isolate);
   tns::Assert(cache != nullptr && cache->GlobalEventTarget != nullptr, isolate);
   Local<Object> globalTarget = cache->GlobalEventTarget->Get(isolate);
 
-  Local<Value> result;
-  bool success = BuiltinLoader::RunBuiltin(context, BuiltinId::kErrorEvents)
-                     .ToLocal(&result);
-  tns::Assert(success && result->IsFunction(), isolate);
-
-  Local<v8::Function> iife = result.As<v8::Function>();
-
   Local<v8::Function> nativeReportFatal;
-  success = v8::Function::New(context, NativeReportFatalCallback)
-                .ToLocal(&nativeReportFatal);
+  bool success = v8::Function::New(context, NativeReportFatalCallback)
+                     .ToLocal(&nativeReportFatal);
   tns::Assert(success, isolate);
 
-  Local<Value> installArgs[] = {globalTarget, nativeReportFatal};
-  Local<Value> iifeResult;
-  success = iife->Call(context, context->Global(), 2, installArgs)
-                .ToLocal(&iifeResult);
-  tns::Assert(success && iifeResult->IsArray(), isolate);
+  Local<Object> binding = Object::New(isolate);
+  success =
+      binding
+          ->Set(context, tns::ToV8String(isolate, "globalTarget"), globalTarget)
+          .FromMaybe(false) &&
+      binding
+          ->Set(context, tns::ToV8String(isolate, "nativeReportFatal"),
+                nativeReportFatal)
+          .FromMaybe(false);
+  tns::Assert(success, isolate);
+
+  Local<Value> result;
+  success = BuiltinLoader::RunBuiltin(context, BuiltinId::kErrorEvents, binding)
+                .ToLocal(&result);
+  tns::Assert(success && result->IsArray(), isolate);
 
-  Local<v8::Array> closures = iifeResult.As<v8::Array>();
+  Local<v8::Array> closures = result.As<v8::Array>();
   Local<Value> errorFn, rejectionFn, handledFn;
   tns::Assert(
       closures->Get(context, 0).ToLocal(&errorFn) && errorFn->IsFunction(),

NativeScript/runtime/Events.cpp

@@ -9,10 +9,9 @@ using namespace v8;
 namespace tns {
 
 void Events::Init(Local<Context> context) {
-  // Generic WHATWG event primitives. Plain (module-free) script, strict inside
-  // the IIFE, ES5-ish so it never depends on other runtime extensions. The IIFE
-  // installs Event/EventTarget and the global EventTarget methods, then returns
-  // the internal EventTarget instance backing the global so native dispatch
+  // Generic WHATWG event primitives (internal/events.js). The builtin installs
+  // Event/EventTarget and the global EventTarget methods, then returns the
+  // internal EventTarget instance backing the global so native dispatch
   // survives app code overwriting globalThis.dispatchEvent. The error-events
   // layer (ErrorEvents::Init) runs immediately after and installs the native
   // listener-error reporter through _installListenerErrorReporter.
@@ -21,18 +20,11 @@ void Events::Init(Local<Context> context) {
   Local<Value> result;
   bool success =
       BuiltinLoader::RunBuiltin(context, BuiltinId::kEvents).ToLocal(&result);
-  tns::Assert(success && result->IsFunction(), isolate);
-
-  Local<v8::Function> iife = result.As<v8::Function>();
-
-  Local<Value> iifeResult;
-  success =
-      iife->Call(context, context->Global(), 0, nullptr).ToLocal(&iifeResult);
-  tns::Assert(success && iifeResult->IsObject(), isolate);
+  tns::Assert(success && result->IsObject(), isolate);
 
   auto cache = Caches::Get(isolate);
-  cache->GlobalEventTarget = std::make_unique<Persistent<v8::Object>>(
-      isolate, iifeResult.As<Object>());
+  cache->GlobalEventTarget =
+      std::make_unique<Persistent<v8::Object>>(isolate, result.As<Object>());
 }
 
 }  // namespace tns

NativeScript/runtime/PromiseProxy.cpp

@@ -24,22 +24,22 @@ static void IsRuntimeRunloopCallback(const FunctionCallbackInfo<Value>& args) {
 void PromiseProxy::Init(v8::Local<v8::Context> context) {
   Isolate* isolate = v8::Isolate::GetCurrent();
 
-  Local<Value> result;
-  bool success = BuiltinLoader::RunBuiltin(context, BuiltinId::kPromiseProxy)
-                     .ToLocal(&result);
-  tns::Assert(success && result->IsFunction(), isolate);
-
-  Local<v8::Function> installProxy = result.As<v8::Function>();
-
   Local<v8::Function> isRuntimeRunloop;
-  success = v8::Function::New(context, IsRuntimeRunloopCallback)
-                .ToLocal(&isRuntimeRunloop);
+  bool success = v8::Function::New(context, IsRuntimeRunloopCallback)
+                     .ToLocal(&isRuntimeRunloop);
   tns::Assert(success, isolate);
 
-  Local<Value> installArgs[] = {isRuntimeRunloop};
-  Local<Value> installResult;
-  success = installProxy->Call(context, context->Global(), 1, installArgs)
-                .ToLocal(&installResult);
+  Local<Object> binding = Object::New(isolate);
+  success = binding
+                ->Set(context, tns::ToV8String(isolate, "isRuntimeRunloop"),
+                      isRuntimeRunloop)
+                .FromMaybe(false);
+  tns::Assert(success, isolate);
+
+  Local<Value> result;
+  success =
+      BuiltinLoader::RunBuiltin(context, BuiltinId::kPromiseProxy, binding)
+          .ToLocal(&result);
   tns::Assert(success, isolate);
 }
 

NativeScript/runtime/js/README.md

@@ -0,0 +1,37 @@
+# Runtime builtins
+
+The `.js` files in this directory are the runtime's internal JavaScript. At
+build time the "Generate RuntimeBuiltins" Xcode phase runs `tools/js2c.mjs`,
+which embeds them into `NativeScript/runtime/generated/RuntimeBuiltins.cpp`;
+at runtime `BuiltinLoader::RunBuiltin` compiles and executes them with an
+`internal/<name>.js` script origin and a process-wide bytecode cache.
+
+## Contract (Node's internalBinding idiom)
+
+Every file is compiled as a **function body** via `v8::ScriptCompiler::CompileFunction`
+with one fixed parameter:
+
+```js
+const { someNative, anotherNative } = binding;
+```
+
+- `binding` is a plain object of natives built by the C++ call site; a file
+  that needs nothing from C++ simply doesn't mention it.
+- Because the file is a function body, **top-level `return` is legal** — a
+  builtin's return value is what `RunBuiltin` hands back to C++ (used to
+  return factory functions and init results).
+- Strict mode is per-file: start the file with `"use strict";` to opt in.
+- Destructure `binding` once, at the top of the file, so the file's native
+  dependencies are visible and greppable.
+
+## Rules
+
+- Run at isolate init, before any user code: capture any global you rely on
+  (e.g. `globalThis.Event`) eagerly so later monkey-patching can't break you.
+- No `import`/`export` — these are classic function bodies, not modules.
+- ESLint (`eslint.config.mjs` at the repo root, run by lint-staged) declares
+  `binding` and the reachable native globals; `no-undef` is the typo net.
+  If a builtin starts using a new native global, add it there.
+- File names are kebab-case; the name determines the `BuiltinId` enum value
+  (`promise-proxy.js` → `kPromiseProxy`) and the script origin. New files must
+  also be added to `tools/js2c-inputs.xcfilelist`.

NativeScript/runtime/js/class-extends.js

@@ -1,4 +1,3 @@
-(function() { 
     function __extends(d, b) { 
          for (var p in b) {
              if (b.hasOwnProperty(p)) {
@@ -10,4 +9,3 @@
 (__.prototype = b.prototype, new __());
     } 
     return __extends;
-})()