@homaiohq/napi-quickfix 0.1.0 → 0.3.0

package/dist/cjs/tls-tunnel.d.ts

@@ -0,0 +1,143 @@
+/**
+ * In-process TLS tunnel for initiators: the stunnel client model.
+ *
+ * QuickFIX is built without its OpenSSL-based `SSLSocketInitiator` (see
+ * CMakeLists.txt), so TLS is terminated in Node instead: the tunnel listens on
+ * a loopback port, the plain `FIX::SocketInitiator` connects to it (point
+ * `SocketConnectHost`/`SocketConnectPort` at {@link TlsTunnel.host} /
+ * {@link TlsTunnel.port}), and every accepted connection is carried to the real
+ * counterparty over `tls.connect`.
+ */
+import { EventEmitter } from 'node:events';
+import { type Server } from 'node:net';
+import { type CipherNameAndProtocol, type ConnectionOptions, type PeerCertificate } from 'node:tls';
+/** Options for {@link createTlsTunnel}. */
+export interface TlsTunnelOptions {
+    /** Host name or IP of the counterparty's TLS endpoint. */
+    host: string;
+    /** Port of the counterparty's TLS endpoint. */
+    port: number;
+    /**
+     * Passed to `tls.connect()` for every connection (CA, client certificate for
+     * mTLS, `minVersion`, ciphers, ...). `servername` (SNI, and the name the
+     * server certificate is checked against) defaults to `host` unless `host` is
+     * an IP address.
+     */
+    tls?: Omit<ConnectionOptions, 'host' | 'port' | 'socket' | 'path'>;
+    /**
+     * Loopback port to listen on. Defaults to `0`, an ephemeral port read back
+     * from {@link TlsTunnel.port}. Set it to point a static `.cfg` file at the
+     * tunnel, like stunnel's `accept = 127.0.0.1:<port>`.
+     */
+    localPort?: number;
+}
+/** Details of an established TLS connection, emitted as `'secureConnect'`. */
+export interface TlsTunnelSecureConnectInfo {
+    /** Whether the server certificate was verified against the trusted CAs. */
+    authorized: boolean;
+    /**
+     * Why verification failed, as the OpenSSL verification code (e.g.
+     * `'UNABLE_TO_VERIFY_LEAF_SIGNATURE'`, the `code` a `'tlsError'` carries
+     * otherwise). Only reachable with `rejectUnauthorized: false`.
+     */
+    authorizationError?: string;
+    /** Negotiated protocol, e.g. `'TLSv1.3'`. */
+    protocol: string | null;
+    /** Negotiated cipher. */
+    cipher: CipherNameAndProtocol;
+    /** The server's certificate (an empty object if it sent none). */
+    peerCertificate: PeerCertificate;
+}
+/**
+ * Events emitted by a {@link TlsTunnel}. There is deliberately no `'error'`
+ * event: connection failures are reported as `'tlsError'`, so a tunnel without
+ * listeners never crashes the process.
+ */
+export interface TlsTunnelEvents {
+    /** A connection to the counterparty completed its TLS handshake. */
+    secureConnect: [info: TlsTunnelSecureConnectInfo];
+    /**
+     * A connection to the counterparty failed (DNS, TCP, handshake, certificate
+     * verification, `tls` options `tls.connect` rejects) or broke. The
+     * initiator's loopback connection is closed with it, so QuickFIX reconnects
+     * after its `ReconnectInterval`. Also emitted when the loopback server fails
+     * to accept a connection (e.g. `EMFILE`).
+     */
+    tlsError: [error: Error];
+}
+/**
+ * A running TLS tunnel, created by {@link createTlsTunnel}.
+ *
+ * Its handles are unref'd: the tunnel alone never keeps the process alive (a
+ * started engine does). Close it after the engine has stopped, so a graceful
+ * Logout still reaches the counterparty.
+ */
+export declare class TlsTunnel extends EventEmitter {
+    #private;
+    /** Loopback address the tunnel listens on (`SocketConnectHost`). */
+    readonly host = "127.0.0.1";
+    /** Loopback port the tunnel listens on (`SocketConnectPort`). */
+    readonly port: number;
+    /** The counterparty's TLS endpoint. */
+    readonly remote: {
+        readonly host: string;
+        readonly port: number;
+    };
+    /** @internal Use {@link createTlsTunnel}. */
+    constructor(server: Server, port: number, options: TlsTunnelOptions);
+    /**
+     * Stop listening and destroy every live connection. Idempotent: later calls
+     * return the same Promise.
+     */
+    close(): Promise<void>;
+    /** Same as {@link TlsTunnel.close}; enables `await using tunnel = ...`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Open a TLS tunnel to `options.host`:`options.port` and resolve once it
+ * listens on a loopback port.
+ *
+ * @example
+ * ```ts
+ * const tunnel = await createTlsTunnel({
+ *   host: 'fix.broker.com',
+ *   port: 9443,
+ *   tls: { ca: readFileSync('broker-ca.pem') },
+ * });
+ * tunnel.on('tlsError', (err) => console.error('TLS:', err.message));
+ * const settings = SessionSettings.fromString(`
+ * [DEFAULT]
+ * ConnectionType=initiator
+ * SocketConnectHost=${tunnel.host}
+ * SocketConnectPort=${tunnel.port}
+ * ...`);
+ * const initiator = new Initiator({ settings, handlers });
+ * await initiator.start();
+ * // ... later: engine first, so the Logout still crosses the tunnel
+ * await initiator.stop();
+ * await tunnel.close();
+ * ```
+ *
+ * @returns A Promise that rejects with a `TypeError` if `host`, `port` or
+ *   `localPort` is invalid, and with the listen error (e.g. `EADDRINUSE` for a
+ *   fixed `localPort` already in use) if the loopback port cannot be bound.
+ */
+export declare function createTlsTunnel(options: TlsTunnelOptions): Promise<TlsTunnel>;
+export interface TlsTunnel {
+    /** Register a listener for a tunnel event (typed per {@link TlsTunnelEvents}). */
+    on<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Register a one-shot listener for a tunnel event. */
+    once<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Alias of {@link TlsTunnel.on}. */
+    addListener<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Remove a previously registered listener. */
+    off<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Alias of {@link TlsTunnel.off}. */
+    removeListener<E extends keyof TlsTunnelEvents>(event: E, listener: (...args: TlsTunnelEvents[E]) => void): this;
+    /** Remove all listeners (optionally for a single event). */
+    removeAllListeners<E extends keyof TlsTunnelEvents>(event?: E): this;
+    /** Emit a tunnel event with its typed arguments. */
+    emit<E extends keyof TlsTunnelEvents>(event: E, ...args: TlsTunnelEvents[E]): boolean;
+    /** List the listeners registered for an event. */
+    listeners<E extends keyof TlsTunnelEvents>(event: E): Array<(...args: TlsTunnelEvents[E]) => void>;
+}

package/dist/cjs/tls-tunnel.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TlsTunnel = void 0;
+exports.createTlsTunnel = createTlsTunnel;
+/**
+ * In-process TLS tunnel for initiators: the stunnel client model.
+ *
+ * QuickFIX is built without its OpenSSL-based `SSLSocketInitiator` (see
+ * CMakeLists.txt), so TLS is terminated in Node instead: the tunnel listens on
+ * a loopback port, the plain `FIX::SocketInitiator` connects to it (point
+ * `SocketConnectHost`/`SocketConnectPort` at {@link TlsTunnel.host} /
+ * {@link TlsTunnel.port}), and every accepted connection is carried to the real
+ * counterparty over `tls.connect`.
+ */
+const node_events_1 = require("node:events");
+const node_net_1 = require("node:net");
+const node_tls_1 = require("node:tls");
+const LOOPBACK = '127.0.0.1';
+/** How long a connection may take to wind down once either side has ended. */
+const DRAIN_TIMEOUT_MS = 5000;
+/**
+ * A running TLS tunnel, created by {@link createTlsTunnel}.
+ *
+ * Its handles are unref'd: the tunnel alone never keeps the process alive (a
+ * started engine does). Close it after the engine has stopped, so a graceful
+ * Logout still reaches the counterparty.
+ */
+class TlsTunnel extends node_events_1.EventEmitter {
+    /** Loopback address the tunnel listens on (`SocketConnectHost`). */
+    host = LOOPBACK;
+    /** Loopback port the tunnel listens on (`SocketConnectPort`). */
+    port;
+    /** The counterparty's TLS endpoint. */
+    remote;
+    #server;
+    #tls;
+    #pairs = new Set();
+    #closing;
+    /** @internal Use {@link createTlsTunnel}. */
+    constructor(server, port, options) {
+        super();
+        this.#server = server;
+        this.port = port;
+        this.remote = Object.freeze({ host: options.host, port: options.port });
+        // `socket` and `path` are excluded by the types only: drop them for JS
+        // callers too, or every connection would go to them instead of host:port.
+        const { socket: _socket, path: _path, ...tls } = (options.tls ?? {});
+        const servername = tls.servername ?? ((0, node_net_1.isIP)(options.host) === 0 ? options.host : undefined);
+        this.#tls = {
+            ...tls,
+            ...(servername === undefined ? {} : { servername }),
+            host: options.host,
+            port: options.port,
+        };
+        server.on('connection', (local) => this.#onConnection(local));
+        // A failed accept() (EMFILE, ENFILE, ...) is emitted on the server: without
+        // a listener it would be thrown.
+        server.on('error', (err) => {
+            if (!this.#closing)
+                this.emit('tlsError', err);
+        });
+    }
+    #onConnection(local) {
+        if (this.#closing) {
+            local.destroy();
+            return;
+        }
+        local.unref();
+        // QuickFIX writes its Logon as soon as it connects: hold it until the
+        // handshake is done and the pipe below takes over. It is read rather than
+        // left in a paused socket, which is not read at all: the engine's EOF or
+        // reset would go unseen, and a handshake completing after the engine gave
+        // up would still deliver its stale Logon.
+        const pending = [];
+        const hold = (chunk) => pending.push(chunk);
+        local.on('data', hold);
+        // tls.connect throws synchronously on options it cannot build a secure
+        // context from (bad PEM, unknown minVersion, ...): report it like any other
+        // connection failure instead of letting it escape the 'connection' handler.
+        let remote;
+        try {
+            remote = (0, node_tls_1.connect)(this.#tls);
+        }
+        catch (err) {
+            local.on('error', () => { });
+            local.destroy();
+            this.emit('tlsError', err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        remote.unref();
+        const pair = { local, remote };
+        this.#pairs.add(pair);
+        // Once piped, a side that ends or closes is wound down gracefully on the
+        // other: it is ended, so the data still queued in the tunnel (a Logout, the
+        // TLS close_notify) is delivered rather than reset, and drained of what it
+        // still receives so it sees its peer's EOF. Anything still open
+        // DRAIN_TIMEOUT_MS after the first EOF is destroyed. Before the handshake
+        // completes there is nothing to deliver: an EOF or close drops both sides,
+        // and QuickFIX reconnects on its own schedule.
+        let piped = false;
+        let open = 2;
+        let drainTimer;
+        const linger = () => {
+            drainTimer ??= setTimeout(() => {
+                local.destroy();
+                remote.destroy();
+            }, DRAIN_TIMEOUT_MS).unref();
+        };
+        const onClose = (closed, other) => () => {
+            if (--open === 0) {
+                clearTimeout(drainTimer);
+                this.#pairs.delete(pair);
+            }
+            else if (!piped) {
+                other.destroy();
+            }
+            else {
+                other.unpipe(closed);
+                other.resume();
+                other.end();
+                linger();
+            }
+        };
+        local.on('error', () => {
+            // ECONNRESET and the like from the engine's side: nothing to report.
+        });
+        remote.on('error', (err) => {
+            if (!this.#closing)
+                this.emit('tlsError', err);
+        });
+        local.once('close', onClose(local, remote));
+        remote.once('close', onClose(remote, local));
+        local.once('end', () => {
+            if (piped) {
+                linger();
+            }
+            else {
+                local.destroy();
+                remote.destroy();
+            }
+        });
+        remote.once('secureConnect', () => {
+            local.setNoDelay(true);
+            remote.setNoDelay(true);
+            // Each side's EOF ends the other. The loopback socket is half-open, so
+            // after QuickFIX's EOF the counterparty's last bytes still reach it; the
+            // TLS socket ends itself on the counterparty's EOF, so what QuickFIX
+            // still sends is discarded (its peer has gone).
+            local.off('data', hold);
+            for (const chunk of pending)
+                remote.write(chunk);
+            pending.length = 0;
+            local.pipe(remote);
+            remote.pipe(local);
+            remote.once('end', () => {
+                local.unpipe(remote);
+                local.resume();
+                linger();
+            });
+            piped = true;
+            // Typed as an Error, but a string code at runtime, and null once the
+            // certificate verified.
+            const authorizationError = remote.authorizationError;
+            this.emit('secureConnect', {
+                authorized: remote.authorized,
+                ...(authorizationError ? { authorizationError } : {}),
+                protocol: remote.getProtocol(),
+                cipher: remote.getCipher(),
+                peerCertificate: remote.getPeerCertificate(),
+            });
+        });
+    }
+    /**
+     * Stop listening and destroy every live connection. Idempotent: later calls
+     * return the same Promise.
+     */
+    close() {
+        this.#closing ??= new Promise((resolve) => {
+            for (const { local, remote } of this.#pairs) {
+                local.destroy();
+                remote.destroy();
+            }
+            this.#pairs.clear();
+            // The only possible error is "not running", which still means closed.
+            this.#server.close(() => resolve());
+        });
+        return this.#closing;
+    }
+    /** Same as {@link TlsTunnel.close}; enables `await using tunnel = ...`. */
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+}
+exports.TlsTunnel = TlsTunnel;
+/**
+ * Open a TLS tunnel to `options.host`:`options.port` and resolve once it
+ * listens on a loopback port.
+ *
+ * @example
+ * ```ts
+ * const tunnel = await createTlsTunnel({
+ *   host: 'fix.broker.com',
+ *   port: 9443,
+ *   tls: { ca: readFileSync('broker-ca.pem') },
+ * });
+ * tunnel.on('tlsError', (err) => console.error('TLS:', err.message));
+ * const settings = SessionSettings.fromString(`
+ * [DEFAULT]
+ * ConnectionType=initiator
+ * SocketConnectHost=${tunnel.host}
+ * SocketConnectPort=${tunnel.port}
+ * ...`);
+ * const initiator = new Initiator({ settings, handlers });
+ * await initiator.start();
+ * // ... later: engine first, so the Logout still crosses the tunnel
+ * await initiator.stop();
+ * await tunnel.close();
+ * ```
+ *
+ * @returns A Promise that rejects with a `TypeError` if `host`, `port` or
+ *   `localPort` is invalid, and with the listen error (e.g. `EADDRINUSE` for a
+ *   fixed `localPort` already in use) if the loopback port cannot be bound.
+ */
+async function createTlsTunnel(options) {
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError('createTlsTunnel({ host, port, tls?, localPort? })');
+    }
+    if (typeof options.host !== 'string' || options.host === '') {
+        throw new TypeError('host must be a non-empty string');
+    }
+    if (!isPort(options.port, 1)) {
+        throw new TypeError('port must be an integer from 1 to 65535');
+    }
+    const localPort = options.localPort ?? 0;
+    if (!isPort(localPort, 0)) {
+        throw new TypeError('localPort must be an integer from 0 to 65535');
+    }
+    // Half-open, so QuickFIX's EOF does not end the loopback socket before the
+    // counterparty's last bytes have crossed it (see #onConnection).
+    const server = (0, node_net_1.createServer)({ allowHalfOpen: true });
+    await new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(localPort, LOOPBACK);
+    });
+    server.unref();
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : localPort;
+    return new TlsTunnel(server, port, options);
+}
+function isPort(value, min) {
+    return Number.isInteger(value) && value >= min && value <= 65535;
+}

package/dist/esm/acceptor.d.ts

@@ -27,4 +27,3 @@ export declare class Acceptor extends Engine {
     /** @param options Engine options. */
     constructor(options: EngineOptions);
 }
-//# sourceMappingURL=acceptor.d.ts.map

package/dist/esm/acceptor.js

@@ -32,4 +32,3 @@ export class Acceptor extends Engine {
         super(native.AcceptorWrap, options);
     }
 }
-//# sourceMappingURL=acceptor.js.map

package/dist/esm/application.d.ts

@@ -113,4 +113,3 @@ export declare class FixReject extends Error {
  * ```
  */
 export declare function fixReject(kind: FixRejectKind, message?: string, detail?: string): FixReject;
-//# sourceMappingURL=application.d.ts.map

package/dist/esm/application.js

@@ -55,4 +55,3 @@ export class FixReject extends Error {
 export function fixReject(kind, message, detail) {
     return new FixReject(kind, message, detail);
 }
-//# sourceMappingURL=application.js.map

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

@@ -13,6 +13,8 @@ import type { Message } from './message.js';
  * ```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 {
@@ -41,9 +43,25 @@ export declare class DataDictionary {
      * 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.
-     *   `fixError: 'InvalidMessage'` / `'FieldNotFound'` / `'IncorrectTagValue'`).
+     *   `fixErrorName: 'InvalidMessage'` / `'RequiredTagMissing'` /
+     *   `'IncorrectTagValue'` / `'UnsupportedVersion'`).
      */
-    validate(msg: Message): void;
+    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;
 }
-//# sourceMappingURL=data-dictionary.d.ts.map

package/dist/esm/data-dictionary.js

@@ -12,6 +12,8 @@ import { native } from './native.js';
  * ```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 {
@@ -63,11 +65,37 @@ export class DataDictionary {
      * 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.
-     *   `fixError: 'InvalidMessage'` / `'FieldNotFound'` / `'IncorrectTagValue'`).
+     *   `fixErrorName: 'InvalidMessage'` / `'RequiredTagMissing'` /
+     *   `'IncorrectTagValue'` / `'UnsupportedVersion'`).
      */
-    validate(msg) {
-        this.#native.validate(msg.nativeHandle);
+    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);
     }
 }
-//# sourceMappingURL=data-dictionary.js.map

package/dist/esm/engine.d.ts

@@ -8,6 +8,7 @@ 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}. */
@@ -73,7 +74,11 @@ export declare abstract class Engine extends EventEmitter {
      * Stop the engine.
      *
      * Runs off the main thread and resolves once shutdown completes, keeping the
-     * event loop free for any in-flight callbacks.
+     * 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.
      *
@@ -83,8 +88,42 @@ export declare abstract class Engine extends EventEmitter {
      * ```
      */
     stop(force?: boolean): Promise<void>;
-    /** Whether any session is currently logged on. */
-    isLoggedOn(): boolean;
+    /**
+     * 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.
@@ -111,4 +150,3 @@ export interface Engine {
     /** List the listeners registered for an event. */
     listeners<E extends keyof EngineEvents>(event: E): Array<(...args: EngineEvents[E]) => void>;
 }
-//# sourceMappingURL=engine.d.ts.map

package/dist/esm/engine.js

@@ -6,7 +6,8 @@
  */
 import { EventEmitter } from 'node:events';
 import { Message } from './message.js';
-import { SessionID } from './session-id.js';
+import { SessionID, toNativeSessionID } from './session-id.js';
+import { Session } from './session.js';
 /**
  * Base class for the FIX session engines.
  *
@@ -103,7 +104,11 @@ export class Engine extends EventEmitter {
      * Stop the engine.
      *
      * Runs off the main thread and resolves once shutdown completes, keeping the
-     * event loop free for any in-flight callbacks.
+     * 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.
      *
@@ -115,9 +120,50 @@ export class Engine extends EventEmitter {
     stop(force) {
         return this.#native.stop(force);
     }
-    /** Whether any session is currently logged on. */
-    isLoggedOn() {
-        return this.#native.isLoggedOn();
+    /**
+     * 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
@@ -131,4 +177,3 @@ export class Engine extends EventEmitter {
         this.#native.unref();
     }
 }
-//# sourceMappingURL=engine.js.map