thetadatadx 8.0.26 → 8.0.30

package/README.md

@@ -36,14 +36,19 @@ async function main() {
   // With timeout
   const snap = tdx.stockSnapshotQuote(['AAPL', 'MSFT'], null, null, 5000);
 
-  // Streaming — `nextEvent` is async; `await` it or you'll get a
-  // `Promise` object back and `event.kind` will be `undefined`.
-  tdx.startStreaming();
+  // Streaming — register a callback. napi-rs `ThreadsafeFunction`
+  // routes every event through libuv's `uv_async_t` queue onto the
+  // Node main thread; the callback runs there, decoupled from the
+  // FPSS reader thread. A slow callback fills the SSOT dispatcher's
+  // bounded queue and overflow events are dropped (observable via
+  // `tdx.droppedEventCount()`); the FPSS TLS reader is never blocked.
+  tdx.startStreaming((event) => {
+    if (event.kind === 'quote') {
+      console.log(event.quote.bid, event.quote.ask);
+    }
+  });
   tdx.subscribeQuotes('AAPL');
-  const event = await tdx.nextEvent(1000); // poll with 1s timeout
-  if (event && event.kind === 'quote') {
-    console.log(event.quote.bid, event.quote.ask);
-  }
+  // ...do other work; the callback fires on incoming events...
   tdx.stopStreaming();
 }
 
@@ -60,20 +65,21 @@ the Rust side, so the full typed surface lives in `index.d.ts`
 import type { OhlcTick, GreeksTick, Quote, Trade, FpssEvent } from 'thetadatadx';
 ```
 
-Historical endpoints return `Tick[]`; `nextEvent()` is async and resolves
-to a discriminated `FpssEvent | null` union, narrowed on `event.kind`:
+Historical endpoints return `Tick[]`. Streaming events arrive through the
+`startStreaming(callback)` registration; the callback receives a
+discriminated `FpssEvent`, narrowed on `event.kind`:
 
 ```ts
-const event = await tdx.nextEvent(1000);
-if (!event) return; // timeout
-switch (event.kind) {
-  case 'quote':    /* event.quote is Quote */    break;
-  case 'trade':    /* event.trade is Trade */    break;
-  case 'ohlcvc':   /* event.ohlcvc is Ohlcvc */  break;
-  case 'open_interest': /* event.openInterest is OpenInterest */ break;
-  case 'simple':   /* event.simple is FpssSimplePayload */ break;
-  case 'raw_data': /* event.rawData is FpssRawDataPayload */ break;
-}
+tdx.startStreaming((event: FpssEvent) => {
+  switch (event.kind) {
+    case 'quote':    /* event.quote is Quote */    break;
+    case 'trade':    /* event.trade is Trade */    break;
+    case 'ohlcvc':   /* event.ohlcvc is Ohlcvc */  break;
+    case 'open_interest': /* event.openInterest is OpenInterest */ break;
+    case 'simple':   /* event.simple is FpssSimplePayload */ break;
+    case 'raw_data': /* event.rawData is FpssRawDataPayload */ break;
+  }
+});
 ```
 
 The `kind` field is typed as the string-literal union
@@ -87,7 +93,7 @@ including Vite, esbuild, ts-jest, and Next.js.
 
 Anywhere a Rust `u64` or `i64` crosses the napi boundary it surfaces as
 JavaScript `bigint` (not `number`): `volume` and `count` on every
-OHLC / EOD tick, `droppedEvents()` on the streaming client, and
+OHLC / EOD tick, `droppedEventCount()` on the streaming client, and
 `received_at_ns` on every FPSS event. Use `bigint` literal syntax
 (`42n`) for comparisons or widen to `Number(x)` at the point of
 display (watch for loss of precision beyond 2^53).

package/index.d.ts

@@ -9,18 +9,19 @@ export declare class ThetaDataDx {
   /** Connect with a credentials file (line 1 = email, line 2 = password). */
   static connectFromFile(path: string): ThetaDataDx
   /**
-   * Cumulative count of FPSS events dropped because the JS polling
-   * side disconnected before the FPSS callback could hand them off.
+   * Cumulative count of FPSS events dropped because the SSOT
+   * `StreamingDispatcher`'s bounded queue overflowed before the
+   * drain thread could hand the event off to the JS callback.
    *
-   * Counter lives on the client instance (not inside the
-   * `start_streaming` / `reconnect` closures), so the value survives
-   * reconnect and is observable at any point — before streaming,
-   * during, or after `shutdown()`.
+   * Forwards to `thetadatadx::ThetaDataDx::dropped_event_count` so
+   * the value matches every other binding (C ABI, Python, future
+   * C++) and survives reconnect — the dispatcher carries the count
+   * across `start_streaming` / `reconnect` cycles.
    *
    * Returned as `bigint` so it can represent the full `u64` range
    * (Number would top out at 2^53).
    */
-  droppedEvents(): bigint
+  droppedEventCount(): bigint
   /**
    * List all available stock ticker symbols.
    *
@@ -760,8 +761,27 @@ export declare class ThetaDataDx {
    * - `venue`: `"nqb"`
    */
   stockHistoryOHLCRange(symbol: string, startDate: string | Date, endDate: string | Date, interval?: string | undefined | null, startTime?: string | Date | undefined | null, endTime?: string | Date | undefined | null, venue?: string | undefined | null, timeoutMs?: number | undefined | null): Array<OhlcTick>
-  /** Start FPSS streaming. Events are buffered; poll with next_event(). */
-  startStreaming(): void
+  /**
+   * Start FPSS streaming and register a JS callback for incoming events.
+   *
+   * The dispatcher's drain thread routes every typed FPSS event through
+   * napi-rs `ThreadsafeFunction` to the Node main thread, where the user's
+   * `callback(event)` runs. The FPSS reader thread itself never touches V8:
+   * events cross the bounded `crossbeam_channel(8192)` queue inside the
+   * SSOT `StreamingDispatcher` first.
+   *
+   * Node's libuv requires JS callbacks on the main thread, so
+   * `ThreadsafeFunction` (with its internal `uv_async_t` queue) is the only
+   * safe path. This binding deliberately does NOT expose a
+   * `start_streaming_inline` opt-in: calling into V8 from any thread other
+   * than the main loop is undefined behavior.
+   *
+   * Backpressure: a slow callback fills the dispatcher queue and overflow
+   * events are dropped, observable via `droppedEventCount()`. The FPSS TLS
+   * reader is never blocked — vendor disconnects on slow consumers cannot
+   * happen on this path.
+   */
+  startStreaming(callback: (event: FpssEvent) => void): void
   /** Whether the streaming connection is active. */
   isStreaming(): boolean
   /** Subscribe to real-time quote data for a stock symbol. */
@@ -802,9 +822,14 @@ export declare class ThetaDataDx {
   contractLookup(id: number): string | null
   /** Get a snapshot of currently active subscriptions. */
   activeSubscriptions(): any
-  /** Poll for the next FPSS event. */
-  nextEvent(timeoutMs: number): Promise<({ kind: 'ohlcvc'; ohlcvc: Ohlcvc } | { kind: 'open_interest'; openInterest: OpenInterest } | { kind: 'quote'; quote: Quote } | { kind: 'trade'; trade: Trade } | { kind: 'simple'; simple: FpssSimplePayload } | { kind: 'raw_data'; rawData: FpssRawDataPayload }) | null>
-  /** Reconnect streaming and re-subscribe all previous subscriptions. */
+  /**
+   * Reconnect FPSS streaming and re-register the previously installed callback.
+   *
+   * Requires a prior `startStreaming(callback)`; throws if no callback is
+   * registered. All active subscriptions are restored on the new connection
+   * — see `thetadatadx::ThetaDataDx::reconnect_streaming` for partial-failure
+   * semantics.
+   */
   reconnect(): void
   /** Stop streaming while keeping the historical client usable. */
   stopStreaming(): void
@@ -826,9 +851,9 @@ export interface CalendarDay {
  * event as `event.quote.contract` / `event.trade.contract` / etc.
  */
 export interface Contract {
-  root: string
+  symbol: string
   secType: number
-  expDate?: number
+  expiration?: number
   isCall?: boolean
   strike?: number
 }
@@ -1096,7 +1121,7 @@ export interface OpenInterestTick {
 
 /** Option contract. Contract specification. */
 export interface OptionContract {
-  root: string
+  symbol: string
   expiration: number
   strike: number
   right: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thetadatadx",
-  "version": "8.0.26",
+  "version": "8.0.30",
   "description": "Native ThetaData SDK for Node.js — powered by Rust via napi-rs",
   "license": "Apache-2.0",
   "repository": {
@@ -30,9 +30,9 @@
     "@napi-rs/cli": "^3.6.2"
   },
   "optionalDependencies": {
-    "thetadatadx-linux-x64-gnu": "8.0.26",
-    "thetadatadx-darwin-arm64": "8.0.26",
-    "thetadatadx-win32-x64-msvc": "8.0.26"
+    "thetadatadx-linux-x64-gnu": "8.0.30",
+    "thetadatadx-darwin-arm64": "8.0.30",
+    "thetadatadx-win32-x64-msvc": "8.0.30"
   },
   "engines": {
     "node": ">= 20"