nodejs-order-book 10.0.1 → 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">
@@ -486,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:

package/dist/cjs/errors.js

@@ -1,5 +1,4 @@
 "use strict";
-var _a, _b;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CustomError = exports.OrderBookError = exports.ErrorMessages = exports.ErrorCodes = exports.ERROR = void 0;
 var ERROR;
@@ -19,63 +18,66 @@ var ERROR;
     ERROR["LIMIT_ORDER_POST_ONLY"] = "LIMIT_ORDER_POST_ONLY";
     ERROR["ORDER_ALREDY_EXISTS"] = "ORDER_ALREDY_EXISTS";
     ERROR["ORDER_NOT_FOUND"] = "ORDER_NOT_FOUND";
+    ERROR["STP_TRIGGERED"] = "STP_TRIGGERED";
 })(ERROR || (exports.ERROR = ERROR = {}));
-exports.ErrorCodes = (_a = {},
+exports.ErrorCodes = {
     // 10xx General issues
-    _a[ERROR.DEFAULT] = 1000,
+    [ERROR.DEFAULT]: 1000,
     // 11xx Request issues
-    _a[ERROR.INVALID_ORDER_TYPE] = 1100,
-    _a[ERROR.INVALID_SIDE] = 1101,
-    _a[ERROR.INVALID_QUANTITY] = 1102,
-    _a[ERROR.INVALID_PRICE] = 1103,
-    _a[ERROR.INVALID_PRICE_OR_QUANTITY] = 1104,
-    _a[ERROR.INVALID_TIF] = 1105,
-    _a[ERROR.LIMIT_ORDER_FOK_NOT_FILLABLE] = 1106,
-    _a[ERROR.LIMIT_ORDER_POST_ONLY] = 1107,
-    _a[ERROR.INVALID_CONDITIONAL_ORDER] = 1108,
-    _a[ERROR.ORDER_ALREDY_EXISTS] = 1109,
-    _a[ERROR.ORDER_NOT_FOUND] = 1110,
+    [ERROR.INVALID_ORDER_TYPE]: 1100,
+    [ERROR.INVALID_SIDE]: 1101,
+    [ERROR.INVALID_QUANTITY]: 1102,
+    [ERROR.INVALID_PRICE]: 1103,
+    [ERROR.INVALID_PRICE_OR_QUANTITY]: 1104,
+    [ERROR.INVALID_TIF]: 1105,
+    [ERROR.LIMIT_ORDER_FOK_NOT_FILLABLE]: 1106,
+    [ERROR.LIMIT_ORDER_POST_ONLY]: 1107,
+    [ERROR.INVALID_CONDITIONAL_ORDER]: 1108,
+    [ERROR.ORDER_ALREDY_EXISTS]: 1109,
+    [ERROR.ORDER_NOT_FOUND]: 1110,
     // 12xx Internal error
-    _a[ERROR.INSUFFICIENT_QUANTITY] = 1200,
-    _a[ERROR.INVALID_PRICE_LEVEL] = 1201,
-    _a[ERROR.INVALID_JOURNAL_LOG] = 1201,
-    _a);
-exports.ErrorMessages = (_b = {},
-    _b[ERROR.DEFAULT] = "Something wrong",
-    _b[ERROR.INSUFFICIENT_QUANTITY] = "Insufficient quantity to calculate price",
-    _b[ERROR.INVALID_CONDITIONAL_ORDER] = "Stop-Limit Order (BUY: marketPrice < stopPrice <= price, SELL: marketPrice > stopPrice >= price). Stop-Market Order (BUY: marketPrice < stopPrice, SELL: marketPrice > stopPrice). OCO order (BUY: price < marketPrice < stopPrice, SELL: price > marketPrice > stopPrice)",
-    _b[ERROR.INVALID_ORDER_TYPE] = "Supported order type are 'limit' and 'market'",
-    _b[ERROR.INVALID_PRICE] = "Invalid order price",
-    _b[ERROR.INVALID_PRICE_LEVEL] = "Invalid order price level",
-    _b[ERROR.INVALID_PRICE_OR_QUANTITY] = "Invalid order price or quantity",
-    _b[ERROR.INVALID_QUANTITY] = "Invalid order quantity",
-    _b[ERROR.INVALID_SIDE] = "Invalid side: must be either 'sell' or 'buy'",
-    _b[ERROR.INVALID_TIF] = "Invalid TimeInForce: must be one of 'GTC', 'IOC' or 'FOK'",
-    _b[ERROR.LIMIT_ORDER_FOK_NOT_FILLABLE] = "Limit FOK order not fillable",
-    _b[ERROR.LIMIT_ORDER_POST_ONLY] = "Post-only limit order rejected because would execute immediately",
-    _b[ERROR.ORDER_ALREDY_EXISTS] = "Order already exists",
-    _b[ERROR.ORDER_NOT_FOUND] = "Order not found",
-    _b[ERROR.INVALID_JOURNAL_LOG] = "Invalid journal log format",
-    _b);
-var OrderBookError = /** @class */ (function () {
-    function OrderBookError(error) {
-        var _a;
-        var errorMessage;
+    [ERROR.INSUFFICIENT_QUANTITY]: 1200,
+    [ERROR.INVALID_PRICE_LEVEL]: 1201,
+    [ERROR.INVALID_JOURNAL_LOG]: 1201,
+    [ERROR.STP_TRIGGERED]: 1202,
+};
+exports.ErrorMessages = {
+    [ERROR.DEFAULT]: "Something wrong",
+    [ERROR.INSUFFICIENT_QUANTITY]: "Insufficient quantity to calculate price",
+    [ERROR.INVALID_CONDITIONAL_ORDER]: "Stop-Limit Order (BUY: marketPrice < stopPrice <= price, SELL: marketPrice > stopPrice >= price). Stop-Market Order (BUY: marketPrice < stopPrice, SELL: marketPrice > stopPrice). OCO order (BUY: price < marketPrice < stopPrice, SELL: price > marketPrice > stopPrice)",
+    [ERROR.INVALID_ORDER_TYPE]: "Supported order type are 'limit' and 'market'",
+    [ERROR.INVALID_PRICE]: "Invalid order price",
+    [ERROR.INVALID_PRICE_LEVEL]: "Invalid order price level",
+    [ERROR.INVALID_PRICE_OR_QUANTITY]: "Invalid order price or quantity",
+    [ERROR.INVALID_QUANTITY]: "Invalid order quantity",
+    [ERROR.INVALID_SIDE]: "Invalid side: must be either 'sell' or 'buy'",
+    [ERROR.INVALID_TIF]: "Invalid TimeInForce: must be one of 'GTC', 'IOC' or 'FOK'",
+    [ERROR.LIMIT_ORDER_FOK_NOT_FILLABLE]: "Limit FOK order not fillable",
+    [ERROR.LIMIT_ORDER_POST_ONLY]: "Post-only limit order rejected because would execute immediately",
+    [ERROR.ORDER_ALREDY_EXISTS]: "Order already exists",
+    [ERROR.ORDER_NOT_FOUND]: "Order not found",
+    [ERROR.INVALID_JOURNAL_LOG]: "Invalid journal log format",
+    [ERROR.STP_TRIGGERED]: "Self-trade prevention triggered",
+};
+class OrderBookError {
+    message;
+    code;
+    constructor(error) {
+        let errorMessage;
         if (error != null && exports.ErrorMessages[error] != null) {
             errorMessage = exports.ErrorMessages[error];
         }
         else {
-            var customMessage = error === undefined || error === "" ? "" : ": ".concat(error);
-            errorMessage = "".concat(exports.ErrorMessages.DEFAULT).concat(customMessage);
+            const customMessage = error === undefined || error === "" ? "" : `: ${error}`;
+            errorMessage = `${exports.ErrorMessages.DEFAULT}${customMessage}`;
         }
         this.message = errorMessage;
-        this.code = (_a = exports.ErrorCodes[error]) !== null && _a !== void 0 ? _a : exports.ErrorCodes[ERROR.DEFAULT];
+        this.code = exports.ErrorCodes[error] ?? exports.ErrorCodes[ERROR.DEFAULT];
     }
-    return OrderBookError;
-}());
+}
 exports.OrderBookError = OrderBookError;
 /* node:coverage ignore next - Don't know why this line is uncoverd */
-var CustomError = function (error) {
+const CustomError = (error) => {
     return new OrderBookError(error);
 };
 exports.CustomError = CustomError;

package/dist/cjs/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Side = exports.OrderType = exports.OrderBook = void 0;
+exports.Side = exports.SelfTradePreventionMode = exports.OrderType = exports.OrderBook = void 0;
 /* node:coverage disable */
-var orderbook_1 = require("./orderbook");
+const orderbook_1 = require("./orderbook");
 Object.defineProperty(exports, "OrderBook", { enumerable: true, get: function () { return orderbook_1.OrderBook; } });
-var types_1 = require("./types");
+const types_1 = require("./types");
 Object.defineProperty(exports, "OrderType", { enumerable: true, get: function () { return types_1.OrderType; } });
+Object.defineProperty(exports, "SelfTradePreventionMode", { enumerable: true, get: function () { return types_1.SelfTradePreventionMode; } });
 Object.defineProperty(exports, "Side", { enumerable: true, get: function () { return types_1.Side; } });
 /* node:coverage enable */