A simple yet robust order matching engine implementation for financial markets, supporting limit/market orders with price-time and pro-rata matching algorithms.

npm install node-matching-engine

import { 
  MatchingEngine, 
  MatchingAlgorithm, 
  OrderSide, 
  OrderType 
} from 'node-matching-engine'


// Create engines with different algorithms
const priceTimeEngine = new MatchingEngine() // default
const proRataEngine = new MatchingEngine(MatchingAlgorithm.PRO_RATA)

// Pro-Rata matching example
const engine = new MatchingEngine(MatchingAlgorithm.PRO_RATA)

// Add larger quantity order (later time)
engine.match({
  id: '1',
  price: 100,
  side: OrderSide.BID,
  quantity: 10,
  time: Date.now() + 1,
  type: OrderType.LIMIT
})

// Add smaller quantity order (earlier time)
engine.match({
  id: '2',
  price: 100,
  side: OrderSide.BID,
  quantity: 5,
  time: Date.now(),
  type: OrderType.LIMIT
})

// Matching ask order
const trades = engine.match({
  id: '3',
  price: 100,
  side: OrderSide.ASK,
  quantity: 8,
  time: Date.now(),
  type: OrderType.LIMIT
})

// Execution order: Larger quantity (10) first, then smaller (5)
// Trades: [{bidOrderId: '1', quantity: 8}, ...]

• Supported Order Types

  • Limit Orders
  • Market Orders
  • Immediate-or-Cancel (IOC) semantics for unfilled quantities

• Matching Algorithms

  • Price-Time Priority (default)
  • Pro-Rata (proportional allocation)
  • Configurable algorithm selection during engine initialization

• Matching Logic

  • Bid/Ask sorting:
    • Price-Time:
      • Bids: Descending price → Ascending time
      • Asks: Ascending price → Ascending time
    • Pro-Rata:
      • Bids: Descending price → Descending quantity → Ascending time
      • Asks: Ascending price → Descending quantity → Ascending time
  • Partial order fills supported
  • Market orders never enter order book

1. Price priority
2. Time priority (earlier orders first)

1. Price priority
2. Quantity priority (larger orders first)
3. Time priority (earlier orders first)

• Single instrument support only
• No hybrid matching algorithms
• No minimum volume thresholds for pro-rata
• No order execution visualization
• No advanced order types (stop orders, etc.)
• No performance optimizations for large order books

The engine throws specific errors for:

• Order validation failures (OrderValidationError)
• Trading while disabled (TradingDisabledError)

Comprehensive test suite covering:

• Basic matching scenarios
• Partial fills
• Price-time priority
• Market order execution
• Error conditions
• Order book state management

Run tests: npm test:unit

• Stop-Loss orders
• Take-Profit orders
• Trailing Stop orders
• Iceberg orders (hidden quantity)
• Fill-or-Kill (FOK) execution

• Order cancellation by ID
• Order modification support
• Time-in-Force (TTL) for orders
• Conditional orders (based on market triggers)

• Binary heap implementation for price levels
• Order ID indexing for fast lookups
• Batch order processing
• Order book snapshot caching

• Real-time spread calculation
• Depth of Market (DOM) visualization
• Trade history persistence
• Volume-Weighted Average Price (VWAP)

• WebSocket API for real-time updates
• FIX protocol support
• Plugin architecture for extensions
• Market data simulator

• Multi-instrument support
• Auction mode implementation
• Backtesting framework
• Role-based access control
• Audit trail and event logging