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

package/modules/hermes-compat/include/hermes/Public/CtorConfig.h

@@ -0,0 +1,88 @@
+/*
+ * 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.
+ */
+
+/*
+ * Generates a config class and its Builder from a field list, the way Hermes
+ * does. Same shape as upstream -- getX, getDefaultX, rebuild, Builder::withX,
+ * hasX, update, build -- so code written against Hermes compiles unchanged.
+ */
+
+#pragma once
+
+#include <utility>
+
+#define _HERMES_CTORCONFIG_FIELD(CX, TYPE, NAME, ...) TYPE NAME##_{__VA_ARGS__};
+#define _HERMES_CTORCONFIG_EXPLICIT(CX, TYPE, NAME, ...) \
+  bool NAME##Explicit_{false};
+
+#define _HERMES_CTORCONFIG_GETTER(CX, TYPE, NAME, ...) \
+  inline TYPE get##NAME() const {                      \
+    return NAME##_;                                    \
+  }                                                    \
+  static CX TYPE getDefault##NAME() {                  \
+    using TypeAsSingleToken = TYPE;                    \
+    return TypeAsSingleToken{__VA_ARGS__};             \
+  }
+
+#define _HERMES_CTORCONFIG_SETTER(CX, TYPE, NAME, ...) \
+  inline auto with##NAME(TYPE NAME)->decltype(*this) { \
+    config_.NAME##_ = std::move(NAME);                 \
+    NAME##Explicit_ = true;                            \
+    return *this;                                      \
+  }                                                    \
+  bool has##NAME() const {                             \
+    return NAME##Explicit_;                            \
+  }
+
+#define _HERMES_CTORCONFIG_UPDATE(CX, TYPE, NAME, ...) \
+  if (newConfig.has##NAME()) with##NAME(newConfig.config_.get##NAME());
+
+#define _HERMES_CTORCONFIG_STRUCT(NAME, FIELDS, BUILD_BODY)                    \
+  class NAME {                                                                 \
+    FIELDS(_HERMES_CTORCONFIG_FIELD)                                           \
+                                                                               \
+   public:                                                                     \
+    class Builder;                                                             \
+    friend Builder;                                                            \
+    FIELDS(_HERMES_CTORCONFIG_GETTER)                                          \
+    inline Builder rebuild() const;                                            \
+                                                                               \
+   private:                                                                    \
+    inline void doBuild(const Builder &builder);                               \
+  };                                                                           \
+                                                                               \
+  class NAME::Builder {                                                        \
+    NAME config_;                                                              \
+    FIELDS(_HERMES_CTORCONFIG_EXPLICIT)                                        \
+                                                                               \
+   public:                                                                     \
+    Builder() = default;                                                       \
+    explicit Builder(const NAME &config) : config_(config) {}                  \
+    inline const NAME build() {                                                \
+      config_.doBuild(*this);                                                  \
+      return config_;                                                          \
+    }                                                                          \
+    inline Builder update(const NAME::Builder &newConfig);                     \
+    FIELDS(_HERMES_CTORCONFIG_SETTER)                                          \
+  };                                                                           \
+                                                                               \
+  inline NAME::Builder NAME::rebuild() const {                                 \
+    return Builder(*this);                                                     \
+  }                                                                            \
+                                                                               \
+  inline NAME::Builder NAME::Builder::update(const NAME::Builder &newConfig) { \
+    FIELDS(_HERMES_CTORCONFIG_UPDATE)                                          \
+    return *this;                                                              \
+  }                                                                            \
+                                                                               \
+  inline void NAME::doBuild(const NAME::Builder &builder) {                    \
+    (void)builder;                                                             \
+    BUILD_BODY                                                                 \
+  }
+
+/// Marks a field whose default is not constexpr, as upstream does.
+#define HERMES_NON_CONSTEXPR

package/modules/hermes-compat/include/hermes/Public/GCConfig.h

@@ -0,0 +1,83 @@
+/*
+ * 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 <hermes/Public/CtorConfig.h>
+
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <limits>
+#include <string>
+
+namespace hermes::vm {
+
+using gcheapsize_t = uint32_t;
+
+enum ReleaseUnused {
+  kReleaseUnusedNone = 0,
+  kReleaseUnusedOld,
+  kReleaseUnusedYoungOnFull,
+  kReleaseUnusedYoungAlways
+};
+
+enum class GCEventKind {
+  CollectionStart,
+  CollectionEnd,
+};
+
+/// Hermes fills this in for its analytics callback. QuickJS never emits one,
+/// so the fields exist to be named, not to be populated.
+struct GCAnalyticsEvent {
+  std::string runtimeDescription;
+  std::string gcKind;
+  std::string collectionType;
+  std::string cause;
+  std::chrono::milliseconds duration{0};
+  std::chrono::milliseconds cpuDuration{0};
+  uint64_t allocated{0};
+  uint64_t size{0};
+  uint64_t external{0};
+  uint64_t survivalRatio{0};
+};
+
+#define GC_TRIPWIRE_FIELDS(F) \
+  F(constexpr, gcheapsize_t, Limit, std::numeric_limits<gcheapsize_t>::max())
+
+_HERMES_CTORCONFIG_STRUCT(GCTripwireConfig, GC_TRIPWIRE_FIELDS, {});
+
+#define GC_HANDLESAN_FIELDS(F)            \
+  F(constexpr, double, SanitizeRate, 0.0) \
+  F(constexpr, int64_t, RandomSeed, -1)
+
+_HERMES_CTORCONFIG_STRUCT(GCSanitizeConfig, GC_HANDLESAN_FIELDS, {});
+
+#define GC_FIELDS(F)                                                      \
+  F(constexpr, gcheapsize_t, MinHeapSize, 0)                              \
+  F(constexpr, gcheapsize_t, InitHeapSize, 32 << 20)                      \
+  F(constexpr, gcheapsize_t, MaxHeapSize, 3u << 30)                       \
+  F(constexpr, double, OccupancyTarget, 0.5)                              \
+  F(constexpr, unsigned, EffectiveOOMThreshold,                           \
+    std::numeric_limits<unsigned>::max())                                 \
+  F(constexpr, GCSanitizeConfig, SanitizeConfig)                          \
+  F(constexpr, bool, ShouldRandomizeAllocSpace, false)                    \
+  F(constexpr, bool, ShouldRecordStats, false)                            \
+  F(constexpr, ReleaseUnused, ShouldReleaseUnused, kReleaseUnusedOld)     \
+  F(HERMES_NON_CONSTEXPR, std::string, Name, "")                          \
+  F(HERMES_NON_CONSTEXPR, GCTripwireConfig, TripwireConfig)               \
+  F(constexpr, bool, AllocInYoung, true)                                  \
+  F(constexpr, bool, RevertToYGAtTTI, false)                              \
+  F(constexpr, bool, ProtectMetadata, false)                              \
+  F(HERMES_NON_CONSTEXPR, std::function<void(const GCAnalyticsEvent &)>,  \
+    AnalyticsCallback, nullptr)                                           \
+  F(HERMES_NON_CONSTEXPR, std::function<void(GCEventKind, const char *)>, \
+    Callback, nullptr)
+
+_HERMES_CTORCONFIG_STRUCT(GCConfig, GC_FIELDS, {});
+
+}  // namespace hermes::vm

package/modules/hermes-compat/include/hermes/Public/HermesExport.h

@@ -0,0 +1,17 @@
+/*
+ * 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
+
+// The shim is always compiled into the app, so there is no import case.
+#ifndef HERMES_EXPORT
+#if defined(_MSC_VER)
+#define HERMES_EXPORT
+#else
+#define HERMES_EXPORT __attribute__((visibility("default")))
+#endif
+#endif

package/modules/hermes-compat/include/hermes/Public/RuntimeConfig.h

@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+
+/*
+ * The full field set, with Hermes's own defaults, so that code configuring the
+ * VM compiles unchanged.
+ *
+ * Almost none of it has a QuickJS equivalent. Rather than drop settings
+ * silently, makeHermesRuntime() compares the config it is handed against these
+ * defaults and reports every field it cannot honour -- loudly for the ones
+ * that change what JavaScript is allowed to do, such as EnableEval, and once
+ * for tuning fields nothing observable depends on.
+ */
+
+#pragma once
+
+#include <hermes/Public/CrashManager.h>
+#include <hermes/Public/CtorConfig.h>
+#include <hermes/Public/GCConfig.h>
+
+#include <cstdint>
+#include <string>
+
+namespace hermes::vm {
+
+enum CompilationMode {
+  SmartCompilation,
+  ForceEagerCompilation,
+  ForceLazyCompilation
+};
+
+class PinnedHermesValue;
+
+#define RUNTIME_FIELDS(F)                                    \
+  F(HERMES_NON_CONSTEXPR, vm::GCConfig, GCConfig)            \
+  F(constexpr, PinnedHermesValue *, RegisterStack, nullptr)  \
+  F(constexpr, unsigned, MaxNumRegisters, 1024 * 1024)       \
+  F(constexpr, bool, EnableJIT, false)                       \
+  F(constexpr, bool, EnableEval, true)                       \
+  F(constexpr, bool, VerifyEvalIR, false)                    \
+  F(constexpr, bool, OptimizedEval, false)                   \
+  F(constexpr, bool, AsyncBreakCheckInEval, false)           \
+  F(constexpr, bool, ES6Promise, true)                       \
+  F(constexpr, bool, ES6Proxy, true)                         \
+  F(constexpr, bool, Intl, true)                             \
+  F(constexpr, bool, TraceEnabled, false)                    \
+  F(HERMES_NON_CONSTEXPR, std::string, TraceScratchPath, "") \
+  F(HERMES_NON_CONSTEXPR, std::string, TraceResultPath, "")  \
+  F(constexpr, bool, EnableSampledStats, false)              \
+  F(constexpr, bool, EnableSampleProfiling, true)            \
+  F(constexpr, bool, RandomizeMemoryLayout, false)           \
+  F(constexpr, unsigned, BytecodeWarmupPercent, 0)           \
+  F(constexpr, bool, TrackIO, false)                         \
+  F(constexpr, bool, EnableHermesInternal, true)             \
+  F(constexpr, bool, EnableHermesInternalTestMethods, false) \
+  F(constexpr, bool, EnableGenerator, true)                  \
+  F(constexpr, bool, MicrotaskQueue, false)                  \
+  F(constexpr, uint32_t, VMExperimentFlags, 0)
+
+_HERMES_CTORCONFIG_STRUCT(RuntimeConfig, RUNTIME_FIELDS, {});
+
+}  // namespace hermes::vm

package/modules/hermes-compat/include/hermes/Public/SamplingProfiler.h

@@ -0,0 +1,22 @@
+/*
+ * 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 <hermes/Public/HermesExport.h>
+
+namespace facebook::hermes::sampling_profiler {
+
+// Named so that IHermes::dumpSampledTraceToProfile has a complete return type.
+// QuickJS has no sampling profiler, so a caller that reads a Profile does not
+// compile -- which is the right answer, and happens at build time.
+class HERMES_EXPORT Profile {
+ public:
+  Profile() = default;
+};
+
+}  // namespace facebook::hermes::sampling_profiler

package/modules/hermes-compat/include/hermes/hermes.h

@@ -0,0 +1,195 @@
+/*
+ * 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.
+ */
+
+/*
+ * A source-compatible <hermes/hermes.h> whose makeHermesRuntime() returns a
+ * QuickJS-backed runtime, so libraries that create their own Hermes runtime --
+ * react-native-worklets, and so react-native-reanimated -- build and run
+ * unmodified. Those libraries select an engine with __has_include(<hermes/
+ * hermes.h>) and have no third-engine branch, so without this they cannot be
+ * used at all.
+ *
+ * This is source compatibility, never ABI compatibility. These headers must
+ * not be on the include path while a real libhermes is on the link line.
+ *
+ * Rule when editing: no member declaration below may be conditional on a
+ * preprocessor macro. Free functions may be; virtual functions and data
+ * members may not. A conditional virtual shifts every vtable slot after it,
+ * and consumers are compiled separately from this shim with flags it does not
+ * control -- the failure is a silent call to the wrong function.
+ */
+
+#pragma once
+
+#include <hermes/DebuggerAPI.h>
+#include <hermes/Public/HermesExport.h>
+#include <hermes/Public/RuntimeConfig.h>
+#include <hermes/Public/SamplingProfiler.h>
+#include <jsi/jsi.h>
+
+#include <memory>
+#include <ostream>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+struct SHUnit;
+struct SHRuntime;
+
+namespace hermes::vm {
+class GCExecTrace {
+ public:
+  GCExecTrace() = default;
+};
+class Runtime;
+}  // namespace hermes::vm
+
+namespace facebook {
+namespace jsi {
+class ThreadSafeRuntime;
+}
+
+namespace hermes {
+
+class HermesRuntime;
+
+/// Engine-global operations that need no runtime instance. The UUIDs match
+/// real Hermes so that castInterface in unmodified third-party code succeeds.
+class HERMES_EXPORT IHermesRootAPI : public jsi::ICast {
+ public:
+  static constexpr jsi::UUID uuid{
+      0xb654d898, 0xdfad, 0x11ef, 0x859a, 0x325096b39f47};
+
+  virtual std::unique_ptr<HermesRuntime> makeHermesRuntime(
+      const ::hermes::vm::RuntimeConfig &runtimeConfig) = 0;
+
+  /// Always false: nothing here produces Hermes bytecode. A caller handed a
+  /// real .hbc bundle takes its "this is source" path and fails in the parser,
+  /// so the shim sniffs the HBC magic and reports, naming the real cause.
+  virtual bool isHermesBytecode(const uint8_t *data, size_t len) = 0;
+  virtual uint32_t getBytecodeVersion() = 0;
+  virtual void prefetchHermesBytecode(const uint8_t *data, size_t len) = 0;
+  virtual bool hermesBytecodeSanityCheck(
+      const uint8_t *data, size_t len, std::string *errorMessage) = 0;
+  virtual void setFatalHandler(void (*handler)(const std::string &)) = 0;
+  virtual std::pair<const uint8_t *, size_t> getBytecodeEpilogue(
+      const uint8_t *data, size_t len) = 0;
+  virtual void enableSamplingProfiler(double meanHzFreq) = 0;
+  virtual void disableSamplingProfiler() = 0;
+  virtual void dumpSampledTraceToFile(const std::string &fileName) = 0;
+  virtual void dumpSampledTraceToStream(std::ostream &stream) = 0;
+  virtual std::unordered_map<std::string, std::vector<std::string>>
+  getExecutedFunctions() = 0;
+  virtual bool isCodeCoverageProfilerEnabled() = 0;
+  virtual void enableCodeCoverageProfiler() = 0;
+  virtual void disableCodeCoverageProfiler() = 0;
+
+ protected:
+  ~IHermesRootAPI() {}
+};
+
+class HERMES_EXPORT ISetFatalHandler : public jsi::ICast {
+ public:
+  static constexpr jsi::UUID uuid{
+      0xda98a610, 0x09cb, 0x11f0, 0x87bf, 0x325096b39f47};
+  virtual void setFatalHandler(void (*handler)(const std::string &)) = 0;
+
+ protected:
+  ~ISetFatalHandler() = default;
+};
+
+/// Hermes-specific per-runtime methods.
+class HERMES_EXPORT IHermes : public jsi::ICast {
+ public:
+  static constexpr jsi::UUID uuid{
+      0xe85cfa22, 0xdfae, 0x11ef, 0xa6f7, 0x325096b39f47};
+
+  virtual ICast *getHermesRootAPI() = 0;
+  virtual void sampledTraceToStreamInDevToolsFormat(std::ostream &stream) = 0;
+  virtual sampling_profiler::Profile dumpSampledTraceToProfile() = 0;
+  virtual void resetTimezoneCache() = 0;
+  virtual void loadSegment(
+      std::unique_ptr<const jsi::Buffer> buffer, const jsi::Value &context) = 0;
+
+  /// QuickJS heap objects do not move, so an object's address is a stable id
+  /// for its lifetime -- the contract Hermes documents, including that an id
+  /// may be reused after the object is collected.
+  virtual uint64_t getUniqueID(const jsi::Object &o) const = 0;
+  virtual uint64_t getUniqueID(const jsi::BigInt &s) const = 0;
+  virtual uint64_t getUniqueID(const jsi::String &s) const = 0;
+  virtual uint64_t getUniqueID(const jsi::PropNameID &pni) const = 0;
+  virtual uint64_t getUniqueID(const jsi::Symbol &sym) const = 0;
+  virtual uint64_t getUniqueID(const jsi::Value &val) const = 0;
+  virtual jsi::Value getObjectForID(uint64_t id) = 0;
+
+  virtual const ::hermes::vm::GCExecTrace &getGCExecTrace() const = 0;
+  virtual std::string getIOTrackingInfoJSON() = 0;
+  virtual debugger::Debugger &getDebugger() = 0;
+
+  struct DebugFlags {};
+
+  virtual void debugJavaScript(
+      const std::string &src, const std::string &sourceURL,
+      const DebugFlags &debugFlags) = 0;
+  virtual void registerForProfiling() = 0;
+  virtual void unregisterForProfiling() = 0;
+
+  /// Backed by the engine's interrupt handler, which the interpreter polls.
+  virtual void asyncTriggerTimeout() = 0;
+  virtual void watchTimeLimit(uint32_t timeoutInMs) = 0;
+  virtual void unwatchTimeLimit() = 0;
+
+  virtual jsi::Value evaluateJavaScriptWithSourceMap(
+      const std::shared_ptr<const jsi::Buffer> &buffer,
+      const std::shared_ptr<const jsi::Buffer> &sourceMapBuf,
+      const std::string &sourceURL) = 0;
+  virtual jsi::Value evaluateSHUnit(SHUnit *(*shUnitCreator)()) = 0;
+  virtual SHRuntime *getSHRuntime() noexcept = 0;
+
+  /// Returns nullptr. Handing back the JSContext* would let a caller
+  /// reinterpret_cast it to hermes::vm::Runtime* and corrupt memory.
+  virtual void *getVMRuntimeUnsafe() const = 0;
+
+ protected:
+  ~IHermes() = default;
+};
+
+class HERMES_EXPORT IHermesTestHelpers : public jsi::ICast {
+ public:
+  static constexpr jsi::UUID uuid{
+      0x664e489a, 0xf941, 0x11ef, 0xa44c, 0x325096b39f47};
+  virtual size_t rootsListLengthForTests() const = 0;
+
+ protected:
+  ~IHermesTestHelpers() = default;
+};
+
+class HermesRuntime : public jsi::Runtime, public IHermes {
+ public:
+  ~HermesRuntime() override = default;
+
+  using jsi::Runtime::castInterface;
+};
+
+HERMES_EXPORT jsi::ICast *makeHermesRootAPI();
+
+HERMES_EXPORT ::hermes::vm::RuntimeConfig hardenedHermesRuntimeConfig();
+
+HERMES_EXPORT std::unique_ptr<HermesRuntime> makeHermesRuntime(
+    const ::hermes::vm::RuntimeConfig &runtimeConfig =
+        ::hermes::vm::RuntimeConfig());
+
+/// Returns nullptr rather than an unlocked runtime: a caller expecting
+/// Hermes's ThreadSafeRuntime semantics should not silently get less.
+HERMES_EXPORT std::unique_ptr<jsi::ThreadSafeRuntime>
+makeThreadSafeHermesRuntime(
+    const ::hermes::vm::RuntimeConfig &runtimeConfig =
+        ::hermes::vm::RuntimeConfig());
+
+}  // namespace hermes
+}  // namespace facebook

package/modules/hermes-compat/include/hermes/inspector/RuntimeAdapter.h

@@ -0,0 +1,43 @@
+/*
+ * 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 <hermes/hermes.h>
+
+#include <memory>
+
+#ifndef INSPECTOR_EXPORT
+#if defined(_MSC_VER)
+#define INSPECTOR_EXPORT
+#else
+#define INSPECTOR_EXPORT __attribute__((visibility("default")))
+#endif
+#endif
+
+namespace facebook::hermes::inspector_modern {
+
+/// Owns a runtime for the debugger to attach to. Kept because worklets names
+/// the type; see Registration.h for what attaching actually does here.
+class INSPECTOR_EXPORT RuntimeAdapter {
+ public:
+  virtual ~RuntimeAdapter() = 0;
+  virtual HermesRuntime &getRuntime() = 0;
+  virtual void tickleJs();
+};
+
+class INSPECTOR_EXPORT SharedRuntimeAdapter : public RuntimeAdapter {
+ public:
+  explicit SharedRuntimeAdapter(std::shared_ptr<HermesRuntime> runtime);
+  ~SharedRuntimeAdapter() override;
+  HermesRuntime &getRuntime() override;
+
+ private:
+  std::shared_ptr<HermesRuntime> runtime_;
+};
+
+}  // namespace facebook::hermes::inspector_modern

package/modules/hermes-compat/include/hermes/inspector-modern/chrome/Registration.h

@@ -0,0 +1,31 @@
+/*
+ * 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
+
+#ifdef HERMES_ENABLE_DEBUGGER
+
+#include <hermes/hermes.h>
+#include <hermes/inspector/RuntimeAdapter.h>
+
+#include <memory>
+#include <string>
+
+namespace facebook::hermes::inspector_modern::chrome {
+
+using DebugSessionToken = int;
+
+/// Defined so debug builds of worklets link. It does not register a target:
+/// the app's main runtime is debuggable through jsinspector-modern and
+/// modules/cdp, a runtime created through this shim is not.
+extern DebugSessionToken enableDebugging(
+    std::unique_ptr<RuntimeAdapter> adapter, const std::string &title);
+extern void disableDebugging(DebugSessionToken session);
+
+}  // namespace facebook::hermes::inspector_modern::chrome
+
+#endif  // HERMES_ENABLE_DEBUGGER

package/modules/hermes-compat/include/hermes-compat/Diagnostics.h

@@ -0,0 +1,35 @@
+/*
+ * 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 <cstdint>
+#include <functional>
+
+namespace qjs::hermescompat {
+
+enum class Severity : uint8_t {
+  Degraded,     ///< Ran, but not the way Hermes would have.
+  Ignored,      ///< Did nothing, and nothing observable depended on it.
+  Unsupported,  ///< Could not be honoured; the result is a safe stand-in.
+};
+
+using Handler =
+    std::function<void(Severity, const char *api, const char *detail)>;
+
+/// Replaces the default handler, which writes to stderr, or to logcat on
+/// Android. Nothing aborts: how strict to be is the embedder's call.
+void setHandler(Handler handler);
+
+/// Reports the first time each `api` is seen, so a call in a loop says it
+/// once. Called by the shim; `api` is always a literal.
+void report(Severity severity, const char *api, const char *detail);
+
+/// Forgets which APIs have reported, so the next call to each reports again.
+void resetForTesting();
+
+}  // namespace qjs::hermescompat