@react-native-quickjs/quickjs 1.0.0-alpha.0

package/src/module/QuickJSModule.cpp

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include "QuickJSModule.h"
+
+#include <algorithm>
+#include <cstring>
+
+#include "QuickJSRuntime.h"
+
+namespace qjs {
+
+namespace {
+
+// Function-local rather than namespace-scope, so registration from another
+// translation unit's static initializer cannot run before the vector is
+// constructed. QJS_REGISTER_MODULE exists to be used from other translation
+// units, and initialization order across them is unspecified.
+std::vector<ModuleRegistration> &registry() {
+  static std::vector<ModuleRegistration> modules;
+  return modules;
+}
+
+}  // namespace
+
+void registerModule(const ModuleRegistration &module) {
+  if (module.install == nullptr || module.name == nullptr) {
+    return;
+  }
+
+  auto &modules = registry();
+  for (const auto &existing : modules) {
+    if (std::strcmp(existing.name, module.name) == 0) {
+      return;
+    }
+  }
+  modules.push_back(module);
+
+  // stable_sort so equal priorities keep registration order, which is what a
+  // module author leaving priority at its default would expect.
+  std::stable_sort(
+      modules.begin(), modules.end(),
+      [](const ModuleRegistration &a, const ModuleRegistration &b) {
+        return a.priority < b.priority;
+      });
+}
+
+const std::vector<ModuleRegistration> &registeredModules() {
+  return registry();
+}
+
+void installModules(jsi::Runtime &runtime) {
+  for (const auto &module : registry()) {
+    module.install(runtime);
+  }
+}
+
+JSContext *contextFromRuntime(jsi::Runtime &runtime) noexcept {
+  // dynamic_cast rather than a type tag: the reference may be any
+  // implementation, including a decorator around ours, and guessing wrong
+  // would corrupt memory rather than fail cleanly.
+  auto *quickjs = dynamic_cast<QuickJSRuntime *>(&runtime);
+  return quickjs != nullptr ? quickjs->context() : nullptr;
+}
+
+}  // namespace qjs

package/src/module/QuickJSModule.h

@@ -0,0 +1,108 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include <vector>
+
+struct JSContext;
+
+namespace qjs {
+
+namespace jsi = facebook::jsi;
+
+/**
+ * The QuickJS module ABI.
+ *
+ * A module is a standalone npm package containing C or C++ that installs
+ * globals into the runtime -- a native implementation of an API React Native
+ * would otherwise ship as a JavaScript shim. `TextEncoder` is the archetype:
+ * the shim walks a string one code unit at a time building an array, where the
+ * native version is a bounds-checked loop into a pre-sized buffer.
+ *
+ * Modules are ordinary consumers of JSI, so they stay portable and testable on
+ * the host -- until they need not to be, at which point see
+ * `contextFromRuntime()`.
+ */
+
+/// Installs a module's globals. Called once per runtime, before any
+/// application JavaScript runs.
+using ModuleInstaller = void (*)(jsi::Runtime &);
+
+struct ModuleRegistration {
+  /// Conventionally the npm package name. Used in diagnostics and to make
+  /// double registration detectable.
+  const char *name;
+
+  ModuleInstaller install;
+
+  /// Ascending install order, so a module depending on another's globals can
+  /// order itself after it. Ties keep registration order.
+  int priority;
+};
+
+/**
+ * Registers a module to be installed into every runtime created afterwards.
+ * Safe to call before any runtime exists.
+ *
+ * A duplicate name is ignored rather than fatal: static libraries get linked
+ * twice more often than anyone expects, and crashing an app over it would be a
+ * poor trade.
+ */
+void registerModule(const ModuleRegistration &module);
+
+inline void registerModule(
+    const char *name, ModuleInstaller install, int priority = 0) {
+  registerModule(ModuleRegistration{name, install, priority});
+}
+
+/// `makeQuickJSRuntime()` calls this. Call it yourself only for a runtime you
+/// built by other means.
+void installModules(jsi::Runtime &runtime);
+
+const std::vector<ModuleRegistration> &registeredModules();
+
+/**
+ * The `JSContext *` behind `runtime`, or nullptr if it is not one of ours.
+ *
+ * Use it where JSI cannot express something efficiently. The cost is
+ * portability, so check the return value rather than assuming it, and keep a
+ * plain-JSI path behind it. `QuickJSModuleNative.h` has the companion helpers;
+ * it is a separate header because it pulls in `quickjs.h`, which a portable
+ * module has no reason to see.
+ */
+JSContext *contextFromRuntime(jsi::Runtime &runtime) noexcept;
+
+/**
+ * Registers a module at static-initialization time.
+ *
+ * Convenient, but a static initializer in a static library is dropped by the
+ * linker unless something in its translation unit is referenced. The primary
+ * mechanism for a shipped module is therefore generated registration code,
+ * which cannot be stripped. Use this for shared libraries and tests.
+ */
+/* The indirection is so INSTALL_FN may be a qualified name such as
+   ns::install -- pasting that into an identifier would not compile. */
+#define QJS_REGISTER_MODULE_IMPL2(NAME, INSTALL_FN, UNIQUE)                \
+  namespace {                                                              \
+  struct QjsModuleAutoRegister_##UNIQUE {                                  \
+    QjsModuleAutoRegister_##UNIQUE() {                                     \
+      ::qjs::registerModule(NAME, INSTALL_FN);                             \
+    }                                                                      \
+  };                                                                       \
+  static QjsModuleAutoRegister_##UNIQUE qjs_module_auto_register_##UNIQUE; \
+  }
+
+#define QJS_REGISTER_MODULE_IMPL(NAME, INSTALL_FN, UNIQUE) \
+  QJS_REGISTER_MODULE_IMPL2(NAME, INSTALL_FN, UNIQUE)
+
+#define QJS_REGISTER_MODULE(NAME, INSTALL_FN) \
+  QJS_REGISTER_MODULE_IMPL(NAME, INSTALL_FN, __LINE__)
+
+}  // namespace qjs

package/src/module/QuickJSModuleNative.h

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <jsi/jsi.h>
+#include <quickjs.h>
+
+#include "QuickJSModule.h"
+#include "QuickJSRuntime.h"
+
+/**
+ * The engine escape hatch for QuickJS modules.
+ *
+ * Include this to work directly against the engine, which is the recommended
+ * way to write a module here. A module written against `QuickJSModule.h` alone
+ * is portable JSI and runs on any jsi::Runtime; that is the right choice only
+ * when the module must also run on Hermes.
+ *
+ * The decisive reason is constructors. A jsi::Function from
+ * createFromHostFunction is not a constructor, and `new` against it does not
+ * fail loudly: `thisVal` is the constructor function itself, so writes to
+ * `this` mutate the constructor, `instanceof` is false, and
+ * `class S extends Thing {}` gives undefined from `new S()`. JSI's
+ * HostFunctionType has no new.target and no way to build `this` from
+ * `.prototype`, so it cannot be fixed from above. `JS_NewCFunction2` with
+ * `JS_CFUNC_constructor` gives a real constructor.
+ *
+ * The rest is cost. Creating a Uint8Array in plain JSI means fetching the
+ * global constructor and calling it, per call, against one `JS_NewUint8Array`;
+ * `JS_NewStringLen` takes UTF-8 bytes directly; `JS_GetUint8Array` reads a
+ * typed array without copying. Atoms, classes and opaque pointers have no JSI
+ * spelling at all.
+ *
+ * A module that needs both writes the fast path behind a check:
+ *
+ *     JSContext *ctx = qjs::contextFromRuntime(rt);
+ *     if (ctx) { ... } else { ... }
+ *
+ * Ownership follows the rest of the runtime. `adopt*` takes the reference you
+ * pass; `borrow*` returns one you must not free, valid only as long as the
+ * original. A `JS_*` function returning a JSValue gives you a reference you
+ * own.
+ */
+
+namespace qjs {
+
+/// The concrete runtime, or nullptr if `runtime` is not ours.
+inline QuickJSRuntime *quickJSRuntime(jsi::Runtime &runtime) noexcept {
+  return dynamic_cast<QuickJSRuntime *>(&runtime);
+}
+
+/// Wraps a JSValue you own as a jsi::Value, transferring ownership. The usual
+/// return path for a host function that used the engine directly.
+inline jsi::Value adoptJSValue(jsi::Runtime &runtime, JSValue value) {
+  auto *rt = quickJSRuntime(runtime);
+  if (rt == nullptr) {
+    // Nothing owns this value now and it cannot be freed without a context, so
+    // this is a programming error rather than a runtime condition.
+    throw jsi::JSINativeException(
+        "adoptJSValue called on a runtime that is not QuickJS-backed");
+  }
+  return rt->createValue(value);
+}
+
+/// Borrows the JSValue behind a jsi::Value. Owned by `value`, valid only while
+/// it is, and must not be freed.
+inline JSValue borrowJSValue(jsi::Runtime &runtime, const jsi::Value &value) {
+  auto *rt = quickJSRuntime(runtime);
+  if (rt == nullptr) {
+    throw jsi::JSINativeException(
+        "borrowJSValue called on a runtime that is not QuickJS-backed");
+  }
+  return rt->toJSValue(value);
+}
+
+/// Converts a pending quickjs exception into a thrown jsi::JSError. Call it
+/// whenever an engine API returns the exception sentinel: a pending exception
+/// left alive past the host function's return corrupts the engine's error
+/// state and fails far from its cause.
+[[noreturn]] inline void throwPendingQuickJSError(jsi::Runtime &runtime) {
+  auto *rt = quickJSRuntime(runtime);
+  if (rt == nullptr) {
+    throw jsi::JSINativeException("QuickJS error on a non-QuickJS runtime");
+  }
+  rt->throwPendingError();
+}
+
+}  // namespace qjs

package/src/runtime/QuickJSInstance.cpp

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include "QuickJSInstance.h"
+
+#include "QuickJSRuntimeFactory.h"
+
+#if defined(RNQJS_ENABLE_CDP) && RNQJS_ENABLE_CDP
+#include "QuickJSInspector.h"
+#endif
+
+namespace facebook::react {
+
+std::unique_ptr<JSRuntime> QuickJSInstance::createJSRuntime(
+    std::shared_ptr<MessageQueueThread> /*msgQueueThread*/) noexcept {
+  // The message queue thread is unused: the debugger work that has to happen on
+  // the JS thread is routed through React Native's RuntimeExecutor instead.
+  auto runtime = qjs::makeQuickJSRuntime(config_);
+
+#if defined(RNQJS_ENABLE_CDP) && RNQJS_ENABLE_CDP
+  if (config_.enableDebugger) {
+    return std::make_unique<qjs::QuickJSInspectorRuntime>(std::move(runtime));
+  }
+#endif
+
+  // JSIRuntimeHolder's base class vends a FallbackRuntimeTargetDelegate, which
+  // is the honest answer for a runtime that was never instrumented: DevTools
+  // still gets the Runtime domain through generic JSI, and the Debugger domain
+  // reports that it cannot bind breakpoints.
+  return std::make_unique<JSIRuntimeHolder>(std::move(runtime));
+}
+
+}  // namespace facebook::react

package/src/runtime/QuickJSInstance.h

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <react/runtime/JSRuntimeFactory.h>
+
+#include <memory>
+#include <utility>
+
+#include "QuickJSRuntimeConfig.h"
+
+namespace facebook::react {
+
+class MessageQueueThread;
+
+/**
+ * The React Native engine entry point: hands a QuickJS-backed jsi::Runtime to
+ * ReactInstance. Shared by the Android and Apple layers, which do nothing but
+ * construct this and pass it through.
+ */
+class QuickJSInstance : public JSRuntimeFactory {
+ public:
+  /**
+   * Default construction turns the debugger on in debug builds.
+   *
+   * Decided here rather than in the two platform layers, which would otherwise
+   * each need the same decision and fail silently on getting it wrong: the app
+   * runs, DevTools attaches, and no breakpoint ever binds -- on that platform
+   * only.
+   *
+   * It cannot be deferred until a frontend connects. Statement traps are
+   * emitted at parse time, so a runtime that was not instrumented before the
+   * bundle ran cannot be made debuggable afterwards. "Is this app debuggable?"
+   * is therefore a build-time question, and the honest default is yes in debug
+   * and no in release -- matching where React Native enables its own inspector.
+   */
+  QuickJSInstance() {
+    config_.enableDebugger = debuggerEnabledByDefault();
+  }
+
+  explicit QuickJSInstance(qjs::QuickJSRuntimeConfig config)
+      : config_(std::move(config)) {}
+
+  ~QuickJSInstance() override = default;
+
+  /// Exposed so an embedder building a config by hand can ask for the same
+  /// answer rather than re-deriving it. DEBUG is what CocoaPods defines for
+  /// Debug configurations and NDEBUG what CMake defines for Release; neither
+  /// platform sets the other's macro, so both are checked.
+  static constexpr bool debuggerEnabledByDefault() {
+#if !defined(RNQJS_ENABLE_CDP) || !RNQJS_ENABLE_CDP
+    // No debugger compiled into this binary, so setting the flag would only buy
+    // parse-time instrumentation nothing can use.
+    return false;
+#elif (defined(DEBUG) && DEBUG) || !defined(NDEBUG)
+    return true;
+#else
+    return false;
+#endif
+  }
+
+  std::unique_ptr<JSRuntime> createJSRuntime(
+      std::shared_ptr<MessageQueueThread> msgQueueThread) noexcept override;
+
+ private:
+  qjs::QuickJSRuntimeConfig config_;
+};
+
+}  // namespace facebook::react