Merge pull request #473 from fasenderos/response-order-object

feat: order now will be returned as object

BREAKING CHANGE: The OrderBook previously returned an instance of the BaseOrder class (new BaseOrder()) for its orders. With this update, it now returns the underlying plain object instead

Author: fasenderos

README.md

@@ -393,6 +393,8 @@ A `snapshot` represents the state of the order book at a specific point in time.
 Snapshots are crucial for restoring the order book to a previous state. The orderbook can restore from a snapshot before processing any journal logs, ensuring consistency and accuracy.
 After taking the snapshot, you can safely remove all logs preceding the `lastOp` id.
 
+**Note**: The snapshot of the order book returns an object containing an `array` of `bids` and `asks`, which in turn are arrays of order objects. If the snapshot is saved to the database as a `string`, make sure to pass the snapshot in its original format when initializing the order book. For example, you can achieve this by using `JSON.parse` to convert the string back into its original object form.
+
 ```js
 const ob = new OrderBook({ enableJournaling: true})
 

src/order.ts

@@ -13,6 +13,7 @@ import {
 	type Side,
 	type TimeInForce,
 } from "./types";
+import { safeStringify } from "./utils";
 
 abstract class BaseOrder {
 	readonly _id: string;
@@ -141,7 +142,7 @@ export class LimitOrder extends BaseOrder {
     makerQty: ${this._makerQty}
     takerQty: ${this._takerQty}`;
 
-	toJSON = (): string => JSON.stringify(this.toObject());
+	toJSON = (): string | null => safeStringify(this.toObject());
 
 	toObject = (): ILimitOrder => ({
 		id: this._id,
@@ -184,7 +185,7 @@ export class StopMarketOrder extends BaseOrder {
     stopPrice: ${this._stopPrice}
     time: ${this._time}`;
 
-	toJSON = (): string => JSON.stringify(this.toObject());
+	toJSON = (): string | null => safeStringify(this.toObject());
 
 	toObject = (): IStopMarketOrder => ({
 		id: this._id,
@@ -249,10 +250,11 @@ export class StopLimitOrder extends BaseOrder {
     size: ${this._size}
     price: ${this._price}
     stopPrice: ${this._stopPrice}
+	isOCO: ${this.isOCO}
     timeInForce: ${this._timeInForce}
     time: ${this._time}`;
 
-	toJSON = (): string => JSON.stringify(this.toObject());
+	toJSON = (): string | null => safeStringify(this.toObject());
 
 	toObject = (): IStopLimitOrder => ({
 		id: this._id,
@@ -261,6 +263,7 @@ export class StopLimitOrder extends BaseOrder {
 		size: this._size,
 		price: this._price,
 		stopPrice: this._stopPrice,
+		isOCO: this.isOCO,
 		timeInForce: this._timeInForce,
 		time: this._time,
 	});

src/orderbook.ts

@@ -12,12 +12,13 @@ import { StopBook } from "./stopbook";
 import {
 	type CreateOrderOptions,
 	type ICancelOrder,
+	type ILimitOrder,
+	type IOrder,
 	type IProcessOrder,
 	type JournalLog,
 	type LimitOrderOptions,
 	type MarketOrderOptions,
 	type OCOOrderOptions,
-	type Order,
 	type OrderBookOptions,
 	OrderType,
 	type OrderUpdatePrice,
@@ -346,8 +347,8 @@ export class OrderBook {
 	 * @param orderID - The ID of the order to be returned
 	 * @returns The order if exists or `undefined`
 	 */
-	public order = (orderID: string): LimitOrder | undefined => {
-		return this.orders[orderID];
+	public order = (orderID: string): ILimitOrder | undefined => {
+		return this.orders[orderID]?.toObject();
 	};
 
 	// Returns price levels and volume at price level
@@ -412,13 +413,13 @@ export class OrderBook {
 	};
 
 	public snapshot = (): Snapshot => {
-		const bids: Array<{ price: number; orders: LimitOrder[] }> = [];
-		const asks: Array<{ price: number; orders: LimitOrder[] }> = [];
+		const bids: Array<{ price: number; orders: ILimitOrder[] }> = [];
+		const asks: Array<{ price: number; orders: ILimitOrder[] }> = [];
 		this.bids.priceTree().forEach((price: number, orders: OrderQueue) => {
-			bids.push({ price, orders: orders.toArray() });
+			bids.push({ price, orders: orders.toArray().map((o) => o.toObject()) });
 		});
 		this.asks.priceTree().forEach((price: number, orders: OrderQueue) => {
-			asks.push({ price, orders: orders.toArray() });
+			asks.push({ price, orders: orders.toArray().map((o) => o.toObject()) });
 		});
 		return { bids, asks, ts: Date.now(), lastOp: this._lastOp };
 	};
@@ -534,7 +535,7 @@ export class OrderBook {
 				isOCO: true,
 			});
 			this.stopBook.add(stopLimit);
-			response.done.push(stopLimit);
+			response.done.push(stopLimit.toObject());
 		} else {
 			response.err = CustomError(ERROR.INVALID_CONDITIONAL_ORDER);
 		}
@@ -547,7 +548,7 @@ export class OrderBook {
 	): IProcessOrder => {
 		if (this.stopBook.validConditionalOrder(this._marketPrice, stopOrder)) {
 			this.stopBook.add(stopOrder);
-			response.done.push(stopOrder);
+			response.done.push(stopOrder.toObject());
 		} else {
 			response.err = CustomError(ERROR.INVALID_CONDITIONAL_ORDER);
 		}
@@ -558,15 +559,17 @@ export class OrderBook {
 		this._lastOp = snapshot.lastOp;
 		for (const level of snapshot.bids) {
 			for (const order of level.orders) {
-				this.orders[order.id] = order;
-				this.bids.append(order);
+				const newOrder = OrderFactory.createOrder(order);
+				this.orders[newOrder.id] = newOrder;
+				this.bids.append(newOrder);
 			}
 		}
 
 		for (const level of snapshot.asks) {
 			for (const order of level.orders) {
-				this.orders[order.id] = order;
-				this.asks.append(order);
+				const newOrder = OrderFactory.createOrder(order);
+				this.orders[newOrder.id] = newOrder;
+				this.asks.append(newOrder);
 			}
 		}
 	};
@@ -586,16 +589,14 @@ export class OrderBook {
 		delete this.orders[orderID];
 		const side = order.side === Side.BUY ? this.bids : this.asks;
 		const response: ICancelOrder = {
-			order: side.remove(order),
+			order: side.remove(order)?.toObject(),
 		};
 
 		// Delete OCO Order only when the delete request comes from user
 		if (!internalDeletion && order.ocoStopPrice !== undefined) {
-			response.stopOrder = this.stopBook.remove(
-				order.side,
-				orderID,
-				order.ocoStopPrice,
-			);
+			response.stopOrder = this.stopBook
+				.remove(order.side, orderID, order.ocoStopPrice)
+				?.toObject();
 		}
 
 		if (this.enableJournaling) {
@@ -698,16 +699,16 @@ export class OrderBook {
 			});
 			if (response.done.length > 0) {
 				response.partialQuantityProcessed = size - quantityToTrade;
-				response.partial = order;
+				response.partial = order.toObject();
 			}
 			this.orders[orderID] = sideToAdd.append(order);
 		} else {
 			let totalQuantity = 0;
 			let totalPrice = 0;
 
-			response.done.forEach((order: Order) => {
+			response.done.forEach((order: IOrder) => {
 				totalQuantity += order.size;
-				totalPrice += (order as LimitOrder).price * order.size;
+				totalPrice += (order as ILimitOrder).price * order.size;
 			});
 
 			if (response.partialQuantityProcessed > 0 && response.partial !== null) {
@@ -728,7 +729,7 @@ export class OrderBook {
 				takerQty,
 				makerQty,
 			});
-			response.done.push(order);
+			response.done.push(order.toObject());
 		}
 
 		// If IOC order was not matched completely remove from the order book
@@ -787,7 +788,7 @@ export class OrderBook {
 						response,
 					);
 				}
-				response.activated.push(stopOrder);
+				response.activated.push(stopOrder.toObject());
 			});
 		}
 	};
@@ -914,13 +915,14 @@ export class OrderBook {
 				const headOrder = orderQueue.head();
 				if (headOrder !== undefined) {
 					if (response.quantityLeft < headOrder.size) {
-						response.partial = OrderFactory.createOrder({
+						const partial = OrderFactory.createOrder({
 							...headOrder.toObject(),
 							size: headOrder.size - response.quantityLeft,
 						});
-						this.orders[headOrder.id] = response.partial;
+						response.partial = partial.toObject();
+						this.orders[headOrder.id] = partial;
 						response.partialQuantityProcessed = response.quantityLeft;
-						orderQueue.update(headOrder, response.partial);
+						orderQueue.update(headOrder, partial);
 						response.quantityLeft = 0;
 					} else {
 						response.quantityLeft = response.quantityLeft - headOrder.size;

src/types.ts

@@ -152,6 +152,7 @@ export interface IStopLimitOrder {
 	stopPrice: number;
 	timeInForce: TimeInForce;
 	time: number;
+	isOCO: boolean;
 }
 
 /**
@@ -168,16 +169,19 @@ export type StopOrderOptions =
 	| StopLimitOrderOptions
 	| OCOOrderOptions;
 
+export type IStopOrder = IStopLimitOrder | IStopMarketOrder;
+export type IOrder = ILimitOrder | IStopOrder;
+
 /**
  * Represents the result of processing an order.
  */
 export interface IProcessOrder {
 	/** Array of fully processed orders. */
-	done: Order[];
+	done: IOrder[];
 	/** Array of activated (stop limit or stop market) orders */
-	activated: StopOrder[];
+	activated: IStopOrder[];
 	/** The partially processed order, if any. */
-	partial: LimitOrder | null;
+	partial: ILimitOrder | null;
 	/** The quantity that has been processed in the partial order. */
 	partialQuantityProcessed: number;
 	/** The remaining quantity that needs to be processed. */
@@ -331,8 +335,8 @@ export type CreateOrderOptions =
  * Represents a cancel order operation.
  */
 export interface ICancelOrder {
-	order: LimitOrder;
-	stopOrder?: StopOrder;
+	order: ILimitOrder;
+	stopOrder?: IStopOrder;
 	/** Optional log related to the order cancellation. */
 	log?: CancelOrderJournalLog;
 }
@@ -386,14 +390,14 @@ export interface Snapshot {
 		/** Price of the ask order */
 		price: number;
 		/** List of orders associated with this price */
-		orders: LimitOrder[];
+		orders: ILimitOrder[];
 	}>;
 	/** List of bid orders, each with a price and a list of associated orders */
 	bids: Array<{
 		/** Price of the bid order */
 		price: number;
 		/** List of orders associated with this price */
-		orders: LimitOrder[];
+		orders: ILimitOrder[];
 	}>;
 	/** Unix timestamp representing when the snapshot was taken */
 	ts: number;

src/utils.ts

@@ -0,0 +1,18 @@
+/* node:coverage ignore next - Don't know why this line is uncovered */
+// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+export const safeStringify = (value: any): string | null => {
+	try {
+		return JSON.stringify(value);
+	} catch (error) {
+		return null;
+	}
+};
+
+/* node:coverage ignore next - Don't know why this line is uncovered */
+export const safeParse = <T>(value: string): T | null => {
+	try {
+		return JSON.parse(value);
+	} catch (error) {
+		return null;
+	}
+};

test/order.test.ts

@@ -45,7 +45,7 @@ void test("it should create LimitOrder", () => {
 		assert.equal(order.makerQty, size);
 		assert.equal(order.takerQty, 0);
 		assert.equal(order.ocoStopPrice, undefined);
-		assert.deepEqual(order.toObject(), {
+		assert.deepStrictEqual(order.toObject(), {
 			id,
 			type,
 			side,
@@ -115,7 +115,7 @@ void test("it should create LimitOrder", () => {
 		assert.equal(order.makerQty, size);
 		assert.equal(order.takerQty, 0);
 		assert.equal(order.ocoStopPrice, ocoStopPrice);
-		assert.deepEqual(order.toObject(), {
+		assert.deepStrictEqual(order.toObject(), {
 			id,
 			type,
 			side,
@@ -181,7 +181,7 @@ void test("it should create StopMarketOrder", () => {
 	assert.equal(order.size, size);
 	assert.equal(order.stopPrice, stopPrice);
 	assert.equal(order.time, time);
-	assert.deepEqual(order.toObject(), {
+	assert.deepStrictEqual(order.toObject(), {
 		id,
 		type,
 		side,
@@ -242,13 +242,14 @@ void test("it should create StopLimitOrder", () => {
 		assert.equal(order.timeInForce, timeInForce);
 		assert.equal(order.time, time);
 		assert.equal(order.isOCO, false);
-		assert.deepEqual(order.toObject(), {
+		assert.deepStrictEqual(order.toObject(), {
 			id,
 			type,
 			side,
 			size,
 			price,
 			stopPrice,
+			isOCO: false,
 			timeInForce,
 			time,
 		});
@@ -260,6 +261,7 @@ void test("it should create StopLimitOrder", () => {
     size: ${size}
     price: ${price}
     stopPrice: ${stopPrice}
+	isOCO: false
     timeInForce: ${timeInForce}
     time: ${time}`,
 		);
@@ -272,6 +274,7 @@ void test("it should create StopLimitOrder", () => {
 				size,
 				price,
 				stopPrice,
+				isOCO: false,
 				timeInForce,
 				time,
 			}),
@@ -306,13 +309,14 @@ void test("it should create StopLimitOrder", () => {
 		assert.equal(order.timeInForce, timeInForce);
 		assert.equal(order.time, time);
 		assert.equal(order.isOCO, true);
-		assert.deepEqual(order.toObject(), {
+		assert.deepStrictEqual(order.toObject(), {
 			id,
 			type,
 			side,
 			size,
 			price,
 			stopPrice,
+			isOCO: true,
 			timeInForce,
 			time,
 		});
@@ -324,6 +328,7 @@ void test("it should create StopLimitOrder", () => {
     size: ${size}
     price: ${price}
     stopPrice: ${stopPrice}
+	isOCO: true
     timeInForce: ${timeInForce}
     time: ${time}`,
 		);
@@ -336,6 +341,7 @@ void test("it should create StopLimitOrder", () => {
 				size,
 				price,
 				stopPrice,
+				isOCO: true,
 				timeInForce,
 				time,
 			}),
@@ -376,7 +382,7 @@ void test("it should create order without passing a date or id", (t) => {
 	});
 	assert.equal(order.id, fakeId);
 	assert.equal(order.time, fakeTimestamp);
-	assert.deepEqual(order.toObject(), {
+	assert.deepStrictEqual(order.toObject(), {
 		id: fakeId,
 		type,
 		side,