Merge pull request #435 from ayshadogo/feat/order-book

Order Book Service (storage, queries, snapshots)

Author: DevMuhdishaq

.freebuff/project-id

@@ -1 +0,0 @@
-7abb7b97-ecb7-44ec-9f88-a47b534dbacd

src/orders/dto/order-book-query.dto.ts

@@ -0,0 +1,15 @@
+import { IsOptional, IsInt, Min, Max } from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class OrderBookQueryDto {
+  /**
+   * Number of price levels to return per side (bids/asks).
+   * Defaults to 10, max 100.
+   */
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  depth?: number = 10;
+}

src/orders/dto/paginated-orders.dto.ts

@@ -0,0 +1,25 @@
+import { IsOptional, IsInt, Min, Max, IsEnum } from 'class-validator';
+import { Type } from 'class-transformer';
+import { OrderStatus } from '../../common/enums/order-type.enum';
+
+export class PaginatedOrdersQueryDto {
+  /** Page number (1-indexed). */
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  /** Items per page (default 20, max 100). */
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 20;
+
+  /** Filter by order status. */
+  @IsOptional()
+  @IsEnum(OrderStatus)
+  status?: OrderStatus;
+}

src/orders/listeners/order-book-update.listener.spec.ts

@@ -0,0 +1,100 @@
+// Mock the problematic imports that aren't installed in the test env
+jest.mock('@nestjs/websockets', () => ({}));
+jest.mock('socket.io', () => ({ Server: jest.fn() }));
+jest.mock('uuid', () => ({ v4: jest.fn(() => 'test-uuid') }));
+
+import { Test, TestingModule } from '@nestjs/testing';
+import { OrderBookUpdateListener } from './order-book-update.listener';
+import { WebSocketService } from '../../websocket/services/websocket.service';
+import type { OrderBookResponse } from '../services/order-book.service';
+
+const mockWebSocketService = {
+  broadcastOrderBookUpdate: jest.fn(),
+  broadcastOrderUpdate: jest.fn(),
+  broadcastTradeExecution: jest.fn(),
+};
+
+describe('OrderBookUpdateListener', () => {
+  let listener: OrderBookUpdateListener;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        OrderBookUpdateListener,
+        { provide: WebSocketService, useValue: mockWebSocketService },
+      ],
+    }).compile();
+
+    listener = module.get(OrderBookUpdateListener);
+  });
+
+  describe('handleOrderBookUpdate', () => {
+    it('should broadcast order book update with correct shape', () => {
+      const response: OrderBookResponse = {
+        assetId: 1,
+        pair: 'BTC',
+        topOfBook: {
+          bestBid: { price: 99, amount: 5, count: 1 },
+          bestAsk: { price: 101, amount: 3, count: 1 },
+          spread: 2,
+          midPrice: 100,
+        },
+        bids: [
+          { price: 99, amount: 5, count: 1 },
+          { price: 98, amount: 10, count: 2 },
+        ],
+        asks: [
+          { price: 101, amount: 3, count: 1 },
+          { price: 102, amount: 8, count: 3 },
+        ],
+        timestamp: '2026-08-20T12:00:00.000Z',
+        sequence: 42,
+      };
+
+      listener.handleOrderBookUpdate(response);
+
+      expect(mockWebSocketService.broadcastOrderBookUpdate).toHaveBeenCalledWith({
+        asset: '1',
+        bids: [
+          { price: 99, amount: 5, count: 1 },
+          { price: 98, amount: 10, count: 2 },
+        ],
+        asks: [
+          { price: 101, amount: 3, count: 1 },
+          { price: 102, amount: 8, count: 3 },
+        ],
+        timestamp: '2026-08-20T12:00:00.000Z',
+        sequence: 42,
+      });
+    });
+
+    it('should handle empty order book', () => {
+      const response: OrderBookResponse = {
+        assetId: 2,
+        pair: 'ETH',
+        topOfBook: {
+          bestBid: null,
+          bestAsk: null,
+          spread: null,
+          midPrice: null,
+        },
+        bids: [],
+        asks: [],
+        timestamp: '2026-08-20T12:00:00.000Z',
+        sequence: 1,
+      };
+
+      listener.handleOrderBookUpdate(response);
+
+      expect(mockWebSocketService.broadcastOrderBookUpdate).toHaveBeenCalledWith({
+        asset: '2',
+        bids: [],
+        asks: [],
+        timestamp: '2026-08-20T12:00:00.000Z',
+        sequence: 1,
+      });
+    });
+  });
+});

src/orders/listeners/order-book-update.listener.ts

@@ -0,0 +1,43 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { WebSocketService } from '../../websocket/services/websocket.service';
+import type { OrderBookResponse } from '../services/order-book.service';
+
+/**
+ * Listens for order book update events emitted by OrderBookService and
+ * broadcasts them to WebSocket subscribers on the `orderbook:<assetId>`
+ * channel. This satisfies the acceptance criteria:
+ *   "Order book updates streamed to subscribed clients within 1s of change
+ *    for top-of-book."
+ *
+ * The event is emitted synchronously by EventEmitter2 after every order
+ * mutation (place, cancel, fill), so subscribers see changes nearly
+ * instantly — well within the 1-second requirement.
+ */
+@Injectable()
+export class OrderBookUpdateListener {
+  private readonly logger = new Logger(OrderBookUpdateListener.name);
+
+  constructor(private readonly webSocketService: WebSocketService) {}
+
+  @OnEvent('orderbook.update')
+  handleOrderBookUpdate(response: OrderBookResponse): void {
+    const channel = `orderbook:${response.assetId}`;
+
+    this.webSocketService.broadcastOrderBookUpdate({
+      asset: String(response.assetId),
+      bids: response.topOfBook.bestBid
+        ? [response.topOfBook.bestBid, ...response.bids.slice(1)]
+        : response.bids,
+      asks: response.topOfBook.bestAsk
+        ? [response.topOfBook.bestAsk, ...response.asks.slice(1)]
+        : response.asks,
+      timestamp: response.timestamp,
+      sequence: response.sequence,
+    });
+
+    this.logger.debug(
+      `Broadcast order book update for asset ${response.assetId} to channel ${channel} (seq=${response.sequence})`,
+    );
+  }
+}