[DX] Handling Types

[bradennapier]

Posting as an issue instead of a JIRA for this one. When working with the sdk from a developer perspective so far, I have run into it being slightly cumbersome to see what is expected. Since the doc tags are nested values as well, in the end things can be hard.

This is really two separate considerations:

Type Expansion Consideration

We may want to implement a simple fix to make this far nicer to use for the developer.

export type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;

// then use like:
getOrders(findOrders: Expand<request.FindOrders>): Promise<response.Order[]>;

This trick will change the above to:

Being tsdoc compliant (Official Microsoft / Typescript Language Server spec)

In addition to this, if possible, it'd be ideal to also consider being compliant with tsdoc so that the typescript experience is as developers would expect.

/**
 * @typedef {Object} request.FindOrders
 * @property {string} nonce - UUIDv1
 * @property {string} wallet
 * @property {string} [market] - Base-quote pair e.g. 'IDEX-ETH'
 * @property {boolean} [closed] - false only returns active orders on the order book; true only returns orders that are no longer on the order book and resulted in at least one fill; only applies if orderId is absent
 * @property {number} [start] - Starting timestamp (inclusive)
 * @property {number} [end] - Ending timestamp (inclusive)
 * @property {number} [limit=50] - Max results to return from 1-1000
 * @property {string} [fromId] - orderId of the earliest (oldest) order, only applies if orderId is absent
 */
export interface FindOrders extends FindByWallet, FindWithPagination {
    market?: string;
    closed: boolean;
    fromId?: string;
}

Typescript currently will not have any context about any of the properties included here, requiring the end user to continually scan back to the docs rather than having it all inline

Whereas by just making sure we add the tsdoc compliance syntax, the user gets it without effort:

/**
 * @typedef {Object} request.FindOrders
 * @property {string} nonce - UUIDv1
 * @property {string} wallet
 * @property {string} [market] - Base-quote pair e.g. 'IDEX-ETH'
 * @property {boolean} [closed] - false only returns active orders on the order book; true only returns orders that are no longer on the order book and resulted in at least one fill; only applies if orderId is absent
 * @property {number} [start] - Starting timestamp (inclusive)
 * @property {number} [end] - Ending timestamp (inclusive)
 * @property {number} [limit=50] - Max results to return from 1-1000
 * @property {string} [fromId] - orderId of the earliest (oldest) order, only applies if orderId is absent
 */
export interface FindOrders extends FindByWallet, FindWithPagination {
    /** Base-quote pair e.g. 'IDEX-ETH'  */
    market?: string;
    closed: boolean;
    fromId?: string;
}

While it is slightly cumbersome to copy for both the jsdoc and the tsdoc cases, it makes the api FAR more useable without the constant need to reference the docs and find what you need.