Inbound messages API

Convert a ParsedMessage into a typed, name-keyed InboundMessage.

Purely dictionary-driven and total — it never throws and never re-reads the wire. Each top-level field is resolved to its dictionary name and routed by Dictionary.envelopeTags: header/trailer tags to the envelope, everything else to the body. Repeating groups become arrays of entry objects under their counter's name, recursively, so a nested group inside an entry reads the same way as one at the top.

A tag the dictionary does not know is not put in the body. It has no name to key by, and inventing one ("9999") would make the body un-renderable. It stays reachable on InboundMessage.parsed, and parse has already reported it as parse/unknown-tag.

The body type B is a claim about the message, not a check: pass a generated body type when the MsgType is known at the call site, or leave the default and narrow with a guard from inboundTypeGuard (see InboundBody for why the default is any). Nothing here validates the claim — that is validate's job, against the ParsedMessage.

A received message as a typed read model: the MessageView read surface over a name-keyed body, plus the session envelope and the parsed original.

The body carries the message's own fields keyed by name, with the envelope split off into envelope and group counters keyed to arrays of entry objects — the shape a generated <Msg>Body type describes, so inboundTypeGuard can narrow an unnarrowed inbound message to InboundMessage<MarketDataSnapshotFullRefreshBody> and every get() after it is typed. It holds what the wire actually carried: an optional field that did not arrive is absent, and a field that does not belong to this message (which parse reports as parse/tag-not-in-message) is present but untyped.

Being a MessageView it also renders: inbound.render(envelope) re-emits the body with a fresh envelope, which is the useful shape for a proxy that re-signs what it forwards. For a byte-exact echo of what arrived, go through toEncodeMessage(inbound.parsed) instead — see the module note on raw vs value.

An InboundMessage whose MsgType is pinned to the literal M rather than a bare string — the member shape of InboundUnion, and what a narrowing guard produces.

The pin is what makes msgType usable as a discriminant: switch narrows a union by a literal-typed property, and InboundMessage alone declares msgType: string, which discriminates nothing. Pinning also means a narrowed message reports the truth — after a guard for 'W', msgType really is 'W', not string.

The session envelope of a received message — the standard header and trailer fields, keyed by name and carrying their coerced values.

This is the half of a message the generated MessageBodies types deliberately exclude: on the way out those fields belong to the session layer and are supplied to MessageView.render, so a body type never mentions them. On the way IN they are simply present in the bytes, and reading MsgSeqNum off a received message is the most ordinary thing a session does — hence a typed home for them here rather than a detour back through the tag-keyed ParsedMessage.

Which fields land here is decided by the dictionary's header/trailer components (see Dictionary.envelopeTags), not by this list: the named properties below are the ones stable across FIX 4.x and FIXT, typed for convenience, and the index signature carries everything else the dictionary's header defines (OnBehalfOfCompID, NoHops entries' fields, ApplVerID, …).

The loose body shape of a received message — the read-side counterpart of UntypedBody. A repeating-group entry has the same shape, so it is also what an untyped entry array holds.

It is NOT UntypedBody: that type describes what a caller may write (FieldValue — string | number | boolean, never absent), whereas a value read off the wire is a DecodedValue (adding string[] for MultipleValueString) and an optional field is genuinely absent.

It is also not the default body of toInbound, which is any — pass this explicitly (toInbound<InboundBody>(…)) when you mean to read a message whose type you will not narrow. The default cannot be this type, or any other loose one: a generated body is an interface, and TypeScript never gives an interface an implicit index signature, so no index-signature type is ever its supertype. A narrowing predicate whose target is not assignable to the declared type yields an INTERSECTION rather than a replacement, and the loose get overload would then win at every call site — silently undoing the narrowing. any is what keeps inboundTypeGuard an actual narrowing, and it is the same choice MessageTypeGuard makes on the write side.

The typed read surface of a received message whose MsgType value is M in a Bodies registry — the inbound counterpart of MessageOf, for annotating a narrowed message (a handler parameter, a variable).

Every message in a Bodies registry as ONE discriminated union, keyed on msgType — what turns switch (message.msgType) into a narrowing dispatch instead of a chain of guards.

Each member is an InboundOf, so msgType is a literal in every branch and get() inside a case is typed to that message's body while InboundMessage.envelope and InboundMessage.parsed stay reachable. Handle every member and default narrows to never, giving compile-time exhaustiveness; handle a subset and default stays live and typed — a known message this consumer does not process.

if (isKnownInbound(inbound)) {  switch (inbound.msgType) {    case MsgType.Logon:            return onLogon(inbound);      // LogonBody    case MsgType.MarketDataRequest: return onRequest(inbound);   // MarketDataRequestBody    default:                        return;                      // known, not ours  }}

Two consequences of being a union, both worth knowing before reaching for it:

• Read the envelope before the switch, the body after. msgType and envelope are the same type in every member, so they read fine unnarrowed; get() is a different signature per member, and calling it on the un-narrowed union is a "not callable" error. That is the right discipline anyway — session fields before dispatch, body fields inside it.
• An unknown MsgType cannot be a member. A fallback member typed msgType: string overlaps every literal, so no case ever eliminates it and its loose get poisons every branch. Exclude unknown messages first, with a guard from inboundKnownGuard — which also matches how they parse: an unrecognised MsgType is read FLAT, with no groups reconstructed, so it was never union-shaped.

Build an InboundTypeGuard bound to a Bodies registry (the generated MessageBodies map of MsgType value → body type). Dict packages re-export the result as isInboundType; a consumer can bind one itself from any dict package's exported MessageBodies:

import { inboundTypeGuard } from '@boarteam/fix';import type { MessageBodies } from '@boarteam/fix-dict-fix44';​const isInboundType = inboundTypeGuard<MessageBodies>();if (isInboundType(inbound, 'W')) {  inbound.get('NoMDEntries');   // the typed entry array  inbound.envelope.MsgSeqNum;   // still reachable after narrowing}

Pure and side-effect-free: the only runtime work is message.msgType === msgType.

A Bodies-bound narrowing guard for received messages — the inbound counterpart of MessageTypeGuard, and the reason a switch (message.msgType) with a cast per branch is no longer necessary.

It narrows to InboundMessage, not MessageView, so the InboundMessage.envelope and InboundMessage.parsed of the message survive the narrowing — a session almost always wants MsgSeqNum alongside the body fields it just gained types for.

Build an InboundKnownGuard over a dictionary — the step that has to precede a switch (message.msgType) dispatch, because an unknown MsgType cannot be a union member (see InboundUnion).

The runtime test is dictionary.messageByMsgType(msgType) !== undefined. That stands in for "is a key of Bodies", which is not testable at runtime — Bodies is a type. The two agree as long as the dictionary and the Bodies map come from the SAME dict package, since the generator emits MessageBodies from this very dictionary; pairing a Bodies from one dialect with a dictionary from another is a mistake this cannot catch, the same way messageFactory cannot.

import { inboundKnownGuard } from '@boarteam/fix';import { dictionary, type MessageBodies } from '@boarteam/fix-dict-fix44';​const isKnownInbound = inboundKnownGuard<MessageBodies>(dictionary);

A guard that separates a received message the dictionary knows from one it does not, narrowing the former to InboundUnion so it can be dispatched with switch. Build one with inboundKnownGuard.