feat: expose TextEncoder/TextDecoder from ns:util and node:util

Matches the updated NativeScript/ios#448. The lazy tier's private exports
cache generalizes into BuiltinLoader::GetExports, one per-isolate cache
every entry point to a builtin shares — the ns:/node: module registry
(whose per-specifier exports map it replaces), the lazy globals, and any
binding factory. ns:util re-exports TextEncoder/TextDecoder as the very
class objects the globals hold, lazily end to end (SetLazyDataProperty on
the binding, getters in ns-util.js/node-util.js), and node:util forwards
them as Node does.

Author: edusperoni

docs/ns-builtin-modules.md

@@ -59,6 +59,7 @@ Rules:
 |---|---|
 | `inspect(value[, options])` | Formats any value for human consumption: depth-limited, output-capped, cycle-safe, never invokes getters (except a guarded `error.stack` read and custom `toString` overrides, which are honored). `options.depth` (number) overrides the default depth of 2. Other option keys are reserved. |
 | `format(fmt, ...args)` | Node-style printf formatting: `%s`, `%d`, `%i`, `%f`, `%j`, `%o`, `%O`, `%%`. Extra arguments are appended space-separated, objects rendered via `inspect`. When `fmt` is not a string or contains no substitutions, all arguments are formatted and joined with spaces. `console.*` routes its arguments through this, so `console.log("%d apples", 3)` works. |
+| `TextEncoder` / `TextDecoder` | The WHATWG encoding interfaces, **the very same class objects the globals of those names hold** (`require("ns:util").TextDecoder === globalThis.TextDecoder`). Reading either member is what materializes them, so requiring the module costs nothing extra. |
 
 ```js
 const { inspect, format } = require("ns:util");
@@ -78,6 +79,13 @@ format("%j", { ok: true }); // '{"ok":true}'
 format("100% sure", "extra"); // "100% sure extra"  (no placeholder consumed)
 ```
 
+```js
+const { TextEncoder, TextDecoder } = require("ns:util");
+
+TextDecoder === globalThis.TextDecoder; // true
+new TextDecoder().decode(new TextEncoder().encode("héllo")); // "héllo"
+```
+
 **Stability caveat (verbatim from Node's contract):** the output of `inspect`
 (and therefore `format`'s object rendering) may change between runtime
 versions for readability; it is intended for humans and must not be parsed
@@ -400,7 +408,7 @@ unmodified where a shim exists:
 
 | module | exports | notes |
 |---|---|---|
-| `node:util` | `inspect`, `format` | Re-exports `ns:util`'s members unchanged (`nodeUtil.inspect === nsUtil.inspect`) from a **distinct, separately frozen module object**. Documented as partial. |
+| `node:util` | `inspect`, `format`, `TextEncoder`, `TextDecoder` | Re-exports `ns:util`'s members unchanged (`nodeUtil.inspect === nsUtil.inspect`) from a **distinct, separately frozen module object**. `TextEncoder`/`TextDecoder` are the globals of those names, as they are in Node. Documented as partial. |
 | `node:url` | `fileURLToPath`, `pathToFileURL` | Node-strict converters between `file:` URLs and paths. Documented as partial — no `URL`/`URLSearchParams` re-exports (both are globals), no legacy `url.parse`/`format`/`resolve`. |
 | `node:module` | `createRequire` | Re-exports `ns:module`'s `createRequire` unchanged from a **distinct, separately frozen module object**. `createPumpingRequire` is deliberately absent: it has no Node counterpart, so code written against this shim keeps running on Node. `require.resolve`/`.cache`/`.main` are not implemented, and neither is any other `node:module` member (`Module`, `builtinModules`, `isBuiltin`, `register`, `syncBuiltinESMExports`). Documented as partial. |
 

docs/text-encoding.md

@@ -21,6 +21,12 @@ The tier is the intended home for further web globals (`Blob`, `fetch`,
 `test-app/runtime/src/main/cpp/js/README.md` for the rules a lazy builtin
 lives by.
 
+The per-isolate exports cache behind the tier (`BuiltinLoader::GetExports`) is
+shared with the `ns:`/`node:` module registry: `require("ns:util").TextDecoder`
+and `require("node:util").TextDecoder` are the very class objects the globals
+hold, whichever entry point is reached first
+(see [ns-builtin-modules](ns-builtin-modules.md)).
+
 ## TextEncoder / TextDecoder
 
 Node's split: `js/text-encoding.js` owns the WebIDL surface (brand checks via

test-app/app/src/main/assets/app/tests/nsUtilEncodingOrderWorker.js

@@ -0,0 +1,28 @@
+// A worker is a fresh isolate, which is what makes the access order testable:
+// the parent realm has already materialized TextEncoder/TextDecoder by the
+// time any spec runs. Nothing here may touch either name before the handler,
+// or the requested order is lost.
+onmessage = function (msg) {
+    var order = msg.data;
+    var results = { order: order };
+
+    if (order === "global-first") {
+        var globalEncoder = globalThis.TextEncoder;
+        var globalDecoder = globalThis.TextDecoder;
+        var nsUtil = require("ns:util");
+        var nodeUtil = require("node:util");
+        results.encoder = nsUtil.TextEncoder === globalEncoder && nodeUtil.TextEncoder === globalEncoder;
+        results.decoder = nsUtil.TextDecoder === globalDecoder && nodeUtil.TextDecoder === globalDecoder;
+        results.roundTrip = new nsUtil.TextDecoder().decode(new nodeUtil.TextEncoder().encode("ok"));
+    } else {
+        var util = require("ns:util");
+        var node = require("node:util");
+        var utilEncoder = util.TextEncoder;
+        var utilDecoder = node.TextDecoder;
+        results.encoder = globalThis.TextEncoder === utilEncoder && node.TextEncoder === utilEncoder;
+        results.decoder = globalThis.TextDecoder === utilDecoder && util.TextDecoder === utilDecoder;
+        results.roundTrip = new node.TextDecoder().decode(new util.TextEncoder().encode("ok"));
+    }
+
+    postMessage(results);
+};

test-app/app/src/main/assets/app/tests/testNsUtil.js

@@ -12,6 +12,44 @@ describe("ns:util", function () {
         expect(require("ns:util")).toBe(util);
     });
 
+    it("exposes the encoding interfaces the globals expose", function () {
+        expect(typeof util.TextEncoder).toBe("function");
+        expect(typeof util.TextDecoder).toBe("function");
+        // One run of the text-encoding builtin backs both entry points, so the
+        // classes are identical objects no matter which is reached first.
+        expect(util.TextEncoder).toBe(globalThis.TextEncoder);
+        expect(util.TextDecoder).toBe(globalThis.TextDecoder);
+    });
+
+    it("round trips text through the module's encoding interfaces", function () {
+        var bytes = new util.TextEncoder().encode("héllo");
+        expect(bytes instanceof Uint8Array).toBe(true);
+        expect(bytes.length).toBe(6);
+        expect(new util.TextDecoder().decode(bytes)).toBe("héllo");
+    });
+
+    it("keeps the classes identical in a fresh isolate, whichever is touched first", function (done) {
+        var orders = ["global-first", "util-first"];
+        var replies = 0;
+        orders.forEach(function (order) {
+            var worker = new Worker("./nsUtilEncodingOrderWorker.js");
+            worker.onmessage = function (msg) {
+                expect(msg.data).toEqual({
+                    order: order,
+                    encoder: true,
+                    decoder: true,
+                    roundTrip: "ok",
+                });
+                worker.terminate();
+                replies++;
+                if (replies === orders.length) {
+                    done();
+                }
+            };
+            worker.postMessage(order);
+        });
+    });
+
     it("throws for an unknown builtin", function () {
         expect(function () {
             require("ns:definitely-not-a-module");
@@ -158,6 +196,15 @@ describe("node:util", function () {
         expect(Object.isFrozen(nodeUtil)).toBe(true);
         expect(nodeUtil.inspect).toBe(util.inspect);
         expect(nodeUtil.format).toBe(util.format);
+        expect(nodeUtil.TextEncoder).toBe(util.TextEncoder);
+        expect(nodeUtil.TextDecoder).toBe(util.TextDecoder);
+    });
+
+    it("exposes Node's encoding interfaces, identical to the globals", function () {
+        expect(Object.keys(nodeUtil).sort()).toEqual(["TextDecoder", "TextEncoder", "format", "inspect"]);
+        expect(nodeUtil.TextEncoder).toBe(globalThis.TextEncoder);
+        expect(nodeUtil.TextDecoder).toBe(globalThis.TextDecoder);
+        expect(new nodeUtil.TextDecoder("utf-8").decode(new nodeUtil.TextEncoder().encode("ok"))).toBe("ok");
     });
 
     it("is a singleton per realm", function () {

test-app/runtime/src/main/cpp/Base64.cpp

@@ -2,6 +2,7 @@
 
 #include <vector>
 
+#include "BuiltinLoader.h"
 #include "Util.h"
 
 using namespace v8;
@@ -167,14 +168,18 @@ void AtobCallback(const FunctionCallbackInfo<Value>& info) {
     }
 }
 
-}  // namespace
-
-Local<Object> Base64::CreateBinding(Local<Context> context) {
+MaybeLocal<Object> CreateBinding(Local<Context> context) {
     Isolate* isolate = v8::Isolate::GetCurrent();
     Local<Object> binding = Object::New(isolate);
     tns::SetMethodNoSideEffect(context, binding, "btoa", BtoaCallback);
     tns::SetMethodNoSideEffect(context, binding, "atob", AtobCallback);
     return binding;
 }
 
+}  // namespace
+
+MaybeLocal<Object> Base64::GetExports(Local<Context> context) {
+    return BuiltinLoader::GetExports(context, BuiltinId::kBase64, CreateBinding);
+}
+
 }  // namespace tns

test-app/runtime/src/main/cpp/Base64.h

@@ -12,7 +12,11 @@ namespace tns {
  */
 class Base64 {
 public:
-    static v8::Local<v8::Object> CreateBinding(v8::Local<v8::Context> context);
+    /*
+     * The builtin's exports, `{ atob, btoa }`, from the one run it gets per
+     * isolate.
+     */
+    static v8::MaybeLocal<v8::Object> GetExports(v8::Local<v8::Context> context);
 };
 
 }  // namespace tns

test-app/runtime/src/main/cpp/BuiltinLoader.cpp

@@ -38,6 +38,15 @@ constexpr const char* kPrimordialsParamName = "primordials";
 constexpr const char* kInternalsParamName = "internals";
 constexpr size_t kParamCount = 6;
 
+/*
+ * `module.exports` of every builtin that has run in this isolate, indexed by
+ * id. Per isolate because a builtin is a singleton per realm, so workers run
+ * their own copy of a file and export their own objects.
+ */
+struct BuiltinExportsState {
+    v8::Global<Object> exports[static_cast<unsigned>(BuiltinId::kCount)];
+};
+
 /*
  * This runtime's intrinsics snapshot, builtin require and shared internals
  * object. Per-runtime state rather than an isolate-keyed shared map, so
@@ -258,4 +267,32 @@ MaybeLocal<Value> BuiltinLoader::RunBuiltin(Local<Context> context, BuiltinId id
     return CallBuiltin(context, id, binding, primordials, internals);
 }
 
+MaybeLocal<Object> BuiltinLoader::GetExports(Local<Context> context, BuiltinId id,
+                                             BindingFactory bindingFactory) {
+    Isolate* isolate = v8::Isolate::GetCurrent();
+    auto* state = RuntimeState::For<BuiltinExportsState>(isolate);
+    if (state == nullptr) {
+        return MaybeLocal<Object>();
+    }
+
+    const unsigned index = static_cast<unsigned>(id);
+    if (!state->exports[index].IsEmpty()) {
+        return state->exports[index].Get(isolate);
+    }
+
+    Local<Object> binding;
+    if (bindingFactory != nullptr && !bindingFactory(context).ToLocal(&binding)) {
+        return MaybeLocal<Object>();
+    }
+
+    Local<Value> result;
+    if (!RunBuiltin(context, id, binding).ToLocal(&result) || !result->IsObject()) {
+        return MaybeLocal<Object>();
+    }
+
+    Local<Object> exports = result.As<Object>();
+    state->exports[index].Reset(isolate, exports);
+    return exports;
+}
+
 }  // namespace tns

test-app/runtime/src/main/cpp/BuiltinLoader.h

@@ -8,6 +8,13 @@ namespace tns {
 
 class BuiltinLoader {
 public:
+    /*
+     * Builds the bag of natives a builtin receives as its `binding` parameter.
+     * GetExports calls it only when the builtin actually runs, so a call site
+     * that hits the cache pays nothing for it.
+     */
+    using BindingFactory = v8::MaybeLocal<v8::Object> (*)(v8::Local<v8::Context>);
+
     /*
      * Compiles the builtin identified by id as a function body with the fixed
      * parameters `exports`, `require`, `module`, `binding` (Node's module
@@ -32,6 +39,18 @@ class BuiltinLoader {
     static v8::MaybeLocal<v8::Value> RunBuiltin(
             v8::Local<v8::Context> context, BuiltinId id,
             v8::Local<v8::Value> binding = v8::Local<v8::Value>());
+
+    /*
+     * The builtin's `module.exports`, running it at most once per isolate.
+     * Every entry point that reaches the same file — the `ns:`/`node:` module
+     * registry, the lazy-global tier, another builtin's `require` — shares
+     * that one run, so a value a file exports is the same object through all
+     * of them. Empty when the builtin failed to run (an exception is pending)
+     * or exported a non-object.
+     */
+    static v8::MaybeLocal<v8::Object> GetExports(v8::Local<v8::Context> context,
+                                                 BuiltinId id,
+                                                 BindingFactory binding);
 };
 
 }  // namespace tns

test-app/runtime/src/main/cpp/LazyGlobals.cpp

@@ -2,8 +2,6 @@
 
 #include "ArgConverter.h"
 #include "Base64.h"
-#include "BuiltinLoader.h"
-#include "RuntimeState.h"
 #include "TextEncoding.h"
 
 using namespace v8;
@@ -12,60 +10,26 @@ namespace tns {
 
 namespace {
 
-using BindingFactory = Local<Object> (*)(Local<Context>);
+/*
+ * The builtin's `module.exports`, from the single run it gets per isolate
+ * (BuiltinLoader::GetExports). Two globals out of the same file therefore
+ * cost one run, and so does a module that exports the same interfaces.
+ */
+using ExportsAccessor = MaybeLocal<Object> (*)(Local<Context>);
 
 struct LazyGlobalEntry {
     const char* name;
-    BuiltinId builtin;
     const char* exportName;  // key of `name` in the builtin's module.exports
-    BindingFactory binding;  // natives the builtin needs, null if it needs none
+    ExportsAccessor exports;
 };
 
 constexpr LazyGlobalEntry kLazyGlobals[] = {
-        {"TextEncoder", BuiltinId::kTextEncoding, "TextEncoder",
-         TextEncoding::CreateBinding},
-        {"TextDecoder", BuiltinId::kTextEncoding, "TextDecoder",
-         TextEncoding::CreateBinding},
-        {"atob", BuiltinId::kBase64, "atob", Base64::CreateBinding},
-        {"btoa", BuiltinId::kBase64, "btoa", Base64::CreateBinding},
+        {"TextEncoder", "TextEncoder", TextEncoding::GetExports},
+        {"TextDecoder", "TextDecoder", TextEncoding::GetExports},
+        {"atob", "atob", Base64::GetExports},
+        {"btoa", "btoa", Base64::GetExports},
 };
 
-// One entry per builtin this tier can run, so two globals from the same file
-// cost one run.
-struct LazyGlobalsState {
-    v8::Global<Object> exports[static_cast<unsigned>(BuiltinId::kCount)];
-};
-
-MaybeLocal<Object> GetExports(Local<Context> context,
-                              const LazyGlobalEntry& entry) {
-    Isolate* isolate = v8::Isolate::GetCurrent();
-    auto* state = RuntimeState::For<LazyGlobalsState>(isolate);
-    if (state == nullptr) {
-        return MaybeLocal<Object>();
-    }
-
-    const unsigned index = static_cast<unsigned>(entry.builtin);
-    if (!state->exports[index].IsEmpty()) {
-        return state->exports[index].Get(isolate);
-    }
-
-    Local<Value> binding;
-    if (entry.binding != nullptr) {
-        binding = entry.binding(context);
-    }
-
-    Local<Value> result;
-    if (!BuiltinLoader::RunBuiltin(context, entry.builtin, binding)
-                 .ToLocal(&result) ||
-        !result->IsObject()) {
-        return MaybeLocal<Object>();
-    }
-
-    Local<Object> exports = result.As<Object>();
-    state->exports[index].Reset(isolate, exports);
-    return exports;
-}
-
 void LazyGlobalGetter(Local<v8::Name> property,
                       const PropertyCallbackInfo<Value>& info) {
     Isolate* isolate = info.GetIsolate();
@@ -74,7 +38,7 @@ void LazyGlobalGetter(Local<v8::Name> property,
     Local<Context> context = isolate->GetCurrentContext();
 
     Local<Object> exports;
-    if (!GetExports(context, *entry).ToLocal(&exports)) {
+    if (!entry->exports(context).ToLocal(&exports)) {
         return;
     }
     Local<Value> value;

test-app/runtime/src/main/cpp/LazyGlobals.h

@@ -9,9 +9,10 @@ namespace tns {
  * Globals whose implementation is a runtime builtin that must not run until
  * someone actually reaches for the name. Each entry is registered on the
  * global template as a lazy data property; the first read runs the builtin
- * once per isolate and caches its exports, so sibling names (TextEncoder and
- * TextDecoder) share the run, and V8 then replaces the property with a plain
- * data property so later reads cost nothing.
+ * through the per-isolate exports cache (BuiltinLoader::GetExports), so
+ * sibling names (TextEncoder and TextDecoder) share the run — as does a
+ * module exporting the same interfaces — and V8 then replaces the property
+ * with a plain data property so later reads cost nothing.
  *
  * A builtin behind this tier runs at an arbitrary point in the isolate's life
  * rather than during init, so it may only consume `internals` keys published