jspurefix 5.6.2 → 5.8.0

package/README.md

@@ -3,66 +3,58 @@
 [![CI](https://github.com/TimelordUK/jspurefix/actions/workflows/ci.yml/badge.svg)](https://github.com/TimelordUK/jspurefix/actions/workflows/ci.yml)
 [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 
-## C# Port Available
-
-This TypeScript FIX engine has been ported to C#:
-
-- **Codebase**: [cspurefix](https://github.com/TimelordUK/cspurefix)
-- **Demo**: [purefix-standalone-demo](https://github.com/TimelordUK/purefix-standalone-demo)
-- **NuGet**: [PureFix.Types.Core](https://www.nuget.org/packages/PureFix.Types.Core/)
-
----
-
-1. fast 100% native clean fix engine for Node JS
-1. supports tls encrypted sessions over tcp
-1. represent data dictionary as quickfix or repo notation
-1. compile interface types against definitions
-1. ascii / fixml supported
-1. parses repeat groups, components and raw data fields
-1. views make convinient ways of accessing data
-1. complete trade capture sample to get started
-1. a skeleton example shows connection, login and session only
-1. parse fix logs into human readable format - JSON, tokens
-1. socket session management for login, heartbeat etc
-1. implement httpInitiator or acceptor
-
-## Typescript FIX Engine for Node JS
-
-This fix engine provides a fast easy API to parse or send finacial protocol FIX messages. It is implemented entirely in typescript and runs in Node JS. Messages of any complexity can be handled providing they are backed by a suitable data dictionary. All structures within a message will be resolved for easy access - groups of components containing groups etc.
-
-## Installing
-
-compiled typescript is now included. Install the package from npm:
+A fast, fully native TypeScript [FIX protocol](https://www.fixtrading.org/) engine for Node.js. Built around a data-dictionary driven parser, with first-class support for sessions over TCP/TLS, persistent message stores, sequence recovery, FIXML over HTTP, and generated typed interfaces for any FIX dialect.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Session Configuration](#session-configuration)
+  - [TLS](#tls)
+  - [Body length padding](#body-length-padding)
+- [Persistence & Recovery](#persistence--recovery)
+  - [Choosing a store](#choosing-a-store)
+  - [`ResetSeqNumFlag` semantics](#resetseqnumflag-semantics)
+  - [Resending messages](#resending-messages)
+- [Working with Messages](#working-with-messages)
+- [FIXML over HTTP](#fixml-over-http)
+- [Data Dictionaries](#data-dictionaries)
+- [`jsfix` CLI — log parsing & stats](#jsfix-cli--log-parsing--stats)
+- [Performance](#performance)
+- [Developing on jspurefix](#developing-on-jspurefix)
+- [C# Port](#c-port)
+- [License](#license)
+
+## Features
+
+- 100% native TypeScript — no native bindings, runs anywhere Node.js does
+- ASCII (tag=value) and FIXML message encodings
+- Repeating groups, components, nested structures and raw data fields
+- Dictionary-driven: load QuickFIX XML or FIX repository definitions, compile typed interfaces
+- Full session lifecycle: logon, heartbeats, test requests, resend requests, logout
+- TLS-encrypted sessions over TCP
+- Pluggable persistent message store (in-memory or file) with sequence recovery
+- HTTP initiator/acceptor for FIXML
+- Command-line tool for parsing FIX logs into tokens, JSON, or structure dumps
+- Sample applications: trade capture, market data, FIXML OMS, recovering skeleton
+
+## Installation
 
 ```shell
-  npm install jspurefix
-  cd node_modules/jspurefix && npm run unzip-repo
+npm install jspurefix
+cd node_modules/jspurefix && npm run unzip-repo
 ```
 
-see our [demo application](https://github.com/TimelordUK/jspf-demo/)
-
-```shell
-  https://github.com/TimelordUK/jspf-demo
-```
+`unzip-repo` extracts the bundled FIX dictionaries. The `postinstall` hook will normally do this for you, but the command is exposed in case you need to re-run it.
 
-if you wish to generate custom messages this is easily doing using quick fix XML format - see [quickfix demo](https://github.com/TimelordUK/jspf-md-demo)
+A standalone demo project lives at [TimelordUK/jspf-demo](https://github.com/TimelordUK/jspf-demo) — the fastest way to see a working initiator/acceptor.
 
-edit the dictionary file data/generate and run the generator.
-
-```shell
-  npm run generate
-```
+## Quickstart
 
-check the messages generated in src\types
-
-```shell
-  https://github.com/TimelordUK/jspf-md-demo
-```
-
-import types for usage with a client
+Import the session types you need from `jspurefix` and the typed FIX messages for your dialect:
 
 ```typescript
-
 import {
   AsciiSession,
   MsgView,
@@ -70,102 +62,94 @@ import {
   IJsFixLogger,
   Dictionary,
   MsgType,
-  IJsFixConfig,
   initiator,
   acceptor,
   makeConfig
 } from 'jspurefix'
-// types for the specific FIX dialect
+
 import {
   ITradeCaptureReport,
   ITradeCaptureReportRequest,
   ITradeCaptureReportRequestAck
 } from 'jspurefix/dist/types/FIX4.4/repo'
-
 ```
 
-see example trade-capture-client - use
-
-### getting started
-
-clone from git
-
-unix
-
-```shell
-  git clone https://github.com/TimelordUK/jspurefix.git
-  cd jspurefix
-  script/build.sh
-```
+A minimal session subclasses `AsciiSession` and implements two callbacks: `onReady` (connection up, logon confirmed) and `onApplicationMsg` (a non-session message arrived).
 
-```shell
-  npm install
-  npm run unzip-repo
-  ./node_modules/.bin/tsc --version
-  ./node_modules/.bin/tsc
-  npm run tcp-tc
-```
+```typescript
+class TradeCaptureClient extends AsciiSession {
+  constructor (public readonly config: IJsFixConfig) {
+    super(config)
+    this.logReceivedMsgs = true
+    this.fixLog = config.logFactory.plain(`jsfix.${config.description.application.name}.txt`)
+    this.logger = config.logFactory.logger(`${this.me}:TradeCaptureClient`)
+  }
 
-windows
+  protected onReady (view: MsgView): void {
+    const tcr: ITradeCaptureReportRequest =
+      TradeFactory.tradeCaptureReportRequest('all-trades', new Date())
+    this.send(MsgType.TradeCaptureReportRequest, tcr)
+  }
 
-```shell
-  git clone https://github.com/TimelordUK/jspurefix.git
-  cd jspurefix
-  script\build.cmd
+  protected onApplicationMsg (msgType: string, view: MsgView): void {
+    switch (msgType) {
+      case MsgType.TradeCaptureReport: {
+        const tc: ITradeCaptureReport = view.toObject()
+        this.logger.info(`tc ${tc.TradeReportID} ${tc.Instrument.Symbol} ${tc.LastQty} @ ${tc.LastPx}`)
+        break
+      }
+    }
+  }
+}
 ```
 
-or
+The full sample lives at `src/sample/tcp/trade-capture/` and runs both sides over a local socket:
 
 ```shell
-  git clone https://github.com/TimelordUK/jspurefix.git
-  cd jspurefix
-  npm install
-  npm run unzip-repo
-  node_modules/.bin/tsc
-  npm run tcp-tc
+npm run tcp-tc      # full trade-capture client/server demo
+npm run tcp-sk      # bare skeleton: connect, log on, idle
+npm run http-oms    # FIXML order/exec-report over HTTP
 ```
 
-## Run Sample
-
-The code provided in src/sample/tcp/trade_capture is a good place to start in building an application with this library. In this case both client and server are run together communicating over a socket.  In reality a client is more likely connecting to an external acceptor such as CME, ICE.
-
-There is also a skeleton application which shows all application code stripped away to just enough to create a connection, login and see the session.
+Each demo terminates after about a minute, or with Ctrl-C.
 
-Both examples will automatically close down after ~1 minute or can be terminated CTRL-C
+## Session Configuration
 
-ensure the repo dictionary has been unpacked above.  This provides the data dictionary
-used to parse messages.
+A session is described by a JSON file (or any object matching `ISessionDescription`). Example: `data/session/test-initiator.json`.
 
-run examples such as the trade capture, simple skeleton or http.
-
-```shell
-npm run tcp-tc
-```
-
-```shell
-npm run tcp-sk
-```
-
-included is an example fixml over http application where an order is submitted and execution report returned.
-
-```shell
-npm run http-oms
+```json
+{
+  "application": {
+    "type": "initiator",
+    "name": "test_client",
+    "reconnectSeconds": 10,
+    "tcp": { "host": "localhost", "port": 2344 },
+    "protocol": "ascii",
+    "dictionary": "repo44"
+  },
+  "Username": "js-client",
+  "Password": "pwd-client",
+  "EncryptMethod": 0,
+  "ResetSeqNumFlag": true,
+  "HeartBtInt": 30,
+  "SenderCompId": "init-comp",
+  "TargetCompID": "accept-comp",
+  "TargetSubID": "fix",
+  "BeginString": "FIX.4.4"
+}
 ```
 
-## tls SSL encryption
-
-see example data\session\test-initiator-tls.json
+### TLS
 
-to run the provided example tls trade capture a script such as script\getKey.ps1 can be run to generate self certified certificates. This is a powershell script that requires openssl in the tunnel e.g. /mingw64/bin/openssl. the ca field below is only required when using self certified and will not be needed for a third party vendor where certificates are provided. Set enableTrace flag whilst diagnosing the session.
+Add a `tls` block under `application.tcp`. The `ca` field is only needed for self-signed certificates; commercial vendors will supply this for you. `script/getKey.ps1` will generate a self-signed CA + client/server pair (requires `openssl` on the path).
 
 ```json
 {
   "application": {
-    "reconnectSeconds": 10,
     "type": "initiator",
     "name": "test_client",
     "tcp": {
-      "host" : "localhost",
+      "host": "localhost",
       "port": 2344,
       "tls": {
         "timeout": 10000,
@@ -173,45 +157,66 @@ to run the provided example tls trade capture a script such as script\getKey.ps1
         "enableTrace": true,
         "key": "data/session/certs/client/client.key",
         "cert": "data/session/certs/client/client.crt",
-        "ca": [
-          "data/session/certs/ca/ca.crt"
-        ]
+        "ca": ["data/session/certs/ca/ca.crt"]
       }
     },
     "protocol": "ascii",
     "dictionary": "repo44"
   },
-  "Username": "js-tls-client",
-  "Password": "pwd-tls-client",
-  "EncryptMethod": 0,
-  "ResetSeqNumFlag": true,
-  "LastSentSeqNum": 10,
-  "LastReceivedSeqNum": 11,
-  "HeartBtInt": 30,
-  "SenderCompId": "init-tls-comp",
-  "TargetCompID": "accept-tls-comp",
-  "TargetSubID": "fix",
-  "BeginString": "FIX4.4",
-  "BodyLengthChars": 6
+  "BeginString": "FIX4.4"
 }
 ```
 
-## configure the body length field padding width
+See `data/session/test-initiator-tls.json` for the complete file.
+
+### Body length padding
+
+`BodyLengthChars` controls how the tag-9 body-length field is zero-padded. Defaults to `7`; set to a smaller value (e.g. `6`) when interoperating with a counterparty that requires it.
+
+```json
+{ "BodyLengthChars": 6 }
+```
+
+## Persistence & Recovery
 
-see example initiator file data\session\test-initiator-tls.json.
+By default, every session uses an in-memory message store — sequence numbers and any stored messages are lost when the process exits. For production use you'll typically want either persisted sequences or a full file-backed store with replay.
 
-i.e. include field BodyLengthChars which defaults to 7 characters if omitted.
+### Choosing a store
+
+Add a `store` block to the session description. Omit it to keep the in-memory default.
 
 ```json
 {
-  "BodsyLengthChars": 6
+  "store": { "type": "memory" }
+}
+```
+
+```json
+{
+  "store": {
+    "type": "file",
+    "directory": "/var/fix/sessions"
+  }
 }
 ```
 
-## launching without resetting message sequences
+The file store writes QuickFIX-compatible files into the directory:
 
-If the message sequences are persisted over multiple sessions and are not reset on logon (ie. `"ResetSeqNumFlag": false,`),
-then the previously used sequence numbers can be set as follows:
+| File | Contents |
+| --- | --- |
+| `<session>.seqnums` | Current sender / target sequence numbers |
+| `<session>.session` | Session creation timestamp |
+| `<session>.header` | Index lines `seqnum,offset,length` into `.body` |
+| `<session>.body` | Concatenated raw FIX messages for resend |
+
+Session names are derived from `BeginString-SenderCompID-TargetCompID`.
+
+You can also pass a custom factory programmatically via `IJsFixConfig.sessionStoreFactory` — useful for testing or for plugging in an alternative backend (Redis, S3, etc.).
+
+### `ResetSeqNumFlag` semantics
+
+- `"ResetSeqNumFlag": true` — every logon resets sender/target sequences back to 1. The engine clears the persisted store before sending the Logon, so the message correctly carries `MsgSeqNum=1` even after a reconnect with recovered state. (See [issue #140](https://github.com/TimelordUK/jspurefix/issues/140).)
+- `"ResetSeqNumFlag": false` — sequences are preserved across logons. To seed initial sequences for a brand-new session (no persisted store), set `LastSentSeqNum` and `LastReceivedSeqNum`:
 
 ```json
 {
@@ -221,21 +226,20 @@ then the previously used sequence numbers can be set as follows:
 }
 ```
 
-## resending messages
+With a file store configured, `LastSentSeqNum` / `LastReceivedSeqNum` are only consulted the first time a session is started; subsequent runs read from the persisted `.seqnums` file.
 
-By default, the library will not resend past messages as this requires persisting messages which depending on the volume,
-may also require a database. If you want to support resending you must override `AsciiSession.onResendRequest()` with a resending logic.
-Additionally, make sure to include the original message sequence and the duplicate message flag in the FIX object:
+### Resending messages
+
+When a counterparty asks for missed messages, the engine needs access to the originals. The file store keeps every encoded message and the bundled `AsciiSession.onResendRequest()` will replay from it automatically. If you're using the in-memory store and want resend support, override `onResendRequest()` with your own retrieval logic and set the duplicate flag on each replayed message:
 
 ```typescript
 {
-...messageBodyData,
-    StandardHeader: { PossDupFlag: true, MsgSeqNum: sequenceNumber},
+  ...messageBodyData,
+  StandardHeader: { PossDupFlag: true, MsgSeqNum: sequenceNumber }
 }
-
 ```
 
-### Example
+Example payload:
 
 ```json
 {
@@ -252,229 +256,75 @@ Additionally, make sure to include the original message sequence and the duplica
 }
 ```
 
-## Unit Tests
-
-there is a comprehensive suite of tests which can be run
-
-```shell
-npm t
-```
-
-```bash
-PASS  src/test/elastic-buffer.test.ts
-RUNS  src/test/session.test.ts
-PASS  src/test/encode-proxy.test.tsst.ts
-PASS  src/test/execution-report.test.ts
-PASS  src/test/view-decode.test.ts
-PASS  src/test/ascii-encoder.test.ts
-PASS  src/test/ascii-parser.test.ts
-PASS  src/test/includes.test.ts
-PASS  src/test/fixml-alloc-parse.test.ts (9.433s)
-PASS  src/test/repo-full-fixml-msg.test.ts (6.025s)
-PASS  src/test/fixml-mkt-data-settle-parse.test.ts (6.021s)
-PASS  src/test/qf-full-msg.test.ts
-PASS  src/test/logon.test.ts
-PASS  src/test/fixml-mkt-data-fut-parse.test.ts (7.761s)
-PASS  src/test/time-formatter.test.ts
-PASS  src/test/ascii-segment.test.ts
-PASS  src/test/session-state.test.ts
-PASS  src/test/fixml-tc-bi-lateral-parse.test.ts (7.534s)
-PASS  src/test/ascii-tag-pos.test.ts
-PASS  src/test/fix-log-replay.test.ts
-PASS  src/test/repo-full-ascii-msg.test.ts
-PASS  src/test/session.test.ts (52.637s)
-
-Test Suites: 21 passed, 21 total
-Tests:       204 passed, 204 total
-Snapshots:   0 total
-Time:        54.606s, estimated 65s
-Ran all test suites.
-```
-
-## Dictionary Definitions
-
-base definitions on existing template e.g. quickfix format FIX44.xml
-create an alias in data/dictionary.json
-compile interfaces
-
-```shell
-npm run cmd -- --dict=repo42 --compile
-```
-
-use the alias in a session file e.g. data/session/test-httpInitiator.json
-
-## sample trade-capture-client.ts
-
-the method onApplicationMsg is called when a message is received.  In this case the client has inherited from AsciiSession which carries out the session management.
-
-```typescript
-  constructor (public readonly config: IJsFixConfig) {
-  super(config)
-  this.logReceivedMsgs = true
-  this.reports = new Dictionary<ITradeCaptureReport>()
-  this.fixLog = config.logFactory.plain(`jsfix.${config.description.application.name}.txt`)
-  this.logger = config.logFactory.logger(`${this.me}:TradeCaptureClient`)
-}
-
-protected onApplicationMsg (msgType: string, view: MsgView): void {
-  this.logger.info(`${view.toJson()}`)
-  switch (msgType) {
-  case MsgType.TradeCaptureReport: {
-      // create an object and cast to the interface
-      const tc: ITradeCaptureReport = view.toObject()
-      this.reports.addUpdate(tc.TradeReportID, tc)
-      this.logger.info(`[reports: ${this.reports.count()}] received tc ExecID = ${tc.ExecID} TradeReportID  = ${tc.TradeReportID} Symbol = ${tc.Instrument.Symbol} ${tc.LastQty} @ ${tc.LastPx}`)
-      break
-    }
-
-  case MsgType.TradeCaptureReportRequestAck: {
-      const tc: ITradeCaptureReportRequestAck = view.toObject()
-      this.logger.info(`received tcr ack ${tc.TradeRequestID} ${tc.TradeRequestStatus}`)
-      break
-    }
-  }
-}
-```
-
-the client onReady method is called when a connection is made and logon established and confirmed.  In this case, client sends a trade capture request to the server.
-
-```typescript
-  protected onReady (view: MsgView): void {
-  this.logger.info('ready')
-  const tcr: ITradeCaptureReportRequest = TradeFactory.tradeCaptureReportRequest('all-trades', new Date())
-// send request to server
-this.send(MsgType.TradeCaptureReportRequest, tcr)
-const logoutSeconds = 32
-this.logger.info(`will logout after ${logoutSeconds}`)
-setTimeout(() => {
-  this.done()
-}, logoutSeconds * 1000)
-}
-
-```
-
-## working with Views
-
-see src/test/view-decode.test.ts
-
+## Working with Messages
 
-note that a view can only be used within a callback context unless it is cloned.  Once returned, the memory is re-used for next message.  It is intended to convert to an object or parsed into an application specific message.
-
-fetch a group view
+A `MsgView` is a zero-copy view over the parse buffer. The view is only valid inside the callback that received it — clone it (`view.clone()`) if you need to hold onto it past the current tick. Most code converts the view to a typed object via `toObject()`.
 
 ```typescript
-  const noMDEntriesView: MsgView = view.getView('NoMDEntries')
-const mmEntryView: MsgView = noMDEntriesView.getGroupInstance(1)
-
-const mmEntryExpireTimeAsString: string = mmEntryView.getString('ExpireTime')
-expect(mmEntryExpireTimeAsString).toEqual('20180608-20:53:14.000')
-expect(mmEntryView.getString(126)).toEqual('20180608-20:53:14.000')
+import { ITradeCaptureReport } from 'jspurefix/dist/types/FIX4.4/repo'
+const tc: ITradeCaptureReport = view.toObject()
 ```
 
-fetch single tags
+Read a single tag by name or number:
 
 ```typescript
-  const erView: MsgView = views[0]
 expect(erView.getString(35)).toEqual('8')
 expect(erView.getString('MsgType')).toEqual('8')
-expect(erView.getString(8)).toEqual('FIX4.4')
 expect(erView.getTyped(9)).toEqual(6542)
 expect(erView.getTyped('TotNumReports')).toEqual(19404)
-expect(erView.getTyped('StrikePrice')).toEqual(52639)
 ```
 
-fetch repeated tag
+Read several tags in one call:
 
 ```typescript
-  const erView: MsgView = views[0]
-expect(erView.getStrings('PartyID')).toEqual(['magna.', 'iaculis', 'vitae,'])
+const [a, b, c, d] = view.getTypedTags([8, 9, 35, 49])
 ```
 
-fetch a set of tags
+Read all instances of a repeated tag:
 
 ```typescript
-  const [a, b, c, d] = view.getTypedTags([8, 9, 35, 49])
-expect(a).toEqual('FIX4.4')
-expect(b).toEqual(2955)
-expect(c).toEqual('W')
-expect(d).toEqual('sender-10')
+expect(erView.getStrings('PartyID')).toEqual(['magna.', 'iaculis', 'vitae,'])
 ```
 
-convert view into an object which can be used alongside an interface for intellisense.
+Drill into a repeating group or component:
 
 ```typescript
-  import { ITradeCaptureReport } from '../../../types/FIX4.4/repo/trade_capture_report'
-import { ITradeCaptureReportRequest } from '../../../types/FIX4.4/repo/trade_capture_report_request'
+const noMDEntriesView: MsgView = view.getView('NoMDEntries')
+const firstEntry: MsgView = noMDEntriesView.getGroupInstance(1)
+const expireTime: string = firstEntry.getString('ExpireTime')
 
-const tc: ITradeCaptureReport = view.toObject()
+const instrument: IInstrument = view.getView('Instrument').toObject()
 ```
 
-from data/examples/FIX.4.4/quickfix/execution-report
-
-get first in group fetched from object where group is array
+Convert nested structures in one call:
 
 ```typescript
-  import { IUndInstrmtGrp } from '../types/FIX4.4/quickfix/set/und_instrmt_grp'
-import { IUnderlyingInstrument } from '../types/FIX4.4/quickfix/set/underlying_instrument'
-const erView: MsgView = views[0]
-const undInstrmtGrpView: MsgView = erView.getView('UndInstrmtGrp')
-const undInstrmtGrpViewAsObject: IUndInstrmtGrp = undInstrmtGrpView.toObject()
-expect(undInstrmtGrpViewAsObject.NoUnderlyings.length).toEqual(2)
-const underlying0: IUnderlyingInstrument = undInstrmtGrpViewAsObject.NoUnderlyings[0].UnderlyingInstrument
-expect(underlying0.UnderlyingSymbol).toEqual('massa.')
+const legGrp: IInstrumentLeg[] = view.getView('InstrmtLegGrp.NoLegs').toObject()
 ```
 
-fetch nested structure in one call
-
-```typescript
-  const legGrpView = view.getView('InstrmtLegGrp.NoLegs')
-expect(legGrpView).toBeTruthy()
-const legGrp: IInstrumentLeg[] = legGrpView.toObject()
-expect(legGrp).toBeTruthy()
-expect(Array.isArray(legGrp))
-expect(legGrp.length).toEqual(2)
-```
-
-get a tokenised view of tags in view
+Dump a tokenised view of every tag in a message:
 
 ```typescript
 console.log(view.toString())
 ```
 
-get a component from parent - this is very low cost
+See `src/test/ascii/view-decode.test.ts` for many more examples.
 
-```typescript
- const instrumentView: MsgView = view.getView('Instrument')
-const instrumentObject: IInstrument = view.getView('Instrument').toObject()
-```
+## FIXML over HTTP
 
-## FIXML
+ASCII and FIXML sessions share the same `AsciiSession`-style application API — the framing is the only thing that changes. A small HTTP OMS demo lives at `src/sample/http/oms/`.
 
-Please see sample code src/sample/http for an example of how fixml can be used. Note regardless of using AsciiChars or Fixml application code looks very similar for example the client in this case.
+Build an order:
 
 ```typescript
-  protected onReady (view: MsgView): void {
-  this.logger.info('onReady')
-  const logoutSeconds = this.logoutSeconds
-  const req = this.factory.createOrder('IBM', Side.Buy, 10000, 100.12)
-  this.send('NewOrderSingle', req)
-  this.logger.info(`will logout after ${logoutSeconds}`)
-  setTimeout(() => {
-  this.done()
-}, 11 * 1000)
-}
-
 public createOrder (symbol: string, side: Side, qty: number, price: number): INewOrderSingle {
-  const id: number = this.id++
   return {
-    ClOrdID: `Cli${id}`,
+    ClOrdID: `Cli${this.id++}`,
     Account: this.account,
     Side: side,
     Price: price,
     OrdType: OrdType.Limit,
-    OrderQtyData: {
-      OrderQty: qty
-    } as IOrderQtyData,
+    OrderQtyData: { OrderQty: qty } as IOrderQtyData,
     Instrument: {
       Symbol: symbol,
       SecurityID: '459200101',
@@ -485,335 +335,154 @@ public createOrder (symbol: string, side: Side, qty: number, price: number): INe
 }
 ```
 
-this renders to this message sent over http
+That renders to:
 
 ```xml
 <FIXML>
-    <Order ID="Cli1" Acct="TradersRUs" Side="1" Typ="2" Px="100.12" TmInForce="1">
-        <Hdr SID="accept-comp" TID="init-comp" SSub="user123" TSub="INC"/>
-        <Instrmt Sym="IBM" ID="459200101" Src="4"/>
-        <OrdQty Qty="10000"/>
-    </Order>
+  <Order ID="Cli1" Acct="TradersRUs" Side="1" Typ="2" Px="100.12" TmInForce="1">
+    <Hdr SID="accept-comp" TID="init-comp" SSub="user123" TSub="INC"/>
+    <Instrmt Sym="IBM" ID="459200101" Src="4"/>
+    <OrdQty Qty="10000"/>
+  </Order>
 </FIXML>
 ```
 
-the server receives this message and sends back an execution report :-
+The server receives the order and produces an execution report:
 
 ```typescript
-  protected onApplicationMsg (msgType: string, view: MsgView): void {
-  // dispatch messages
-  this.logger.info(view.toJson())
-  switch (msgType) {
-  case 'Order': {
-      const order: INewOrderSingle = view.toObject()
-      this.logger.info(`received order id ${order.ClOrdID}`)
-      const fill: IExecutionReport = this.factory.fillOrder(order)
-      this.send('ExecutionReport', fill)
-    }
+protected onApplicationMsg (msgType: string, view: MsgView): void {
+  if (msgType === 'Order') {
+    const order: INewOrderSingle = view.toObject()
+    const fill: IExecutionReport = this.factory.fillOrder(order)
+    this.send('ExecutionReport', fill)
   }
 }
-
-public fillOrder (order: INewOrderSingle): IExecutionReport {
-  const id: number = this.execId++
-  return {
-    ClOrdID: order.ClOrdID,
-    OrdType: order.OrdType,
-    TransactTime: new Date(),
-    AvgPx: order.Price,
-    LeavesQty: 0,
-    LastPx: order.Price,
-    ExecType: ExecType.OrderStatus,
-    OrdStatus: OrdStatus.Filled,
-    ExecID: `exec${id}`,
-    Side: order.Side,
-    Price: order.Price,
-    OrderQtyData: {
-      OrderQty: order.OrderQtyData.OrderQty
-    } as IOrderQtyData,
-    Instrument: {
-      Symbol: order.Instrument.Symbol,
-      SecurityID: order.Instrument.SecurityID,
-      SecurityIDSource: SecurityIDSource.IsinNumber
-    } as IInstrument
-  } as IExecutionReport
-}
 ```
 
-the fixml is sent back to the client :-
+Reply on the wire:
 
 ```xml
 <FIXML>
-    <ExecRpt ID="Cli1" ExecID="exec1" ExecTyp="I" Stat="2" Side="1" Typ="2" Px="100.12" LastPx="100.12" LeavesQty="0" AvgPx="100.12" TxnTm="2018-10-07T12:16:12.584">
-        <Hdr SID="accept-comp" TID="init-comp" TSub="fix"/>
-        <Instrmt Sym="IBM" ID="459200101" Src="4"/>
-        <OrdQty Qty="10000"/>
-    </ExecRpt>
+  <ExecRpt ID="Cli1" ExecID="exec1" ExecTyp="I" Stat="2" Side="1" Typ="2"
+           Px="100.12" LastPx="100.12" LeavesQty="0" AvgPx="100.12"
+           TxnTm="2018-10-07T12:16:12.584">
+    <Hdr SID="accept-comp" TID="init-comp" TSub="fix"/>
+    <Instrmt Sym="IBM" ID="459200101" Src="4"/>
+    <OrdQty Qty="10000"/>
+  </ExecRpt>
 </FIXML>
 ```
 
-## Performance
+## Data Dictionaries
 
-These messages have been randomly generated with command line tool. They are syntactically valid.
+jspurefix ships definitions for FIX 4.0–4.4 and FIX 5.0 SP0/SP1/SP2 in both QuickFIX XML and FIX-repository formats, under bundled aliases such as `repo44`, `qf44`, `qf50sp2`. The alias map lives at `data/dictionary.json`.
 
-### data/examples/FIX.4.4/repo/execution-report/fix.txt
+To add a custom dialect:
 
-```shell
-npm run repo44-bench-er
-```
-### performance on Windows Intel Core I7-4770 @ 3.5 GHz
-```shell
-[8]: repeats = 250000, fields = 58, length = 604 chars, elapsed ms 3658, 14.632 micros per msg
-[8]: iterations = 80000, fields = 646, length = 6572 chars, elapsed ms 16499, 206.23749999999998 micros per msg
-```
-### performance on Windows 12th Gen Intel(R) Core(TM) i7-12700H 2.30 GHz
-```shell
-[8]: iterations = 80000, fields = 646, length = 6572 chars, elapsed ms 7476, 93.45 micros per msg
-```
+1. Drop your QuickFIX-style XML into `data/`.
+2. Add an alias to `data/dictionary.json`.
+3. Generate typed interfaces under `src/types`:
 
-### data/examples/FIX.4.4/repo/security-definition/fix.txt
+   ```shell
+   npm run cmd -- --dict=repo42 --compile
+   ```
 
-```shell
-npm run repo44-bench-sd
-```
+4. Reference the alias from your session description (`"dictionary": "repo42"`).
 
-### performance on Windows Intel Core I7-4770 @ 3.5 GHz
-```shell
-[d]: repeats = 150000, fields = 223, length = 2233 chars, elapsed ms 7962, 53.080000000000005 micros per msg
-d]: iterations = 150000, fields = 229, length = 2466 chars, elapsed ms 8672, 57.81333333333333 micros per msg
-```
-### performance on Windows 12th Gen Intel(R) Core(TM) i7-12700H 2.30 GHz
-```
-[d]: iterations = 150000, fields = 229, length = 2466 chars, elapsed ms 4628, 30.85333333333333 micros per msg
-```
+See [jspf-md-demo](https://github.com/TimelordUK/jspf-md-demo) for a worked example.
 
-### data/examples/FIX.4.4/repo/trade-capture/fix.txt
+## `jsfix` CLI — log parsing & stats
+
+The `jsfix-cmd` tool parses any FIX log given an appropriate dictionary.
+
+Token dump for a specific message type:
 
 ```shell
-npm run repo44-bench-tc
-```
-### performance on Windows Intel Core I7-4770 @ 3.5 GHz
-```shell
-[AE]: repeats = 30000, fields = 613, length = 5818 chars, elapsed ms 5206, 173.53333333333333 micros per msg
-[AE]: iterations = 30000, fields = 578, length = 5741 chars, elapsed ms 5245, 174.83333333333334 micros per msg```
+npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --type=AD --tokens
 ```
 
-### performance on Windows 12th Gen Intel(R) Core(TM) i7-12700H 2.30 GHz
-```shell
-[AE]: iterations = 30000, fields = 578, length = 5741 chars, elapsed ms 2725, 90.83333333333333 micros per msg```
+```
+[0] 8 (BeginString) = FIX4.4, [1] 9 (BodyLength) = 0000135
+[2] 35 (MsgType) = AD[TradeCaptureReportRequest], [3] 49 (SenderCompID) = init-comp
+[4] 56 (TargetCompID) = accept-comp, [5] 34 (MsgSeqNum) = 2
+...
 ```
 
-### data/examples/FIX.4.4/quickfix/heartbeat/fix.txt
+Per-type message counts for the file:
 
 ```shell
-npm run qf-bench-hb
+npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --stats
 ```
 
-### performance on Windows Intel Core I7-4770 @ 3.5 GHz
-```shell
-[0]: iterations = 250000, fields = 10, length = 131 chars, elapsed ms 950, 3.8 micros per msg
+```json
+{ "0": 1, "5": 2, "A": 2, "AD": 1, "AQ": 2, "AE": 5 }
 ```
-### performance on Windows 12th Gen Intel(R) Core(TM) i7-12700H 2.30 GHz
-```shell
-[0]: iterations = 250000, fields = 10, length = 131 chars, elapsed ms 468, 1.8719999999999999 micros per msg
-````
 
-### data/examples/FIX.4.4/quickfix/logon/fix.txt
+Convert to typed objects:
 
 ```shell
-npm run qf-bench-lo
+npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --type=AD --objects
 ```
 
-### performance on Windows Intel Core I7-4770 @ 3.5 GHz
+Show the parser's view of nested structures within a message:
+
 ```shell
-[A]: iterations = 250000, fields = 22, length = 214 chars, elapsed ms 1466, 5.864 micros per msg
+npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --type=AD --structures
 ```
-### performance on Windows 12th Gen Intel(R) Core(TM) i7-12700H 2.30 GHz
+
+Repeat-parse for benchmarking (`--repeats=N`):
+
 ```shell
-[A]: iterations = 250000, fields = 22, length = 214 chars, elapsed ms 693, 2.7720000000000002 micros per msg
+npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --stats --repeats=20
 ```
 
-## Log parsing
+## Performance
 
-the command line tool jsfix can be used to parse any fix log providing an appropriate dictionary is provided.
+Numbers below are illustrative — generated messages, single-threaded, parser-only (no I/O). Run them yourself with the corresponding `npm run` script.
 
-## parsing fields
+| Benchmark | Script | Fields/msg | Length (chars) | I7-4770 @ 3.5 GHz | i7-12700H @ 2.3 GHz | Ryzen 9 7950X @ 4.5 GHz |
+| --- | --- | --- | --- | --- | --- | --- |
+| Heartbeat | `npm run qf-bench-hb` | 10 | 131 | 3.8 µs/msg | 1.9 µs/msg | 1.7 µs/msg |
+| Logon | `npm run qf-bench-lo` | 22 | 214 | 5.9 µs/msg | 2.8 µs/msg | 2.5 µs/msg |
+| Execution Report (large) | `npm run repo44-bench-er` | 646 | 6 571 | 206.2 µs/msg | 93.5 µs/msg | 72.9 µs/msg |
+| Security Definition † | `npm run repo44-bench-sd` | 52 | 557 | — | — | 5.6 µs/msg |
+| Trade Capture † | `npm run repo44-bench-tc` | 112 | 1 137 | — | — | 9.3 µs/msg |
 
-```shell
-npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --type=AD --tokens
-```
+† The SD and TC fixtures have shrunk since the older measurements were taken (SD was 229 fields / 2 466 chars, TC was 578 fields / 5 741 chars), so the prior numbers aren't comparable with the current fixture and have been dropped from the row. Re-running them on the older hardware would produce a clean third column. Ryzen measurements taken on Node 24 LTS, WSL2.
 
-```shell
-[0] 8 (BeginString) = FIX4.4, [1] 9 (BodyLength) = 0000135
-[2] 35 (MsgType) = AD[TradeCaptureReportRequest], [3] 49 (SenderCompID) = init-comp
-[4] 56 (TargetCompID) = accept-comp, [5] 34 (MsgSeqNum) = 2
-[6] 57 (TargetSubID) = fix, [7] 52 (SendingTime) = 20180923-16:07:04.763
-[8] 568 (TradeRequestID) = all-trades, [9] 569 (TradeRequestType) = 0[AllTrades]
-[10] 263 (SubscriptionRequestType) = 1[SnapshotAndUpdates], [11] 580 (NoDates) = 1
-[12] 75 (TradeDate) = 20180923, [13] 10 (CheckSum) = 250
-```
+## Developing on jspurefix
 
-## stats on entire file
+Clone and build:
 
 ```shell
-npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --stats
-```
-
-```json
-messages 13 elapsed ms 8
-{
-  "0": 1,
-  "5": 2,
-  "A": 2,
-  "AD": 1,
-  "AQ": 2,
-  "AE": 5
-}
+git clone https://github.com/TimelordUK/jspurefix.git
+cd jspurefix
+npm install         # postinstall unpacks the FIX dictionaries
+npm run build
 ```
 
-## benchmark parsing repeated reads of file
+Run the test suite (Jest, single worker, with coverage):
 
-```cmd
-npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --stats --repeats=20
-```
-
-```json
-messages 13 elapsed ms 0
-{
-  "0": 1,
-  "5": 2,
-  "A": 2,
-  "AD": 1,
-  "AQ": 2,
-  "AE": 5
-}
+```shell
+npm test
 ```
 
-## parse message type in a file
+The full suite currently runs 535 tests across 43 suites and takes ~70 s on a modern laptop. `script/build.sh` (unix) and `script\build.cmd` (windows) wrap install + build + test if you want a one-shot bootstrap.
 
-```cmd
-npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --type=AD --objects
-```
+Try a sample end-to-end:
 
-```json
-{
-  "StandardHeader": {
-    "BeginString": "FIX4.4",
-    "BodyLength": 135,
-    "MsgType": "AD",
-    "SenderCompID": "init-comp",
-    "TargetCompID": "accept-comp",
-    "MsgSeqNum": 2,
-    "TargetSubID": "fix",
-    "SendingTime": "2018-09-23T16:07:04.763Z"
-  },
-  "TradeRequestID": "all-trades",
-  "TradeRequestType": 0,
-  "SubscriptionRequestType": "1",
-  "TrdCapDtGrp": [
-    {
-      "TradeDate": "2018-09-22T23:00:00.000Z"
-    }
-  ],
-  "StandardTrailer": {
-    "CheckSum": "250"
-  }
-}
+```shell
+npm run tcp-tc      # trade-capture client + server
 ```
 
-as above where --type=AE --objects
+## C# Port
 
-```json
-{
-  "StandardHeader": {
-    "BeginString": "FIX4.4",
-    "BodyLength": 213,
-    "MsgType": "AE",
-    "SenderCompID": "accept-comp",
-    "TargetCompID": "init-comp",
-    "MsgSeqNum": 4,
-    "TargetSubID": "fix",
-    "SendingTime": "2018-09-23T16:07:04.986Z"
-  },
-  "TradeReportID": "100001",
-  "TradeReportTransType": 0,
-  "TradeReportType": 0,
-  "TrdType": 0,
-  "ExecID": "600001",
-  "OrdStatus": "2",
-  "PreviouslyReported": false,
-  "Instrument": {
-    "Symbol": "Gold",
-    "SecurityID": "Gold.INC"
-  },
-  "LastQty": 107,
-  "LastPx": 45.38,
-  "TradeDate": "2018-09-22T23:00:00.000Z",
-  "TransactTime": "2018-09-23T16:07:04.776Z",
-  "StandardTrailer": {
-    "CheckSum": "54"
-  }
-}
-```
+This engine has been ported to C# as [cspurefix](https://github.com/TimelordUK/cspurefix), which is kept in lockstep with this codebase. If you're on .NET:
 
-## show all structures within a message
+- **Source**: [TimelordUK/cspurefix](https://github.com/TimelordUK/cspurefix)
+- **Demo**: [TimelordUK/purefix-standalone-demo](https://github.com/TimelordUK/purefix-standalone-demo)
+- **NuGet**: [PureFix.Types.Core](https://www.nuget.org/packages/PureFix.Types.Core/)
 
-```shell
-npm run cmd -- --dict=repo44 --fix=data/examples/FIX.4.4/jsfix.test_client.txt --delimiter="|" --type=AD --structures
-```
+## License
 
-```json
-[
-  {
-    "name": "StandardHeader",
-    "depth": 2,
-    "startTag": 8,
-    "startPosition": 0,
-    "endTag": 52,
-    "endPosition": 7,
-    "delimiterTag": 0,
-    "delimiterPositions": []
-  },
-  {
-    "name": "TrdCapDtGrp",
-    "depth": 1,
-    "startTag": 580,
-    "startPosition": 11,
-    "endTag": 75,
-    "endPosition": 12,
-    "delimiterTag": 75,
-    "delimiterPositions": [
-      12
-    ]
-  },
-  {
-    "name": "StandardTrailer",
-    "depth": 1,
-    "startTag": 10,
-    "startPosition": 13,
-    "endTag": 10,
-    "endPosition": 13,
-    "delimiterTag": 0,
-    "delimiterPositions": []
-  },
-  {
-    "name": "TradeCaptureReportRequest",
-    "depth": 1,
-    "startTag": 8,
-    "startPosition": 0,
-    "endTag": 10,
-    "endPosition": 13,
-    "delimiterTag": 0,
-    "delimiterPositions": []
-  },
-  {
-    "name": "StandardTrailer",
-    "depth": 0,
-    "startTag": 10,
-    "startPosition": 14,
-    "endTag": 10,
-    "endPosition": 13,
-    "delimiterTag": 0,
-    "delimiterPositions": []
-  }
-]
-```
+MIT. See [LICENSE](./LICENSE).