add instrument symbol discovery helper

Author: thaaddeus

src/instrumentinfo.ts

@@ -51,12 +51,43 @@ async function getInstrumentInfoForExchange(exchange: Exchange, filterOrSymbol?:
   }
 }
 
-type InstrumentInfoFilter = {
+export async function findInstrumentSymbols(
+  exchanges: Exchange[],
+  filter: InstrumentInfoFilter,
+  selector: InstrumentSymbolSelector = 'id'
+): Promise<InstrumentSymbols[]> {
+  if (selector !== 'id' && selector !== 'datasetId') {
+    throw new Error("Invalid selector. Supported values are 'id' and 'datasetId'.")
+  }
+
+  return await Promise.all(
+    exchanges.map(async (exchange) => {
+      const instruments = (await getInstrumentInfoForExchange(exchange, filter)) as InstrumentInfo[]
+
+      return {
+        exchange,
+        symbols: instruments.map((instrument) => (selector === 'datasetId' ? instrument.datasetId ?? instrument.id : instrument.id))
+      }
+    })
+  )
+}
+
+export type InstrumentSymbolSelector = 'id' | 'datasetId'
+
+export type InstrumentSymbols = {
+  exchange: Exchange
+  symbols: string[]
+}
+
+export type InstrumentInfoFilter = {
   baseCurrency?: string | string[]
   quoteCurrency?: string | string[]
   type?: SymbolType | SymbolType[]
   contractType?: ContractType | ContractType[]
+  underlyingType?: UnderlyingType | UnderlyingType[]
   active?: boolean
+  availableSince?: string
+  availableTo?: string
 }
 
 export type ContractType =
@@ -76,6 +107,8 @@ export type ContractType =
   | 'repo'
   | 'index'
 
+export type UnderlyingType = 'native' | 'equity' | 'commodity' | 'fixed_income' | 'fx' | 'index' | 'pre_market'
+
 export interface InstrumentInfo {
   /** symbol id */
   id: string
@@ -104,6 +137,8 @@ export interface InstrumentInfo {
   expirationType?: 'daily' | 'weekly' | 'next_week' | 'quarter' | 'next_quarter'
   /** the underlying index for derivatives */
   underlyingIndex?: string
+  /** underlying asset class */
+  underlyingType?: UnderlyingType
   /** price tick size, price precision can be calculated from it */
   priceIncrement: number
   /** amount tick size, amount/size precision can be calculated from it */

test/instrumentinfo.test.ts

@@ -0,0 +1,81 @@
+import { jest } from '@jest/globals'
+import { findInstrumentSymbols, getInstrumentInfo, init, type InstrumentInfoFilter } from '../dist/index.js'
+import { describeLive } from './live.js'
+
+function createFetchMock(...responses: Response[]) {
+  const fetchMock = jest.fn<typeof fetch>()
+
+  for (const response of responses) {
+    fetchMock.mockResolvedValueOnce(response)
+  }
+
+  return fetchMock
+}
+
+describe('findInstrumentSymbols', () => {
+  const originalFetch = global.fetch
+
+  afterEach(() => {
+    global.fetch = originalFetch
+    init()
+    jest.restoreAllMocks()
+  })
+
+  test('returns dataset ids and falls back to id when datasetId is omitted', async () => {
+    global.fetch = createFetchMock(
+      new Response(JSON.stringify([{ id: 'btcusdt', datasetId: 'BTCUSDT' }, { id: 'ethusdt' }]), { status: 200 })
+    )
+    init({ endpoint: 'https://example.com/v1' })
+
+    await expect(findInstrumentSymbols(['binance'], { active: true }, 'datasetId')).resolves.toEqual([
+      { exchange: 'binance', symbols: ['BTCUSDT', 'ethusdt'] }
+    ])
+  })
+
+  test('rejects invalid selector values at runtime', async () => {
+    await expect(findInstrumentSymbols(['binance'], { active: true }, 'nativeId' as any)).rejects.toThrow('Invalid selector')
+  })
+})
+
+describeLive('instrument info live', () => {
+  const bitmexXbtUsdPerpetualFilter: InstrumentInfoFilter = {
+    baseCurrency: 'BTC',
+    quoteCurrency: 'USD',
+    type: 'perpetual',
+    contractType: 'inverse_perpetual',
+    underlyingType: 'native',
+    active: true
+  }
+
+  afterEach(() => {
+    init()
+  })
+
+  test('fetches public BitMEX instrument metadata', async () => {
+    const instrument = await getInstrumentInfo('bitmex', 'XBTUSD')
+
+    expect(instrument).toMatchObject({
+      id: 'XBTUSD',
+      datasetId: 'XBTUSD',
+      exchange: 'bitmex',
+      baseCurrency: 'BTC',
+      quoteCurrency: 'USD',
+      type: 'perpetual',
+      contractType: 'inverse_perpetual',
+      underlyingType: 'native',
+      active: true
+    })
+  })
+
+  test('finds public BitMEX symbol ids by metadata filter', async () => {
+    await expect(findInstrumentSymbols(['bitmex'], bitmexXbtUsdPerpetualFilter)).resolves.toEqual([
+      { exchange: 'bitmex', symbols: ['XBTUSD'] }
+    ])
+  })
+
+  test('finds public BitMEX dataset ids by metadata filter', async () => {
+    await expect(findInstrumentSymbols(['bitmex'], bitmexXbtUsdPerpetualFilter, 'datasetId')).resolves.toEqual([
+      { exchange: 'bitmex', symbols: ['XBTUSD'] }
+    ])
+  })
+})

test/package-exports.test.ts

@@ -20,13 +20,15 @@ describe('package exports', () => {
       path.join(tempDir, 'import-test.mjs'),
       `
         import * as tardis from 'tardis-dev'
-        import { replay, stream } from 'tardis-dev'
+        import { findInstrumentSymbols, replay, stream } from 'tardis-dev'
         console.log(JSON.stringify({
           namespaceReplay: typeof tardis.replay,
           namespaceStream: typeof tardis.stream,
+          namespaceFindInstrumentSymbols: typeof tardis.findInstrumentSymbols,
           hasDefault: Object.prototype.hasOwnProperty.call(tardis, 'default'),
           namedReplay: typeof replay,
-          namedStream: typeof stream
+          namedStream: typeof stream,
+          namedFindInstrumentSymbols: typeof findInstrumentSymbols
         }))
       `.trim() + '\n'
     )
@@ -41,9 +43,11 @@ describe('package exports', () => {
     expect(importOutput).toEqual({
       namespaceReplay: 'function',
       namespaceStream: 'function',
+      namespaceFindInstrumentSymbols: 'function',
       hasDefault: false,
       namedReplay: 'function',
-      namedStream: 'function'
+      namedStream: 'function',
+      namedFindInstrumentSymbols: 'function'
     })
 
     rmSync(tempDir, { force: true, recursive: true })