@homaiohq/napi-quickfix 0.0.0-stage → 0.1.0

package/dist/cjs/acceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptor.js","sourceRoot":"","sources":["../../src/acceptor.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,2CAAqC;AACrC,2CAAyD;AAIzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,cAAsB,SAAQ,kBAAM;IAClC,qCAAqC;IACrC,YAAY,OAAsB;QAChC,KAAK,CAAC,kBAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/cjs/application.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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;
+//# sourceMappingURL=application.d.ts.map

package/dist/cjs/application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/application.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,QAAQ,CAAC,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACtC,wCAAwC;IACxC,OAAO,CAAC,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACrC,kDAAkD;IAClD,QAAQ,CAAC,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACvD;;;OAGG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACrD;;;OAGG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACzD;;;OAGG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,aAAa,GACb,wBAAwB,GACxB,qBAAqB,GACrB,mBAAmB,GACnB,eAAe,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,YAAY,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAMjE;CACF;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAE3F"}

package/dist/cjs/application.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixReject = void 0;
+exports.fixReject = fixReject;
+/**
+ * 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');
+ *   },
+ * }
+ * ```
+ */
+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;
+    }
+}
+exports.FixReject = FixReject;
+/**
+ * Convenience factory for a {@link FixReject}. Equivalent to
+ * `new FixReject(kind, message, detail)`.
+ *
+ * @example
+ * ```ts
+ * throw fixReject('DoNotSend');
+ * ```
+ */
+function fixReject(kind, message, detail) {
+    return new FixReject(kind, message, detail);
+}
+//# sourceMappingURL=application.js.map

package/dist/cjs/application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.js","sourceRoot":"","sources":["../../src/application.ts"],"names":[],"mappings":";;;;AA2EA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAuB,SAAQ,KAAK;IAClC;;;OAGG;IACM,QAAQ,CAAgB;IACjC;;;;OAIG;IACM,YAAY,CAAgB;IACrC,qEAAqE;IAC5D,MAAM,CAAU;IAEzB,YAAY,IAAmB,EAAE,OAAgB,EAAE,MAAe;QAChE,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;;AAED;;;;;;;;GAQG;AACH,mBAA0B,IAAmB,EAAE,OAAgB,EAAE,MAAe;IAC9E,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC9C,CAAC"}

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

@@ -0,0 +1,49 @@
+/**
+ * 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
+ * ```
+ */
+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.
+     * @throws A `QuickFixError` on any validation failure (e.g.
+     *   `fixError: 'InvalidMessage'` / `'FieldNotFound'` / `'IncorrectTagValue'`).
+     */
+    validate(msg: Message): void;
+}
+//# sourceMappingURL=data-dictionary.d.ts.map

package/dist/cjs/data-dictionary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-dictionary.d.ts","sourceRoot":"","sources":["../../src/data-dictionary.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAU,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;;IAIzB,yFAAyF;IACzF,OAAO,eAEN;IAED;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAU/C;IAED;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAQ7C;IAED,gDAAgD;IAChD,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAE9D;IAED,2DAA2D;IAC3D,IAAI,YAAY,IAAI,oBAAoB,CAEvC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAE3B;CACF"}

package/dist/cjs/data-dictionary.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataDictionary = void 0;
+/**
+ * Ergonomic wrapper around the native `FIX::DataDictionary`.
+ */
+const native_js_1 = require("./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
+ * ```
+ */
+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_js_1.native.dataDictionaryFromFile?.(xmlPath) ??
+            native_js_1.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_js_1.native.dataDictionaryFromString?.(xml) ??
+            native_js_1.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.
+     * @throws A `QuickFixError` on any validation failure (e.g.
+     *   `fixError: 'InvalidMessage'` / `'FieldNotFound'` / `'IncorrectTagValue'`).
+     */
+    validate(msg) {
+        this.#native.validate(msg.nativeHandle);
+    }
+}
+exports.DataDictionary = DataDictionary;
+//# sourceMappingURL=data-dictionary.js.map

package/dist/cjs/data-dictionary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-dictionary.js","sourceRoot":"","sources":["../../src/data-dictionary.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,2CAAgE;AAGhE;;;;;;;;;;;GAWG;AACH;IACE,0CAA0C;IACjC,OAAO,CAAuB;IAEvC,yFAAyF;IACzF,YAAoB,MAA4B;QAC9C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAe;QAC7B,oEAAoE;QACpE,uDAAuD;QACvD,MAAM,MAAM,GACV,kBAAM,CAAC,sBAAsB,EAAE,CAAC,OAAO,CAAC;YACxC,kBAAM,CAAC,kBAAkB,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CAAC,GAAW;QAC3B,MAAM,MAAM,GACV,kBAAM,CAAC,wBAAwB,EAAE,CAAC,GAAG,CAAC;YACtC,kBAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,gDAAgD;IAChD,MAAM,CAAC,UAAU,CAAC,MAA4B;QAC5C,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,2DAA2D;IAC3D,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,GAAY;QACnB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC1C,CAAC;CACF"}

package/dist/cjs/engine.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 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.
+     *
+     * @param force When `true`, aborts immediately instead of draining gracefully.
+     *
+     * @example
+     * ```ts
+     * await initiator.stop();
+     * ```
+     */
+    stop(force?: boolean): Promise<void>;
+    /** Whether any session is currently logged on. */
+    isLoggedOn(): boolean;
+    /**
+     * 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>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/cjs/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAEL,KAAK,uBAAuB,EAI7B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC/B,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC/B,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACpD,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAChD,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;CACnD;AAED;;;;;;;;;;GAUG;AACH,8BAAsB,MAAO,SAAQ,YAAY;;IAI/C;;;OAGG;IACH,SAAS,aAAa,MAAM,EAAE,uBAAuB,EAAE,OAAO,EAAE,aAAa,EA6D5E;IAED;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAErB;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnC;IAED,kDAAkD;IAClD,UAAU,IAAI,OAAO,CAEpB;IAED;;;OAGG;IACH,GAAG,IAAI,IAAI,CAEV;IAED,kEAAkE;IAClE,KAAK,IAAI,IAAI,CAEZ;CACF;AAgBD,MAAM,WAAW,MAAM;IACrB,gFAAgF;IAChF,EAAE,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/F,wDAAwD;IACxD,IAAI,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACjG,kCAAkC;IAClC,WAAW,CAAC,CAAC,SAAS,MAAM,YAAY,EACtC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GAC3C,IAAI,CAAC;IACR,+CAA+C;IAC/C,GAAG,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IAChG,mCAAmC;IACnC,cAAc,CAAC,CAAC,SAAS,MAAM,YAAY,EACzC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GAC3C,IAAI,CAAC;IACR,4DAA4D;IAC5D,kBAAkB,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAClE,qDAAqD;IACrD,IAAI,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAChF,kDAAkD;IAClD,SAAS,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;CAC9F"}

package/dist/cjs/engine.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Engine = void 0;
+/**
+ * Shared implementation for {@link Initiator} and {@link Acceptor}.
+ *
+ * Both are thin subclasses of {@link Engine} that differ only in which native
+ * constructor they instantiate.
+ */
+const node_events_1 = require("node:events");
+const message_js_1 = require("./message.js");
+const session_id_js_1 = require("./session-id.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.
+ */
+class Engine extends node_events_1.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 = session_id_js_1.SessionID.fromNative(id);
+                userHandlers.onCreate?.(sid);
+                this.emit('create', sid);
+            },
+            onLogon: (id) => {
+                const sid = session_id_js_1.SessionID.fromNative(id);
+                userHandlers.onLogon?.(sid);
+                this.emit('logon', sid);
+            },
+            onLogout: (id) => {
+                const sid = session_id_js_1.SessionID.fromNative(id);
+                userHandlers.onLogout?.(sid);
+                this.emit('logout', sid);
+            },
+            toAdmin: (m, id) => {
+                const msg = message_js_1.Message.fromNative(m);
+                const sid = session_id_js_1.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_js_1.Message.fromNative(m);
+                const sid = session_id_js_1.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_js_1.Message.fromNative(m);
+                const sid = session_id_js_1.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_js_1.Message.fromNative(m);
+                const sid = session_id_js_1.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.
+     *
+     * @param force When `true`, aborts immediately instead of draining gracefully.
+     *
+     * @example
+     * ```ts
+     * await initiator.stop();
+     * ```
+     */
+    stop(force) {
+        return this.#native.stop(force);
+    }
+    /** Whether any session is currently logged on. */
+    isLoggedOn() {
+        return this.#native.isLoggedOn();
+    }
+    /**
+     * 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();
+    }
+}
+exports.Engine = Engine;
+//# sourceMappingURL=engine.js.map

package/dist/cjs/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/cjs/enums.d.ts

@@ -0,0 +1,22 @@
+export { FIELD, type FieldName } from './generated/fields.js';
+/** A single group of FIX constants (name → value). */
+export type EnumGroup = Readonly<Record<string, number | string>>;
+/** The full, frozen tree of FIX constants. */
+export type Enums = Readonly<Record<string, EnumGroup>>;
+/**
+ * The complete tree of FIX constants (frozen), e.g. `enums.FIELD.MsgType`,
+ * `enums.MsgType.Logon`, `enums.Side.Buy`.
+ *
+ * `enums.FIELD` is the same table as {@link FIELD}; the value groups come from
+ * the native engine.
+ */
+export declare const enums: Enums;
+/** A group of numeric FIX constants (name → number). */
+export type NumericEnumGroup = Readonly<Record<string, number>>;
+/** A group of string-valued FIX constants (name → string), e.g. {@link MsgType}. */
+export type StringEnumGroup = Readonly<Record<string, string>>;
+/** MsgType values (strings), e.g. `MsgType.Logon === 'A'`. */
+export declare const MsgType: StringEnumGroup;
+/** Side values (strings), e.g. `Side.Buy === '1'`. */
+export declare const Side: StringEnumGroup;
+//# sourceMappingURL=enums.d.ts.map

package/dist/cjs/enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/enums.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE9D,sDAAsD;AACtD,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;AAElE,8CAA8C;AAC9C,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAYxD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,KAEnB,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhE,oFAAoF;AACpF,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,OAAO,EAAE,eAAyE,CAAC;AAEhG,sDAAsD;AACtD,eAAO,MAAM,IAAI,EAAE,eAAsE,CAAC"}