@homaiohq/napi-quickfix 0.0.0-stage → 0.2.0

package/dist/esm/group.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Ergonomic wrapper around the native `FIX::Group`: one entry of a repeating
+ * group.
+ */
+import { type NativeGroup } from './native.js';
+/**
+ * One entry of a FIX repeating group.
+ *
+ * A group is identified by its **count tag** (`field`, e.g. `453 NoPartyIDs`)
+ * and its **delimiter** (`delim`, the first tag of every entry, e.g.
+ * `448 PartyID`). Build an entry, fill its fields, then
+ * {@link Message.addGroup} it; QuickFIX maintains the count field for you.
+ *
+ * Field values are accepted as `string | number` on input (numbers are written
+ * without exponent notation) and always returned as `string`, exactly as on
+ * {@link Message}. Groups nest: an entry can carry its own repeating groups
+ * through the same `addGroup` / `getGroup` API.
+ *
+ * Entries read back with `getGroup` are **snapshot copies**: mutating one does
+ * not change the message it came from. Write it back with
+ * {@link Message.replaceGroup}.
+ *
+ * Group indices are **1-based**, as in QuickFIX.
+ *
+ * @example
+ * ```ts
+ * import { Group, Message, FIELD } from '@homaiohq/napi-quickfix';
+ *
+ * const party = new Group(FIELD.NoPartyIDs, FIELD.PartyID)
+ *   .setField(FIELD.PartyID, 'TRADER-1')
+ *   .setField(FIELD.PartyIDSource, 'D')
+ *   .setField(FIELD.PartyRole, 11);
+ * order.addGroup(party);
+ *
+ * order.groupCount(FIELD.NoPartyIDs);           // 1
+ * order.getGroup(1, FIELD.NoPartyIDs).getField(FIELD.PartyID); // 'TRADER-1'
+ * ```
+ */
+export declare class Group {
+    #private;
+    /**
+     * Create an empty group entry.
+     *
+     * @param field The group's count tag (e.g. `FIELD.NoPartyIDs`), or an
+     *   existing native handle to adopt (internal).
+     * @param delim The delimiter: the first tag of every entry (e.g.
+     *   `FIELD.PartyID`).
+     * @param order Optional complete field order of an entry, delimiter first
+     *   (e.g. `[448, 447, 452]`). Fields not listed sort after the listed ones by
+     *   tag number. Without it, fields sort delimiter-first then by tag number,
+     *   which already matches the standard dictionaries for most groups.
+     */
+    constructor(field: number | NativeGroup, delim?: number, order?: readonly number[]);
+    /** @internal Wrap an existing native group handle. */
+    static fromNative(handle: NativeGroup): Group;
+    /** @internal The native handle backing this group. */
+    get nativeHandle(): NativeGroup;
+    /** The group's count tag (e.g. `453` for `NoPartyIDs`). */
+    get field(): number;
+    /** The delimiter: the first tag of every entry (e.g. `448` for `PartyID`). */
+    get delim(): number;
+    /**
+     * Read a field by tag.
+     * @throws A `QuickFixError` (`fixErrorName: 'FieldNotFound'`) if absent.
+     */
+    getField(tag: number): string;
+    /** Set a field. Returns `this` for chaining. */
+    setField(tag: number, value: string | number): this;
+    /** Whether a field is present. */
+    isSetField(tag: number): boolean;
+    /** Remove a field (no-op if absent). Returns `this` for chaining. */
+    removeField(tag: number): this;
+    /** Read a field by tag, or `undefined` if absent. */
+    getFieldIfSet(tag: number): string | undefined;
+    /** The number of fields, including every field of every nested group entry. */
+    totalFields(): number;
+    /** Whether the entry has no fields of its own. */
+    isEmpty(): boolean;
+    /** Remove every field and nested group. Returns `this` for chaining. */
+    clear(): this;
+    /** The entry's own fields, in wire order, as `[tag, value]` pairs. */
+    fields(): [number, string][];
+    /** Iterates the entry's own fields as `[tag, value]` pairs (see {@link Group.fields}). */
+    [Symbol.iterator](): IterableIterator<[number, string]>;
+    /**
+     * Append a nested group entry under its own count tag (a copy is stored; the
+     * count field is updated). Returns `this` for chaining.
+     * @throws `TypeError` when `group.delim` differs from the delimiter of the
+     *   entries already stored under `group.field`.
+     */
+    addGroup(group: Group): this;
+    /**
+     * A snapshot copy of the `index`-th entry (1-based) of the nested group `tag`.
+     * Mutations do not affect this entry; write them back with
+     * {@link Group.replaceGroup}.
+     * @throws A `QuickFixError` (`fixErrorName: 'FieldNotFound'`) when the tag
+     *   has no entries or `index` is out of range.
+     */
+    getGroup(index: number, tag: number): Group;
+    /**
+     * 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: number, group: Group): this;
+    /**
+     * Remove every entry of the nested group `tag` (and its count field), or
+     * only the `index`-th entry (1-based). Returns `this`.
+     *
+     * Removing every entry of a tag that has none is a no-op.
+     * @throws A `QuickFixError` (`fixErrorName: 'FieldNotFound'`) when the
+     *   `index`-th entry does not exist.
+     */
+    removeGroup(tag: number): this;
+    removeGroup(index: number, tag: number): this;
+    /** Whether the nested group `tag` has any entry, or has an `index`-th entry (1-based). */
+    hasGroup(tag: number): boolean;
+    hasGroup(index: number, tag: number): boolean;
+    /** The number of entries of the nested group `tag` (0 if none). */
+    groupCount(tag: number): number;
+    /** The entry's fields (and nested groups) as a SOH-delimited string, in wire order. */
+    toString(): string;
+}

package/dist/esm/group.js

@@ -0,0 +1,181 @@
+/**
+ * Ergonomic wrapper around the native `FIX::Group`: one entry of a repeating
+ * group.
+ */
+import { native } from './native.js';
+import { formatFieldValue } from './field-value.js';
+/**
+ * One entry of a FIX repeating group.
+ *
+ * A group is identified by its **count tag** (`field`, e.g. `453 NoPartyIDs`)
+ * and its **delimiter** (`delim`, the first tag of every entry, e.g.
+ * `448 PartyID`). Build an entry, fill its fields, then
+ * {@link Message.addGroup} it; QuickFIX maintains the count field for you.
+ *
+ * Field values are accepted as `string | number` on input (numbers are written
+ * without exponent notation) and always returned as `string`, exactly as on
+ * {@link Message}. Groups nest: an entry can carry its own repeating groups
+ * through the same `addGroup` / `getGroup` API.
+ *
+ * Entries read back with `getGroup` are **snapshot copies**: mutating one does
+ * not change the message it came from. Write it back with
+ * {@link Message.replaceGroup}.
+ *
+ * Group indices are **1-based**, as in QuickFIX.
+ *
+ * @example
+ * ```ts
+ * import { Group, Message, FIELD } from '@homaiohq/napi-quickfix';
+ *
+ * const party = new Group(FIELD.NoPartyIDs, FIELD.PartyID)
+ *   .setField(FIELD.PartyID, 'TRADER-1')
+ *   .setField(FIELD.PartyIDSource, 'D')
+ *   .setField(FIELD.PartyRole, 11);
+ * order.addGroup(party);
+ *
+ * order.groupCount(FIELD.NoPartyIDs);           // 1
+ * order.getGroup(1, FIELD.NoPartyIDs).getField(FIELD.PartyID); // 'TRADER-1'
+ * ```
+ */
+export class Group {
+    /** @internal Underlying native handle. */
+    #native;
+    /**
+     * Create an empty group entry.
+     *
+     * @param field The group's count tag (e.g. `FIELD.NoPartyIDs`), or an
+     *   existing native handle to adopt (internal).
+     * @param delim The delimiter: the first tag of every entry (e.g.
+     *   `FIELD.PartyID`).
+     * @param order Optional complete field order of an entry, delimiter first
+     *   (e.g. `[448, 447, 452]`). Fields not listed sort after the listed ones by
+     *   tag number. Without it, fields sort delimiter-first then by tag number,
+     *   which already matches the standard dictionaries for most groups.
+     */
+    constructor(field, delim, order) {
+        if (typeof field !== 'number') {
+            // Adopt an existing native handle (getGroup path).
+            this.#native = field;
+        }
+        else {
+            if (typeof delim !== 'number') {
+                throw new TypeError('new Group(field: number, delim: number, order?: number[])');
+            }
+            this.#native = new native.GroupWrap(field, delim, order);
+        }
+    }
+    /** @internal Wrap an existing native group handle. */
+    static fromNative(handle) {
+        return new Group(handle);
+    }
+    /** @internal The native handle backing this group. */
+    get nativeHandle() {
+        return this.#native;
+    }
+    /** The group's count tag (e.g. `453` for `NoPartyIDs`). */
+    get field() {
+        return this.#native.field();
+    }
+    /** The delimiter: the first tag of every entry (e.g. `448` for `PartyID`). */
+    get delim() {
+        return this.#native.delim();
+    }
+    /**
+     * Read a field by tag.
+     * @throws A `QuickFixError` (`fixErrorName: 'FieldNotFound'`) if absent.
+     */
+    getField(tag) {
+        return this.#native.getField(tag);
+    }
+    /** Set a field. Returns `this` for chaining. */
+    setField(tag, value) {
+        this.#native.setField(tag, formatFieldValue(value));
+        return this;
+    }
+    /** Whether a field is present. */
+    isSetField(tag) {
+        return this.#native.isSetField(tag);
+    }
+    /** Remove a field (no-op if absent). Returns `this` for chaining. */
+    removeField(tag) {
+        this.#native.removeField(tag);
+        return this;
+    }
+    /** Read a field by tag, or `undefined` if absent. */
+    getFieldIfSet(tag) {
+        return this.#native.getFieldIfSet(tag);
+    }
+    /** The number of fields, including every field of every nested group entry. */
+    totalFields() {
+        return this.#native.totalFields();
+    }
+    /** Whether the entry has no fields of its own. */
+    isEmpty() {
+        return this.#native.isEmpty();
+    }
+    /** Remove every field and nested group. Returns `this` for chaining. */
+    clear() {
+        this.#native.clear();
+        return this;
+    }
+    /** The entry's own fields, in wire order, as `[tag, value]` pairs. */
+    fields() {
+        return this.#native.fields();
+    }
+    /** Iterates the entry's own fields as `[tag, value]` pairs (see {@link Group.fields}). */
+    [Symbol.iterator]() {
+        return this.fields()[Symbol.iterator]();
+    }
+    /**
+     * Append a nested group entry under its own count tag (a copy is stored; the
+     * count field is updated). Returns `this` for chaining.
+     * @throws `TypeError` when `group.delim` differs from the delimiter of the
+     *   entries already stored under `group.field`.
+     */
+    addGroup(group) {
+        this.#native.addGroup(group.nativeHandle);
+        return this;
+    }
+    /**
+     * A snapshot copy of the `index`-th entry (1-based) of the nested group `tag`.
+     * Mutations do not affect this entry; write them back with
+     * {@link Group.replaceGroup}.
+     * @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 nested group `tag` (0 if none). */
+    groupCount(tag) {
+        return this.#native.groupCount(tag);
+    }
+    /** The entry's fields (and nested groups) as a SOH-delimited string, in wire order. */
+    toString() {
+        return this.#native.toString();
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,68 @@
+import type { Message } from './message.js';
+import { type SessionID } from './session-id.js';
+export { Message, createMessage, parseMessage } from './message.js';
+export type { MessageParseOptions, MessageJSON } from './message.js';
+export { Group } from './group.js';
+export { SessionID } from './session-id.js';
+export { SessionSettings } from './session-settings.js';
+export { DataDictionary } from './data-dictionary.js';
+export { Initiator } from './initiator.js';
+export { Acceptor } from './acceptor.js';
+export { Engine } from './engine.js';
+export type { EngineOptions, EngineEvents } from './engine.js';
+export { Session, lookupSession, doesSessionExist, getSessions, numSessions } from './session.js';
+export { FixReject, fixReject } from './application.js';
+export type { ApplicationHandlers, FixRejectKind } from './application.js';
+export type { QuickFixError } from './native.js';
+export { enums, FIELD, VALUES, MsgType, Side, OrdType, TimeInForce } from './enums.js';
+export type { Enums, EnumGroup, FieldName, ValueGroups, ValueGroupName } from './enums.js';
+/**
+ * Send a message to the target session identified by `sessionID`.
+ *
+ * Wraps `FIX::Session::sendToTarget`. The session must exist and be logged on
+ * for delivery; otherwise the engine queues or drops per its configuration.
+ *
+ * Runs off the main thread and resolves once the engine has accepted (or
+ * rejected) the message, so the event loop stays free for callbacks. On a
+ * missing session the returned Promise rejects with a
+ * {@link QuickFixError} (`fixErrorName: 'SessionNotFound'`). The send is
+ * bound to the engine that owns the session when it is called: if that
+ * engine is stopped before the send reaches its session, the Promise rejects
+ * with `SessionNotFound` rather than running through an engine created later
+ * with the same id.
+ *
+ * @param message The message to send.
+ * @param sessionID The destination session.
+ * @returns A Promise resolving to `true` if the message was accepted for sending.
+ * @throws {TypeError} synchronously if `sessionID` is neither a {@link SessionID}
+ *   nor a qualifier string (it is not routed by the header instead).
+ *
+ * @example
+ * ```ts
+ * import { sendToTarget, createMessage, SessionID, FIELD, MsgType } from '@homaiohq/napi-quickfix';
+ * const order = createMessage({ [FIELD.MsgType]: MsgType.NewOrderSingle });
+ * await sendToTarget(order, new SessionID('FIX.4.4', 'CLIENT', 'BROKER'));
+ * ```
+ */
+export declare function sendToTarget(message: Message, sessionID: SessionID): Promise<boolean>;
+/**
+ * Send a message to the session identified by the message's **own header**
+ * (`BeginString`, `SenderCompID`, `TargetCompID`) plus an optional session
+ * qualifier.
+ *
+ * Wraps the `FIX::Session::sendToTarget(message, qualifier)` overload. Same
+ * threading and error behaviour as the SessionID form; a message whose header
+ * does not identify an existing session rejects with
+ * `fixErrorName: 'SessionNotFound'`.
+ *
+ * @param message The message to send; its header must carry tags 8, 49 and 56.
+ * @param qualifier Optional session qualifier (`SessionQualifier` in the settings).
+ */
+export declare function sendToTarget(message: Message, qualifier?: string): Promise<boolean>;
+/** The QuickFIX engine / addon version string. */
+export declare const version: () => string;
+/**
+ * Parse the MsgType (tag 35) out of a raw FIX wire string. Low-level helper;
+ * prefer {@link Message.parse} + {@link Message.getMsgType} for general use.
+ */
+export declare const quickfixParseMsgType: (raw: string) => string;

package/dist/esm/index.js

@@ -0,0 +1,43 @@
+/**
+ * `@homaiohq/napi-quickfix` — a modern Node-API binding for the QuickFIX C++
+ * FIX-protocol engine.
+ *
+ * @packageDocumentation
+ */
+import { native } from './native.js';
+import { toNativeSessionID } from './session-id.js';
+// --- Pure layer -----------------------------------------------------------
+export { Message, createMessage, parseMessage } from './message.js';
+export { Group } from './group.js';
+export { SessionID } from './session-id.js';
+export { SessionSettings } from './session-settings.js';
+export { DataDictionary } from './data-dictionary.js';
+// --- Session engine -------------------------------------------------------
+export { Initiator } from './initiator.js';
+export { Acceptor } from './acceptor.js';
+export { Engine } from './engine.js';
+export { Session, lookupSession, doesSessionExist, getSessions, numSessions } from './session.js';
+export { FixReject, fixReject } from './application.js';
+// --- Enums / constants ----------------------------------------------------
+// Every other value group (ExecType, OrdStatus, SecurityType, ...) is reachable
+// as `enums.<Field>` / `VALUES.<Field>`, or by name from the
+// `@homaiohq/napi-quickfix/values` subpath, which keeps this namespace small.
+export { enums, FIELD, VALUES, MsgType, Side, OrdType, TimeInForce } from './enums.js';
+export function sendToTarget(message, sessionIDOrQualifier) {
+    // Dispatch on the primitive, not `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 (see toNativeSessionID). Anything
+    // else is a TypeError here rather than an `undefined` target the native
+    // layer would read as "route by the message header".
+    const target = typeof sessionIDOrQualifier === 'string' || sessionIDOrQualifier === undefined
+        ? sessionIDOrQualifier
+        : toNativeSessionID(sessionIDOrQualifier, 'sessionID');
+    return native.sendToTarget(message.nativeHandle, target);
+}
+/** The QuickFIX engine / addon version string. */
+export const version = () => native.version();
+/**
+ * Parse the MsgType (tag 35) out of a raw FIX wire string. Low-level helper;
+ * prefer {@link Message.parse} + {@link Message.getMsgType} for general use.
+ */
+export const quickfixParseMsgType = (raw) => native.quickfixParseMsgType(raw);

package/dist/esm/initiator.d.ts

@@ -0,0 +1,29 @@
+import { Engine, type EngineOptions } from './engine.js';
+export type { EngineOptions } from './engine.js';
+/**
+ * A FIX session initiator (wraps `FIX::SocketInitiator`). Initiators establish
+ * outbound connections to acceptors as configured in {@link EngineOptions.settings}.
+ *
+ * Extends {@link Engine} (an {@link import('node:events').EventEmitter}), so you
+ * can observe lifecycle/message events in addition to supplying `handlers`.
+ * Remember: only `handlers` may mutate outbound messages or reject inbound ones;
+ * events are observe-only.
+ *
+ * @example
+ * ```ts
+ * const initiator = new Initiator({
+ *   settings: SessionSettings.fromString(cfg),
+ *   handlers: { onLogon: (id) => console.log('up', id.toString()) },
+ *   store: 'memory',
+ *   log: 'none',
+ * });
+ * initiator.on('fromApp', (msg) => console.log('recv', msg.getMsgType()));
+ * await initiator.start();
+ * // ... later
+ * await initiator.stop();
+ * ```
+ */
+export declare class Initiator extends Engine {
+    /** @param options Engine options. */
+    constructor(options: EngineOptions);
+}

package/dist/esm/initiator.js

@@ -0,0 +1,34 @@
+/**
+ * FIX session initiator (client side — connects out to acceptors).
+ */
+import { native } from './native.js';
+import { Engine } from './engine.js';
+/**
+ * A FIX session initiator (wraps `FIX::SocketInitiator`). Initiators establish
+ * outbound connections to acceptors as configured in {@link EngineOptions.settings}.
+ *
+ * Extends {@link Engine} (an {@link import('node:events').EventEmitter}), so you
+ * can observe lifecycle/message events in addition to supplying `handlers`.
+ * Remember: only `handlers` may mutate outbound messages or reject inbound ones;
+ * events are observe-only.
+ *
+ * @example
+ * ```ts
+ * const initiator = new Initiator({
+ *   settings: SessionSettings.fromString(cfg),
+ *   handlers: { onLogon: (id) => console.log('up', id.toString()) },
+ *   store: 'memory',
+ *   log: 'none',
+ * });
+ * initiator.on('fromApp', (msg) => console.log('recv', msg.getMsgType()));
+ * await initiator.start();
+ * // ... later
+ * await initiator.stop();
+ * ```
+ */
+export class Initiator extends Engine {
+    /** @param options Engine options. */
+    constructor(options) {
+        super(native.InitiatorWrap, options);
+    }
+}

package/dist/esm/load-native.cjs

@@ -0,0 +1,5 @@
+// Authored (NOT compiled by tsc). Copied verbatim into dist/esm and dist/cjs by
+// build:ts:copy. From either of those directories, two levels up is the package
+// root, where prebuilds/ lives (and build/Release/*.node in local dev).
+const path = require('node:path');
+module.exports = require('node-gyp-build')(path.join(__dirname, '..', '..'));