Better typescript typing for the `NewFuturesOrder` type

[nothing9537]

Hello. I noticed one inconvenience when using the package.

When you want to send a new order via USDMClient,

binanceClient.submitNewOrder({ type: 'MARKET' })

there is a general type NewFutureOrder. But in the Binance documentation, there are some combinations of type and everything else. I suggest rewriting the types to make them more convenient, so that the arguments are defined via type and picked up dynamically depending on the transmitted type.

import { BooleanString, FuturesOrderType, OrderSide, OrderTimeInForce, PositionSide, PriceMatchMode, SelfTradePreventionMode, WorkingType } from 'binance';

type BooleanStringUpper = 'TRUE' | 'FALSE';
type PriceOrMatch = { price: string; priceMatch?: never } | { price?: never; priceMatch: PriceMatchMode };
type QtyOrCloseAll = { closePosition: 'true'; quantity?: never; reduceOnly?: never } | { closePosition?: 'false'; quantity: string };
type TIFRequired = { timeInForce: Exclude<OrderTimeInForce, 'GTD'>; goodTillDate?: never } | { timeInForce: 'GTD'; goodTillDate: number | string };
type TIFOptional = { timeInForce?: Exclude<OrderTimeInForce, 'GTD'>; goodTillDate?: never } | { timeInForce: 'GTD'; goodTillDate: number | string };

export interface BaseRequest {
  recvWindow?: number; // default 5000, max 60000
}

export interface NewFuturesOrderBase extends BaseRequest {
  symbol: string;
  side: OrderSide;
  positionSide?: PositionSide; // mandatory in Hedge Mode
  type: FuturesOrderType;
  newClientOrderId?: string; // ^[\.A-Z\:/a-z0-9_-]{1,36}$
  newOrderRespType?: 'ACK' | 'RESULT'; // default ACK
  reduceOnly?: BooleanString; // not allowed in Hedge Mode and with closePosition='true'
  selfTradePreventionMode?: SelfTradePreventionMode; // applies when TIF=GTC/IOC/GTD
}

/** LIMIT: quantity + TIF mandatory + (price XOR priceMatch) */
export type LimitNewFuturesOrder = NewFuturesOrderBase & { type: 'LIMIT'; quantity: string } & TIFRequired & PriceOrMatch;

/** MARKET: quantity */
export type MarketNewFuturesOrder = NewFuturesOrderBase & { type: 'MARKET'; quantity: string };

/** STOP: quantity + stopPrice + (price XOR priceMatch) + optional TIF */
export type StopNewFuturesOrder = NewFuturesOrderBase & {
  type: 'STOP';
  quantity: string;
  stopPrice: string;
  workingType?: WorkingType; // MARK_PRICE | CONTRACT_PRICE
  priceProtect?: BooleanStringUpper; // TRUE | FALSE
} & TIFOptional &
  PriceOrMatch;

/** TAKE_PROFIT: as STOP, priceProtect is also allowed */
export type TakeProfitNewFuturesOrder = NewFuturesOrderBase & {
  type: 'TAKE_PROFIT';
  quantity: string;
  stopPrice: string;
  workingType?: WorkingType;
  priceProtect?: BooleanStringUpper;
} & TIFOptional &
  PriceOrMatch;

/** STOP_MARKET: stopPrice + (quantity XOR closePosition) */
export type StopMarketNewFuturesOrder = NewFuturesOrderBase & {
  type: 'STOP_MARKET';
  stopPrice: string;
  workingType?: WorkingType;
  priceProtect?: BooleanStringUpper;
} & QtyOrCloseAll;

/** TAKE_PROFIT_MARKET: as STOP_MARKET */
export type TakeProfitMarketNewFuturesOrder = NewFuturesOrderBase & {
  type: 'TAKE_PROFIT_MARKET';
  stopPrice: string;
  workingType?: WorkingType;
  priceProtect?: BooleanStringUpper;
} & QtyOrCloseAll;

/** TRAILING_STOP_MARKET: callbackRate mandatory; closePosition not allowed */
export type TrailingStopMarketNewFuturesOrder = NewFuturesOrderBase & {
  type: 'TRAILING_STOP_MARKET';
  quantity: string;
  callbackRate: string; // min 0.1, max 10 (1 => 1%)
  activationPrice?: string;
  workingType?: WorkingType;
};

/** Type map (useful for generics) */
export interface NewFuturesOrderMap {
  LIMIT: LimitNewFuturesOrder;
  MARKET: MarketNewFuturesOrder;
  STOP: StopNewFuturesOrder;
  TAKE_PROFIT: TakeProfitNewFuturesOrder;
  STOP_MARKET: StopMarketNewFuturesOrder;
  TAKE_PROFIT_MARKET: TakeProfitMarketNewFuturesOrder;
  TRAILING_STOP_MARKET: TrailingStopMarketNewFuturesOrder;
}

/** Universal union of all orders */
export type NewFuturesOrder = NewFuturesOrderMap[keyof NewFuturesOrderMap]; // ! That's what we use in binanceRESTClient.submitNewOrder()

/** Useful generic: get form by type constant */
export type NewFuturesOrderByType<T extends keyof NewFuturesOrderMap> = NewFuturesOrderMap[T];

/** Utility type to restrict additional fields when declaring (useful in function signatures) */
export type Exact<T> = T & Record<Exclude<string, keyof T>, never>;

So, in the end, we can use NewFuturesOrder in the REST client and possibly in the WebSocket client.

[JJ-Cro]

This does look tempting, but it is better from my opinion to keep it more general because Binance tends to change/update this often and we could fall behind there.

While the users can do what you did on their own for more safety.

Let's see what Tiago thinks.

[tiagosiebler]

Thanks for putting this together! Honestly, I really like this and it's something I've wanted in place for a while now. I've always been on a balance in how granular the SDKs are with each exchange. Right now the assumption is that anyone using the SDK is also looking at the exchange docs in tandem, at least to validate parameters and other finer business rules in how individual endpoints behave. So we've kept typing relatively loose but detailed. All the properties are (or at least should be) there, though there's not much work done on type flowing to resolve which parameters become optional/required depending on properties such as order type.

The perspective of maintainability is the primary reason I haven't taken this level of detail everywhere. There are a huge amount of endpoints on Binance alone, so we do have to pick and choose how granular we go with some of the endpoints. I'm happy to integrate this for a high impact endpoint such as the new order submissions - if you're happy to make the PR (& ideally help maintain it as it evolves)? Worst case scenario, over time if this endpoint's request type continues to evolve or change, it might revert to becoming increasingly generic again (so it doesn't block usage).

[nothing9537]

Thank you for your detailed response! To be honest, I find it difficult to imagine that anything in this endpoint could change globally. In this implementation, there is a breakdown into order types, and the most that could change, in my opinion, is that some fields will be added to a specific order type (unlikely to be removed something global). It's possible to add specific fields on a case-by-case type basis.

What do you think about it?

[JJ-Cro]

The worst part is Binance can add another type of order silently, or it can change what is mandatory for one order and our type gets outdated.

That is why the general usage was done so that our types are easily used, while still need a minimum research by the user to see which fields they need for their type of order.

From my perspective, this adds a lot of complexity in maintaining it especially knowing how Binance is with the changes and their silent updates.

[nothing9537]

Unfortunately, yes, you are right about silent updates. This requires constant monitoring of documentation and checking types.