feat(example-improvements): reshaped example into generic script allows to run stream and reply tests for any exchange/channel/symbol (#70)

Author: marcinvalas

ADD_NEW_EXCHANGE.md

@@ -92,6 +92,27 @@ Mapper tests should cover:
 
 Run tests and validation — see AGENTS.md for the full checklist.
 
+### 5. Validate live and replay output
+
+After adding or changing a real-time feed, mapper, filter, or upstream API version branch, validate the implementation against actual data in addition to mapper snapshots. Build first because `example.js` imports `dist/index.js`.
+
+```bash
+npm run build
+```
+
+Use `example.js` to check native and normalized output for at least one active symbol and each channel or normalized data type touched by the change:
+
+```bash
+node example.js stream <exchange> <symbol> <channel>
+node example.js --normalized stream <exchange> <symbol> <data-type>
+node example.js replay <exchange> <symbol> <channel> <from> <to>
+node example.js --normalized replay <exchange> <symbol> <data-type> <from> <to>
+```
+
+For order book changes, confirm the expected snapshot behavior: snapshot-capable feeds should emit an initial `book_change` with `isSnapshot=true`, then deltas with `isSnapshot=false` when the exchange contract provides deltas. For trades, tickers, liquidations, and other mapped data types, confirm that messages are produced for the requested symbol and that key fields are populated from the documented exchange semantics.
+
+If a channel is intentionally state-only or should emit nothing for a message variant, validate the paired channel or later payload that should produce the normalized output. Record any skipped live or replay checks in the PR notes.
+
 ## Decision Points
 
 - **Date-based mapper versioning** — If the exchange changed its API format at some point, define the switch in the exchange mapper registry with `mapper([{ until, use }, { use }])`. Look at existing `*Mappers` exports in `src/mappers/{exchange}.ts` files for the pattern.

example.js

@@ -1,35 +1,137 @@
-import { replayNormalized, streamNormalized, normalizeTrades, compute, computeTradeBars } from 'tardis-dev'
-
-const historicalMessages = replayNormalized(
-  {
-    exchange: 'binance',
-    symbols: ['btcusdt'],
-    from: '2024-03-01',
-    to: '2024-03-02'
-  },
-  normalizeTrades
-)
-
-const realTimeMessages = streamNormalized(
-  {
-    exchange: 'binance',
-    symbols: ['btcusdt']
-  },
-  normalizeTrades
-)
-
-async function produceVolumeBasedTradeBars(messages) {
-  // aggregate by 1 BTC traded volume
-  const withVolumeTradeBars = compute(messages, computeTradeBars({ kind: 'volume', interval: 1 }))
-
-  for await (const message of withVolumeTradeBars) {
-    if (message.type === 'trade_bar') {
-      console.log(message.name, message)
-    }
+import {
+  normalizeBookChanges,
+  normalizeBookTickers,
+  normalizeDerivativeTickers,
+  normalizeLiquidations,
+  normalizeOptionsSummary,
+  normalizeTrades,
+  replay,
+  replayNormalized,
+  stream,
+  streamNormalized
+} from './dist/index.js'
+
+const options = getOptions(process.argv.slice(2))
+const optionsError = getOptionsError(options)
+if (optionsError !== undefined) {
+  console.error(`${optionsError}
+
+Usage:
+  node example.js stream <exchange> <symbol> <channel>
+  node example.js replay <exchange> <symbol> <channel> <from> <to>
+  node example.js --normalized stream <exchange> <symbol> <data-type>
+  node example.js --normalized replay <exchange> <symbol> <data-type> <from> <to>
+
+Examples:
+  node example.js stream mexc-futures BTC_USDT push.depth
+  node example.js replay mexc-futures BTC_USDT push.depth 2026-06-17 2026-06-18
+  node example.js --normalized stream mexc-futures BTC_USDT book_change
+  node example.js --normalized replay mexc-futures BTC_USDT book_change 2026-06-17 2026-06-18`)
+  process.exit(1)
+}
+
+for await (const message of createMessageStream(options)) {
+  if (message === undefined || message?.type === 'disconnect') {
+    console.log({ type: 'disconnect' })
+    continue
+  }
+
+  console.log(message)
+}
+
+function getOptions(args) {
+  const normalized = args.includes('--normalized')
+  const positionalArgs = args.filter((arg) => arg !== '--normalized')
+
+  const normalizersByDataType = {
+    trade: normalizeTrades,
+    book_change: normalizeBookChanges,
+    derivative_ticker: normalizeDerivativeTickers,
+    option_summary: normalizeOptionsSummary,
+    liquidation: normalizeLiquidations,
+    book_ticker: normalizeBookTickers
+  }
+
+  return {
+    mode: positionalArgs[0], // 'stream' or 'replay'
+    normalized,
+    exchange: positionalArgs[1],
+    symbols: [positionalArgs[2]],
+    channel: normalized ? undefined : positionalArgs[3],
+    dataType: normalized ? positionalArgs[3] : undefined,
+    normalizer: normalized ? normalizersByDataType[positionalArgs[3]] : undefined,
+    from: positionalArgs[4],
+    to: positionalArgs[5]
+  }
+}
+
+function getOptionsError(options) {
+  if (options.mode !== 'stream' && options.mode !== 'replay') {
+    return 'Missing or invalid mode. Expected "stream" or "replay".'
+  }
+  if (options.exchange === undefined) {
+    return 'Missing exchange name.'
+  }
+  if (options.symbols[0] === undefined) {
+    return 'Missing symbol.'
+  }
+  if (options.normalized && options.dataType === undefined) {
+    return 'Missing normalized data type.'
+  }
+  if (options.normalized === false && options.channel === undefined) {
+    return 'Missing native channel.'
+  }
+  if (options.normalized && options.normalizer === undefined) {
+    return `Invalid normalized data type "${options.dataType}".`
+  }
+  if (options.mode === 'replay' && (options.from === undefined || options.to === undefined)) {
+    return 'Replay mode requires from and to dates.'
   }
 }
 
-await produceVolumeBasedTradeBars(historicalMessages)
+function createMessageStream(options) {
+  if (options.normalized) {
+    if (options.mode === 'stream') {
+      return streamNormalized(
+        {
+          exchange: options.exchange,
+          symbols: options.symbols,
+          timeoutIntervalMS: 20_000,
+          withDisconnectMessages: true,
+          onError: (error) => console.error(`[${options.exchange}] ${error.message}`)
+        },
+        options.normalizer
+      )
+    }
+
+    return replayNormalized(
+      {
+        exchange: options.exchange,
+        symbols: options.symbols,
+        from: options.from,
+        to: options.to,
+        withDisconnectMessages: true
+      },
+      options.normalizer
+    )
+  }
 
-// or for real time data
-//  await produceVolumeBasedTradeBars(realTimeMessages)
+  const nativeFilters = [{ channel: options.channel, symbols: options.symbols }]
+  if (options.mode === 'stream') {
+    return stream({
+      exchange: options.exchange,
+      filters: nativeFilters,
+      timeoutIntervalMS: 20_000,
+      withDisconnects: true,
+      onError: (error) => console.error(`[${options.exchange}] ${error.message}`)
+    })
+  }
+
+  return replay({
+    exchange: options.exchange,
+    from: options.from,
+    to: options.to,
+    filters: nativeFilters,
+    withDisconnects: true
+  })
+}