@homaiohq/napi-quickfix 0.0.0-stage → 0.2.0

package/dist/esm/application.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Application-callback types for the session engine.
+ *
+ * Handlers are invoked **synchronously** by QuickFIX on its own threads via the
+ * native bridge. Two callbacks may mutate their message argument in place
+ * (`toAdmin`/`toApp`), and several may reject a message by **throwing** a typed
+ * rejection (`toApp`/`fromApp`/`fromAdmin`). Throwing anything else surfaces as
+ * a generic rejection.
+ *
+ * The {@link Initiator}/{@link Acceptor} also emit observe-only EventEmitter
+ * events mirroring these callbacks — but events cannot mutate or reject; that
+ * MUST go through the handlers.
+ */
+import type { Message } from './message.js';
+import type { SessionID } from './session-id.js';
+/**
+ * User-supplied FIX application callbacks.
+ *
+ * All are optional. Runtime semantics:
+ * - `onCreate`/`onLogon`/`onLogout` — fire-and-forget notifications.
+ * - `toAdmin`/`toApp` — invoked before an outbound message is sent; may **mutate**
+ *   the message in place (e.g. add credentials to a Logon in `toAdmin`).
+ * - `toApp` — additionally may **throw** {@link FixReject} with kind `'DoNotSend'`
+ *   to suppress sending.
+ * - `fromAdmin`/`fromApp` — invoked for inbound messages; may **throw**
+ *   {@link FixReject} to reject (e.g. `'RejectLogon'`, `'UnsupportedMessageType'`).
+ */
+export interface ApplicationHandlers {
+    /** A new session was created. */
+    onCreate?(sessionID: SessionID): void;
+    /** A session successfully logged on. */
+    onLogon?(sessionID: SessionID): void;
+    /** A session logged out (or was disconnected). */
+    onLogout?(sessionID: SessionID): void;
+    /**
+     * About to send an admin (session-level) message. May mutate `message`.
+     * @param message The outbound message (mutable).
+     */
+    toAdmin?(message: Message, sessionID: SessionID): void;
+    /**
+     * About to send an application message. May mutate `message`, or throw a
+     * {@link FixReject} with kind `'DoNotSend'` to suppress it.
+     */
+    toApp?(message: Message, sessionID: SessionID): void;
+    /**
+     * Received an admin (session-level) message. May throw a {@link FixReject}
+     * (e.g. `'RejectLogon'`) to reject it.
+     */
+    fromAdmin?(message: Message, sessionID: SessionID): void;
+    /**
+     * Received an application message. May throw a {@link FixReject} (e.g.
+     * `'UnsupportedMessageType'`, `'DoNotSend'`) to reject it.
+     */
+    fromApp?(message: Message, sessionID: SessionID): void;
+}
+/**
+ * The kinds of rejection the native bridge understands. Throwing a
+ * {@link FixReject} with one of these maps to the matching QuickFIX behaviour:
+ * - `'DoNotSend'` → `FIX::DoNotSend` (from `toApp`)
+ * - `'RejectLogon'` → `FIX::RejectLogon` (from `fromAdmin`)
+ * - `'UnsupportedMessageType'` → `FIX::UnsupportedMessageType` (from `fromApp`)
+ * - `'IncorrectDataFormat'` → `FIX::IncorrectDataFormat`
+ * - `'IncorrectTagValue'` → `FIX::IncorrectTagValue`
+ * - `'FieldNotFound'` → `FIX::FieldNotFound`
+ */
+export type FixRejectKind = 'DoNotSend' | 'RejectLogon' | 'UnsupportedMessageType' | 'IncorrectDataFormat' | 'IncorrectTagValue' | 'FieldNotFound';
+/**
+ * A typed rejection error to throw from an {@link ApplicationHandlers} callback.
+ *
+ * The native bridge inspects a thrown error's `fixError` property (a
+ * {@link FixRejectKind}) to decide which QuickFIX exception to raise on the
+ * engine thread. Throwing any error without a recognized `fixError` results in a
+ * generic rejection.
+ *
+ * For symmetry with errors flowing the OTHER way (native → JS
+ * {@link import('./native.js').QuickFixError}), a `FixReject` also carries a
+ * `fixErrorName` set to the same stable {@link FixRejectKind} discriminator.
+ * Here `fixError` and `fixErrorName` are identical (the kinds are already
+ * space-free); the pair exists so both directions expose the same shape.
+ *
+ * @example
+ * ```ts
+ * handlers: {
+ *   fromApp(msg) {
+ *     if (msg.getMsgType() === 'X') throw new FixReject('UnsupportedMessageType');
+ *   },
+ * }
+ * ```
+ */
+export declare class FixReject extends Error {
+    /**
+     * Discriminator read by the native bridge to map to a FIX exception. The
+     * bridge maps rejections by THIS property.
+     */
+    readonly fixError: FixRejectKind;
+    /**
+     * Stable, space-free discriminator (equal to {@link FixReject.fixError}).
+     * Mirrors {@link import('./native.js').QuickFixError.fixErrorName} so both
+     * error directions share one shape.
+     */
+    readonly fixErrorName: FixRejectKind;
+    /** Optional extra detail forwarded to the engine where supported. */
+    readonly detail?: string;
+    constructor(kind: FixRejectKind, message?: string, detail?: string);
+}
+/**
+ * Convenience factory for a {@link FixReject}. Equivalent to
+ * `new FixReject(kind, message, detail)`.
+ *
+ * @example
+ * ```ts
+ * throw fixReject('DoNotSend');
+ * ```
+ */
+export declare function fixReject(kind: FixRejectKind, message?: string, detail?: string): FixReject;

package/dist/esm/application.js

@@ -0,0 +1,57 @@
+/**
+ * A typed rejection error to throw from an {@link ApplicationHandlers} callback.
+ *
+ * The native bridge inspects a thrown error's `fixError` property (a
+ * {@link FixRejectKind}) to decide which QuickFIX exception to raise on the
+ * engine thread. Throwing any error without a recognized `fixError` results in a
+ * generic rejection.
+ *
+ * For symmetry with errors flowing the OTHER way (native → JS
+ * {@link import('./native.js').QuickFixError}), a `FixReject` also carries a
+ * `fixErrorName` set to the same stable {@link FixRejectKind} discriminator.
+ * Here `fixError` and `fixErrorName` are identical (the kinds are already
+ * space-free); the pair exists so both directions expose the same shape.
+ *
+ * @example
+ * ```ts
+ * handlers: {
+ *   fromApp(msg) {
+ *     if (msg.getMsgType() === 'X') throw new FixReject('UnsupportedMessageType');
+ *   },
+ * }
+ * ```
+ */
+export class FixReject extends Error {
+    /**
+     * Discriminator read by the native bridge to map to a FIX exception. The
+     * bridge maps rejections by THIS property.
+     */
+    fixError;
+    /**
+     * Stable, space-free discriminator (equal to {@link FixReject.fixError}).
+     * Mirrors {@link import('./native.js').QuickFixError.fixErrorName} so both
+     * error directions share one shape.
+     */
+    fixErrorName;
+    /** Optional extra detail forwarded to the engine where supported. */
+    detail;
+    constructor(kind, message, detail) {
+        super(message ?? kind);
+        this.name = 'FixReject';
+        this.fixError = kind;
+        this.fixErrorName = kind;
+        this.detail = detail;
+    }
+}
+/**
+ * Convenience factory for a {@link FixReject}. Equivalent to
+ * `new FixReject(kind, message, detail)`.
+ *
+ * @example
+ * ```ts
+ * throw fixReject('DoNotSend');
+ * ```
+ */
+export function fixReject(kind, message, detail) {
+    return new FixReject(kind, message, detail);
+}

package/dist/esm/data-dictionary.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Ergonomic wrapper around the native `FIX::DataDictionary`.
+ */
+import { type NativeDataDictionary } from './native.js';
+import type { Message } from './message.js';
+/**
+ * A FIX data dictionary, used to validate messages against a FIX spec XML.
+ *
+ * Construct via {@link DataDictionary.fromFile} or
+ * {@link DataDictionary.fromString}; direct construction is not supported.
+ *
+ * @example
+ * ```ts
+ * const dd = DataDictionary.fromFile('./spec/FIX44.xml');
+ * dd.validate(msg); // throws QuickFixError if invalid
+ * dd.getFieldName(35); // 'MsgType'
+ * Message.parse(raw, { dictionary: dd }); // structural parse (repeating groups)
+ * ```
+ */
+export declare class DataDictionary {
+    #private;
+    /** @internal Use {@link DataDictionary.fromFile} / {@link DataDictionary.fromString}. */
+    private constructor();
+    /**
+     * Load a data dictionary from a FIX spec XML file.
+     *
+     * @param xmlPath Path to the FIX spec XML (e.g. `FIX44.xml`).
+     * @throws A `QuickFixError` (`fixError: 'ConfigError'`) if the file is invalid.
+     */
+    static fromFile(xmlPath: string): DataDictionary;
+    /**
+     * Load a data dictionary from FIX spec XML held in memory.
+     *
+     * @param xml The FIX spec XML contents.
+     * @throws A `QuickFixError` (`fixError: 'ConfigError'`) if the XML is invalid.
+     */
+    static fromString(xml: string): DataDictionary;
+    /** @internal Wrap an existing native handle. */
+    static fromNative(handle: NativeDataDictionary): DataDictionary;
+    /** @internal The native handle backing this dictionary. */
+    get nativeHandle(): NativeDataDictionary;
+    /**
+     * Validate a message against this dictionary.
+     *
+     * @param msg The message to validate.
+     * @param bodyOnly When `true`, validate only as the *application* dictionary
+     *   (QuickFIX's `validate(msg, true)`): the BeginString version check and the
+     *   tag/value validation of the header and trailer fields are skipped. It is
+     *   not a check of a draft body: `BeginString` and `MsgType` must be set, and
+     *   every field the dictionary requires, header and trailer included (e.g.
+     *   `BodyLength`, `CheckSum`), must be present. Defaults to `false`.
+     * @throws A `QuickFixError` on any validation failure (e.g.
+     *   `fixErrorName: 'InvalidMessage'` / `'RequiredTagMissing'` /
+     *   `'IncorrectTagValue'` / `'UnsupportedVersion'`).
+     */
+    validate(msg: Message, bodyOnly?: boolean): void;
+    /** The BeginString the spec declares (e.g. `'FIX.4.4'`), or `''` if it has none. */
+    getVersion(): string;
+    /** The name of a field tag (e.g. `35` → `'MsgType'`), or `undefined` if the spec does not define it. */
+    getFieldName(tag: number): string | undefined;
+    /** The tag of a field name (e.g. `'MsgType'` → `35`), or `undefined` if the spec does not define it. */
+    getFieldTag(name: string): number | undefined;
+    /** Whether the spec defines a field with this tag. */
+    isField(tag: number): boolean;
+    /** Whether the spec defines a message with this MsgType (e.g. `'D'`). */
+    isMsgType(msgType: string): boolean;
+}

package/dist/esm/data-dictionary.js

@@ -0,0 +1,101 @@
+/**
+ * Ergonomic wrapper around the native `FIX::DataDictionary`.
+ */
+import { native } from './native.js';
+/**
+ * A FIX data dictionary, used to validate messages against a FIX spec XML.
+ *
+ * Construct via {@link DataDictionary.fromFile} or
+ * {@link DataDictionary.fromString}; direct construction is not supported.
+ *
+ * @example
+ * ```ts
+ * const dd = DataDictionary.fromFile('./spec/FIX44.xml');
+ * dd.validate(msg); // throws QuickFixError if invalid
+ * dd.getFieldName(35); // 'MsgType'
+ * Message.parse(raw, { dictionary: dd }); // structural parse (repeating groups)
+ * ```
+ */
+export class DataDictionary {
+    /** @internal Underlying native handle. */
+    #native;
+    /** @internal Use {@link DataDictionary.fromFile} / {@link DataDictionary.fromString}. */
+    constructor(handle) {
+        this.#native = handle;
+    }
+    /**
+     * Load a data dictionary from a FIX spec XML file.
+     *
+     * @param xmlPath Path to the FIX spec XML (e.g. `FIX44.xml`).
+     * @throws A `QuickFixError` (`fixError: 'ConfigError'`) if the file is invalid.
+     */
+    static fromFile(xmlPath) {
+        // The native `fromFile` may be a module-level fn or a class static;
+        // prefer the module-level fn, fall back to the static.
+        const handle = native.dataDictionaryFromFile?.(xmlPath) ??
+            native.DataDictionaryWrap.fromFile?.(xmlPath);
+        if (!handle) {
+            throw new Error('native DataDictionary.fromFile is unavailable');
+        }
+        return new DataDictionary(handle);
+    }
+    /**
+     * Load a data dictionary from FIX spec XML held in memory.
+     *
+     * @param xml The FIX spec XML contents.
+     * @throws A `QuickFixError` (`fixError: 'ConfigError'`) if the XML is invalid.
+     */
+    static fromString(xml) {
+        const handle = native.dataDictionaryFromString?.(xml) ??
+            native.DataDictionaryWrap.fromString?.(xml);
+        if (!handle) {
+            throw new Error('native DataDictionary.fromString is unavailable');
+        }
+        return new DataDictionary(handle);
+    }
+    /** @internal Wrap an existing native handle. */
+    static fromNative(handle) {
+        return new DataDictionary(handle);
+    }
+    /** @internal The native handle backing this dictionary. */
+    get nativeHandle() {
+        return this.#native;
+    }
+    /**
+     * Validate a message against this dictionary.
+     *
+     * @param msg The message to validate.
+     * @param bodyOnly When `true`, validate only as the *application* dictionary
+     *   (QuickFIX's `validate(msg, true)`): the BeginString version check and the
+     *   tag/value validation of the header and trailer fields are skipped. It is
+     *   not a check of a draft body: `BeginString` and `MsgType` must be set, and
+     *   every field the dictionary requires, header and trailer included (e.g.
+     *   `BodyLength`, `CheckSum`), must be present. Defaults to `false`.
+     * @throws A `QuickFixError` on any validation failure (e.g.
+     *   `fixErrorName: 'InvalidMessage'` / `'RequiredTagMissing'` /
+     *   `'IncorrectTagValue'` / `'UnsupportedVersion'`).
+     */
+    validate(msg, bodyOnly = false) {
+        this.#native.validate(msg.nativeHandle, bodyOnly);
+    }
+    /** The BeginString the spec declares (e.g. `'FIX.4.4'`), or `''` if it has none. */
+    getVersion() {
+        return this.#native.getVersion();
+    }
+    /** The name of a field tag (e.g. `35` → `'MsgType'`), or `undefined` if the spec does not define it. */
+    getFieldName(tag) {
+        return this.#native.getFieldName(tag);
+    }
+    /** The tag of a field name (e.g. `'MsgType'` → `35`), or `undefined` if the spec does not define it. */
+    getFieldTag(name) {
+        return this.#native.getFieldTag(name);
+    }
+    /** Whether the spec defines a field with this tag. */
+    isField(tag) {
+        return this.#native.isField(tag);
+    }
+    /** Whether the spec defines a message with this MsgType (e.g. `'D'`). */
+    isMsgType(msgType) {
+        return this.#native.isMsgType(msgType);
+    }
+}

package/dist/esm/engine.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared implementation for {@link Initiator} and {@link Acceptor}.
+ *
+ * Both are thin subclasses of {@link Engine} that differ only in which native
+ * constructor they instantiate.
+ */
+import { EventEmitter } from 'node:events';
+import { type NativeEngineConstructor } from './native.js';
+import { Message } from './message.js';
+import { SessionID } from './session-id.js';
+import { Session } from './session.js';
+import type { ApplicationHandlers } from './application.js';
+import type { SessionSettings } from './session-settings.js';
+/** Options for constructing an {@link Initiator} or {@link Acceptor}. */
+export interface EngineOptions {
+    /** Parsed session settings ({@link SessionSettings.fromString}/`fromFile`). */
+    settings: SessionSettings;
+    /**
+     * Synchronous application callbacks. These may mutate outbound messages and
+     * throw to reject inbound ones (see {@link ApplicationHandlers}).
+     */
+    handlers?: ApplicationHandlers;
+    /** Message-store factory. Defaults to the engine's default (`'file'`). */
+    store?: 'file' | 'memory';
+    /** Log factory. Defaults to the engine's default. */
+    log?: 'screen' | 'file' | 'none';
+}
+/**
+ * Events emitted (observe-only) by an {@link Engine}. Each mirrors a callback in
+ * {@link ApplicationHandlers} but CANNOT mutate or reject — do that via
+ * `handlers`.
+ */
+export interface EngineEvents {
+    create: [sessionID: SessionID];
+    logon: [sessionID: SessionID];
+    logout: [sessionID: SessionID];
+    toAdmin: [message: Message, sessionID: SessionID];
+    fromAdmin: [message: Message, sessionID: SessionID];
+    toApp: [message: Message, sessionID: SessionID];
+    fromApp: [message: Message, sessionID: SessionID];
+}
+/**
+ * Base class for the FIX session engines.
+ *
+ * Extends Node's {@link EventEmitter}: in addition to invoking your `handlers`,
+ * the engine emits an observe-only event for each callback
+ * (`'create' | 'logon' | 'logout' | 'toAdmin' | 'fromAdmin' | 'toApp' | 'fromApp'`).
+ *
+ * **Important:** mutation of outbound messages and rejection of inbound ones
+ * MUST be done in `handlers` (which run synchronously and can throw); event
+ * listeners run after and cannot affect the message or reject it.
+ */
+export declare abstract class Engine extends EventEmitter {
+    #private;
+    /**
+     * @param Native The native engine constructor (`InitiatorWrap`/`AcceptorWrap`).
+     * @param options Engine options.
+     */
+    protected constructor(Native: NativeEngineConstructor, options: EngineOptions);
+    /**
+     * Start the engine (begins connecting / listening).
+     *
+     * Runs off the main thread, so the Node.js event loop stays free to service
+     * the application callbacks/events the engine fires. The returned Promise
+     * resolves once startup completes.
+     *
+     * @example
+     * ```ts
+     * await initiator.start();
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the engine.
+     *
+     * Runs off the main thread and resolves once shutdown completes, keeping the
+     * event loop free for any in-flight callbacks. Once it settles the engine's
+     * sessions are destroyed. A `stop()` called while another is still in flight
+     * (even from a `'logout'` listener that stop fired) returns the same Promise,
+     * so it too settles only once the sessions are gone; the first call's
+     * `force` applies to both.
+     *
+     * @param force When `true`, aborts immediately instead of draining gracefully.
+     *
+     * @example
+     * ```ts
+     * await initiator.stop();
+     * ```
+     */
+    stop(force?: boolean): Promise<void>;
+    /**
+     * Whether a session is logged on.
+     *
+     * With no argument: `true` if **any** of this engine's sessions is logged on.
+     * With a {@link SessionID}: `true` only if that session belongs to this engine
+     * and is logged on (`false`, not an error, for a foreign id). Always `false`
+     * before {@link Engine.start} and once {@link Engine.stop} has settled; while
+     * a graceful stop is still in progress it reports the live state.
+     *
+     * @throws {TypeError} if `sessionID` is given but is not a {@link SessionID}
+     *   (it does not fall back to the engine-wide form).
+     */
+    isLoggedOn(sessionID?: SessionID): boolean;
+    /**
+     * The ids of the sessions this engine was configured with (every `[SESSION]`
+     * in its settings). Stable for the engine's lifetime, including after
+     * {@link Engine.stop}.
+     */
+    getSessions(): SessionID[];
+    /**
+     * A handle on one of this engine's sessions.
+     *
+     * @returns The {@link Session}, or `undefined` if `sessionID` is not one of
+     *   this engine's sessions or {@link Engine.stop} has settled (that destroys
+     *   its sessions). While a stop is still in progress the sessions are alive,
+     *   so a `'logout'` listener can still read e.g. the final sequence numbers.
+     *
+     * @example
+     * ```ts
+     * initiator.on('logon', (id) => {
+     *   const session = initiator.getSession(id)!;
+     *   console.log('next seq', session.getExpectedSenderNum());
+     * });
+     * ```
+     */
+    getSession(sessionID: SessionID): Session | undefined;
+    /**
+     * Keep the Node.js event loop alive while the engine is running (default once
+     * started). Pair with {@link Engine.unref} to let a short script exit.
+     */
+    ref(): void;
+    /** Allow the process to exit even while the engine is running. */
+    unref(): void;
+}
+export interface Engine {
+    /** Register a listener for an engine event (typed per {@link EngineEvents}). */
+    on<E extends keyof EngineEvents>(event: E, listener: (...args: EngineEvents[E]) => void): this;
+    /** Register a one-shot listener for an engine event. */
+    once<E extends keyof EngineEvents>(event: E, listener: (...args: EngineEvents[E]) => void): this;
+    /** Alias of {@link Engine.on}. */
+    addListener<E extends keyof EngineEvents>(event: E, listener: (...args: EngineEvents[E]) => void): this;
+    /** Remove a previously registered listener. */
+    off<E extends keyof EngineEvents>(event: E, listener: (...args: EngineEvents[E]) => void): this;
+    /** Alias of {@link Engine.off}. */
+    removeListener<E extends keyof EngineEvents>(event: E, listener: (...args: EngineEvents[E]) => void): this;
+    /** Remove all listeners (optionally for a single event). */
+    removeAllListeners<E extends keyof EngineEvents>(event?: E): this;
+    /** Emit an engine event with its typed arguments. */
+    emit<E extends keyof EngineEvents>(event: E, ...args: EngineEvents[E]): boolean;
+    /** List the listeners registered for an event. */
+    listeners<E extends keyof EngineEvents>(event: E): Array<(...args: EngineEvents[E]) => void>;
+}

package/dist/esm/engine.js

@@ -0,0 +1,179 @@
+/**
+ * Shared implementation for {@link Initiator} and {@link Acceptor}.
+ *
+ * Both are thin subclasses of {@link Engine} that differ only in which native
+ * constructor they instantiate.
+ */
+import { EventEmitter } from 'node:events';
+import { Message } from './message.js';
+import { SessionID, toNativeSessionID } from './session-id.js';
+import { Session } from './session.js';
+/**
+ * Base class for the FIX session engines.
+ *
+ * Extends Node's {@link EventEmitter}: in addition to invoking your `handlers`,
+ * the engine emits an observe-only event for each callback
+ * (`'create' | 'logon' | 'logout' | 'toAdmin' | 'fromAdmin' | 'toApp' | 'fromApp'`).
+ *
+ * **Important:** mutation of outbound messages and rejection of inbound ones
+ * MUST be done in `handlers` (which run synchronously and can throw); event
+ * listeners run after and cannot affect the message or reject it.
+ */
+export class Engine extends EventEmitter {
+    /** @internal Underlying native engine handle. */
+    #native;
+    /**
+     * @param Native The native engine constructor (`InitiatorWrap`/`AcceptorWrap`).
+     * @param options Engine options.
+     */
+    constructor(Native, options) {
+        super();
+        const userHandlers = options.handlers ?? {};
+        // Bridge native handlers: wrap native handles into TS classes, invoke the
+        // user's handler (preserving mutate/throw semantics — exceptions propagate
+        // to the native bridge, which maps them to FIX exceptions), then emit the
+        // observe-only event.
+        const nativeHandlers = {
+            onCreate: (id) => {
+                const sid = SessionID.fromNative(id);
+                userHandlers.onCreate?.(sid);
+                this.emit('create', sid);
+            },
+            onLogon: (id) => {
+                const sid = SessionID.fromNative(id);
+                userHandlers.onLogon?.(sid);
+                this.emit('logon', sid);
+            },
+            onLogout: (id) => {
+                const sid = SessionID.fromNative(id);
+                userHandlers.onLogout?.(sid);
+                this.emit('logout', sid);
+            },
+            toAdmin: (m, id) => {
+                const msg = Message.fromNative(m);
+                const sid = SessionID.fromNative(id);
+                // Handler may mutate `msg` (writes go straight to the native handle).
+                userHandlers.toAdmin?.(msg, sid);
+                this.emit('toAdmin', msg, sid);
+            },
+            toApp: (m, id) => {
+                const msg = Message.fromNative(m);
+                const sid = SessionID.fromNative(id);
+                // May mutate or throw FixReject('DoNotSend') — do NOT swallow.
+                userHandlers.toApp?.(msg, sid);
+                this.emit('toApp', msg, sid);
+            },
+            fromAdmin: (m, id) => {
+                const msg = Message.fromNative(m);
+                const sid = SessionID.fromNative(id);
+                // May throw FixReject('RejectLogon', ...) — do NOT swallow.
+                userHandlers.fromAdmin?.(msg, sid);
+                this.emit('fromAdmin', msg, sid);
+            },
+            fromApp: (m, id) => {
+                const msg = Message.fromNative(m);
+                const sid = SessionID.fromNative(id);
+                // May throw FixReject('UnsupportedMessageType', ...) — do NOT swallow.
+                userHandlers.fromApp?.(msg, sid);
+                this.emit('fromApp', msg, sid);
+            },
+        };
+        this.#native = new Native({
+            settings: options.settings.nativeHandle,
+            handlers: nativeHandlers,
+            store: options.store,
+            log: options.log,
+        });
+    }
+    /**
+     * Start the engine (begins connecting / listening).
+     *
+     * Runs off the main thread, so the Node.js event loop stays free to service
+     * the application callbacks/events the engine fires. The returned Promise
+     * resolves once startup completes.
+     *
+     * @example
+     * ```ts
+     * await initiator.start();
+     * ```
+     */
+    start() {
+        return this.#native.start();
+    }
+    /**
+     * Stop the engine.
+     *
+     * Runs off the main thread and resolves once shutdown completes, keeping the
+     * event loop free for any in-flight callbacks. Once it settles the engine's
+     * sessions are destroyed. A `stop()` called while another is still in flight
+     * (even from a `'logout'` listener that stop fired) returns the same Promise,
+     * so it too settles only once the sessions are gone; the first call's
+     * `force` applies to both.
+     *
+     * @param force When `true`, aborts immediately instead of draining gracefully.
+     *
+     * @example
+     * ```ts
+     * await initiator.stop();
+     * ```
+     */
+    stop(force) {
+        return this.#native.stop(force);
+    }
+    /**
+     * Whether a session is logged on.
+     *
+     * With no argument: `true` if **any** of this engine's sessions is logged on.
+     * With a {@link SessionID}: `true` only if that session belongs to this engine
+     * and is logged on (`false`, not an error, for a foreign id). Always `false`
+     * before {@link Engine.start} and once {@link Engine.stop} has settled; while
+     * a graceful stop is still in progress it reports the live state.
+     *
+     * @throws {TypeError} if `sessionID` is given but is not a {@link SessionID}
+     *   (it does not fall back to the engine-wide form).
+     */
+    isLoggedOn(sessionID) {
+        return sessionID === undefined
+            ? this.#native.isLoggedOn()
+            : this.#native.isLoggedOn(toNativeSessionID(sessionID, 'sessionID'));
+    }
+    /**
+     * The ids of the sessions this engine was configured with (every `[SESSION]`
+     * in its settings). Stable for the engine's lifetime, including after
+     * {@link Engine.stop}.
+     */
+    getSessions() {
+        return this.#native.getSessions().map((h) => SessionID.fromNative(h));
+    }
+    /**
+     * A handle on one of this engine's sessions.
+     *
+     * @returns The {@link Session}, or `undefined` if `sessionID` is not one of
+     *   this engine's sessions or {@link Engine.stop} has settled (that destroys
+     *   its sessions). While a stop is still in progress the sessions are alive,
+     *   so a `'logout'` listener can still read e.g. the final sequence numbers.
+     *
+     * @example
+     * ```ts
+     * initiator.on('logon', (id) => {
+     *   const session = initiator.getSession(id)!;
+     *   console.log('next seq', session.getExpectedSenderNum());
+     * });
+     * ```
+     */
+    getSession(sessionID) {
+        const handle = this.#native.getSession(toNativeSessionID(sessionID, 'sessionID'));
+        return handle ? Session.fromNative(handle) : undefined;
+    }
+    /**
+     * Keep the Node.js event loop alive while the engine is running (default once
+     * started). Pair with {@link Engine.unref} to let a short script exit.
+     */
+    ref() {
+        this.#native.ref();
+    }
+    /** Allow the process to exit even while the engine is running. */
+    unref() {
+        this.#native.unref();
+    }
+}