Skip to content

Latest commit

 

History

History
183 lines (141 loc) · 3.63 KB

README.md

File metadata and controls

183 lines (141 loc) · 3.63 KB

FXQL (Foreign Exchange Query Language) Parser

Project Overview

This project implements a custom parsing system for Foreign Exchange (FXQL) statements, allowing users to define currency pair transactions with buy, sell, and cap amounts.

Table of Contents

Features

  • Parse complex Foreign Exchange statements
  • Validate currency pairs and transaction amounts
  • Store parsed statements in a database
  • Comprehensive error handling
  • Supports multiple currency pair statements in a single request

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (v18+ recommended)
  • npm or yarn
  • PostgreSQL (or your preferred database)
  • Docker (optional, for containerization)

Local Development Setup

1. Clone the Repository

 git clone https://github.com/hamzzy/fxql-parser-api.git
 cd fxql-parser

2. Install Dependencies

npm install
# or
yarn install

3. Set Up Environment Variables

Create a .env file in the project root with the following variables:

POSTGRES_NAME=""
POSTGRES_USER=""
POSTGRES_PASSWORD=""
# Database Connection
DATABASE_URL="postgresql://username:password@localhost:5432/fxql_db?schema=public"

# Application Configuration
PORT=3000

4. Initialize Database

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Optional: Seed initial data
npx prisma db seed

5. Run the Application

# Development mode
npm run start:dev
# or
yarn start:dev

# Production mode
npm run start:prod
# or
yarn start:prod

Docker

# Build Docker image
docker compose up

API Documentation

Documentation : https://fxql-parser.up.railway.app/api

Endpoint: POST https://fxql-parser.up.railway.app/fxql-statements

Request Payload

{
  "FXQL": "USD-GBP {\\n  BUY 0.85\\n  SELL 0.90\\n  CAP 10000\\n}"
}

Successful Response

{
  "message": "FXQL Statement Parsed Successfully.",
  "code": "FXQL-200",
  "data": [
    {
      "EntryId": 1,
      "SourceCurrency": "USD",
      "DestinationCurrency": "GBP",
      "SellPrice": 0.85,
      "BuyPrice": 100,
      "CapAmount": 10000
    }
  ]
}

Error Response

{
  "message": "Invalid currency format",
  "code": "FXQL-400",
  "details": "Specific error information"
}

Design Decisions

Parsing Strategy

  • Lexer-Parser architecture for robust statement parsing
  • Stateless parsing with comprehensive error collection
  • Support for multiple statements in a single request

Currency Validation

  • Strict 3-letter uppercase currency code validation
  • Predefined list of supported currencies
  • Prevents parsing of unsupported or malformed currency pairs

Error Handling

  • Granular error tracking
  • Preserves parsing context (line, column)
  • Returns multiple errors if present
  • Provides clear, actionable error messages

Performance Considerations

  • Atomic database transactions
  • Efficient input normalization
  • Limit of 1000 currency pairs per request to prevent system overload

Testing

Running Tests

# Unit tests
npm run test
# or
yarn test

# Coverage report
npm run test:cov
# or
yarn test:cov

Troubleshooting

  • Ensure all environment variables are correctly set
  • Check database connectivity
  • Verify Node.js and npm versions
  • Review application logs for detailed error information