@homaiohq/napi-quickfix 0.0.0-stage → 0.1.0

package/cpp/engine_workers.h

@@ -0,0 +1,86 @@
+#ifndef NAPI_QUICKFIX_ENGINE_WORKERS_H
+#define NAPI_QUICKFIX_ENGINE_WORKERS_H
+
+#include <napi.h>
+
+#include <functional>
+#include <utility>
+
+#include "errors.h"
+
+namespace napi_quickfix {
+
+// A generic AsyncWorker that runs a blocking QuickFIX engine operation
+// (start/stop) on a libuv worker thread and resolves/rejects a JS Promise.
+//
+// Why off-thread: start()/stop() synchronously invoke FIX::Application callbacks
+// (toAdmin/toApp during send-on-logon, onLogout during stop) which the
+// ApplicationBridge dispatches back to the JS thread via a TSFN BlockingCall +
+// future. If the operation ran ON the JS thread, the event loop couldn't service
+// the TSFN trampoline and we'd deadlock. Running it on a worker thread keeps the
+// main event loop free to run CallJs.
+//
+// Lifetime: the worker holds a Napi::ObjectReference to the owning wrap object so
+// it (and its bridge / engine / factories) can't be GC'd while the op is in
+// flight. The ref is released in OnOK/OnError (both run on the JS thread).
+class EngineOpWorker : public Napi::AsyncWorker {
+ public:
+  // onSettled receives `true` if the op succeeded, `false` if it threw.
+  EngineOpWorker(Napi::Env env, Napi::Object owner, std::function<void()> op,
+                 std::function<void(bool)> onSettled)
+      : Napi::AsyncWorker(env),
+        deferred_(Napi::Promise::Deferred::New(env)),
+        op_(std::move(op)),
+        onSettled_(std::move(onSettled)) {
+    ownerRef_ = Napi::Persistent(owner);
+  }
+
+  Napi::Promise Promise() { return deferred_.Promise(); }
+
+  // Runs on a libuv worker thread. NO Napi/JS access allowed here.
+  void Execute() override {
+    try {
+      op_();
+    } catch (const std::exception& e) {
+      err_.Capture(e);
+    } catch (...) {
+      err_.has = true;
+      err_.message = "unknown native error";
+      err_.fixErrorName = "Error";
+    }
+  }
+
+  // Runs on the JS thread.
+  void OnOK() override {
+    Napi::Env env = Env();
+    Napi::HandleScope scope(env);
+    if (onSettled_) onSettled_(!err_.has);
+    if (err_.has) {
+      deferred_.Reject(err_.ToError(env).Value());
+    } else {
+      deferred_.Resolve(env.Undefined());
+    }
+    ownerRef_.Reset();
+  }
+
+  // Runs on the JS thread (only if AsyncWorker::SetError was used; we don't, so
+  // errors flow through OnOK — but provide OnError for completeness/safety).
+  void OnError(const Napi::Error& e) override {
+    Napi::Env env = Env();
+    Napi::HandleScope scope(env);
+    if (onSettled_) onSettled_(false);
+    deferred_.Reject(e.Value());
+    ownerRef_.Reset();
+  }
+
+ private:
+  Napi::Promise::Deferred deferred_;
+  Napi::ObjectReference ownerRef_;
+  std::function<void()> op_;
+  std::function<void(bool)> onSettled_;
+  CapturedError err_;
+};
+
+}  // namespace napi_quickfix
+
+#endif  // NAPI_QUICKFIX_ENGINE_WORKERS_H

package/cpp/enums.cpp

@@ -0,0 +1,66 @@
+#include <napi.h>
+
+namespace napi_quickfix {
+
+namespace {
+
+void SetInt(Napi::Object obj, const char* key, int value) {
+  obj.Set(key, Napi::Number::New(obj.Env(), value));
+}
+
+void SetStr(Napi::Object obj, const char* key, const char* value) {
+  obj.Set(key, Napi::String::New(obj.Env(), value));
+}
+
+}  // namespace
+
+// Exposes commonly-needed FIX enum values (MsgType, Side, ...) as `exports.enums`.
+// Field tags are NOT here: `FIELD` is generated on the TS side from QuickFIX's
+// FixFieldNumbers.h (scripts/gen-fields.mjs) so it covers every field.
+// Not exhaustive by design — a curated, useful subset.
+void RegisterEnums(Napi::Env env, Napi::Object exports) {
+  Napi::Object enums = Napi::Object::New(env);
+
+  // --- MsgType ------------------------------------------------------------
+  Napi::Object msgType = Napi::Object::New(env);
+  SetStr(msgType, "Heartbeat", "0");
+  SetStr(msgType, "TestRequest", "1");
+  SetStr(msgType, "ResendRequest", "2");
+  SetStr(msgType, "Reject", "3");
+  SetStr(msgType, "SequenceReset", "4");
+  SetStr(msgType, "Logout", "5");
+  SetStr(msgType, "Logon", "A");
+  SetStr(msgType, "NewOrderSingle", "D");
+  SetStr(msgType, "ExecutionReport", "8");
+  SetStr(msgType, "OrderCancelRequest", "F");
+  SetStr(msgType, "OrderCancelReplaceRequest", "G");
+  SetStr(msgType, "OrderCancelReject", "9");
+  enums.Set("MsgType", msgType);
+
+  // --- Side ---------------------------------------------------------------
+  Napi::Object side = Napi::Object::New(env);
+  SetStr(side, "Buy", "1");
+  SetStr(side, "Sell", "2");
+  SetStr(side, "SellShort", "5");
+  enums.Set("Side", side);
+
+  // --- OrdType ------------------------------------------------------------
+  Napi::Object ordType = Napi::Object::New(env);
+  SetStr(ordType, "Market", "1");
+  SetStr(ordType, "Limit", "2");
+  SetStr(ordType, "Stop", "3");
+  SetStr(ordType, "StopLimit", "4");
+  enums.Set("OrdType", ordType);
+
+  // --- TimeInForce --------------------------------------------------------
+  Napi::Object tif = Napi::Object::New(env);
+  SetStr(tif, "Day", "0");
+  SetStr(tif, "GoodTillCancel", "1");
+  SetStr(tif, "ImmediateOrCancel", "3");
+  SetStr(tif, "FillOrKill", "4");
+  enums.Set("TimeInForce", tif);
+
+  exports.Set("enums", enums);
+}
+
+}  // namespace napi_quickfix

package/cpp/errors.h

@@ -0,0 +1,142 @@
+// C++ -> Napi::Error translation for the QuickFIX wrapper.
+//
+// Every wrapper method funnels caught exceptions through here so that JS sees a
+// consistent Error shape:
+//   - name:     "QuickFixError"
+//   - message:  the exception's what()
+//   - fixError: a discriminator string. For FIX::Exception this is its `.type`
+//               (e.g. "Field not found: 35", "Configuration failed", ...) which
+//               is stable per concrete type; we ALSO set fixErrorName to the C++
+//               class name (e.g. "FieldNotFound") which is the value TS keys on.
+//   - detail:   the exception's `.detail` when available.
+//
+// NAPI_CPP_EXCEPTIONS is enabled, so throwing a Napi::Error unwinds into a JS
+// throw at the call boundary.
+#ifndef NAPI_QUICKFIX_ERRORS_H
+#define NAPI_QUICKFIX_ERRORS_H
+
+#include <napi.h>
+
+#include <exception>
+#include <string>
+
+#include "quickfix/Exceptions.h"
+
+namespace napi_quickfix {
+
+// Map a concrete FIX::Exception to a stable class-name discriminator. QuickFIX
+// exceptions don't carry RTTI-friendly names, so we dynamic_cast the well-known
+// concrete types (order: most-specific first is not required since they don't
+// inherit from each other beyond Exception).
+inline const char* FixErrorName(const FIX::Exception& e) {
+  if (dynamic_cast<const FIX::ConfigError*>(&e)) return "ConfigError";
+  if (dynamic_cast<const FIX::RuntimeError*>(&e)) return "RuntimeError";
+  if (dynamic_cast<const FIX::FieldNotFound*>(&e)) return "FieldNotFound";
+  if (dynamic_cast<const FIX::FieldConvertError*>(&e)) return "FieldConvertError";
+  if (dynamic_cast<const FIX::MessageParseError*>(&e)) return "MessageParseError";
+  if (dynamic_cast<const FIX::InvalidMessage*>(&e)) return "InvalidMessage";
+  if (dynamic_cast<const FIX::IncorrectDataFormat*>(&e)) return "IncorrectDataFormat";
+  if (dynamic_cast<const FIX::IncorrectTagValue*>(&e)) return "IncorrectTagValue";
+  if (dynamic_cast<const FIX::IncorrectMessageStructure*>(&e)) return "IncorrectMessageStructure";
+  if (dynamic_cast<const FIX::InvalidTagNumber*>(&e)) return "InvalidTagNumber";
+  if (dynamic_cast<const FIX::RequiredTagMissing*>(&e)) return "RequiredTagMissing";
+  if (dynamic_cast<const FIX::TagNotDefinedForMessage*>(&e)) return "TagNotDefinedForMessage";
+  if (dynamic_cast<const FIX::NoTagValue*>(&e)) return "NoTagValue";
+  if (dynamic_cast<const FIX::DuplicateFieldNumber*>(&e)) return "DuplicateFieldNumber";
+  if (dynamic_cast<const FIX::InvalidMessageType*>(&e)) return "InvalidMessageType";
+  if (dynamic_cast<const FIX::UnsupportedMessageType*>(&e)) return "UnsupportedMessageType";
+  if (dynamic_cast<const FIX::UnsupportedVersion*>(&e)) return "UnsupportedVersion";
+  if (dynamic_cast<const FIX::TagOutOfOrder*>(&e)) return "TagOutOfOrder";
+  if (dynamic_cast<const FIX::RepeatedTag*>(&e)) return "RepeatedTag";
+  if (dynamic_cast<const FIX::RepeatingGroupCountMismatch*>(&e)) return "RepeatingGroupCountMismatch";
+  if (dynamic_cast<const FIX::DoNotSend*>(&e)) return "DoNotSend";
+  if (dynamic_cast<const FIX::RejectLogon*>(&e)) return "RejectLogon";
+  if (dynamic_cast<const FIX::SessionNotFound*>(&e)) return "SessionNotFound";
+  if (dynamic_cast<const FIX::DataDictionaryNotFound*>(&e)) return "DataDictionaryNotFound";
+  if (dynamic_cast<const FIX::IOException*>(&e)) return "IOException";
+  if (dynamic_cast<const FIX::SocketException*>(&e)) return "SocketException";
+  return "FixException";
+}
+
+// Build (but do not throw) a Napi::Error from a FIX::Exception.
+inline Napi::Error MakeFixError(Napi::Env env, const FIX::Exception& e) {
+  Napi::Error err = Napi::Error::New(env, e.what());
+  err.Set("name", Napi::String::New(env, "QuickFixError"));
+  err.Set("fixError", Napi::String::New(env, e.type));
+  err.Set("fixErrorName", Napi::String::New(env, FixErrorName(e)));
+  err.Set("detail", Napi::String::New(env, e.detail));
+  return err;
+}
+
+// Build (but do not throw) a Napi::Error from a generic std::exception.
+inline Napi::Error MakeStdError(Napi::Env env, const std::exception& e) {
+  Napi::Error err = Napi::Error::New(env, e.what());
+  err.Set("name", Napi::String::New(env, "QuickFixError"));
+  err.Set("fixErrorName", Napi::String::New(env, "Error"));
+  return err;
+}
+
+// A plain-data capture of an exception's mapped fields, safe to carry across
+// threads (an AsyncWorker's Execute() runs off the JS thread and MUST NOT touch
+// Napi/JS). Populate it in a catch block on the worker thread, then rebuild a
+// Napi::Error from it in OnError/OnOK (which run on the JS thread).
+struct CapturedError {
+  bool has = false;
+  bool isFix = false;
+  std::string message;       // what()
+  std::string fixError;      // FIX::Exception::type (for FIX exceptions)
+  std::string fixErrorName;  // stable class-name discriminator
+  std::string detail;        // FIX::Exception::detail
+
+  void Capture(const std::exception& e) {
+    has = true;
+    message = e.what();
+    if (const auto* fe = dynamic_cast<const FIX::Exception*>(&e)) {
+      isFix = true;
+      fixError = fe->type;
+      fixErrorName = FixErrorName(*fe);
+      detail = fe->detail;
+    } else {
+      isFix = false;
+      fixErrorName = "Error";
+    }
+  }
+
+  // Build (do not throw) a Napi::Error from the captured fields.
+  Napi::Error ToError(Napi::Env env) const {
+    Napi::Error err = Napi::Error::New(env, message);
+    err.Set("name", Napi::String::New(env, "QuickFixError"));
+    if (isFix) {
+      err.Set("fixError", Napi::String::New(env, fixError));
+      err.Set("fixErrorName", Napi::String::New(env, fixErrorName));
+      err.Set("detail", Napi::String::New(env, detail));
+    } else {
+      err.Set("fixErrorName", Napi::String::New(env, fixErrorName));
+    }
+    return err;
+  }
+};
+
+// Translate a caught exception and throw the corresponding Napi::Error. Callers
+// use this inside a catch block, e.g.:
+//   try { ... } catch (const std::exception& e) { TranslateAndThrow(env, e); }
+[[noreturn]] inline void TranslateAndThrow(Napi::Env env, const std::exception& e) {
+  if (const auto* fe = dynamic_cast<const FIX::Exception*>(&e)) {
+    throw MakeFixError(env, *fe);
+  }
+  throw MakeStdError(env, e);
+}
+
+}  // namespace napi_quickfix
+
+// Wrap a QuickFIX-calling body so any std::exception is converted to a JS throw.
+// Usage:
+//   NQ_TRY(env) { ...quickfix calls that may throw... } NQ_CATCH(env)
+// The body may `return` a Napi::Value normally.
+#define NQ_TRY(env) try
+#define NQ_CATCH(env)                                                    \
+  catch (const std::exception& _nq_e) {                                  \
+    ::napi_quickfix::TranslateAndThrow((env), _nq_e);                    \
+  }
+
+#endif  // NAPI_QUICKFIX_ERRORS_H

package/cpp/initiator_wrap.cpp

@@ -0,0 +1,255 @@
+#include "initiator_wrap.h"
+
+#include <string>
+
+#include "quickfix/FileLog.h"
+#include "quickfix/FileStore.h"
+
+#include "engine_common.h"
+#include "engine_workers.h"
+#include "errors.h"
+#include "session_settings_wrap.h"
+
+namespace napi_quickfix {
+
+Napi::FunctionReference InitiatorWrap::constructor_;
+
+namespace {
+
+std::string OptString(Napi::Object opts, const char* key,
+                      const std::string& dflt) {
+  if (opts.Has(key)) {
+    Napi::Value v = opts.Get(key);
+    if (v.IsString()) return v.As<Napi::String>().Utf8Value();
+  }
+  return dflt;
+}
+
+}  // namespace
+
+Napi::Object InitiatorWrap::Init(Napi::Env env, Napi::Object exports) {
+  Napi::Function func = DefineClass(
+      env, "Initiator",
+      {
+          InstanceMethod("start", &InitiatorWrap::Start),
+          InstanceMethod("stop", &InitiatorWrap::Stop),
+          InstanceMethod("isLoggedOn", &InitiatorWrap::IsLoggedOn),
+          InstanceMethod("ref", &InitiatorWrap::Ref),
+          InstanceMethod("unref", &InitiatorWrap::Unref),
+      });
+  constructor_ = Napi::Persistent(func);
+  constructor_.SuppressDestruct();
+  exports.Set("InitiatorWrap", func);
+  return exports;
+}
+
+InitiatorWrap::InitiatorWrap(const Napi::CallbackInfo& info)
+    : Napi::ObjectWrap<InitiatorWrap>(info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsObject()) {
+    throw Napi::TypeError::New(
+        env, "new Initiator({ settings, handlers?, store?, log? })");
+  }
+  Napi::Object opts = info[0].As<Napi::Object>();
+
+  SessionSettingsWrap* settingsWrap =
+      SessionSettingsWrap::UnwrapArg(env, opts.Get("settings"), "settings");
+
+  Napi::Object handlers;
+  if (opts.Has("handlers") && opts.Get("handlers").IsObject()) {
+    handlers = opts.Get("handlers").As<Napi::Object>();
+  } else {
+    handlers = Napi::Object::New(env);
+  }
+
+  std::string store = OptString(opts, "store", "file");
+  std::string log = OptString(opts, "log", "screen");
+
+  const FIX::SessionSettings& settings = settingsWrap->Settings();
+
+  // Bridge must be created on the JS thread (captures env / handlers).
+  bridge_ = std::make_unique<ApplicationBridge>(env, handlers);
+
+  NQ_TRY(env) {
+    if (store == "memory") {
+      storeFactory_ = std::make_unique<FIX::MemoryStoreFactory>();
+    } else {
+      storeFactory_ = std::make_unique<FIX::FileStoreFactory>(settings);
+    }
+
+    if (log == "none") {
+      logFactory_ = std::make_unique<NullLogFactory>();
+    } else if (log == "file") {
+      logFactory_ = std::make_unique<FIX::FileLogFactory>(settings);
+    } else {
+      logFactory_ = std::make_unique<FIX::ScreenLogFactory>(settings);
+    }
+
+    initiator_ = std::make_unique<FIX::SocketInitiator>(
+        *bridge_, *storeFactory_, settings, *logFactory_);
+  } NQ_CATCH(env)
+
+  // Register a cleanup hook so teardown runs deterministically on the MAIN
+  // thread during environment shutdown, BEFORE the TSFN is finalized. ObjectWrap
+  // finalizers do NOT reliably run before env teardown when the loop is
+  // unref'd, so relying on the destructor alone lets a live QuickFIX network
+  // thread call into an already-destroyed TSFN and abort the process.
+  env_ = env;
+  cleanupHook_ = env.AddCleanupHook(&InitiatorWrap::CleanupEntry, this);
+}
+
+void InitiatorWrap::CleanupEntry(InitiatorWrap* self) {
+  // Runs on the MAIN thread during env shutdown. Join network threads and tear
+  // down the bridge before N-API destroys the TSFN. Mark fired so the later
+  // destructor doesn't Remove() an already-freed cleanup hook (double free).
+  self->cleanupHookFired_ = true;
+  self->Teardown(true);
+}
+
+InitiatorWrap::~InitiatorWrap() {
+  // If the object is GC-finalized BEFORE env shutdown, remove the cleanup hook
+  // so it won't fire on freed memory. If the hook already fired, node already
+  // freed the hook data — do NOT Remove() (that would double-free).
+  if (!cleanupHookFired_ && !cleanupHook_.IsEmpty() && env_ != nullptr) {
+    cleanupHook_.Remove(env_);
+  }
+  Teardown(true);
+}
+
+void InitiatorWrap::Teardown(bool force) {
+  // Runs on the MAIN thread (finalizer / explicit teardown). MUST NOT block on a
+  // JS round-trip and MUST NOT deadlock. Ordering matters:
+  //   1. Deactivate the bridge (set a flag, no TSFN op): any callback firing on
+  //      a QuickFIX network thread during the upcoming stop() will pass through
+  //      immediately without touching the TSFN or waiting on the (frozen) JS
+  //      loop. This breaks the stop()->onLogout->BlockingCall deadlock.
+  //   2. stop(force): joins all QuickFIX network threads. After it returns, no
+  //      network thread is running, so none can race into the TSFN.
+  //   3. Abort the TSFN: safe now that no producer thread remains.
+  if (stopped_) return;
+  stopped_ = true;
+  if (bridge_) {
+    bridge_->Deactivate();
+  }
+  if (initiator_ && started_) {
+    try {
+      initiator_->stop(force);
+    } catch (...) {
+    }
+  }
+  if (bridge_) {
+    bridge_->Abort();
+  }
+}
+
+Napi::Value InitiatorWrap::Start(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  auto deferred = Napi::Promise::Deferred::New(env);
+  if (stopped_) {
+    deferred.Reject(Napi::Error::New(env, "Initiator has been stopped").Value());
+    return deferred.Promise();
+  }
+  if (started_) {
+    deferred.Resolve(env.Undefined());
+    return deferred.Promise();
+  }
+  if (busy_) {
+    deferred.Reject(
+        Napi::Error::New(env, "Initiator start/stop already in progress")
+            .Value());
+    return deferred.Promise();
+  }
+  busy_ = true;
+  started_ = true;  // set optimistically; reset in onSettled on failure
+
+  FIX::SocketInitiator* initiator = initiator_.get();
+  auto* self = this;
+  auto* worker = new EngineOpWorker(
+      env, info.This().As<Napi::Object>(),
+      [initiator]() { initiator->start(); },
+      [self](bool ok) {
+        self->busy_ = false;
+        // If start failed, mark not-started so teardown won't try to stop an
+        // engine that never came up, and a later start() can retry.
+        if (!ok) self->started_ = false;
+      });
+  Napi::Promise promise = worker->Promise();
+  worker->Queue();
+  return promise;
+}
+
+Napi::Value InitiatorWrap::Stop(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  bool force = false;
+  if (info.Length() >= 1 && !info[0].IsUndefined()) {
+    force = info[0].ToBoolean().Value();
+  }
+  auto deferred = Napi::Promise::Deferred::New(env);
+  if (stopped_) {
+    deferred.Resolve(env.Undefined());
+    return deferred.Promise();
+  }
+  if (busy_) {
+    deferred.Reject(
+        Napi::Error::New(env, "Initiator start/stop already in progress")
+            .Value());
+    return deferred.Promise();
+  }
+  if (!initiator_ || !started_) {
+    // Never started (or already torn down): just release the TSFN and resolve.
+    stopped_ = true;
+    if (bridge_) bridge_->Release();
+    deferred.Resolve(env.Undefined());
+    return deferred.Promise();
+  }
+  busy_ = true;
+  stopped_ = true;
+
+  FIX::SocketInitiator* initiator = initiator_.get();
+  ApplicationBridge* bridge = bridge_.get();
+  auto* self = this;
+  auto* worker = new EngineOpWorker(
+      env, info.This().As<Napi::Object>(),
+      // stop() runs on the worker thread; its onLogout/toAdmin callbacks fire on
+      // QuickFIX threads while the main loop is free to service the TSFN.
+      [initiator, force]() { initiator->stop(force); },
+      [self, bridge, force](bool /*ok*/) {
+        self->busy_ = false;
+        // Now that stop() has completed and no more callbacks will fire, drain
+        // (or abort) the TSFN so the event loop can exit on its own.
+        if (bridge) {
+          if (force) {
+            bridge->Abort();
+          } else {
+            bridge->Release();
+          }
+        }
+      });
+  Napi::Promise promise = worker->Promise();
+  worker->Queue();
+  return promise;
+}
+
+Napi::Value InitiatorWrap::IsLoggedOn(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (!initiator_ || !started_ || stopped_) {
+    return Napi::Boolean::New(env, false);
+  }
+  NQ_TRY(env) {
+    return Napi::Boolean::New(env, initiator_->isLoggedOn());
+  } NQ_CATCH(env)
+}
+
+Napi::Value InitiatorWrap::Ref(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (bridge_) bridge_->Ref(env);
+  return info.This();
+}
+
+Napi::Value InitiatorWrap::Unref(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (bridge_) bridge_->Unref(env);
+  return info.This();
+}
+
+}  // namespace napi_quickfix

package/cpp/initiator_wrap.h

@@ -0,0 +1,69 @@
+#ifndef NAPI_QUICKFIX_INITIATOR_WRAP_H
+#define NAPI_QUICKFIX_INITIATOR_WRAP_H
+
+#include <napi.h>
+
+#include <memory>
+
+#include "quickfix/Log.h"
+#include "quickfix/MessageStore.h"
+#include "quickfix/SocketInitiator.h"
+
+#include "application_bridge.h"
+
+namespace napi_quickfix {
+
+// Napi::ObjectWrap over FIX::SocketInitiator.
+//
+//   new Initiator({ settings, handlers?, store?, log? })
+//     store: 'file' | 'memory'         (default 'file')
+//     log:   'screen' | 'file' | 'none' (default 'screen')
+//
+// Methods: start / stop(force?) / isLoggedOn / ref / unref.
+class InitiatorWrap : public Napi::ObjectWrap<InitiatorWrap> {
+ public:
+  static Napi::Object Init(Napi::Env env, Napi::Object exports);
+  explicit InitiatorWrap(const Napi::CallbackInfo& info);
+  ~InitiatorWrap() override;
+
+ private:
+  static Napi::FunctionReference constructor_;
+
+  Napi::Value Start(const Napi::CallbackInfo& info);
+  Napi::Value Stop(const Napi::CallbackInfo& info);
+  Napi::Value IsLoggedOn(const Napi::CallbackInfo& info);
+  Napi::Value Ref(const Napi::CallbackInfo& info);
+  Napi::Value Unref(const Napi::CallbackInfo& info);
+
+  void Teardown(bool force);
+
+  // Declaration order matters: members destruct in REVERSE order, so the
+  // initiator (declared last) is destroyed FIRST, before the factories and
+  // bridge it references.
+  std::unique_ptr<ApplicationBridge> bridge_;
+  std::unique_ptr<FIX::MessageStoreFactory> storeFactory_;
+  std::unique_ptr<FIX::LogFactory> logFactory_;
+  std::unique_ptr<FIX::SocketInitiator> initiator_;
+
+  bool started_ = false;
+  bool stopped_ = false;
+  bool busy_ = false;  // guards against overlapping start/stop AsyncWorkers
+
+  static void CleanupEntry(InitiatorWrap* self);
+
+  // Env captured at construction (JS thread), used only to remove the cleanup
+  // hook if the object is GC-finalized before environment shutdown.
+  napi_env env_ = nullptr;
+  // Runs Teardown on the MAIN thread during environment shutdown, BEFORE N-API
+  // finalizes the TSFN — the only reliable point to join QuickFIX network
+  // threads before the TSFN they call into is destroyed. Removed in the
+  // destructor ONLY if the hook has not already fired (node's cleanup wrapper
+  // frees its own data after invoking the hook, so Remove() afterward would
+  // double-free; we track that with cleanupHookFired_).
+  Napi::Env::CleanupHook<void (*)(InitiatorWrap*), InitiatorWrap> cleanupHook_;
+  bool cleanupHookFired_ = false;
+};
+
+}  // namespace napi_quickfix
+
+#endif  // NAPI_QUICKFIX_INITIATOR_WRAP_H