@homaiohq/napi-quickfix 0.1.0 → 0.3.0

package/dist/esm/message.js

@@ -2,11 +2,15 @@
  * Ergonomic wrapper around the native `FIX::Message`.
  */
 import { native } from './native.js';
+import { Group } from './group.js';
+import { formatFieldValue } from './field-value.js';
 /**
  * A FIX message.
  *
  * Field values are accepted as `string | number` on input (numbers are
- * stringified, since FIX is string-on-the-wire) and always returned as `string`.
+ * stringified, since FIX is string-on-the-wire, without exponent notation:
+ * `1e-7` is written `0.0000001`) and always returned as `string`. `NaN` and
+ * `±Infinity` throw a `RangeError`.
  *
  * @example
  * ```ts
@@ -19,6 +23,12 @@ import { native } from './native.js';
  *
  * const parsed = Message.parse(msg.toString());
  * console.log(parsed.getMsgType());
+ *
+ * // Repeating groups: build entries with Group, read them back by 1-based index.
+ * msg.addGroup(new Group(FIELD.NoPartyIDs, FIELD.PartyID).setField(FIELD.PartyID, 'TRADER-1'));
+ * const dd = DataDictionary.fromFile('FIX44.xml');
+ * const withGroups = Message.parse(msg.toString(), { dictionary: dd });
+ * withGroups.getGroup(1, FIELD.NoPartyIDs).getField(FIELD.PartyID); // 'TRADER-1'
  * ```
  */
 export class Message {
@@ -40,7 +50,9 @@ export class Message {
             this.#native = new native.MessageWrap();
         }
         else if (typeof raw === 'string') {
-            this.#native = new native.MessageWrap(raw, opts?.validate ?? false);
+            const sessionDD = opts?.sessionDictionary ?? opts?.dictionary;
+            const appDD = opts?.applicationDictionary ?? opts?.dictionary;
+            this.#native = new native.MessageWrap(raw, opts?.validate ?? false, sessionDD?.nativeHandle ?? null, appDD?.nativeHandle ?? null);
         }
         else {
             // Adopt an existing native handle (bridge path).
@@ -50,8 +62,18 @@ export class Message {
     /**
      * Parse a raw FIX wire string into a {@link Message}.
      *
+     * Pass a `dictionary` to parse repeating groups structurally; without one
+     * the parse is flat (see {@link MessageParseOptions}).
+     *
      * @param raw Raw FIX wire string (SOH-delimited).
      * @param opts Optional parse options.
+     *
+     * @example
+     * ```ts
+     * const dd = DataDictionary.fromFile('./spec/FIX44.xml');
+     * const msg = Message.parse(raw, { dictionary: dd });
+     * msg.getGroup(1, FIELD.NoPartyIDs).getField(FIELD.PartyID);
+     * ```
      */
     static parse(raw, opts) {
         return new Message(raw, opts);
@@ -65,17 +87,133 @@ export class Message {
         return this.#native;
     }
     /**
-     * Read a body field by tag.
-     * @throws A `QuickFixError` (`fixError: 'FieldNotFound'`) if absent.
+     * Read a field by tag. Standard header/trailer tags (`MsgType`,
+     * `SenderCompID`, `CheckSum`, ...) are read from their section, and so are
+     * the header/trailer fields of the session dictionary the message was
+     * parsed with (`sessionDictionary` / `dictionary`) or delivered with (a
+     * message handed to an engine handler). Any other tag is read from the body,
+     * or from the header or trailer if that is where it is.
+     * @throws A `QuickFixError` (`fixErrorName: 'FieldNotFound'`) if absent.
      */
     getField(tag) {
         return this.#native.getField(tag);
     }
-    /** Set a body field. Returns `this` for chaining. */
+    /**
+     * Set a field. Standard header/trailer tags and the session dictionary's
+     * header/trailer fields auto-route to their section (see
+     * {@link Message.getField}). Any other tag is updated in place if the header
+     * or trailer already holds it; otherwise it goes to the body. On a message
+     * without a session dictionary (built with `new Message()`), put a new
+     * custom header field in the header with {@link Message.setHeaderField}.
+     * Returns `this` for chaining.
+     */
     setField(tag, value) {
-        this.#native.setField(tag, String(value));
+        this.#native.setField(tag, formatFieldValue(value));
+        return this;
+    }
+    /** Whether a field is present (same auto-routing as {@link Message.getField}). */
+    isSetField(tag) {
+        return this.#native.isSetField(tag);
+    }
+    /** Remove a field (no-op if absent; same auto-routing). Returns `this` for chaining. */
+    removeField(tag) {
+        this.#native.removeField(tag);
+        return this;
+    }
+    /** Read a field by tag, or `undefined` if absent (same auto-routing). */
+    getFieldIfSet(tag) {
+        return this.#native.getFieldIfSet(tag);
+    }
+    /** Whether the header, body and trailer have no fields of their own. */
+    isEmpty() {
+        return this.#native.isEmpty();
+    }
+    /** The number of body fields, including every field of every group entry. */
+    totalFields() {
+        return this.#native.totalFields();
+    }
+    /** Remove every header, body and trailer field and group. Returns `this` for chaining. */
+    clear() {
+        this.#native.clear();
+        return this;
+    }
+    /** The body's own fields, in wire order, as `[tag, value]` pairs (group entries excluded). */
+    fields() {
+        return this.#native.fields();
+    }
+    /** The header fields, in wire order, as `[tag, value]` pairs. */
+    headerFields() {
+        return this.#native.headerFields();
+    }
+    /** The trailer fields, in wire order, as `[tag, value]` pairs. */
+    trailerFields() {
+        return this.#native.trailerFields();
+    }
+    /** Iterates the body's own fields as `[tag, value]` pairs (see {@link Message.fields}). */
+    [Symbol.iterator]() {
+        return this.fields()[Symbol.iterator]();
+    }
+    /**
+     * Append a repeating-group entry under its count tag (`group.field`). A copy
+     * is stored and the count field is updated. Header groups (e.g. `NoHops`)
+     * auto-route to the header. Returns `this` for chaining.
+     *
+     * @throws `TypeError` when `group.delim` differs from the delimiter of the
+     *   entries already stored under `group.field`.
+     *
+     * @example
+     * ```ts
+     * order.addGroup(new Group(FIELD.NoPartyIDs, FIELD.PartyID).setField(FIELD.PartyID, 'X'));
+     * ```
+     */
+    addGroup(group) {
+        this.#native.addGroup(group.nativeHandle);
+        return this;
+    }
+    /**
+     * A **snapshot copy** of the `index`-th entry (1-based) of the repeating
+     * group `tag`. Mutating the returned {@link Group} does not change this
+     * message; write it back with {@link Message.replaceGroup}.
+     *
+     * Groups exist only on messages built with {@link Message.addGroup} or
+     * parsed with a dictionary, which includes every message the engine hands
+     * to your handlers when the session has `UseDataDictionary=Y` (the
+     * default); a flat parse, or `UseDataDictionary=N`, leaves none.
+     *
+     * @throws A `QuickFixError` (`fixErrorName: 'FieldNotFound'`) when the tag
+     *   has no entries or `index` is out of range.
+     */
+    getGroup(index, tag) {
+        return Group.fromNative(this.#native.getGroup(index, tag));
+    }
+    /**
+     * Overwrite the `index`-th entry (1-based) under `group.field` with a copy of
+     * `group`. Returns `this` for chaining.
+     * @throws A `QuickFixError` (`fixErrorName: 'FieldNotFound'`) when that
+     *   entry does not exist.
+     * @throws `TypeError` when `group.delim` differs from the stored entry's
+     *   delimiter.
+     */
+    replaceGroup(index, group) {
+        this.#native.replaceGroup(index, group.nativeHandle);
+        return this;
+    }
+    removeGroup(a, b) {
+        if (b === undefined) {
+            this.#native.removeGroup(a);
+        }
+        else {
+            this.#native.removeGroup(a, b);
+        }
         return this;
     }
+    hasGroup(a, b) {
+        return b === undefined ? this.#native.hasGroup(a) : this.#native.hasGroup(a, b);
+    }
+    /** The number of entries of the repeating group `tag` (0 if none). */
+    groupCount(tag) {
+        return this.#native.groupCount(tag);
+    }
     /**
      * Read a header field by tag.
      * @throws A `QuickFixError` (`fixError: 'FieldNotFound'`) if absent.
@@ -85,7 +223,7 @@ export class Message {
     }
     /** Set a header field. Returns `this` for chaining. */
     setHeaderField(tag, value) {
-        this.#native.setHeaderField(tag, String(value));
+        this.#native.setHeaderField(tag, formatFieldValue(value));
         return this;
     }
     /**
@@ -97,7 +235,7 @@ export class Message {
     }
     /** Set a trailer field. Returns `this` for chaining. */
     setTrailerField(tag, value) {
-        this.#native.setTrailerField(tag, String(value));
+        this.#native.setTrailerField(tag, formatFieldValue(value));
         return this;
     }
     /** The message type (tag 35), e.g. `'A'` for Logon. */
@@ -153,4 +291,3 @@ export function createMessage(fields) {
 export function parseMessage(raw, opts) {
     return Message.parse(raw, opts);
 }
-//# sourceMappingURL=message.js.map

package/dist/esm/native.d.ts

@@ -1,14 +1,44 @@
 /**
- * Native `FIX::Message` wrapper. FIX is string-on-the-wire, so every field
- * value crosses the boundary as a string.
+ * The field and repeating-group operations every `FIX::FieldMap` exposes.
+ * Shared by the message body and by group entries. Group indices are 1-based,
+ * as in QuickFIX; `getGroup` returns a snapshot copy.
  */
-export interface NativeMessage {
+export interface NativeFieldMap {
     getField(tag: number): string;
     setField(tag: number, value: string): void;
+    isSetField(tag: number): boolean;
+    removeField(tag: number): void;
+    getFieldIfSet(tag: number): string | undefined;
+    /** Own fields plus every field of every nested group entry. */
+    totalFields(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    /** Own fields, in wire order, as `[tag, value]` pairs. */
+    fields(): [number, string][];
+    addGroup(group: NativeGroup): void;
+    /** @throws A {@link QuickFixError} (`FieldNotFound`) when absent / out of range. */
+    getGroup(index: number, tag: number): NativeGroup;
+    /** @throws A {@link QuickFixError} (`FieldNotFound`) when the slot does not exist. */
+    replaceGroup(index: number, group: NativeGroup): void;
+    removeGroup(tag: number): void;
+    removeGroup(index: number, tag: number): void;
+    hasGroup(tag: number): boolean;
+    hasGroup(index: number, tag: number): boolean;
+    groupCount(tag: number): number;
+}
+/**
+ * Native `FIX::Message` wrapper. FIX is string-on-the-wire, so every field
+ * value crosses the boundary as a string. The {@link NativeFieldMap} methods
+ * auto-route well-known header/trailer tags to the right section; `fields()`,
+ * `isEmpty()` and `totalFields()` read the body, `clear()` empties everything.
+ */
+export interface NativeMessage extends NativeFieldMap {
     getHeaderField(tag: number): string;
     setHeaderField(tag: number, value: string): void;
     getTrailerField(tag: number): string;
     setTrailerField(tag: number, value: string): void;
+    headerFields(): [number, string][];
+    trailerFields(): [number, string][];
     getMsgType(): string;
     toString(): string;
     toPretty(): string;
@@ -16,7 +46,29 @@ export interface NativeMessage {
 /** Constructor shape for the native `MessageWrap` class. */
 export interface NativeMessageConstructor {
     new (): NativeMessage;
-    new (raw: string, validate?: boolean): NativeMessage;
+    /**
+     * Parse `raw`. With a dictionary the parse is structural (repeating groups
+     * become nested groups); without one it is flat. Admin messages always use
+     * the session dictionary; application messages use the application one.
+     */
+    new (raw: string, validate?: boolean, sessionDictionary?: NativeDataDictionary | null, applicationDictionary?: NativeDataDictionary | null): NativeMessage;
+}
+/** Native `FIX::Group` wrapper: one entry of a repeating group. */
+export interface NativeGroup extends NativeFieldMap {
+    /** The group's count tag (e.g. 453 NoPartyIDs). */
+    field(): number;
+    /** The first tag of every entry (e.g. 448 PartyID). */
+    delim(): number;
+    /** The entry's fields (and nested groups) as a SOH-delimited string, in wire order. */
+    toString(): string;
+}
+/** Constructor shape for the native `GroupWrap` class. */
+export interface NativeGroupConstructor {
+    /**
+     * @param order Optional full field order of an entry, delimiter first, no
+     *   zeros. Without it, fields sort delimiter-first then by tag number.
+     */
+    new (field: number, delim: number, order?: readonly number[] | null): NativeGroup;
 }
 /** Native `FIX::SessionID` wrapper. */
 export interface NativeSessionID {
@@ -77,8 +129,19 @@ export interface QuickFixError extends Error {
 }
 /** Native `FIX::DataDictionary` wrapper. */
 export interface NativeDataDictionary {
-    /** Throws a {@link QuickFixError} if the message is invalid. */
-    validate(message: NativeMessage): void;
+    /**
+     * Throws a {@link QuickFixError} if the message is invalid. With `bodyOnly`
+     * the BeginString version check and the tag/value validation of the
+     * header/trailer fields are skipped; required header/trailer fields are
+     * still checked.
+     */
+    validate(message: NativeMessage, bodyOnly?: boolean): void;
+    /** The BeginString the spec declares (e.g. `'FIX.4.4'`), `''` if none. */
+    getVersion(): string;
+    getFieldName(tag: number): string | undefined;
+    getFieldTag(name: string): number | undefined;
+    isField(tag: number): boolean;
+    isMsgType(msgType: string): boolean;
 }
 /**
  * Constructor shape for the native `DataDictionaryWrap` class. `fromString` /
@@ -111,18 +174,105 @@ export interface NativeEngineOptions {
     store?: 'file' | 'memory';
     log?: 'screen' | 'file' | 'none';
 }
+/**
+ * Native handle on a live `FIX::Session`.
+ *
+ * The handle stores only the `FIX::SessionID`; every method re-resolves the
+ * engine-owned session via `FIX::Session::lookupSession` and throws a
+ * {@link QuickFixError} with `fixErrorName: 'SessionNotFound'` once the owning
+ * engine has been stopped.
+ *
+ * Every member is synchronous: none takes the session mutex QuickFIX holds
+ * across application callbacks, so they cannot deadlock the main thread
+ * (`logon()`/`logout()` write a plain flag the network thread reads without a
+ * lock, as QuickFIX's own `Initiator::stop()` does).
+ * `FIX::Session::disconnect()`/`reset()` are not exposed; they are only safe
+ * on the engine's own network thread (see `cpp/session_wrap.cpp`).
+ */
+export interface NativeSession {
+    getSessionID(): NativeSessionID;
+    isLoggedOn(): boolean;
+    isEnabled(): boolean;
+    sentLogon(): boolean;
+    sentLogout(): boolean;
+    receivedLogon(): boolean;
+    isInitiator(): boolean;
+    isAcceptor(): boolean;
+    /** `nowMs` is an epoch-millisecond timestamp; omitted means "now". */
+    isSessionTime(nowMs?: number): boolean;
+    isLogonTime(nowMs?: number): boolean;
+    getExpectedSenderNum(): number;
+    getExpectedTargetNum(): number;
+    setNextSenderMsgSeqNum(seqNum: number): void;
+    setNextTargetMsgSeqNum(seqNum: number): void;
+    getResetOnLogon(): boolean;
+    setResetOnLogon(value: boolean): void;
+    getResetOnLogout(): boolean;
+    setResetOnLogout(value: boolean): void;
+    getResetOnDisconnect(): boolean;
+    setResetOnDisconnect(value: boolean): void;
+    getRefreshOnLogon(): boolean;
+    setRefreshOnLogon(value: boolean): void;
+    getCheckCompId(): boolean;
+    setCheckCompId(value: boolean): void;
+    getCheckLatency(): boolean;
+    setCheckLatency(value: boolean): void;
+    getPersistMessages(): boolean;
+    setPersistMessages(value: boolean): void;
+    getSendRedundantResendRequests(): boolean;
+    setSendRedundantResendRequests(value: boolean): void;
+    getValidateLengthAndChecksum(): boolean;
+    setValidateLengthAndChecksum(value: boolean): void;
+    getSendNextExpectedMsgSeqNum(): boolean;
+    setSendNextExpectedMsgSeqNum(value: boolean): void;
+    getIsNonStopSession(): boolean;
+    setIsNonStopSession(value: boolean): void;
+    getLogonTimeout(): number;
+    setLogonTimeout(seconds: number): void;
+    getLogoutTimeout(): number;
+    setLogoutTimeout(seconds: number): void;
+    getMaxLatency(): number;
+    setMaxLatency(seconds: number): void;
+    getTimestampPrecision(): number;
+    /** Throws a `RangeError` unless `precision` is an integer in `0..9`. */
+    setTimestampPrecision(precision: number): void;
+    logon(): void;
+    logout(reason?: string): void;
+    /** May throw a `QuickFixError` (`IOException`) from the message store. */
+    refresh(): void;
+}
+/**
+ * Constructor shape for the native `SessionWrap` class. Internal: JS obtains a
+ * session through {@link NativeModule.lookupSession} or
+ * {@link NativeEngine.getSession}, never by constructing one.
+ */
+export interface NativeSessionConstructor {
+    new (sessionID: NativeSessionID): NativeSession;
+}
 /**
  * Native engine (SocketInitiator / SocketAcceptor) wrapper.
  *
  * `start`/`stop` run OFF the main thread and resolve a Promise when the engine
  * has finished (re)configuring its sockets, so the Node.js event loop stays free
  * to service the application callbacks the engine fires. `isLoggedOn`/`ref`/
- * `unref` remain synchronous.
+ * `unref`/`getSessions`/`getSession` remain synchronous.
+ *
+ * Once `stop()` settles the engine is destroyed, which also destroys its
+ * `FIX::Session` objects: `getSession` then returns `undefined` and any
+ * previously obtained {@link NativeSession} throws `SessionNotFound`.
  */
 export interface NativeEngine {
     start(): Promise<void>;
     stop(force?: boolean): Promise<void>;
-    isLoggedOn(): boolean;
+    /**
+     * No argument: whether ANY of this engine's sessions is logged on. With a
+     * SessionID: whether THAT session belongs to this engine and is logged on.
+     */
+    isLoggedOn(sessionID?: NativeSessionID): boolean;
+    /** The SessionIDs this engine was configured with (stable across stop()). */
+    getSessions(): NativeSessionID[];
+    /** `undefined` if the id is not one of this engine's sessions or stop() has settled. */
+    getSession(sessionID: NativeSessionID): NativeSession | undefined;
     ref(): void;
     unref(): void;
 }
@@ -131,22 +281,35 @@ export interface NativeEngineConstructor {
     new (options: NativeEngineOptions): NativeEngine;
 }
 /**
- * The nested FIX-constants object exported by the addon, e.g.
- * `enums.MsgType.Logon`, `enums.Side.Buy`. Field tags (`FIELD`) are not exported
- * by the addon; they are generated on the TS side (`src/generated/fields.ts`).
+ * The full surface of the native addon exported by `load-native.cjs`.
+ *
+ * FIX constants are not exported by the addon: field tags (`FIELD`) and value
+ * groups (`MsgType`, `Side`, ...) are generated on the TS side from the
+ * QuickFIX headers (`src/generated/fields.ts`, `src/generated/values.ts`).
  */
-export type NativeEnums = Readonly<Record<string, Readonly<Record<string, number | string>>>>;
-/** The full surface of the native addon exported by `load-native.cjs`. */
 export interface NativeModule {
     version(): string;
     quickfixParseMsgType(raw: string): string;
-    /** Runs off the main thread; resolves `true` if accepted for sending. */
-    sendToTarget(message: NativeMessage, sessionID: NativeSessionID): Promise<boolean>;
-    enums: NativeEnums;
+    /**
+     * Runs off the main thread; resolves `true` if accepted for sending.
+     *
+     * Second argument: an explicit SessionID, or a session qualifier (possibly
+     * omitted/empty), in which case QuickFIX resolves the session from the
+     * message's own header (BeginString / SenderCompID / TargetCompID).
+     */
+    sendToTarget(message: NativeMessage, sessionIDOrQualifier?: NativeSessionID | string): Promise<boolean>;
+    /** `undefined` if no session with that id exists in this process. */
+    lookupSession(sessionID: NativeSessionID): NativeSession | undefined;
+    doesSessionExist(sessionID: NativeSessionID): boolean;
+    /** Every session registered in this process (all engines). */
+    getSessions(): NativeSessionID[];
+    numSessions(): number;
     MessageWrap: NativeMessageConstructor;
+    GroupWrap: NativeGroupConstructor;
     SessionIDWrap: NativeSessionIDConstructor;
     SessionSettingsWrap: NativeSessionSettingsConstructor;
     DataDictionaryWrap: NativeDataDictionaryConstructor;
+    SessionWrap: NativeSessionConstructor;
     InitiatorWrap: NativeEngineConstructor;
     AcceptorWrap: NativeEngineConstructor;
     sessionSettingsFromString?(cfg: string): NativeSessionSettings;
@@ -160,4 +323,3 @@ export interface NativeModule {
  * assert it to the contract here — the single localized cast in the codebase.
  */
 export declare const native: NativeModule;
-//# sourceMappingURL=native.d.ts.map

package/dist/esm/native.js

@@ -14,4 +14,3 @@ import nativeModule from './load-native.cjs';
  * assert it to the contract here — the single localized cast in the codebase.
  */
 export const native = nativeModule;
-//# sourceMappingURL=native.js.map

package/dist/esm/session-id.d.ts

@@ -37,4 +37,15 @@ export declare class SessionID {
     /** The canonical string form, e.g. `FIX.4.4:CLIENT->BROKER`. */
     toString(): string;
 }
-//# sourceMappingURL=session-id.d.ts.map
+/**
+ * @internal The native handle behind a {@link SessionID} argument.
+ *
+ * Duck-typed rather than `instanceof SessionID`: this package ships ESM and
+ * CJS builds, and a `SessionID` created by the other build is a different class
+ * with the same shape. Both builds load the same native addon, so its
+ * `SessionIDWrap` class is the one thing they share, and that is what the
+ * handle is checked against. Anything else -- `null`, `{}`, a `Session` -- is
+ * a `TypeError` naming the argument, rather than silently degrading to an
+ * `undefined` handle that the callee would read as "no session id given".
+ */
+export declare function toNativeSessionID(value: unknown, name: string): NativeSessionID;

package/dist/esm/session-id.js

@@ -60,4 +60,23 @@ export class SessionID {
         return this.#native.toString();
     }
 }
-//# sourceMappingURL=session-id.js.map
+/**
+ * @internal The native handle behind a {@link SessionID} argument.
+ *
+ * Duck-typed rather than `instanceof SessionID`: this package ships ESM and
+ * CJS builds, and a `SessionID` created by the other build is a different class
+ * with the same shape. Both builds load the same native addon, so its
+ * `SessionIDWrap` class is the one thing they share, and that is what the
+ * handle is checked against. Anything else -- `null`, `{}`, a `Session` -- is
+ * a `TypeError` naming the argument, rather than silently degrading to an
+ * `undefined` handle that the callee would read as "no session id given".
+ */
+export function toNativeSessionID(value, name) {
+    const handle = typeof value === 'object' && value !== null
+        ? value.nativeHandle
+        : undefined;
+    if (!(handle instanceof native.SessionIDWrap)) {
+        throw new TypeError(`${name} must be a SessionID`);
+    }
+    return handle;
+}

package/dist/esm/session-settings.d.ts

@@ -44,4 +44,3 @@ export declare class SessionSettings {
     /** The sessions declared by this configuration. */
     getSessions(): SessionID[];
 }
-//# sourceMappingURL=session-settings.d.ts.map

package/dist/esm/session-settings.js

@@ -69,4 +69,3 @@ export class SessionSettings {
         return this.#native.getSessions().map((h) => SessionID.fromNative(h));
     }
 }
-//# sourceMappingURL=session-settings.js.map