nodejs-order-book 10.0.0 → 10.1.1

package/README.md

@@ -29,6 +29,7 @@ Ultra-fast Node.js Order Book written in TypeScript </br> for high-frequency tra
   - [Create OCO (One-Cancels-the-Other) order `oco()`](#create-oco-one-cancels-the-other-order)
   - [Modify an existing order `modifiy()`](#modify-an-existing-order)
   - [Cancel order `cancel()`](#cancel-order)
+- [Self-Trade Prevention (STP)](#self-trade-prevention-stp)
 - [Order Book Options](#order-book-options)
   - [Snapshot](#snapshot)
   - [Journal Logs](#journal-logs)
@@ -50,6 +51,7 @@ Ultra-fast Node.js Order Book written in TypeScript </br> for high-frequency tra
 - Supports `post-only` limit order <img src="https://img.shields.io/badge/New-green" alt="New">
 - Supports conditional orders [**Stop Limit, Stop Market and OCO**](#conditional-orders) <img src="https://img.shields.io/badge/New-green" alt="New">
 - Supports time in force GTC, FOK and IOC <img src="https://img.shields.io/badge/New-green" alt="New">
+- Support [Self-Trade Prevention (STP)](#self-trade-prevention-stp)
 - Supports order cancelling
 - Supports order price and/or size updating <img src="https://img.shields.io/badge/New-green" alt="New">
 - Snapshot and journaling functionalities for restoring the order book during server startup <img src="https://img.shields.io/badge/New-green" alt="New">
@@ -63,19 +65,19 @@ Ultra-fast Node.js Order Book written in TypeScript </br> for high-frequency tra
 
 Install with npm:
 
-```sh
+```
 npm install nodejs-order-book
 ```
 
 Install with yarn:
 
-```sh
+```
 yarn add nodejs-order-book
 ```
 
 Install with pnpm:
 
-```sh
+```
 pnpm add nodejs-order-book
 ```
 
@@ -83,7 +85,7 @@ pnpm add nodejs-order-book
 
 To start using order book you need to import `OrderBook` and create new instance:
 
-```js
+```ts
 import { OrderBook } from 'nodejs-order-book'
 
 const ob = new OrderBook()
@@ -91,20 +93,39 @@ const ob = new OrderBook()
 
 Then you'll be able to use next primary functions:
 
-```js
-ob.createOrder({ type: 'limit' | 'market', side: 'buy' | 'sell', size: number, price?: number, id?: string, postOnly?: boolean, timeInForce?: 'GTC' | 'FOK' | 'IOC' })
+```ts
+ob.createOrder({
+      type: 'limit' | 'market',
+      side: 'buy' | 'sell',
+      size: number,
+      price?: number,
+      id?: string,
+      postOnly?: boolean,
+      timeInForce?: 'GTC' | 'FOK' | 'IOC'
+})
 
-ob.limit({ id: string, side: 'buy' | 'sell', size: number, price: number, postOnly?: boolean, timeInForce?: 'GTC' | 'FOK' | 'IOC' })
+ob.limit({
+      id: string,
+      side: 'buy' | 'sell',
+      size: number,
+      price: number,
+      postOnly?: boolean,
+      timeInForce?: 'GTC' | 'FOK' | 'IOC'
+})
 
 ob.market({ side: 'buy' | 'sell', size: number })
 
-ob.modify(orderID: string, { side: 'buy' | 'sell', size: number, price: number })
+ob.modify(orderID: string, { 
+      side: 'buy' | 'sell',
+      size: number,
+      price: number
+})
 
 ob.cancel(orderID: string)
 ```
 ### Conditional Orders
 Currently `Stop Market`, `Stop Limit` and `OCO` orders are supported.
-```js
+```ts
 import { OrderBook } from 'nodejs-order-book'
 
 const ob = new OrderBook()
@@ -153,26 +174,59 @@ To add an order to the order book you can call the general `createOrder()` funct
 
 ### Create Order
 
-```js
+```ts
 // Create limit order
-ob.createOrder({ type: 'limit', side: 'buy' | 'sell', size: number, price: number, id: string, postOnly?: boolean, timeInForce?: 'GTC' | 'FOK' | 'IOC' })
+ob.createOrder({
+      type: 'limit',
+      side: 'buy' | 'sell',
+      size: number,
+      price: number,
+      id: string,
+      postOnly?: boolean,
+      timeInForce?: 'GTC' | 'FOK' | 'IOC'
+})
 
 // Create market order
-ob.createOrder({ type: 'market', side: 'buy' | 'sell', size: number })
+ob.createOrder({
+      type: 'market',
+      side: 'buy' | 'sell',
+      size: number
+})
 
 // Create stop limit order
-ob.createOrder({ type: 'stop_limit', side: 'buy' | 'sell', size: number, price: number, id: string, stopPrice: number, timeInForce?: 'GTC' | 'FOK' | 'IOC' })
+ob.createOrder({
+      type: 'stop_limit',
+      side: 'buy' | 'sell',
+      size: number,
+      price: number,
+      id: string,
+      stopPrice: number,
+      timeInForce?: 'GTC' | 'FOK' | 'IOC'
+})
 
 // Create stop market order
-ob.createOrder({ type: 'stop_market', side: 'buy' | 'sell', size: number, stopPrice: number })
+ob.createOrder({
+      type: 'stop_market',
+      side: 'buy' | 'sell',
+      size: number,
+      stopPrice: number
+})
 
 // Create OCO order
-ob.createOrder({ type: 'oco', side: 'buy' | 'sell', size: number, stopPrice: number, stopLimitPrice: number, timeInForce?: 'GTC' | 'FOK' | 'IOC', stopLimitTimeInForce?: 'GTC' | 'FOK' | 'IOC' })
+ob.createOrder({
+      type: 'oco',
+      side: 'buy' | 'sell',
+      size: number,
+      stopPrice: number,
+      stopLimitPrice: number,
+      timeInForce?: 'GTC' | 'FOK' | 'IOC',
+      stopLimitTimeInForce?: 'GTC' | 'FOK' | 'IOC'
+})
 ```
 
 ### Create Limit Order
 
-```js
+```ts
 /**
  * Create a limit order. See {@link LimitOrderOptions} for details.
  *
@@ -185,12 +239,19 @@ ob.createOrder({ type: 'oco', side: 'buy' | 'sell', size: number, stopPrice: num
  * @param options.timeInForce - Time-in-force type supported are: GTC, FOK, IOC. Default is GTC
  * @returns An object with the result of the processed order or an error. See {@link IProcessOrder} for the returned data structure
  */
-ob.limit({ side: 'buy' | 'sell', id: string, size: number, price: number, postOnly?: boolean, timeInForce?: 'GTC' | 'FOK' | 'IOC' })
+ob.limit({
+      side: 'buy' | 'sell',
+      id: string,
+      size: number,
+      price: number,
+      postOnly?: boolean,
+      timeInForce?: 'GTC' | 'FOK' | 'IOC'
+})
 ```
 
 For example:
 
-```
+```ts
 ob.limit({ side: "sell", id: "uniqueID", size: 55, price: 100 })
 
 asks: 110 -> 5      110 -> 5
@@ -203,7 +264,7 @@ done    - null
 partial - null
 ```
 
-```
+```ts
 ob.limit({ side: "buy", id: "uniqueID", size: 7, price: 120 })
 
 asks: 110 -> 5
@@ -217,7 +278,7 @@ done    - 2 (or more orders)
 partial - uniqueID order
 ```
 
-```
+```ts
 ob.limit({ side: "buy", id: "uniqueID", size: 3, price: 120 })
 
 asks: 110 -> 5
@@ -232,7 +293,7 @@ partial - 1 order with price 110
 
 ### Create Market Order
 
-```js
+```ts
 /**
  * Create a market order. See {@link MarketOrderOptions} for details.
  *
@@ -246,7 +307,7 @@ ob.market({ side: 'buy' | 'sell', size: number })
 
 For example:
 
-```
+```ts
 ob.market({ side: 'sell', size: 6 })
 
 asks: 110 -> 5      110 -> 5
@@ -260,7 +321,7 @@ partial      - 1 order with price 80
 quantityLeft - 0
 ```
 
-```
+```ts
 ob.market({ side: 'buy', size: 10 })
 
 asks: 110 -> 5
@@ -276,7 +337,7 @@ quantityLeft - 4
 
 ### Create Stop Limit Order
 
-```js
+```ts
 /**
  * Create a stop limit order. See {@link StopLimitOrderOptions} for details.
  *
@@ -289,12 +350,19 @@ quantityLeft - 4
  * @param options.timeInForce - Time-in-force type supported are: GTC, FOK, IOC. Default is GTC
  * @returns An object with the result of the processed order or an error. See {@link IProcessOrder} for the returned data structure
  */
-ob.stopLimit({ side: 'buy' | 'sell', id: string, size: number, price: number, stopPrice: number, timeInForce?: 'GTC' | 'FOK' | 'IOC' })
+ob.stopLimit({
+      side: 'buy' | 'sell',
+      id: string,
+      size: number,
+      price: number,
+      stopPrice: number,
+      timeInForce?: 'GTC' | 'FOK' | 'IOC'
+})
 ```
 
 ### Create Stop Market Order
 
-```js
+```ts
 /**
  * Create a stop market order. See {@link StopMarketOrderOptions} for details.
  *
@@ -304,12 +372,16 @@ ob.stopLimit({ side: 'buy' | 'sell', id: string, size: number, price: number, st
  * @param options.stopPrice - The price at which the order will be triggered.
  * @returns An object with the result of the processed order or an error. See {@link IProcessOrder} for the returned data structure
  */
-ob.stopMarket({ side: 'buy' | 'sell', size: number, stopPrice: number })
+ob.stopMarket({
+      side: 'buy' | 'sell',
+      size: number,
+      stopPrice: number
+})
 ```
 
 ### Create OCO (One-Cancels-the-Other) Order
 
-```js
+```ts
 /**
  * Create an OCO (One-Cancels-the-Other) order.
  * OCO order combines a `stop_limit` order and a `limit` order, where if stop price
@@ -333,12 +405,21 @@ ob.stopMarket({ side: 'buy' | 'sell', size: number, stopPrice: number })
  * @param options.stopLimitTimeInForce - Time-in-force of the `stop_limit` order. Type supported are: GTC, FOK, IOC. Default is GTC
  * @returns An object with the result of the processed order or an error. See {@link IProcessOrder} for the returned data structure
  */
-ob.oco({ side: 'buy' | 'sell', id: string, size: number, price: number, stopPrice: number, stopLimitPrice: number, timeInForce?: 'GTC' | 'FOK' | 'IOC', stopLimitTimeInForce?: 'GTC' | 'FOK' | 'IOC' })
+ob.oco({
+      side: 'buy' | 'sell',
+      id: string,
+      size: number,
+      price: number,
+      stopPrice: number,
+      stopLimitPrice: number,
+      timeInForce?: 'GTC' | 'FOK' | 'IOC',
+      stopLimitTimeInForce?: 'GTC' | 'FOK' | 'IOC'
+})
 ```
 
 ### Modify an existing order
 
-```js
+```ts
 /**
  * Modify an existing order with given ID. When an order is modified by price or quantity,
  * it will be deemed as a new entry. Under the price-time-priority algorithm, orders are
@@ -354,7 +435,7 @@ ob.modify(orderID: string, { size: number, price: number })
 
 For example:
 
-```
+```ts
 ob.limit({ side: "sell", id: "uniqueID", size: 55, price: 100 })
 
 asks: 110 -> 5      110 -> 5
@@ -385,7 +466,7 @@ bids: 90  -> 5      90  -> 5
 
 ### Cancel Order
 
-```js
+```ts
 /**
  * Remove an existing order with given ID from the order book
  *
@@ -397,7 +478,7 @@ ob.cancel(orderID: string)
 
 For example:
 
-```
+```ts
 ob.cancel("myUniqueID-Sell-1-with-100")
 
 asks: 110 -> 5
@@ -407,6 +488,202 @@ bids: 90  -> 5      90  -> 5
       80  -> 1      80  -> 1
 ```
 
+## Self-Trade Prevention (STP)
+
+> Inspired by [Binance's Self-Trade Prevention](https://developers.binance.com/docs/derivatives/usds-margined-futures/faq/stp-faq) — prevents orders from the same account from matching against each other.
+
+### How it works
+
+Each order can carry an `accountId` and a `stpMode`. When a taker order enters the book and would match against a maker order with the same `accountId`, the STP mode of the **taker order** determines what happens:
+
+| Mode | Effect |
+|------|--------|
+| `NONE` | No prevention — orders match normally |
+| `EXPIRE_MAKER` | The resting maker order(s) expire; the taker order continues |
+| `EXPIRE_TAKER` | The taker order is rejected; the resting maker order(s) stay on the book |
+| `EXPIRE_BOTH` | Both the taker and the matching maker order(s) expire |
+
+The STP mode of the **taker** order always takes precedence — the mode stored on a resting maker order is ignored for STP purposes.
+
+### API reference
+
+Add `accountId` and `stpMode` to any order:
+
+```ts
+import { OrderBook, SelfTradePreventionMode, Side } from 'nodejs-order-book'
+
+const ob = new OrderBook()
+
+// Place a resting limit order from account "alice"
+ob.limit({
+  side: Side.BUY,
+  id: 'maker-order',
+  size: 5,
+  price: 100,
+  accountId: 'alice',
+})
+
+// Taker from the same account with STP enabled
+const result = ob.limit({
+  side: Side.SELL,
+  id: 'taker-order',
+  size: 3,
+  price: 90,
+  accountId: 'alice',
+  stpMode: SelfTradePreventionMode.EXPIRE_MAKER,
+})
+
+// Check which orders expired due to STP
+console.log(result.stpExpired) // [{ id: 'maker-order', ... }]
+```
+
+### Response fields
+
+When STP is triggered, the response (`IProcessOrder`) includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stpExpired` | `IOrder[] \| undefined` | Orders that were removed from the book due to STP |
+| `err` | `OrderBookError \| null` | Error with `code: 1202` and `message: "Self-trade prevention triggered"` for `EXPIRE_TAKER` / `EXPIRE_BOTH` |
+
+### Error code
+
+STP rejections return error code `1202`:
+
+```ts
+import { ErrorCodes } from 'nodejs-order-book'
+
+assert.equal(result.err?.code, ErrorCodes.STP_TRIGGERED)
+// → 1202
+assert.equal(result.err?.message, 'Self-trade prevention triggered')
+```
+
+### Scenarios
+
+#### A) EXPIRE_MAKER — maker expires, taker continues
+
+```
+Maker BUY  @ 100  qty: 5  account: "alice"
+Maker BUY  @  90  qty: 5  account: "alice"
+Taker SELL @  90  qty: 3  account: "alice"  mode: EXPIRE_MAKER
+```
+
+The two resting buy orders share the same account as the taker. With `EXPIRE_MAKER`, they are removed from the book and reported in `stpExpired[]`. The taker order (size 3) is placed on the book as a new maker.
+
+```
+stpExpired → [maker-buy-100, maker-buy-90]
+err        → null
+```
+
+#### B) EXPIRE_TAKER — taker expires, maker stays
+
+```
+Maker BUY @ 100  qty: 5  account: "alice"
+Taker SELL @ 90  qty: 3  account: "alice"  mode: EXPIRE_TAKER
+```
+
+The taker order is rejected immediately. The resting maker order remains untouched on the book.
+
+```
+stpExpired → undefined
+err        → { code: 1202, message: "Self-trade prevention triggered" }
+```
+
+#### C) EXPIRE_BOTH — both orders expire
+
+```
+Maker BUY @ 100  qty: 5  account: "alice"
+Taker SELL @ 90  qty: 3  account: "alice"  mode: EXPIRE_BOTH
+```
+
+The maker is removed from the book and the taker is rejected. Both sides expire.
+
+```
+stpExpired → [maker-buy-100]
+err        → { code: 1202, message: "Self-trade prevention triggered" }
+```
+
+#### D) Different accounts — normal matching (no STP)
+
+```
+Maker BUY @ 100  qty: 5  account: "alice"
+Taker SELL @ 90  qty: 3  account: "bob"  mode: EXPIRE_MAKER
+```
+
+The accounts differ, so STP does **not** trigger. The orders match normally.
+
+```
+done   → [filled trade summary]
+stpExpired → undefined
+```
+
+#### E) Mode NONE — no prevention
+
+```
+Maker BUY @ 100  qty: 5  account: "alice"
+Taker SELL @ 90  qty: 3  account: "alice"  mode: NONE
+```
+
+Even though both orders are from the same account, `NONE` mode allows the match.
+
+```
+done   → [filled trade summary]
+stpExpired → undefined
+```
+
+#### F) Market order with EXPIRE_MAKER
+
+```
+Maker BUY @ 100  qty: 5  account: "alice"
+Taker SELL (market)  qty: 3  account: "alice"  mode: EXPIRE_MAKER
+```
+
+The resting maker is expired via STP. The market order has no remaining liquidity, so it also expires.
+
+```
+stpExpired → [maker-buy-100]
+err        → null
+```
+
+#### G) Mixed accounts at the same price level
+
+```
+Maker "alice" BUY @ 100  qty: 5
+Maker "bob"   BUY @ 100  qty: 5
+Taker "alice" SELL @ 90  qty: 8  mode: EXPIRE_MAKER
+```
+
+At price level 100, alice's maker is expired (`stpExpired`), while bob's maker matches normally (`done`). The remaining taker quantity (3) rests on the book.
+
+```
+stpExpired → [maker-alice-100]
+done       → [maker-bob-100]
+```
+
+#### H) STP carries through triggered stop orders
+
+Stop orders preserve the `stpMode` they were created with. When a stop order is triggered and becomes a taker, its STP mode is applied at match time.
+
+```ts
+ob.createOrder({
+  type: OrderType.STOP_LIMIT,
+  side: Side.BUY,
+  size: 3,
+  price: 110,
+  stopPrice: 108,
+  accountId: 'alice',
+  stpMode: SelfTradePreventionMode.EXPIRE_MAKER,
+})
+```
+
+### Important notes
+
+- STP is evaluated using the **taker order's** mode, regardless of what mode the resting maker orders carry.
+- If no `accountId` is specified on either side, STP is **not** triggered (backward compatible).
+- If no `stpMode` is specified, it defaults to `NONE` (no prevention).
+- Stop market and stop limit orders preserve the `stpMode` and apply it when triggered.
+- Modify operations reset `stpMode` to `NONE`.
+
 ## Order Book Options
 
 The orderbook can be initialized with the following options by passing them to the constructor:
@@ -425,7 +702,7 @@ After taking the snapshot, you can safely remove all logs preceding the `lastOp`
 
 **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
+```ts
 const ob = new OrderBook({ enableJournaling: true})
 
 // after every order save the log to the database
@@ -449,7 +726,7 @@ const ob = new OrderBook({ snapshot: JSON.parse(snapshot), journal: log, enableJ
 
 ### Journal Logs
 The `journal` option expects an array of journal logs that you can get by setting `enableJournaling` to true. When the journal is provided, the order book will replay all the operations, bringing the order book to the same state as the last log.
-```js
+```ts
 // Assuming 'logs' is an array of log entries retrieved from the database
 
 const logs = await getLogs()
@@ -459,7 +736,7 @@ By combining snapshots with journaling, you can effectively restore and audit th
 
 ### Enable Journaling
 `enabledJournaling` is a configuration setting that determines whether journaling is enabled or disabled. When enabled, the property `log` will be added to the body of the response for each operation. The logs must be saved to the database and can then be used when a new instance of the order book is instantiated.
-```js
+```ts
 const ob = new OrderBook({ enableJournaling: true }) // false by default
 
 // after every order save the log to the database
@@ -473,7 +750,7 @@ await saveLog(order.log)
 
 Build production (distribution) files in your dist folder:
 
-```sh
+```
 npm run build
 ```
 
@@ -481,7 +758,7 @@ npm run build
 
 To run all the unit-test
 
-```sh
+```
 npm run test
 ```
 
@@ -489,7 +766,7 @@ npm run test
 
 Run testing coverage
 
-```sh
+```
 npm run test:cov
 ```
 
@@ -497,7 +774,7 @@ npm run test:cov
 
 Before running benchmark, make sure to have built the source code with `npm run build` first
 
-```sh
+```
 npm run bench
 ```