Products API (Node + TypeScript)

A REST API built with Node.js, TypeScript, and Express, following Clean Architecture principles. It handles product management via CSV uploads, background processing, and advanced filtering.

Getting Started

Prerequisites

• Node.js (v18+)
• npm

Installation & Running

1. Navigate to the API directory:

   cd api

2. Install dependencies:

   npm install

3. Start the development server:

   docker-compose up --build

   The API will be available at http://localhost:3000.

4. Run tests:

   npm test

Architecture

The project follows Clean Architecture to ensure separation of concerns, testability, and maintainability.

Folder Structure

api/src/
├── application/       # Business logic orchestration
│   └── use-cases/     # Application specific business rules (e.g., ListProducts, ProcessUpload)
├── domain/            # Enterprise business rules (Core)
│   ├── entities/      # Domain objects (e.g., Product)
│   ├── ports/         # Interfaces for external services (e.g., JobQueue)
│   ├── repositories/  # Interfaces for data persistence
│   └── services/      # Domain services interfaces
├── infrastructure/    # External implementations
│   ├── controllers/   # HTTP request handlers
│   ├── parsers/       # CSV parsing logic
│   ├── repositories/  # Concrete repository implementations (e.g., InMemory, Postgres)
│   └── services/      # Concrete service implementations (e.g., ExchangeRate)
├── shared/            # Shared utilities and types (e.g., Result type)
└── main.ts            # Application entry point and dependency injection

Endpoints

Products

• GET /products

  • Retrieve a paginated list of products with filtering and sorting.
  • Query Params:
    • page: Page number (default: 1)
    • limit: Items per page (default: 20)
    • name: Filter by product name
    • minPrice: Minimum price
    • maxPrice: Maximum price
    • sortBy: Field to sort by (name, price, expiration)
    • order: Sort direction (asc, desc)

• POST /products/upload

  • Upload a CSV file for background processing.
  • Body: multipart/form-data with field file.
  • Response: Returns a jobId to track status.

• GET /products/upload/:jobId

  • Check the status of an upload job.

Tech Stack

• Runtime: Node.js
• Language: TypeScript
• Framework: Express
• Testing: Jest
• Validation: Zod
• CSV Processing: fast-csv