@sotatech/nest-fixparser

@sotatech/nest-fixparser là một thư viện NestJS để xử lý giao thức FIX (Financial Information Exchange). Thư viện cung cấp các decorator và service mạnh mẽ để quản lý kết nối, xử lý message và sự kiện FIX một cách dễ dàng.

Tính năng

• Quản lý kết nối FIX:

  • Hỗ trợ nhiều kết nối đồng thời
  • Tự động reconnect với chiến lược backoff tùy chỉnh
  • EventEmitter2 integration cho xử lý sự kiện

• Decorators mạnh mẽ:

  • @OnFixMessage() - Lắng nghe message từ connection cụ thể
  • @OnFixMessageBroadcast() - Lắng nghe message từ TẤT CẢ connections ⭐ MỚI
  • @OnFixConnected() / @OnFixConnectedBroadcast() - Sự kiện kết nối thành công
  • @OnFixError() / @OnFixErrorBroadcast() - Xử lý lỗi
  • @OnFixClose() / @OnFixCloseBroadcast() - Sự kiện đóng kết nối

• NestJS 11 Compatible ⭐ MỚI:

  • Đã loại bỏ ModuleRef đã deprecated
  • Tương thích hoàn toàn với NestJS 11

• Cấu hình linh hoạt:

  • forRoot() - Cấu hình tĩnh
  • forRootAsync() - Cấu hình bất đồng bộ với useFactory trả về mảng connections ⭐ CẬP NHẬT

• Types đầy đủ:

  • FixMessageBroadCast - Message với thông tin connection
  • FixErrorBroadCast - Error với thông tin connection
  • FixConnectedBroadCast - Event kết nối thành công
  • FixCloseBroadCast - Event đóng kết nối

Installation

npm install @sotatech/nest-fixparser

Quick Start

1. Cấu hình Module

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { FixparserModule } from '@sotatech/nest-fixparser';

@Module({
  imports: [
    FixparserModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: async (configService: ConfigService) => {
        const fixConnections = configService.get('configs.fix_connections');
        const mappedConnections = fixConnections.map(conn => ({
          options: conn,
          connectionName: `${conn.type}_${conn.member_code}`,
        }));
        return mappedConnections;
      },
    }),
  ],
})
export class FixConnectionModule {}

2. Sử dụng Decorators

import { Injectable } from '@nestjs/common';
import {
  OnFixMessage,
  OnFixMessageBroadcast,
  OnFixConnectedBroadcast,
  OnFixErrorBroadcast,
  Messages,
  FixMessageBroadCast,
  FixConnectedBroadCast,
  FixErrorBroadCast
} from '@sotatech/nest-fixparser';

@Injectable()
export class FixMessageHandler {
  // Lắng nghe message từ một connection cụ thể
  @OnFixMessage(Messages.NewOrderSingle, 'MD_603')
  handleOrderMessage(message: Message) {
    console.log('New order received:', message);
  }

  // Lắng nghe TẤT CẢ order messages từ TẤT CẢ connections ⭐ MỚI
  @OnFixMessageBroadcast(Messages.NewOrderSingle)
  handleAllOrderMessages(data: FixMessageBroadCast) {
    console.log(`Order from ${data.connectionName}:`, data.message);
  }

  // Lắng nghe TẤT CẢ messages từ TẤT CẢ connections ⭐ MỚI
  @OnFixMessageBroadcast()
  handleAllMessages(data: FixMessageBroadCast) {
    console.log(`Message from ${data.connectionName}:`, data.message);
  }

  // Lắng nghe sự kiện kết nối thành công từ tất cả connections
  @OnFixConnectedBroadcast()
  handleConnectionConnected(data: FixConnectedBroadCast) {
    console.log(`Connection ${data.connectionName} is ready`);
  }

  // Lắng nghe lỗi từ tất cả connections
  @OnFixErrorBroadcast()
  handleConnectionError(data: FixErrorBroadCast) {
    console.error(`Error from ${data.connectionName}:`, data.error.message);
  }
}

3. Sử dụng FixConnectionManager

import { Injectable } from '@nestjs/common';
import { FixConnectionManager } from '@sotatech/nest-fixparser';

@Injectable()
export class FixService {
  constructor(
    private readonly connectionManager: FixConnectionManager,
  ) {}

  async sendOrder(connectionName: string, orderData: any) {
    const connection = this.connectionManager.getConnection(connectionName);

    const message = {
      messageType: Messages.NewOrderSingle,
      // ... order data
    };

    connection.send(message);
  }

  async sendRequestAndWaitResponse(
    connectionName: string,
    requestMessage: Message,
    responseMessageType: string,
    timeout = 5000
  ): Promise<Message> {
    return this.connectionManager.sendRequest(
      connectionName,
      requestMessage,
      responseMessageType,
      timeout
    );
  }
}

Cấu hình chi tiết

Connection Options

const connectionOptions = {
  host: '127.0.0.1',
  port: 9877,
  type: 'MD', // 'MD' hoặc 'TD'
  protocol: 'tcp',
  sender: 'SENDER_ID',
  target: 'TARGET_ID',
  fixVersion: 'FIX.4.4',
  heartbeatIntervalSeconds: 30,
  // ... các options khác

  // Reconnect options (tự động thiết lập nếu không cung cấp)
  reconnect: {
    initialDelay: 1000,
    exponentialBackoff: true,
    maxDelay: 30000,
  }
};

Environment Variables Example

# config/fix.config.ts
export const fixConnections = [
  {
    member_code: 603,
    host: '171.244.199.144',
    port: 9877,
    type: 'MD',
    protocol: 'tcp',
    sender: 'TVKD117',
    target: 'MXVMDGW',
    fixVersion: 'FIX.4.4',
    logging: false,
    heartbeatIntervalSeconds: 30,
    account: 'TVKD_001',
    password: 'password'
  },
  {
    member_code: 603,
    host: '171.244.199.144',
    port: 9877,
    type: 'TD',
    protocol: 'tcp',
    sender: 'TVKD117',
    target: 'MXVMDGW',
    fixVersion: 'FIX.4.4',
    logging: false,
    heartbeatIntervalSeconds: 30,
    account: 'TVKD_001',
    password: 'password'
  }
];

Cập nhật từ phiên bản cũ

Breaking Changes v0.0.20

1. NestJS 11 Compatibility

   • ModuleRef đã được loại bỏ khỏi FixConnectionManager
   • Khắc phục lỗi dependency injection

2. forRootAsync Update

   • useFactory bây giờ trả về ConnectionConfig[] thay vì single config
   • Mỗi config có options và connectionName

3. Broadcast Decorators ⭐ MỚI

   • @OnFixMessageBroadcast() - Lắng nghe từ tất cả connections
   • @OnFixConnectedBroadcast() - Event connected từ tất cả
   • @OnFixErrorBroadcast() - Error từ tất cả
   • @OnFixCloseBroadcast() - Close event từ tất cả

4. Types mới ⭐ MỚI

   • FixMessageBroadCast
   • FixErrorBroadCast
   • FixConnectedBroadCast
   • FixCloseBroadCast

Migration Guide

// Cách cũ - forRootAsync
FixparserModule.forRootAsync({
  useFactory: () => ({
    host: '127.0.0.1',
    port: 9877,
    //...
  })
})

// Cách mới - forRootAsync
FixparserModule.forRootAsync({
  useFactory: () => [{
    options: {
      host: '127.0.0.1',
      port: 9877,
      //...
    },
    connectionName: 'primary'
  }]
})

Advanced Usage

Custom Message Handler

@Injectable()
export class CustomFixHandler {
  @OnFixMessageBroadcast(Messages.ExecutionReport)
  async handleExecutionReport(data: FixMessageBroadCast) {
    const { connectionName, message } = data;

    // Xử lý logic business
    if (message.ExecType === 'FILL') {
      console.log(`Fill from ${connectionName}:`, message);
      // Update database, notify users, etc.
    }
  }
}

Error Handling

@Injectable()
export class FixErrorHandler {
  @OnFixErrorBroadcast()
  handleError(data: FixErrorBroadCast) {
    const { connectionName, error } = data;

    // Log error
    console.error(`[${connectionName}] Connection error:`, error);

    // Send alert
    this.alertService.send({
      level: 'ERROR',
      message: `FIX connection ${connectionName} error: ${error.message}`,
      timestamp: new Date()
    });
  }
}

Connection Monitoring

@Injectable()
export class FixMonitorService {
  private connectionsStatus = new Map<string, boolean>();

  @OnFixConnectedBroadcast()
  onConnected(data: FixConnectedBroadCast) {
    this.connectionsStatus.set(data.connectionName, true);
    console.log(`✅ ${data.connectionName} connected`);
  }

  @OnFixCloseBroadcast()
  onClosed(data: FixCloseBroadCast) {
    this.connectionsStatus.set(data.connectionName, false);
    console.log(`❌ ${data.connectionName} closed`);
  }

  getAllConnectionsStatus() {
    return Object.fromEntries(this.connectionsStatus);
  }
}

Sử dụng components từ @sotatech/node-fixjs

Thư viện này đã export tất cả các thành phần từ @sotatech/node-fixjs để bạn không cần cài thêm.

Import các thành phần

// Cách 1: Import từ thư viện chính
import {
  FIXParser,
  FIXServer,
  Field,
  Message,
  Constants
} from '@sotatech/nest-fixparser';

// Cách 2: Import từ module node-fixjs
import {
  FIXParser,
  FIXServer
} from '@sotatech/nest-fixparser/node-fixjs';

Ví dụ sử dụng

// Tạo FIX Parser
const parser = new FIXParser();

// Thiết lập event handlers
parser.onMessage = (message) => {
  console.log('Received FIX message:', message);
};

parser.onOpen = () => {
  console.log('Connected to FIX server');
};

// Kết nối đến server
parser.connect({
  host: 'localhost',
  port: 8192,
  protocol: 'tcp',
  sender: 'SENDER',
  target: 'TARGET',
  fixVersion: 'FIX.4.4'
});

// Tạo FIX Server
const server = new FIXServer({
  host: 'localhost',
  port: 8192,
  protocol: 'tcp'
});

server.onMessage = (message) => {
  console.log('Server received:', message);
};

server.start();

Components có sẵn

Tất cả các thành phần từ @sotatech/node-fixjs đều available:

• Classes: FIXParser, FIXServer
• Components: Field, Message, Logger, MessageBuffer
• Constants: Constants với tất cả FIX tags và message types
• Enums: EncryptMethod, ResetSeqNumFlag, etc.
• Types: Các TypeScript types cho FIX protocol

Xem thêm: NODE_FIXJS_EXPORTS.md

Testing với Yalc

Để test thư viện ở local với yalc:

# 1. Cài đặt yalc
npm install -g yalc

# 2. Build thư viện
pnpm run build

# 3. Publish với yalc
yalc publish

# 4. Trong project test
yalc add @sotatech/nest-fixparser

# 5. Khi có thay đổi
yalc publish
yalc update @sotatech/nest-fixparser

License

MIT License - xem file LICENSE để biết chi tiết

Contributing

Contributions are welcome! Please open an issue hoặc submit pull request.

Support

For issues hoặc questions: GitHub Issues